Files
LithosAnanke/v4/include/v4/mesh.h
T
Claude 3a70e824a2 feat(v4): Phase 7 Task 2b -- pipelining and the hot-words cache, built, off as v3 (#189)
Rulings, Captain Bob 2026-11-13: "Build a hot-words cache"; then, v3 being found to have both off
(ENABLE_PIPELINING, ENABLE_HOTWORDS_CACHE: n in Kconfig.physics and kernel/Makefile), "Built, off as v3".

- The kernel, at every call (mesh.c): v3's hit check, the transition, the likeliest next word (kept as each
  count rises; v3 scans 1024 a call -- the same word but in a tie v3's Q48.16 rounding makes), speculation
  at v3's thresholds into the node's cache; a word past heat 50 promoted at its call (v3 promotes at a
  lookup; v4's heat is the kernel's). Counters from the owner's heap, given back when a word goes.
- The node (dict.f18): (LOOKUP) tries (HOT)'s xts first, in F18, calling only C@; the kernel keeps it true
  (entries that go, or whose name is defined again, taken out). Empty unless the build has the cache.
- Tests: test_mesh_boot.c as built (57 checks) and with both on (mesh-boot-on, 65). v4 test: all pass.
- Reported, v3's own: when full, its promote takes the next slot without looking for the word there (a few
  hot words churn all 32 slots); its prefetch misses are never counted. Both reproduced.
- amd64 boots, RESULT: PASS, but 174 s and 181 s against 2a's 146 s, while on the host the mesh boot is no
  slower: being measured. Not pushed (held to the Phase 7 boundary).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-13 21:52:01 +00:00

216 lines
12 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"
#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 */
typedef struct {
uint64_t 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; 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 */
/* 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;
} 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) */
uint64_t (*ticks)(void); /* the heartbeat's tick count, read at each call (0: v4_mesh_set_tick's) */
/* 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);
/* The heartbeat's tick, for every node (v3's vm->heartbeat.tick_count): what decay is measured by. */
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