admin/LithosAnanake

Fork 0

Files

T

Robert Allan James a5ed8c3d87 Initial commit — LithosAnanke kernel

2026-08-01 07:49:56 -04:00

15 KiB

Raw Blame History

M7.1: Init Capsule Architecture

Status: Design Complete Branch: lithosananke Prerequisite: M7 (VM Parity Validation)

The Immutable Law

Exactly ONE production INIT (p) defines a baby VM.

No INIT is shared implicitly. No base INIT exists. Any similarity between VMs is the result of deliberate reuse by Mama.

This rule is non-negotiable. Everything in this document exists to enforce it.

1. DOMAIN vs PERSONALITY

1.1 DOMAIN (Mama-only Concept)

DOMAIN is a construction and selection space that exists only in Mama FORTH.

DOMAIN is used to:

Classify kinds of VMs (e.g., HTTP, storage, control-plane)
Compose and curate block sets
Run experiments (e)
Decide which block set is promoted to production (p)

DOMAIN:

Is never executed by babies
Is never visible to babies
Is not part of VM truth
Leaves no runtime trace in the baby

DOMAIN answers: "What kind of thing is Mama trying to create?"

1.2 PERSONALITY (Baby-only Reality)

PERSONALITY is the result of Mama's work.

A baby VM receives:

Exactly one (p) INIT
Executed exactly once at birth
Which defines its entire worldview

PERSONALITY:

Defines role, capabilities, invariants, vocabulary
Is immutable for the lifetime of the VM
Is the only truth the VM knows

PERSONALITY answers: "What am I?"

The baby has no knowledge of DOMAIN.

2. What is an Init Capsule?

An INIT capsule is not:

A shared base
A layered inheritance mechanism
A runtime-selectable script
A file or "boot code"

An INIT capsule is:

An ordered, immutable block sequence
A truth-bearing unit
Executed exactly once at VM birth
The sole source of identity for that VM
Referentially addressable — by content hash, not name
Observationally enumerable — Mama can list all capsules

Think: ROM image + provenance, not "config."

3. Architecture Decision

Option 1: One Big Memory Blob (Indexed)

Single contiguous arena with descriptor table + payload region.

Option 2: Individual Named Blobs

Separate addressable entities with symbolic names.

Decision: Hybrid

Physically: Option 1 — single arena, indexed by ID + offset Logically: Option 2 — capsules declared symbolically at build time

At runtime: symbols do not exist. Only facts (hashes, offsets, lengths).

Names lie. Hashes don't.

4. Data Structures

3.1 CapsuleDesc (64 bytes, cache-line aligned)

typedef struct {
    uint64_t magic;          /* 0x00: 'CAPS' | ver | hashAlg | reserved */
    uint64_t capsule_id;     /* 0x08: == content_hash (content-addressed) */
    uint64_t content_hash;   /* 0x10: hash of payload bytes */
    uint64_t offset;         /* 0x18: byte offset into payload arena */
    uint64_t length;         /* 0x20: payload length in bytes */
    uint32_t flags;          /* 0x28: state + policy bits */
    uint32_t owner_vm;       /* 0x2C: 0 = mama, else child VM ID */
    uint64_t birth_count;    /* 0x30: how many VMs born from this */
    uint64_t created_ns;     /* 0x38: monotonic timestamp at registration */
} CapsuleDesc;              /* 0x40 = 64 bytes */

3.2 Magic Field Packing

bits  0..31 : 'CAPS' (0x53504143 little-endian)
bits 32..39 : version (0 for v0)
bits 40..47 : hashAlg (enum CapsuleHashAlg)
bits 48..63 : reserved (zero)

3.3 CapsuleDirHeader

typedef struct {
    uint64_t magic;          /* 'CAPD' | ver | reserved */
    uint64_t arena_base;     /* phys or virt base of payload arena */
    uint64_t arena_size;     /* bytes */
    uint32_t desc_count;     /* current number of descriptors */
    uint32_t desc_capacity;  /* max (fixed at compile time for Phase A) */
    uint64_t dir_hash;       /* hash of descriptor table (for parity) */
} CapsuleDirHeader;

3.4 CapsuleRunRecord (for DoE logging)

typedef struct {
    uint64_t run_id;         /* sequential run identifier */
    uint32_t vm_id;          /* which VM executed this */
    uint32_t reserved;
    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;    /* execution result */
    uint32_t flags;          /* run flags (mode, etc.) */
} CapsuleRunRecord;

5. Content Addressing

Rule: capsule_id MUST be derived from content_hash.

For v0: capsule_id == content_hash (identity)

This ensures:

No sequential ID collisions
No "what's the salt" questions
Facts only, no oracles

6. Hash Algorithm

v0 Choice: xxHash64

Deterministic across hosted + kernel
Easy to implement freestanding
Fast
Good enough collision resistance for practice

Future-proofing: The hashAlg field in magic allows upgrade to SHA-256 or BLAKE3 without breaking history.

typedef enum {
    CAPSULE_HASH_XXHASH64 = 0,
    CAPSULE_HASH_SHA256   = 1,
    CAPSULE_HASH_BLAKE3   = 2,
} CapsuleHashAlg;

7. Flags

6.1 State Flags

#define CAPSULE_FLAG_ACTIVE       0x00000001  /* eligible for use */
#define CAPSULE_FLAG_REVOKED      0x00000002  /* birth-blocked forever */
#define CAPSULE_FLAG_DEPRECATED   0x00000004  /* eligible but discouraged */
#define CAPSULE_FLAG_PINNED       0x00000008  /* immune to GC */

6.2 Mode Flags (Production vs Experiment)

#define CAPSULE_FLAG_PRODUCTION   0x00000010  /* (p) truth-bearing */
#define CAPSULE_FLAG_EXPERIMENT   0x00000020  /* (e) workload only */

Invariant: Exactly one of (p) or (e) must be set.

#define CAPSULE_MODE_VALID(f) \
    ((((f) & CAPSULE_FLAG_PRODUCTION) != 0) ^ \
     (((f) & CAPSULE_FLAG_EXPERIMENT) != 0))

If both or neither are set: invalid capsule.

6.3 Revocation Semantics

A revoked capsule:

Remains enumerable (for audit)
Remains hashable (for provenance)
Is birth-blocked (mama refuses to bind it)

REVOKED always overrides ACTIVE.

8. Eligibility Rules

7.1 Birth Eligibility

A VM may be born only from a (p) capsule:

#define BIRTH_ELIGIBLE(flags) \
    (((flags) & CAPSULE_FLAG_PRODUCTION) && \
     ((flags) & CAPSULE_FLAG_ACTIVE) && \
     !((flags) & CAPSULE_FLAG_REVOKED))

If mama attempts to bind an (e) capsule at birth: hard refusal. No warnings. No fallback. No exceptions.

7.2 DoE/Runtime Eligibility

(e) capsules exist ONLY in Mama's domain. Baby VMs never see them, never execute them, never know they exist.

Mama may execute:

(e) capsules freely on herself (subject to policy)
(p) capsules only as birth capsules for babies (never as workloads)

This prevents the deadly mistake:

"Let's just rerun a production init as an experiment."

No. That turns truth into a variable.

7.3 Twins, Triplets, and Variants

Twins/Triplets/Variants are not special constructs. They are simply:

Multiple VMs born from the same (p) capsule (twins)
VMs born from similar (p) capsules (variants)

Any similarity between VMs is the result of:

Mama deliberately choosing the same (p) capsule for birth
Mama creating similar (p) capsules from shared block sets

There is no implicit inheritance. There is no base class. If two VMs share behavior, it's because Mama made them share it — not because of any hidden mechanism.

9. Parity Integration

Birth becomes a parity checkpoint:

PARITY:BIRTH vm_id=42 capsule_id=0xA13F mode=p capsule_hash=0x... dict_hash=0x...

DoE runs are logged separately:

PARITY:RUN vm_id=42 run_id=17 capsule_id=0xBEEF mode=e pre_dict=0x... post_dict=0x...

8.1 Truth Chain

For any VM, you can prove:

Which capsule created it (birth_capsule_id)
What the capsule contained (content_hash)
What dictionary state resulted (dict_hash)
What workloads were run after birth (CapsuleRunRecord log)

This is provenance. This is science. This is patent-grade.

10. Arena Placement

Phase A: Static (M7.1 - M8)

Descriptor table + payload arena live in .rodata or dedicated section
Built by tooling (or compiled-in)
Zero allocator dependency
Deterministic

/* In kernel image */
extern const CapsuleDirHeader capsule_directory;
extern const CapsuleDesc capsule_descriptors[];
extern const uint8_t capsule_arena[];

Phase B: Dynamic (Future)

Mama manages RAM arena
Runtime capsule registration
Optional persistence via memory-mapped block store

Key: CapsuleDesc doesn't care where bytes come from. It only cares about offset/length within "the arena."

11. Capacity

Phase A: Fixed Array

#define MAX_CAPSULES 256

CapsuleDirHeader includes desc_count and desc_capacity.

Growable arrays can come later without interface changes.

12. Who Writes Descriptors?

Phase A (Static)

Build tooling generates descriptors
Kernel boots with sealed capsule directory
Mama reads and binds, never writes

Phase B (Dynamic)

Mama appends new capsules to RAM arena
Only mama writes descriptors at runtime
Children never write descriptors, ever

13. VM Birth Protocol

Mama selects one production INIT (p) (by content hash)
Mama validates eligibility:
- CAPSULE_FLAG_PRODUCTION set
- CAPSULE_FLAG_ACTIVE set
- CAPSULE_FLAG_REVOKED not set
Mama allocates a new VM
INIT blocks are copied into the VM execution window (RAM blocks 0–2047)
INIT blocks are executed sequentially
Execution window is cleared
VM begins life with its PERSONALITY fully imprinted

Mama logs parity checkpoint:

PARITY:BIRTH vm_id=N capsule_id=X mode=p capsule_hash=H dict_hash=D

Mama increments capsule.birth_count

There is:

No shared INIT
No implicit base
No post-birth INIT execution
No runtime selection

The baby VM cannot:

Enumerate sibling capsules
Mutate the arena
Know its own capsule ID (optional: can query mama)
See or know about DOMAIN

14. DoE Execution Protocol

Mama selects workload capsule(s)
Mama validates eligibility:
- CAPSULE_FLAG_EXPERIMENT set
- CAPSULE_FLAG_ACTIVE set
- CAPSULE_FLAG_REVOKED not set
For each workload: a. Record pre_dict_hash b. Execute capsule on target VM c. Record post_dict_hash d. Log run record:
```
PARITY:RUN vm_id=N run_id=R capsule_id=X mode=e pre_dict=P post_dict=Q
```

DoE runs do not change the VM's birth truth. They are experiments, not identity.

15. Validation Function

typedef enum {
    CAPSULE_VALID = 0,
    CAPSULE_ERR_BAD_MAGIC,
    CAPSULE_ERR_BAD_VERSION,
    CAPSULE_ERR_BAD_HASH_ALG,
    CAPSULE_ERR_BOUNDS,
    CAPSULE_ERR_MODE_INVALID,
    CAPSULE_ERR_REVOKED_ACTIVE,
    CAPSULE_ERR_HASH_MISMATCH,
} CapsuleValidateResult;

CapsuleValidateResult capsule_validate(
    const CapsuleDesc *desc,
    const uint8_t *arena_base,
    uint64_t arena_size,
    int verify_hash  /* if true, recompute and compare */
);

Checks:

Magic signature and version
Hash algorithm is known
offset + length <= arena_size
Exactly one of (p)/(e) is set
REVOKED and ACTIVE not both set (REVOKED wins, but warn)
Optional: recompute hash and compare to content_hash

16. File Deliverables

File	Purpose
`include/starkernel/capsule.h`	CapsuleDesc, CapsuleDirHeader, flags, enums
`include/starkernel/capsule_run.h`	CapsuleRunRecord for DoE logging
`src/starkernel/capsule/capsule_validate.c`	Validation function
`src/starkernel/capsule/capsule_birth.c`	Birth protocol implementation
`src/starkernel/capsule/capsule_run.c`	DoE run logging

17. Summary

Principle	Enforcement
One truth per VM	Birth only accepts (p) capsules
DOMAIN is Mama-only	Construction concept, never visible to babies
PERSONALITY is baby-only	Executed INIT result, immutable identity
(e) capsules are Mama-only	Never executed by or visible to baby VMs
Content-addressed	`capsule_id == content_hash`
Names don't exist at runtime	Symbolic resolution at build time only
Revocation is permanent	REVOKED overrides ACTIVE, capsule stays enumerable
DoE doesn't change truth	Workloads are (e), logged separately
Mama sees all	Children see one capsule, read-only
No implicit sharing	Twins exist because Mama chose same capsule
Provenance is mandatory	PARITY:BIRTH and PARITY:RUN logged

18. Next Steps

Implement capsule.h — structs, flags, macros
Implement capsule_validate() — freestanding, no libc
Build tooling — generate static capsule directory from .4th files
Integrate with birth — extend sk_vm_bootstrap to accept capsule pointer
Parity logging — extend parity subsystem for BIRTH/RUN records

19. Gap Analysis (Resolved)

18.1 Payload Encoding

Decision: Raw UTF-8 FORTH source for Phase A.

Simple, debuggable, portable
Hash computed over raw bytes
Tokenization/compilation is premature optimization
Future phases may add CAPSULE_FLAG_TOKENIZED if needed

18.2 VM ID Allocation

Mama maintains a VM registry:

typedef struct {
    uint32_t vm_id;           /* assigned at birth, immutable */
    uint64_t birth_capsule_id;
    uint64_t birth_timestamp_ns;
    uint32_t state;           /* EMBRYO, LIVE, DEAD */
    uint32_t flags;
} VMRegistryEntry;

VM ID 0 is reserved (mama)
IDs are sequential (1, 2, 3, ...)
ID is never reused within a session

18.3 Birth Failure Handling

If init execution fails:

VM never transitions to LIVE state
VM is marked STILLBORN

Parity log records failure:

PARITY:BIRTH_FAILED vm_id=N capsule_id=X error=E partial_dict_hash=H

Partial state is not observable by other VMs
Mama may retry with same or different capsule

18.4 Run Log Storage

CapsuleRunRecord entries stored in:

Phase A: Fixed ring buffer in kernel BSS

#define MAX_RUN_RECORDS 1024
CapsuleRunRecord run_log[MAX_RUN_RECORDS];
uint32_t run_log_head;

Phase B: Append-only log, optionally persisted to block device

18.5 Atomicity of birth_count

Rule: Only mama increments birth_count.

Since mama is single-threaded (or serialized), no atomic operations needed in Phase A. Phase B (SMP mama) would require __atomic_fetch_add.

18.6 xxHash64 Implementation

Freestanding xxHash64 required:

include/starkernel/xxhash64.h
src/starkernel/hash/xxhash64.c

Public domain implementation (~200 lines). Must be:

No libc dependency
Deterministic across platforms
Seedable (seed = 0 for capsule hashing)

20. Implementation Checklist

include/starkernel/capsule.h — structs, flags, macros
include/starkernel/capsule_run.h — CapsuleRunRecord
include/starkernel/xxhash64.h — hash function
src/starkernel/hash/xxhash64.c — freestanding xxHash64
src/starkernel/capsule/capsule_validate.c — validation
src/starkernel/capsule/capsule_birth.c — birth protocol
src/starkernel/capsule/capsule_run.c — DoE run logging
tools/mkcapsule.c — build tool to generate capsule directory
Extend parity subsystem for BIRTH/BIRTH_FAILED/RUN records
VM registry in mama

This design will still make sense 20 years from now.

15 KiB Raw Blame History Unescape Escape