Files
LithosAnanke/v4/include/v4/mesh.h
T
Claude 28ffed8f57 feat(v4): Phase 7 Task 4 -- the loops' words: v3's physics-freeze and inference words, F18 asking the kernel (#189)
capsules/v4/physics.4th, a kernel capsule on Hera (blocks 8200-8201): FREEZE-WORD UNFREEZE-WORD FROZEN?
HEAT! HEAT@ DECAY-RATE@ Q.VARIANCE INFER-DECAY-SLOPE INFER-WINDOW-WIDTH INFER-RUN INFER-WINDOW@ INFER-DECAY@
INFER-VARIANCE@ INFER-FIT@ INFER-EARLY-EXIT@ -- each a KERNEL-WORD, requests -21..-34 (v4/mesh.h), served by
the kernel on any node: "The compudynamics is stadium/fabric" (Captain Bob, 2026-11-14). A word is named as
v3's, the newest visible entry of CONTEXT then FORTH (the image gains CONTEXT's address); the arithmetic is
v4/system/inference.c, v3's to the bit. Q48.16 results are v4's doubles (low cell, then high). HEAT! starts
the word's decay from now. Test first with v3's POST cases in v4's address units: test_mesh_boot.c 86
checks, 95 on, 83 without opcode physics. docs/reference/v4-dictionary.tsv: the 15 words (392 live).
amd64 PASS, word_count=392. Not pushed (held to the end of Phase 7).

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

332 lines
19 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 ) */
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