admin/LithosAnanake
1
0
Fork 0
Code Issues Pull Requests Actions 13 Packages Projects Releases Wiki Activity

starkernel: item 3.8 -- VM identifiers as UUID/GUID

Browse Source 
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>
This commit is contained in:
Robert Allan James
2026-08-04 19:50:34 -04:00
co-authored by Claude Sonnet 5
parent ec2c97ef70
commit 9b305a5be7
20 changed files with 31751 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/starkernel/capsule/capsule_birth.c
+35 -24
View File
@@ -64,7 +64,9 @@ typedef struct vm_node {
static vm_node_t *vm_registry_head = (void *)0;
static uint32_t vm_registry_count = 0;
static uint32_t next_vm_id = 1; /* VM 0 reserved for Mama */
/* item 3.8: vm_id generation moved to vm_uuid_next()'s deterministic pool;
* the monotonic next_vm_id counter this replaced is gone. Hera's id is
* vm_uuid_hera() (fixed, reserved), not drawn from the pool. */
/* Copy at most VM_NAME_MAX-1 chars, always null-terminate */
static void vm_name_copy(char *dst, const char *src) {
@@ -84,10 +86,10 @@ static int vm_name_eq(const char *a, const char *b) {
}
/* Internal: return mutable pointer into registry node for vm_id */
static VMRegistryEntry *vm_find_entry_ptr(uint32_t vm_id) {
static VMRegistryEntry *vm_find_entry_ptr(VMUuid vm_id) {
vm_node_t *node = vm_registry_head;
while (node) {
if (node->entry.vm_id == vm_id) return &node->entry;
if (vm_uuid_equal(node->entry.vm_id, vm_id)) return &node->entry;
node = node->next;
}
return (void *)0;
@@ -109,19 +111,18 @@ void capsule_vm_registry_init(void *mama_vm_ptr) {
vm_registry_head = (void *)0;
vm_registry_count = 0;
next_vm_id = 1;
/* Mama is always VM 0 */
/* Mama is always the reserved, fixed vm_uuid_hera() id (item 3.8) */
mama = (vm_node_t *)kmalloc(sizeof(vm_node_t));
if (!mama) return;
mama->entry.vm_id = 0;
mama->entry.vm_id = vm_uuid_hera();
mama->entry.state = VM_STATE_LIVE;
mama->entry.birth_capsule_id = 0;
mama->entry.birth_timestamp_ns = 0;
mama->entry.birth_dict_hash = 0;
mama->entry.flags = 0;
mama->entry.parent_vm_id = 0; /* self-referential: Hera is the root */
mama->entry.parent_vm_id = vm_uuid_hera(); /* self-referential: Hera is the root */
mama->entry.vm_ptr = mama_vm_ptr;
for (i = 0; i < VM_NAME_MAX; i++) mama->entry.name[i] = '\0';
vm_name_copy(mama->entry.name, "Hera");
@@ -142,15 +143,20 @@ static VMRegistryEntry *vm_registry_alloc(void) {
node = (vm_node_t *)kmalloc(sizeof(vm_node_t));
if (!node) return (void *)0;
node->entry.vm_id = 0;
node->entry.vm_id = vm_uuid_none(); /* not yet assigned -- NOT
* vm_uuid_hera(): a
* newly-allocated embryo
* is never Hera (item
* 3.8 caught this exact
* collision class again) */
node->entry.state = VM_STATE_EMBRYO;
node->entry.birth_capsule_id = 0;
node->entry.birth_timestamp_ns = 0;
node->entry.birth_dict_hash = 0;
node->entry.flags = 0;
node->entry.parent_vm_id = 0; /* only Hera calls BIRTH today; see
* design doc's "explicitly out of
* scope" for making this dynamic */
node->entry.parent_vm_id = vm_uuid_hera(); /* only Hera calls BIRTH
* today; see design doc's "explicitly
* out of scope" for making this dynamic */
node->entry.vm_ptr = (void *)0;
for (i = 0; i < VM_NAME_MAX; i++) node->entry.name[i] = '\0';
node->next = (void *)0;
@@ -168,7 +174,7 @@ static VMRegistryEntry *vm_registry_alloc(void) {
return &node->entry;
}
int capsule_vm_registry_get(uint32_t vm_id, VMRegistryEntry *out) {
int capsule_vm_registry_get(VMUuid vm_id, VMRegistryEntry *out) {
VMRegistryEntry *entry;
if (!out) return -1;
entry = vm_find_entry_ptr(vm_id);
@@ -242,12 +248,12 @@ int capsule_vm_find_by_name_nocase(const char *name, VMRegistryEntry *out) {
return -1;
}
void capsule_vm_set_state(uint32_t vm_id, uint32_t state) {
void capsule_vm_set_state(VMUuid vm_id, uint32_t state) {
VMRegistryEntry *entry = vm_find_entry_ptr(vm_id);
if (entry) entry->state = state;
}
void capsule_vm_registry_set_name(uint32_t vm_id, const char *name) {
void capsule_vm_registry_set_name(VMUuid vm_id, const char *name) {
VMRegistryEntry *entry;
if (!name) return;
entry = vm_find_entry_ptr(vm_id);
@@ -277,7 +283,7 @@ static void dispatch_init_forth(void *vm_ctx) {
int capsule_vm_kill(const char *name) {
VMRegistryEntry *entry;
VM *vm;
uint32_t vm_id;
VMUuid vm_id;
uint32_t i;
if (!name) return -1;
@@ -303,7 +309,7 @@ int capsule_vm_kill(const char *name) {
}
/* Hera cannot be killed */
if (entry->vm_id == 0) {
if (vm_uuid_is_hera(entry->vm_id)) {
console_println("KILL: cannot kill Hera");
return -1;
}
@@ -341,11 +347,11 @@ int capsule_vm_kill(const char *name) {
void capsule_vm_kill_all_nonmama(void) {
vm_node_t *node;
VM *vm;
uint32_t vm_id;
VMUuid vm_id;
node = vm_registry_head;
while (node) {
if (node->entry.vm_id == 0 || node->entry.state == VM_STATE_DEAD) {
if (vm_uuid_is_hera(node->entry.vm_id) || node->entry.state == VM_STATE_DEAD) {
node = node->next;
continue;
}
@@ -402,13 +408,18 @@ CapsuleRunResult capsule_birth_mama(
post_dict_hash);
{
VMRegistryEntry *mama_entry = vm_find_entry_ptr(0);
VMRegistryEntry *mama_entry = vm_find_entry_ptr(vm_uuid_hera());
if (mama_entry) {
mama_entry->birth_capsule_id = mama_cap->capsule_id;
mama_entry->birth_dict_hash = post_dict_hash;
}
}
/* item 3.8: seed the vm_uuid pool now that the Mama capsule's content
* hash is known -- before any baby birth (none happens today, item 0.1),
* so the same capsule booted twice produces the same id sequence. */
vm_uuid_pool_init(mama_cap->content_hash);
return CAPSULE_RUN_OK;
}
@@ -422,7 +433,7 @@ CapsuleRunResult capsule_birth_baby(
const CapsuleDesc *descs,
const CapsuleNameEntry *names,
const uint8_t *arena,
uint32_t *out_vm_id,
VMUuid *out_vm_id,
void **out_vm_ctx)
{
if (!capsule_name || !dir || !descs || !names || !arena)
@@ -440,7 +451,7 @@ CapsuleRunResult capsule_birth_baby(
if (vr != CAPSULE_VALID) return CAPSULE_RUN_ERR_INVALID;
if (vm_registry_live_count() >= STADIUM_MAX_VM_COUNT) {
capsule_parity_log_birth_failed(0, cap->capsule_id,
capsule_parity_log_birth_failed(vm_uuid_none(), cap->capsule_id,
CAPSULE_RUN_ERR_FLEET_FULL, 0);
return CAPSULE_RUN_ERR_FLEET_FULL;
}
@@ -448,7 +459,7 @@ CapsuleRunResult capsule_birth_baby(
VMRegistryEntry *entry = vm_registry_alloc();
if (!entry) return CAPSULE_RUN_ERR_INVALID;
uint32_t vm_id = next_vm_id++;
VMUuid vm_id = vm_uuid_next();
entry->vm_id = vm_id;
entry->state = VM_STATE_EMBRYO;
entry->birth_capsule_id = cap->capsule_id;
@@ -533,7 +544,7 @@ CapsuleRunResult capsule_run_experiment(
CapsuleRunRecord record;
record.run_id = 0;
record.vm_id = 0;
record.vm_id = vm_uuid_hera(); /* experiments run on Mama's own VM */
record.reserved = 0;
record.capsule_id = cap->capsule_id;
record.capsule_hash = cap->content_hash;
@@ -546,7 +557,7 @@ CapsuleRunResult capsule_run_experiment(
uint64_t run_id = capsule_run_log_record(&record);
capsule_parity_log_run(0, run_id, cap->capsule_id, pre_dict_hash, post_dict_hash);
capsule_parity_log_run(vm_uuid_hera(), run_id, cap->capsule_id, pre_dict_hash, post_dict_hash);
if (out_run_id) *out_run_id = run_id;