Robert Allan JamesandClaude Sonnet 5
9b305a5be7
Punch list §25 item 3.8 complete. Added after starting item 4.1
surfaced the need to thread a vm_id into stadium_admit()'s new quota
parameter; Captain Bob ruled UUID/GUID rather than keeping the
narrower uint32_t.
New VMUuid type (vm_uuid.h/vm_uuid.c): two uint64_t halves, RFC-4122-
shaped for logging. Not real randomness -- checked directly against
QEMU 10.2.1's actual CPU feature set: amd64 RDRAND and riscv64 Zkr are
both real, available features here; aarch64 has no RNG property on any
CPU model including "max" (verified exhaustively via QMP
query-cpu-model-expansion). Captain Bob ruled a uniform fallback
across all three ISAs rather than a per-architecture split.
Fallback is a deterministic PRNG (splitmix64) seeded from the Mama
capsule's content hash, pre-filling a 16-entry FIFO pool at boot and
refilling with another batch of the same stream when exhausted --
exactly the shape requested. Same capsule booted twice produces the
same id sequence, preserving the dict_hash reproducibility this
session has relied on throughout.
Hera keeps a fixed, reserved all-zero id, not drawn from the pool --
capsule_birth.c uses vm_id == 0 as a load-bearing sentinel in three
places (KILL protection x2, fleet heat-fanout parent-chain
terminator), found by reading before writing any code.
Two real sentinel-collision bugs caught before shipping, same class as
STADIUM_CONTAINS_NONE: vm_uuid_none() (all-ones, not all-zero) for
"not yet assigned"/"no VM" placeholders; confirmed item 3.7's quota
table already used an in_use boolean rather than a vm_id sentinel, so
no second collision was actually possible there -- the dead,
never-referenced STADIUM_QUOTA_SLOT_EMPTY macro was removed.
Blast radius larger than first scoped, flagged mid-work rather than
silently absorbed: capsule_vm_physics.c/.h (the fleet heat-transfer
layer item 2.1 modified earlier this session) has its own vm_id-keyed
node table and walks parent_vm_id chains through the same identity
space, so it needed the same change, plus its callers in
mama_forth_words.c and sk_vm_bootstrap.c.
One live FORTH word contract changed, by explicit ruling: CAPSULE-BIRTH
was ( capsule-id -- vm-id ), a single cell -- can't hold 128 bits.
Captain Bob picked pushing two cells ("there is doubles support in the
FORTH std word set anyway"): ( capsule-id -- vm-id-hi vm-id-lo ).
MAMA-VM-ID changed the same way: ( -- 0 0 ).
Verified: full (not standalone-file) kernel rebuild to catch cross-file
breakage given the size of this change -- it surfaced the
capsule_vm_physics.c blast radius a narrower check would have missed.
Three-architecture boot (amd64, aarch64, riscv64), all reaching ok>
with identical dict_hash=0x3d4e1daf289da94f matching the item-3.7
baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
175 lines
6.4 KiB
C
175 lines
6.4 KiB
C
/*
|
||
StarForth — Steady-State Virtual Machine Runtime
|
||
|
||
Copyright (c) 2023–2025 Robert A. James
|
||
All rights reserved.
|
||
|
||
This file is part of the StarForth project.
|
||
|
||
Licensed under the StarForth License, Version 1.0 (the "License");
|
||
you may not use this file except in compliance with the License.
|
||
|
||
You may obtain a copy of the License at:
|
||
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
|
||
|
||
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||
express or implied, including but not limited to the warranties of
|
||
merchantability, fitness for a particular purpose, and noninfringement.
|
||
|
||
See the License for the specific language governing permissions and
|
||
limitations under the License.
|
||
*/
|
||
|
||
/**
|
||
* capsule_vm_physics.h - Dynamic VM Fleet Physics
|
||
*
|
||
* Structural parallel to the word-level physics engine (execution heat,
|
||
* decay, rolling-window history, regression-inferred slope) applied to
|
||
* VMs instead of dictionary words. Kernel-only: no hosted-build
|
||
* equivalent, since the hosted build has no multi-VM fleet.
|
||
*
|
||
* sum(execution_heat_q48 for all LIVE VMs) == Q.1 is a conservation
|
||
* invariant, held by construction: every state change is a balanced
|
||
* transfer (see design doc VM-PHYSICS-DYNAMIC-FLEET-DESIGN-20260705.md).
|
||
*
|
||
* This is a passive observer of VM activity, never a driver of it —
|
||
* there is no scheduler here. Recording happens only at existing
|
||
* dispatch points (BIRTH, KILL, VM-EXEC, VM-CALL, VM-STEP).
|
||
*/
|
||
|
||
#ifndef STARKERNEL_CAPSULE_VM_PHYSICS_H
|
||
#define STARKERNEL_CAPSULE_VM_PHYSICS_H
|
||
|
||
#include <stdint.h>
|
||
#include "starkernel/vm_uuid.h" /* VMUuid -- FABRIC.md item 3.8 */
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/**
|
||
* vm_physics_init - Register a newly-born VM at zero heat
|
||
*
|
||
* Called from mama_word_birth once a VM reaches VM_STATE_LIVE. Starts
|
||
* at execution_heat_q48 = 0, so conservation holds trivially — no
|
||
* fan-out from existing VMs is needed.
|
||
*
|
||
* @param vm_id Registry VM ID assigned at birth
|
||
*/
|
||
void vm_physics_init(VMUuid vm_id);
|
||
|
||
/**
|
||
* vm_physics_retire - Remove a killed VM, returning its heat to Hera
|
||
*
|
||
* Called from mama_word_kill before the registry entry is torn down.
|
||
* The dying VM's entire remaining heat is transferred up its
|
||
* parent_vm_id chain (VMRegistryEntry, capsule_run.h) to the fleet's
|
||
* single structural root, Hera -- no division, no per-survivor
|
||
* weighting. The chain walk tolerates already-dead intermediate
|
||
* parents (a parent's own parent_vm_id was set once at its birth and
|
||
* never rewritten, so the walk continues through it).
|
||
*
|
||
* @param vm_id Registry VM ID of the VM being killed
|
||
*/
|
||
void vm_physics_retire(VMUuid vm_id);
|
||
|
||
/**
|
||
* vm_physics_touch - Record real dispatch activity against a VM
|
||
*
|
||
* Called from the three existing dispatch primitives (VM-EXEC, VM-CALL,
|
||
* VM-STEP) at the point they've already confirmed the target VM is
|
||
* live. Pulls heat from the rest of the fleet toward the touched VM
|
||
* (amount = elapsed_ticks * fleet_transfer_slope_q48 >> 16) and appends
|
||
* vm_id to the fleet's rolling touch-history window.
|
||
*
|
||
* Restated on the virtual tick (FABRIC.md item 2.1, 2026-08-04): no
|
||
* longer takes a wall-clock timestamp. Reads fleet_heartbeat_tick_count
|
||
* internally, which is execution-paced (advanced once per vm_tick()
|
||
* call, see vm_physics_heartbeat_tick), so the transfer this produces is
|
||
* a deterministic function of the execution stream, not of wall time.
|
||
*
|
||
* @param vm_id Registry VM ID being dispatched to
|
||
*/
|
||
void vm_physics_touch(VMUuid vm_id);
|
||
|
||
/**
|
||
* vm_physics_tick - Heartbeat-gated inference pass
|
||
*
|
||
* Mirrors vm_tick_inference_engine: when the fleet touch-history window
|
||
* is warm, replays it to re-fit fleet_transfer_slope_q48 via the same
|
||
* closed-form log-linear OLS regression used for word-level decay.
|
||
* Skips the update (does not substitute a default) when unwarmed or
|
||
* when fit quality is not usable.
|
||
*
|
||
* @param now_ns Current monotonic time in nanoseconds
|
||
*/
|
||
void vm_physics_tick(uint64_t now_ns);
|
||
|
||
/**
|
||
* vm_physics_heartbeat_tick - Fleet-wide heartbeat, gates vm_physics_tick()
|
||
*
|
||
* Call from every VM's own vm_tick(), not just Hera's. Increments a
|
||
* single fleet-wide tick counter (distinct from any VM's own per-VM
|
||
* HeartbeatState.tick_count) and calls vm_physics_tick() once that
|
||
* shared counter has advanced by HEARTBEAT_INFERENCE_FREQUENCY since
|
||
* the last fit.
|
||
*
|
||
* Fixes a real defect (VM-FLEET-ATTRACTOR-DESIGN-20260705.md rev k):
|
||
* gating this on Hera's own tick_count meant the inference pass almost
|
||
* never fired, because Hera-as-orchestrator mostly blocks on VM-EXEC/
|
||
* VM-CALL dispatch -- work that accrues to the *target* VM's own tick
|
||
* count, not hers. VM-PHYSICS-DYNAMIC-FLEET-DESIGN-20260705.md already
|
||
* specified the fix's direction: fleet_transfer_slope_q48 must be
|
||
* inferred "from aggregate fleet statistics... not one per VM" -- the
|
||
* same principle applies to the readiness signal that gates computing
|
||
* it, not just the regression's own input trajectory.
|
||
*
|
||
* @param now_ns Current monotonic time in nanoseconds (of whichever
|
||
* VM is calling; unused by vm_physics_tick() today)
|
||
*/
|
||
void vm_physics_heartbeat_tick(uint64_t now_ns);
|
||
|
||
/**
|
||
* vm_physics_fleet_heat_sum - Sum of execution_heat_q48 over all LIVE VMs
|
||
*
|
||
* Diagnostic / verification primitive. Should always read Q.1 (65536)
|
||
* if the conservation invariant holds.
|
||
*/
|
||
uint64_t vm_physics_fleet_heat_sum(void);
|
||
|
||
/**
|
||
* vm_physics_heat_of - Current execution_heat_q48 for one VM
|
||
*
|
||
* Transparency primitive (VM-FLEET-ATTRACTOR-DESIGN-20260705.md): the
|
||
* fleet-wide conservation invariant always reads Q.1 by construction, so
|
||
* it carries no information about how heat is actually distributed among
|
||
* live VMs. This is the per-VM fact that sum alone can't provide.
|
||
*
|
||
* @param vm_id Registry VM ID
|
||
* @return execution_heat_q48, or 0 if vm_id is unknown or not live
|
||
*/
|
||
uint64_t vm_physics_heat_of(VMUuid vm_id);
|
||
|
||
/**
|
||
* vm_physics_conserved - Conservation check
|
||
*
|
||
* @return 1 if |vm_physics_fleet_heat_sum() - Q.1| < epsilon, else 0
|
||
*/
|
||
int vm_physics_conserved(void);
|
||
|
||
/**
|
||
* vm_physics_status - Print a diagnostic status report
|
||
*
|
||
* Replaces K-STATUS/VM-STATUS. Reports fleet heat sum, conservation
|
||
* verdict, and the current fleet-wide inferred slope / fit quality /
|
||
* warm-up state -- the fleet-level analog of K-STATUS's per-VM report,
|
||
* adapted to a mechanism with no fixed VM count to enumerate.
|
||
*/
|
||
void vm_physics_status(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* STARKERNEL_CAPSULE_VM_PHYSICS_H */
|