/* 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) /* the loops' words (capsules/v4/physics.4th; #189 Phase 7, Task 4): a word named by (baddr u), as v3's, or cells * of the node's memory (addr u) */ #define V4_REQ_FREEZE_WORD (-21) /* ( baddr u -- ) */ #define V4_REQ_UNFREEZE_WORD (-22) /* ( baddr u -- ) */ #define V4_REQ_FROZEN (-23) /* ( baddr u -- flag ) */ #define V4_REQ_HEAT_STORE (-24) /* ( n baddr u -- ) */ #define V4_REQ_HEAT_FETCH (-25) /* ( baddr u -- n ) */ #define V4_REQ_Q_VARIANCE (-26) /* ( addr u -- q ) */ #define V4_REQ_INFER_SLOPE (-27) /* ( addr u -- q ) */ #define V4_REQ_INFER_WIDTH (-28) /* ( addr u -- n ) */ #define V4_REQ_INFER_RUN (-29) /* ( -- ) */ #define V4_REQ_INFER_WINDOW (-30) /* ( -- u ) */ #define V4_REQ_INFER_DECAY (-31) /* ( -- q ) */ #define V4_REQ_INFER_VARIANCE (-32) /* ( -- q ) */ #define V4_REQ_INFER_FIT (-33) /* ( -- q ) */ #define V4_REQ_INFER_EARLY (-34) /* ( -- flag ) */ 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; /* COMPUDYNAMICS ON THE OPCODES (#189 Phase 7, ruling 7; Captain Bob, 2026-11-14: every loop on the 32 F18 * opcodes as on the composed words, "and an easy revert if opcodes are too granular"): this is the revert -- * 0, and the opcodes are counted and charged to the Stadium as in Phase 1, and nothing more. */ #ifndef OPCODE_PHYSICS #define OPCODE_PHYSICS 1 #endif #define V4_MESH_OPCODES 32u typedef struct { v4_uheat_t heat; /* +1 a retirement, decayed by the ticks since (Loop #3) */ uint64_t last_decay_tick; uint16_t temperature_q8; uint8_t state_flags; /* V4_MESH_STATE_FROZEN */ uint8_t most_likely_next; /* pipelining: the opcode that most often comes next */ uint64_t most_likely_count, total_transitions; uint64_t transitions[V4_MESH_OPCODES]; } v4_mesh_opcode; /* a Rolling Window of Truth (v3's RollingWindowOfTruth): IDs in the order they came, 4096 of them, warm at * 1024, its effective size tuned (Loop #5) */ typedef struct { 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_mesh_window; 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): the words called, in order; and the opcodes retired (ruling 7) */ v4_mesh_window win, opwin; 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 opcodes' physics (ruling 7): their records, the one before, their decay slope, their inference */ v4_mesh_opcode op[V4_MESH_OPCODES]; uint32_t prev_op; /* V4_MESH_NO_WORD: none yet */ uint64_t op_decay_slope_q48; v4_inference_out op_inference; uint64_t op_inference_runs; /* 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