Files
LithosAnanke/v4/include/v4/mesh.h
T
Claude b5d99ba98b feat(v4): Phase 7 Task 3 -- the heartbeat snapshot; the loops complete (#189)
Each cycle publishes v3's HeartbeatSnapshot: the tick, the window's width and fill, the decay slope, and the
dictionary's heat as inference last counted it (words over 50, cooling, the heat in all). One copy, not
v3's two, which are for its heartbeat thread. With it every loop v3 runs before its prompt runs on v4's
word records on every node. Test first: test_mesh_boot.c 73 checks, 81 on. Not pushed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-14 00:10:46 +00:00

287 lines
16 KiB
C

/* SPDX-License-Identifier: LicenseRef-Starship-1.0
* Copyright (c) 2023-2026 Robert A. James
*/
/* mesh.h -- the kernel's boot of the fabric: Hera born empty, given the
* system, and every node stepped together. docs/v4.0.0/MESH.md 9,
* MACHINE.md 3; #189, ENGINE step 4 Phase 1, Task 5b (Captain Bob,
* 2026-11-13: "Build it to proper spec").
*
* There is no scheduler (JUSTIFICATION.md 4: "There is no scheduler to
* write"): every awake node executes an instruction word at each step of
* the fabric (fabric.h), and a node with nothing to do waits at a port.
*
* THE BOOT, as v4/tests/test_host_unit.c does it on the host:
* 1. the nucleus: the machine's ROM assembles the system's source on a
* node of its own (v4/boot.h, v4_boot_assemble), and the system, as
* assembled, is a capsule of F18 cells -- a node that is born is given
* assembled code, never the source (Captain Bob, 2026-10-15);
* 2. Hera is born empty at place 0, with the machine's ROM: the kernel is
* on her port 0 -- it gives her the nucleus a cell at a time, and takes
* her requests: blocks, the kernel's words, the registry (manage.h) --
* and the console on her port 1, which speaks whole messages;
* 3. she is told she is node 10 and where the console is, entered in the
* registry, made the kernel's words, given FORTH-79, sealed, POSTed,
* given the kernel's capsules, and sealed;
* printing the same parity lines as v4_boot_run (boot.h).
*
* A NODE IS BORN (NODE-BORN): in storage the owner gives, with a mesh
* node's ROM, the kernel on its port 0 for its blocks; it is given the
* nucleus by whoever birthed it (centre.4th). NODE-KILL gives the storage
* back.
*
* Nothing here uses the C library. The owner supplies all the memory.
*/
#ifndef V4_MESH_H
#define V4_MESH_H
#include "v4/boot.h"
#include "v4/blocks.h"
#include "v4/fabric.h"
#include "v4/manage.h"
#include "v4/inference.h"
#define V4_MESH_HERA 10 /* Hera's number, as the host mesh numbers her */
#define V4_MESH_CONSOLE 1 /* the console's number as a sender, and her port to it */
#define V4_MESH_NUCLEUS_CELLS (2u * V4_NODE_WORDS + 64u)
/* A WORD'S ACCOUNTS (#189, Phase 2; ENGINE.md 3b): the kernel's record of a word on a node, joined to
* it by the word ID in its header. The node tells the kernel of each entry made and of entries gone
* (dict.f18, (TELL-DEFINED) and (TELL-FORGOTTEN): requests V4_REQ_WORD_DEFINED and _FORGOTTEN on port
* 0); the kernel reads the system's own once, when the node is sealed. At every `call` to a word
* its record counts one: `calls` (v3's execution_heat) and `since`, which the owner takes and clears
* when it charges the Stadium (v4_mesh_charge; Captain Bob, 2026-11-13: "Per heartbeat tick"). */
#define V4_MESH_WORD_IDS 1024u /* word IDs a record is kept for: v3's DICTIONARY_SIZE, the Stadium's bound */
#define V4_REQ_WORD_DEFINED (-19)
#define V4_REQ_WORD_FORGOTTEN (-20)
typedef struct {
v4_uheat_t calls; /* every call since the word was defined */
v4_uheat_t since; /* calls since the owner last charged them */
v4_cell xt; /* the word's xt; 0: no word has this ID */
/* v3's physics on a word (DictPhysics, v3/include/vm.h; #189 Phase 7, Task 1) */
v4_uheat_t heat; /* v3's execution_heat: +1 a call, decayed by the ticks since (Loop #3) */
uint64_t last_decay_tick; /* the node's tick when decay was last applied: the only clock decay reads */
uint16_t temperature_q8; /* the heat, smoothed (an EMA), in Q8 */
uint8_t state_flags; /* the kernel's own: V4_MESH_STATE_PINNED, _FROZEN */
/* pipelining (Loop #4; v3's WordTransitionMetrics), when ENABLE_PIPELINING: how often each word ID came
* next -- V4_MESH_WORD_IDS counters from the owner's alloc, on the first transition -- and the likeliest */
uint64_t *transitions;
uint64_t total_transitions;
uint64_t most_likely_count;
uint32_t most_likely_next;
uint64_t prefetch_attempts, prefetch_hits;
} v4_mesh_account;
/* A word's state flags, as v3's (PHYSICS_STATE_*): immediate and hidden are the node's (its header's
* flags); pinned and frozen are the kernel's, on the record. */
#define V4_MESH_STATE_IMMEDIATE 0x01u
#define V4_MESH_STATE_PINNED 0x02u
#define V4_MESH_STATE_HIDDEN 0x04u
#define V4_MESH_STATE_FROZEN 0x10u
/* Each node's physics (v3's VM fields): its heartbeat's tick, the decay slope (Q48.16 heat a tick;
* v3's INITIAL_DECAY_SLOPE_Q48, which the inference engine tunes), and L8's gate on Loop #3. */
#define V4_MESH_INITIAL_DECAY_SLOPE_Q48 21845u
/* Pipelining and the hot-words cache: built, and off unless the build turns them on, as v3's
* (Kconfig.physics; Captain Bob, 2026-11-13: "Built, off as v3"). v3's thresholds. */
#ifndef ENABLE_PIPELINING
#define ENABLE_PIPELINING 0
#endif
#ifndef ENABLE_HOTWORDS_CACHE
#define ENABLE_HOTWORDS_CACHE 0
#endif
#ifndef SPECULATION_THRESHOLD_Q48
#define SPECULATION_THRESHOLD_Q48 0x8000 /* a probability of 1/2, Q48.16 */
#endif
#ifndef MIN_SAMPLES_FOR_SPECULATION
#define MIN_SAMPLES_FOR_SPECULATION 10
#endif
#define V4_MESH_HOT_HEAT 50u /* v3's HOTWORDS_EXECUTION_HEAT_THRESHOLD */
#define V4_MESH_NO_WORD 0xFFFFFFFFu
#define V4_MESH_WINDOW 4096u /* v3's ROLLING_WINDOW_SIZE */
#define V4_MESH_WINDOW_WARM 1024u /* executions before the window is warm, as v3 */
#define V4_MESH_ADAPTIVE_CHECK 512u /* v3's ADAPTIVE_CHECK_FREQUENCY: executions between diversity checks */
#define V4_MESH_WINDOW_MIN 256u /* v3's ADAPTIVE_MIN_WINDOW_SIZE */
#define V4_MESH_SHRINK_RATE 50u /* v3's ADAPTIVE_SHRINK_RATE, percent */
#define V4_MESH_GROWTH_THRESHOLD 5u /* v3's ADAPTIVE_GROWTH_THRESHOLD, percent */
#define V4_MESH_DECAY_BATCH 64u /* v3's HEARTBEAT_DECAY_BATCH: words decayed in the background a cycle */
/* word calls a heartbeat cycle: Kconfig.heartbeat's HEARTBEAT_CHECK_FREQUENCY (default 256), which the kernel's
* build passes to every object, as v3's (Captain Bob, 2026-11-13: "should probably be either a kconfig knob or a
* feedback loop for RWOT" -- the knob; a feedback loop from the window is a design change, not v3's) */
#ifndef HEARTBEAT_CHECK_FREQUENCY
#define HEARTBEAT_CHECK_FREQUENCY 256
#endif
#define V4_MESH_CHECK_FREQUENCY ((uint32_t)HEARTBEAT_CHECK_FREQUENCY)
#ifndef HEARTBEAT_INFERENCE_FREQUENCY
#define HEARTBEAT_INFERENCE_FREQUENCY 1000 /* Kconfig.heartbeat, as v3's */
#endif
#ifndef HEARTBEAT_TICK_NS
#define HEARTBEAT_TICK_NS 10000ULL
#endif
#define V4_MESH_INFERENCE_EVERY ((uint64_t)HEARTBEAT_INFERENCE_FREQUENCY)
/* L8, the Jacquard selector (v3's ssm_jacquard.c and compudynamics.c, #188: 64 cards, L7 always on): a card's
* gates are ((card & 0x3F) << 1) | L7, in v3's SSM_CFG_* bits. Applied as card_bits() -- not as v3's
* ssm_l8_tick_score_and_select does, one bit off (#196; Captain Bob, 2026-11-13: "v4 correct, v3 as is"). */
#define V4_L8_CARDS 64u
#define V4_L8_REGIMES 8u
#define V4_L8_START 8u /* v3's first card: C4, L3 and L7 */
#define V4_L8_L1 0x40u
#define V4_L8_L2 0x20u
#define V4_L8_L3 0x10u
#define V4_L8_L4 0x08u
#define V4_L8_L5 0x04u
#define V4_L8_L6 0x02u
#define V4_L8_L7 0x01u
typedef struct {
uint32_t regime_scores[V4_L8_REGIMES * V4_L8_CARDS];
uint32_t regime_ticks[V4_L8_REGIMES * V4_L8_CARDS];
uint32_t total_regime_ticks[V4_L8_REGIMES];
uint32_t prev_window[V4_L8_CARDS];
uint32_t prev_locality_q16[V4_L8_CARDS];
uint8_t has_prev[V4_L8_CARDS];
uint8_t current_card, current_regime;
uint8_t hold; /* a card forced (v3's ssm_l8_force_config): L8 does not move from it */
uint64_t changes; /* how many times the card has changed */
} v4_mesh_l8;
typedef struct {
uint64_t tick; /* the node's heartbeat cycles (v3's tick_count): by execution, as v3 */
uint32_t check_counter; /* word calls since the last cycle */
uint32_t cycle_every; /* V4_MESH_CHECK_FREQUENCY */
uint64_t decay_slope_q48;
uint8_t l3_decay; /* L8's gate on Loop #3 */
uint8_t l2_window; /* L8's gate on Loop #2 */
/* the Rolling Window of Truth (Loop #2; v3's RollingWindowOfTruth): the IDs of the words called, in order */
uint32_t history[V4_MESH_WINDOW];
uint32_t window_pos; /* where the next is written */
uint64_t total_executions;
uint32_t effective_window_size; /* may shrink from V4_MESH_WINDOW (Loop #5) */
uint32_t adaptive_check_accumulator;
uint8_t is_warm;
uint8_t adaptive_pending; /* the heartbeat should check the window's diversity */
uint64_t last_pattern_diversity, diversity_checks;
v4_cell decay_cursor; /* background decay: the next word's xt, down the dictionary; 0: from LATEST */
uint64_t decay_cycles;
/* pipelining (Loop #4): the word called before, L8's gate, and the node's counts */
uint32_t prev_id; /* V4_MESH_NO_WORD: none yet */
uint8_t l4_pipelining;
uint64_t prefetch_attempts, prefetch_hits;
/* the hot-words cache (the node's (HOT), v4/image.h): L8's gate (v3's L1_heat_tracking), and its counts */
uint8_t l1_cache;
uint64_t hot_promotions, hot_evictions;
/* L8 and the gates it sets that the other loops read: l1_cache .. l4_pipelining above, and these */
uint8_t l5_window_inference, l6_decay_inference, l7_adaptive_heartrate;
v4_mesh_l8 l8;
/* inference (Loops #5 and #6, v4/inference.h), every V4_MESH_INFERENCE_EVERY ticks: its outputs (v3's
* last_inference_outputs), the tick of its last full run, its counts; and Loop #7, the heartrate it sets */
v4_inference_out inference;
uint64_t last_inference_tick;
uint8_t inference_early_exited;
uint64_t inference_runs, inference_early_exits;
uint64_t tick_target_ns; /* v3's tick_target_ns: HEARTBEAT_TICK_NS, a quarter to four times it */
/* the dictionary as inference last counted it (v3's *_at_check): words over heat 50, words cooling (heat
* 1..9), the heat in all; and the snapshot each cycle publishes (v3's HeartbeatSnapshot) */
uint64_t hot_at_check, stale_at_check, total_heat_at_check;
struct {
uint64_t tick, decay_slope_q48, hot, stale, total_heat;
uint32_t window_width, fill;
} snapshot;
} v4_mesh_physics;
typedef struct v4_mesh v4_mesh;
struct v4_mesh {
/* ---- the owner's: set before v4_mesh_boot ---- */
v4_place *places; /* the fabric's room: `capacity` places */
unsigned capacity;
v4_wire_queue *queues; /* the wires' memory (fabric.h): two for every wire at once */
unsigned queue_count;
v4_manage_entry *reg; /* the registry: `capacity` entries */
v4_blocks *blocks; /* each place's block window, kept by the kernel: `capacity` of them */
v4_fabric_node *nucleus; /* where the ROM assembles the system: a node of its own */
v4_fabric_node *hera; /* Hera's storage */
v4_device *kernel; /* the kernel on each place's port 0: `capacity` of them */
/* storage for a node to be born, or 0: none; and given back */
v4_fabric_node *(*room)(void *self);
void (*unroom)(void *self, v4_fabric_node *x);
/* a node has been born at `place`, numbered `number` once it is told; is gone (may be 0) */
void (*born)(void *self, unsigned place);
void (*gone)(void *self, unsigned place);
/* a node the asker birthed has its system: its parity (may be 0) */
void (*parity)(void *self, unsigned place, v4_cell number, const v4_node *n);
/* the console, the keyboard, the kernel's words and capsules: as v4_boot's (boot.h) */
void (*out)(const char *text, unsigned len);
int (*key)(void);
const char *const *words;
unsigned word_count;
void (*serve)(v4_node *n, unsigned request);
const char *const *capsules;
unsigned capsule_count;
v4_image *im; /* the map's description (v4_map_image), which the boot completes */
/* the words' accounts: `capacity` x V4_MESH_WORD_IDS records, and `capacity` x V4_NODE_WORDS / 8
* bytes, a bit for each address of a node: set for a word's xt (0: none kept) */
v4_mesh_account *accounts;
unsigned char *is_word;
v4_mesh_physics *physics; /* `capacity` of them: each node's (#189, Phase 7) */
/* Loop #7 on Hera: the kernel's heartbeat period, re-armed (v3: heartbeat_set_adaptive_period_ns; may be 0) */
void (*heartrate)(void *self, uint64_t kernel_period_ns);
/* memory for a word's transition counters, zeroed, and given back (pipelining; may be 0: none recorded) */
void *(*alloc)(void *self, unsigned long bytes);
void (*release)(void *self, void *p);
/* a word has gone, its ID free for the next: the owner forgets what it keeps by it (may be 0) */
void (*forgot)(void *self, unsigned place, v4_cell id);
void *self;
/* ---- the mesh's own ---- */
v4_fabric f;
v4_manage m;
unsigned hera_place;
v4_cell cells[V4_MESH_NUCLEUS_CELLS]; /* the nucleus as a capsule of F18 cells */
unsigned cell_count, given; /* how many; how many given to Hera */
unsigned reading_nucleus[64]; /* by place: the next nucleus cell a CAPSULE-CELL gives; 0: not open */
unsigned dones; /* how many texts have said how they ended, ever */
v4_cell done_from, done_how; /* the last of them: from which node, and how */
v4_cell owed_from; /* a node told texts that were left "waiting" ... */
unsigned owed; /* ... and how many of their ends are still to come */
};
/* The boot: the nucleus, Hera, her system, POST. 1, Hera asleep at her
* wires waiting for a line; or 0, the failure printed. */
int v4_mesh_boot(v4_mesh *ms);
/* Text for node `node`, from the console, and the fabric stepped until that node says how the text
* ended: what any node prints goes to `out`; returns how it ended (V4_TEXT_*), or
* V4_BOOT_LINE_STOPPED / _TOO_LONG / _REFUSED / _NO_INPUT (boot.h). Other nodes may run on after it
* returns (v4_mesh_step). V4_BOOT_LINE_WAITING: Hera is asleep awaiting an answer that has not come
* -- nothing else can run, or other nodes have run a long while and not given it; the next text from
* the console breaks the wait (MESH.md 7b.6), and if the answer comes first, `dones` says so. */
int v4_mesh_tell(v4_mesh *ms, v4_cell node, const char *text, unsigned len);
/* One step of the fabric, as the host's idle: every awake node executes an instruction word, and what
* comes back to the console is printed (or counted, for how a text ended: `dones`). Returns how many
* instructions were retired. The host calls it while it waits, whenever v4_mesh_busy says a node can
* run: every node steps together, between lines as during them. */
unsigned v4_mesh_step(v4_mesh *ms);
int v4_mesh_busy(const v4_mesh *ms);
/* A word's record on the node in `place`, by its xt: 0 if that is not a word's xt. */
const v4_mesh_account *v4_mesh_account_at(const v4_mesh *ms, unsigned place, v4_cell xt);
/* L8 held on `card` (0..63) on the node in `place`, its gates applied (v3's ssm_l8_force_config); `hold` 0 lets
* it choose again from there. */
void v4_mesh_l8_force(v4_mesh *ms, unsigned place, unsigned card, int hold);
/* Every node's tick set to `tick` (for tests: a node's tick is its own count of heartbeat cycles). */
void v4_mesh_set_tick(v4_mesh *ms, uint64_t tick);
/* A word's state flags (V4_MESH_STATE_*), or 0 if xt is not a word's. */
unsigned v4_mesh_state_flags(const v4_mesh *ms, unsigned place, v4_cell xt);
/* For each word on the node in `place` called since the last charge: `each(ctx, id, calls)`, and its
* count since is cleared. */
void v4_mesh_charge(v4_mesh *ms, unsigned place, void (*each)(void *ctx, v4_cell id, v4_uheat_t calls), void *ctx);
/* The node numbered `number`, or 0. */
v4_fabric_node *v4_mesh_node(const v4_mesh *ms, v4_cell number);
#endif