Robert Allan JamesandClaude Sonnet 5
d9da82b065
Increment 2: WIREBIND user VMs (the ones that actually run FORTH work; console VMs are pure REPL proxies and never participate) register as Stage 3 switch-signal participants at attach, unregister at teardown. Slot table bumped 8 -> 16, matching messaging.4th's own VM-MAX -- a real, already-agreed ceiling, not an invented number. Added sk_vm_switch_signal_unregister() (compaction-based; Tripod VMs never needed removal, WIREBIND VMs cycle constantly and would otherwise exhaust the bounded table). Increment 3: implements the plan's own ratified option (A) for the async-detach UAF risk -- mark-and-defer via a new pending_reap flag on VMRegistryEntry, deliberately not a new VMState (capsule_vm_kill() already treats VM_STATE_DEAD as idempotent success, which would silently swallow a reap attempt; SWITCHED_OUT still accurately describes a tombstoned VM until the moment it's actually freed). unclean_detach() sets it when capsule_vm_kill() refuses a SWITCHED_OUT target; the Stage 3 checkpoint (vm_core.c) checks it before ever attempting to resume a pending switch target, and calls the new capsule_vm_force_reap() instead -- the one caller allowed to bypass capsule_vm_kill()'s own refusal, because it runs at the exact safe cooperative point the switcher itself controls. A new idle-tick sweep cleans up the WIREBIND live-table entry once the reap has actually happened. Verified clean on all 3 architectures (baseline regression -- no WIREBIND attach happens in a plain boot). The reap mechanism's own correctness under a genuinely parked context is verified separately, next, via a temporary deterministic probe. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BWpNjdwPtFLuVLaAq44L9K
264 lines
9.8 KiB
C
264 lines
9.8 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_run.h - DoE Run Logging (M7.1)
|
||
*
|
||
* Structures for logging capsule execution runs and VM births.
|
||
* Supports provenance tracking and experiment reproducibility.
|
||
*/
|
||
|
||
#ifndef STARKERNEL_CAPSULE_RUN_H
|
||
#define STARKERNEL_CAPSULE_RUN_H
|
||
|
||
#include <stddef.h>
|
||
#include <stdint.h>
|
||
#include "starkernel/vm_uuid.h" /* VMUuid -- FABRIC-0.md item 3.8 */
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/*===========================================================================
|
||
* Run Log Configuration
|
||
*===========================================================================*/
|
||
|
||
/** Phase A: Fixed ring buffer size */
|
||
#define CAPSULE_MAX_RUN_RECORDS 1024
|
||
|
||
/*===========================================================================
|
||
* Result Codes
|
||
*===========================================================================*/
|
||
|
||
typedef enum {
|
||
CAPSULE_RUN_OK = 0,
|
||
CAPSULE_RUN_ERR_INVALID, /* Invalid capsule */
|
||
CAPSULE_RUN_ERR_NOT_ELIGIBLE, /* Capsule not eligible for operation */
|
||
CAPSULE_RUN_ERR_EXEC_FAIL, /* Execution failed */
|
||
CAPSULE_RUN_ERR_HASH_MISMATCH, /* Post-run hash mismatch */
|
||
CAPSULE_RUN_ERR_STILLBORN, /* VM birth failed */
|
||
CAPSULE_RUN_ERR_FLEET_FULL, /* Outer Stadium at stadium_max_vm_count() (FABRIC-0.md item 1.5/2.2) */
|
||
} CapsuleRunResult;
|
||
|
||
/*===========================================================================
|
||
* CapsuleRunRecord - DoE Execution Log Entry
|
||
*===========================================================================*/
|
||
|
||
typedef struct {
|
||
uint64_t run_id; /* Sequential run identifier */
|
||
VMUuid vm_id; /* Which VM executed this (item 3.8) */
|
||
uint32_t reserved; /* Padding */
|
||
uint64_t capsule_id; /* Which capsule was run */
|
||
uint64_t capsule_hash; /* Hash at time of execution */
|
||
uint64_t pre_dict_hash; /* Dictionary state before run */
|
||
uint64_t post_dict_hash; /* Dictionary state after run */
|
||
uint64_t started_ns; /* Monotonic start time */
|
||
uint64_t ended_ns; /* Monotonic end time */
|
||
uint32_t result_code; /* CapsuleRunResult */
|
||
uint32_t flags; /* Run flags (mode, etc.) */
|
||
} CapsuleRunRecord;
|
||
|
||
/*===========================================================================
|
||
* VM Registry Entry
|
||
*===========================================================================*/
|
||
|
||
/** Maximum length of a VM symbolic name, including null terminator */
|
||
#define VM_NAME_MAX 64
|
||
|
||
typedef enum {
|
||
VM_STATE_EMBRYO = 0, /* Allocated but not yet born */
|
||
VM_STATE_LIVE, /* Successfully born, operational */
|
||
VM_STATE_STOPPED, /* Suspended — execution state saved. Set by
|
||
* the START word after STOP cleanly unwinds
|
||
* its C stack back to START's own frame: no
|
||
* live native frame remains, safe to free. */
|
||
VM_STATE_STILLBORN, /* Birth failed */
|
||
VM_STATE_DEAD, /* Terminated */
|
||
VM_STATE_SWITCHED_OUT, /* FABRIC-3.md §XXVIII, Stage 2 (2026-09-13):
|
||
* a live saved register/stack context is
|
||
* parked on this VM's own native stack
|
||
* (SWITCH-TO switched control away mid-
|
||
* execution). Deliberately distinct from
|
||
* VM_STATE_STOPPED -- that state means "no
|
||
* live native frame," this one means the
|
||
* opposite. KILL must refuse/defer here: the
|
||
* parked frame still points into vm->memory
|
||
* and the native stack, both of which a free
|
||
* would invalidate out from under it. */
|
||
} VMState;
|
||
|
||
typedef struct {
|
||
VMUuid vm_id; /* Assigned at birth, immutable (item 3.8) */
|
||
uint32_t state; /* VMState */
|
||
uint64_t birth_capsule_id; /* Which capsule birthed this VM */
|
||
uint64_t birth_timestamp_ns; /* When VM was born */
|
||
uint64_t birth_dict_hash; /* Dictionary hash after birth */
|
||
uint32_t flags; /* VM flags */
|
||
VMUuid parent_vm_id; /* Who birthed this VM. Set once at birth,
|
||
* never rewritten. Hera's own entry is
|
||
* self-referential (parent_vm_id == vm_id
|
||
* == vm_uuid_hera(), all-zero) -- the
|
||
* sentinel a heat-fanout walk up the
|
||
* parent chain stops at. */
|
||
void *vm_ptr; /* Pointer to live VM object; NULL when dead */
|
||
char name[VM_NAME_MAX]; /* Symbolic name, e.g. "Hera", "Hermes" */
|
||
size_t stadium_patron_cell; /* FABRIC-2.md SS B, VM-COOL: this VM's own
|
||
* Stadium cell index (STADIUM_CELL_NONE,
|
||
* i.e. (size_t)-1, if never admitted or
|
||
* already reaped) -- admitted into the VM's
|
||
* own quota at birth, explicitly evicted at
|
||
* KILL. Not Hera's; she is pinned and never
|
||
* reaches this field's purpose. */
|
||
int pending_reap; /* FABRIC-3.md §XXVIII Stage 4 (2026-09-14):
|
||
* set (capsule_vm_set_pending_reap()) when
|
||
* this VM is VM_STATE_SWITCHED_OUT and its
|
||
* owning WIREBIND device has physically
|
||
* detached -- capsule_vm_kill() correctly
|
||
* refuses to free a parked context, but the
|
||
* memory still needs reclaiming once it's
|
||
* no longer coming back. Deliberately a
|
||
* plain flag, not a new VMState: `state`
|
||
* still accurately reads SWITCHED_OUT (a
|
||
* live context genuinely is parked there)
|
||
* until the Stage 3 checkpoint
|
||
* (vm_core.c) notices this flag instead of
|
||
* attempting to resume it, and calls
|
||
* capsule_vm_force_reap() there instead --
|
||
* a safe point the switcher itself
|
||
* controls, not the async detach handler. */
|
||
} VMRegistryEntry;
|
||
|
||
/*===========================================================================
|
||
* Run Log Functions
|
||
*===========================================================================*/
|
||
|
||
/**
|
||
* capsule_run_log_init - Initialize run log
|
||
*/
|
||
void capsule_run_log_init(void);
|
||
|
||
/**
|
||
* capsule_run_log_record - Log a run record
|
||
*
|
||
* @param record Record to log
|
||
* @return Run ID assigned, or 0 on failure
|
||
*/
|
||
uint64_t capsule_run_log_record(const CapsuleRunRecord *record);
|
||
|
||
/**
|
||
* capsule_run_log_get - Get a run record by ID
|
||
*
|
||
* @param run_id Run ID to retrieve
|
||
* @param out Output record
|
||
* @return 0 on success, -1 if not found
|
||
*/
|
||
int capsule_run_log_get(uint64_t run_id, CapsuleRunRecord *out);
|
||
|
||
/**
|
||
* capsule_run_log_count - Get number of logged runs
|
||
*/
|
||
uint32_t capsule_run_log_count(void);
|
||
|
||
/*===========================================================================
|
||
* Parity Logging
|
||
*===========================================================================*/
|
||
|
||
/**
|
||
* capsule_parity_log_birth - Log VM birth parity record
|
||
*
|
||
* Output format:
|
||
* PARITY:BIRTH vm_id=N capsule_id=X mode=p capsule_hash=H dict_hash=D
|
||
*/
|
||
void capsule_parity_log_birth(
|
||
VMUuid vm_id,
|
||
uint64_t capsule_id,
|
||
uint64_t capsule_hash,
|
||
uint64_t dict_hash
|
||
);
|
||
|
||
/**
|
||
* capsule_parity_log_birth_failed - Log failed birth
|
||
*
|
||
* Output format:
|
||
* PARITY:BIRTH_FAILED vm_id=N capsule_id=X error=E partial_dict_hash=H
|
||
*/
|
||
void capsule_parity_log_birth_failed(
|
||
VMUuid vm_id,
|
||
uint64_t capsule_id,
|
||
CapsuleRunResult error,
|
||
uint64_t partial_dict_hash
|
||
);
|
||
|
||
/**
|
||
* capsule_parity_log_run - Log DoE run parity record
|
||
*
|
||
* Output format:
|
||
* PARITY:RUN vm_id=N run_id=R capsule_id=X mode=e pre_dict=P post_dict=Q
|
||
*/
|
||
void capsule_parity_log_run(
|
||
VMUuid vm_id,
|
||
uint64_t run_id,
|
||
uint64_t capsule_id,
|
||
uint64_t pre_dict_hash,
|
||
uint64_t post_dict_hash
|
||
);
|
||
|
||
/**
|
||
* capsule_parity_log_mama_init - Log Mama init parity record
|
||
*
|
||
* Output format:
|
||
* PARITY:MAMA_INIT capsule_id=X mode=m capsule_hash=H dict_hash=D
|
||
*/
|
||
void capsule_parity_log_mama_init(
|
||
uint64_t capsule_id,
|
||
uint64_t capsule_hash,
|
||
uint64_t dict_hash
|
||
);
|
||
|
||
/**
|
||
* capsule_parity_log_kill - Log VM kill parity record
|
||
*
|
||
* Output format:
|
||
* PARITY:KILL vm_id=N name=X
|
||
*/
|
||
void capsule_parity_log_kill(
|
||
VMUuid vm_id,
|
||
const char *name
|
||
);
|
||
|
||
/**
|
||
* capsule_parity_set_output - Set output hooks for parity logging
|
||
*
|
||
* @param putc_fn Function to output a single character
|
||
* @param puts_fn Function to output a string
|
||
*/
|
||
void capsule_parity_set_output(
|
||
void (*putc_fn)(char),
|
||
void (*puts_fn)(const char *)
|
||
);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* STARKERNEL_CAPSULE_RUN_H */
|