Files
LithosAnanke/v4/include/v4/mesh.h
T
Claude 00be537503 feat(v4, kernel): ONE adaptive heartbeat -- it paces itself on the Stadium's resident heat; every VM ticks on it, in lockstep
Captain Bob, 2026-11-17: "The adaptive heartbeat is its own thing ... It has its own independent RWOT and slope
provider. Only one output from the entire stadium is used as a load measurement for heart rate pacing. ... ONE
AS IN THE NUMBER 1 heartbeat (the adaptive one) runs the entire system." Ruled one at a time: the kernel's
heartbeat; resident heat its one input; held in POST; the Stadium charged as before today
(docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md, its first version kept as superseded).

- kernel/src/heartbeat.c, timer.h: heartbeat_pace_from(load) -- its own window of samples, its own slope
  provider (v4's inference arithmetic) every HEARTBEAT_PACE_EVERY samples, Loop #7 setting its own period
  (not stable 20% faster, stable 25% slower, 1/4..4x the 10 ms base). No source (v3's path): nothing runs.
- kernel/src/vm/stadium.c: stadium_resident_heat_total(), read only -- the one output it paces by.
- v4/system/mesh.c, mesh.h: the owner's clock read at every fabric step; each tick delivered, one by one, to
  every node present -- its heartbeat cycle run, active, idle or blocked alike. The tick by execution, the
  nodes' own Loop #7 and the heartrate callback are gone.
- kernel/src/v4/sk_v4.c: the clock gives the heartbeat's bottom half its turn; 0 until POST has ended.
- Tests first, each seen to fail (does not build): kernel/tests/test_heartbeat.c (11 checks),
  test_stadium_node.c (16), test_mesh_boot.c's lockstep checks. Seven Phase 7 checks that assumed the tick by
  execution now drive the test's heartbeat (ruled). POST 990/990 with v3's heat cases as written;
  mesh-boot 103, -on 112, -noop 100, san-mesh-boot 103, every v4 program at both widths, every kernel host
  test: 0 failures. The full `sanitize` target not run (it outlasts the foreground limit).

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

342 lines
20 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)
/* 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 ) */
/* v3's StarForth module: a word's execution heat by the address ' leaves, and the hottest */
#define V4_REQ_ENTROPY_FETCH (-35) /* ( addr -- n ): an error if addr is not a word's */
#define V4_REQ_ENTROPY_STORE (-36) /* ( n addr -- ) */
#define V4_REQ_RESET_ENTROPY (-37) /* ( -- ): every word's heat and temperature to 0 */
#define V4_REQ_HOT_COUNT (-38) /* ( -- n ): words with heat */
#define V4_REQ_HOT_NTH (-39) /* ( i -- xt heat ): the i-th hottest, as v3's TOP-WORDS orders them; 0 0 past them */
#define V4_REQ_XT_HEAT (-40) /* ( xt -- n ): a word's heat, 0 for what is not one */
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 ONE adaptive heartbeat's tick (the mesh's `tick`), the same on every
* node: every node advances one tick on each of its ticks, active or not
* (Captain Bob, 2026-11-17; plan 2026-11-17-one-adaptive-heartbeat) */
uint8_t ticking; /* not 0: the node's physics is set up, and it runs its cycle on each tick */
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;
/* 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) */
/* THE ONE ADAPTIVE HEARTBEAT's tick, as the owner has it (the kernel: its heartbeat's ticks since POST ended --
* held, 0, until then); 0: no heartbeat, the tick never moves. Read at every fabric step; each new tick is
* delivered to every node. The heartbeat paces itself (kernel/src/heartbeat.c): nothing here paces it. */
uint64_t (*clock)(void *self);
/* 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;
uint64_t tick; /* the last of the heartbeat's ticks delivered to every node */
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);
/* The tick, and so every node's, set to `tick`, no cycle run (for tests). */
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