LithosAnanake/.claude/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

> **Note:** There is also a `docs/CLAUDE.md` and `docs/formal/CLAUDE.md` — these govern the
> two-tier documentation-authoring system (`docs/formal/` = press-ready LaTeX for
> patent/SSRN/licensees, `docs/working/` = living drafts) and are still accurate; read them
> if you're touching documentation build tooling. This file at `.claude/CLAUDE.md` is the
> authoritative reference for everything else.

> **Superseded subsystem docs (Captain Bob, 2026-08-15):** `.claude/TRIPOD.md`,
> `.claude/HERMES.md`, `.claude/ARTEMIS.md`, and `.claude/CONSOLE.md` are all superseded —
> `FABRIC.md` (design history) and `FABRIC-2.md` (current/living, read this one first) are
> the sole authoritative source for Tripod/Hermes/Artemis/Console work now. The four
> subsystem docs remain in the repo as historical record only; each carries its own
> superseded-header pointing here. Do not treat them as current, do not read them for design
> authority, and do not cite them in place of `FABRIC.md`/`FABRIC-2.md`.

> **Scope:** This repo is LithosAnanke — the bare-metal UEFI kernel that boots StarForth
> directly on hardware. StarForth (the hosted FORTH-79 VM) has its own separate repository
> now. This repo vendors a full copy of the shared VM source (`src/vm.c`, `src/word_source/`,
> `capsules/`, `proof/`) because LithosAnanke embeds it as its execution engine — that vendored
> code is not a leftover or a second production target, it's load-bearing here. Kernel-specific
> code lives in `src/starkernel/`.

---

## Hard Rules — Captain Bob's Law

- **NEVER CREATE A BRANCH WITHOUT EXPLICIT PERMISSION FROM THE USER.** Work on the branch you are given or already on. Do not create feature branches, session branches, or any other branch unless the user explicitly asks. This applies every time, not just once per session — re-confirm before creating a branch even if one was created earlier in the same conversation.
- **NEVER STASH WITHOUT EXPLICIT PERMISSION.** `git stash` hides work and creates debt. If the working tree is dirty, report it and wait for instructions. Do not stash to work around a problem.
- **NEVER APPLY A FIX NOT EXPLICITLY REQUESTED.** If you identify a bug, report it. Do not fix it unless the user says to. Initiative on code changes causes damage.
- **USE A SUBVERSION-LIKE WORKFLOW.** Commit and push directly to the working branch (including `master` — this repo works directly on `master`; see below). No detours, no side branches, no pull requests unless explicitly requested.
- **AFTER ANY OUT-OF-BRANCH WORK** (switching branches, resetting, fetching, etc.) always return to the correct working branch and do a full `git fetch` + `git pull` to ensure the working tree is clean and current before continuing.
- **ALWAYS START CLEAN.** Before doing any work, verify `git status` is clean and the branch is the correct one. No surprises.
- **ANNOUNCE THE BRANCH** at the start of every session resumption. First line of output after context load: state the current branch and last commit.

### On the branch topology (post-split)

This repo used to be a `lithosananke` branch inside the combined StarForth/LithosAnanke
monorepo, diverging from a `master` that carried StarForth's hosted-VM production line.
That monorepo has been split into two separate repositories. **In this repo, `master` is now
the sole LithosAnanke production line — there is no `lithosananke` branch here, and none is
needed.** Don't look for one, and don't recreate the old two-branch framing when reasoning
about "which line am I on."

---

## Lessons Learned — Hard-Won in the Field

### On Tags
- **Tags are sacred ground.** Each tag has logs attached proving its state. When in doubt about the correct state of any file or branch, look at the tag first. `git show <tag>` and `git log <tag>` are your oracle.

### On the FORTH Dictionary
- **BIRTH, RUN, USE are primitives** — registered in C exactly like DUP, BYE, EXEC. Use `' BIRTH` directly. Never reach for FIND, never add conditionals, never rename them to `CAPSULE-BIRTH` or anything else.
- **FIND is a proven, tested, registered word. Never modify it.** The implementation is intentionally non-standard (parses from input stream). It is tested. Leave it alone.
- **Never modify a registered, tested word to "fix" it.** If something seems wrong with a word, the problem is almost certainly in the caller, not the word.
- **ACL policy belongs in `ACL.4th`, never in C.** No policy logic in `kernel_main.c`, no `vm_find_word` + field assignment for pinning. Use `' WORD ACL-PIN` in FORTH exactly as IMMEDIATE works.
- **`' BIRTH` in shared capsules breaks the hosted build** — BIRTH is kernel-only. Pin it in a kernel-specific capsule, not in `ACL.4th` which is shared. `capsules/ACL.4th` itself documents this exclusion in a comment (line ~64) — it deliberately omits `BIRTH`/`CAPSULE-BIRTH` even though this IS the kernel repo, because `ACL.4th` is meant to stay portable/shared.

### On the Embedded VM vs. the Kernel
- **`src/vm.c`, `include/vm.h`, `capsules/`, `src/word_source/` are the shared/vendored VM
  source.** They must compile and behave correctly both standalone (bare `make` here still
  produces a plain hosted `starforth` binary for quick local sanity checks) and embedded in
  the kernel build. Gate kernel-only code with `#ifdef __STARKERNEL__` or
  `#ifdef STARFORTH_ENABLE_VM`.
- **The vendored VM source has diverged from the standalone StarForth repo's copy** — it is
  not a byte-identical mirror. This repo's `src/word_source/` has 31 files (StarForth's has
  26); the extras (`defer_words.c`, `inference_words.c`, `lifecycle_words_hosted.c`,
  `log_words.c`, `q48_words.c`) are kernel-side-only additions. Don't assume a fix made in
  the StarForth repo needs to be, or even can be cleanly, ported here — check first.
  Similarly `src/starkernel/` here is real and load-bearing (~74 files across arch/boot/
  capsule/hal/memory/math/hash/pci/virtio/vm subtrees) — much larger than older docs claimed.
- **`src/*.c.bak` files (`vm.c.bak`, `doe_metrics.c.bak`, `inference_engine.c.bak`) are
  tracked in git at the `src/` top level.** This looks like repo hygiene debt, not
  intentional. Report it if it comes up; don't delete unprompted.
- **There is no `make test` target in this repo's hosted `Makefile`** (unlike the standalone
  StarForth repo, which has one). Don't invent one. The only acceptance authority for kernel
  changes is the three-arch QEMU boot (see below); bare `make` here is for quick compile
  sanity on the vendored source only, not test execution.
- **`INPUT_BUFFER_SIZE` must be 1025.** `vm_interpret()` is the shared dispatch path for BOTH
  interactive REPL lines AND block content from LOAD. LOAD copies up to 1024 bytes from block
  RAM and calls `vm_interpret()` directly; with a 256-byte cap, everything past byte 255 is
  silently dropped. 1025 = 1024 content bytes + 1 NUL terminator.

### On Working Style
- **When told to stop, stop immediately.** Do not make one more change. Do not commit "just to clean up". Stop.
- **Show the plan and wait for yes before destructive operations** (force push, reset --hard, branch deletion). The user will say yes explicitly when ready.
- **Do not over-engineer.** If the user says "BIRTH is a primitive", that is the complete specification. No conditionals, no fallbacks, no renamed variants.
- **Capsule subsystem wiring belongs in `sk_vm_bootstrap.c`**, not `kernel_main.c`. The bootstrap owns VM init; kernel_main owns hardware milestones.
- **Compose in FORTH first.** Before writing any new C primitive, exhaust the existing vocabulary. New C words are justified only for raw hardware access, atomics, syscalls, or freestanding kernel ops.

---

## Word-Level ACL System — Complete through Phase 7 (independently verified)

**Design doc:** `docs/03-architecture/word-acl/DESIGN.md` (this repo kept the old-style
`docs/03-architecture/` tree alongside the newer `docs/formal/`/`docs/working/` restructure —
both exist here; this path is still current for ACL specifically).

The word-level ACL system is fully implemented, including kernel parity. Key constraints:

- All policy logic in `ACL.4th` — no new C primitives for policy
- Four C fields: `acl_ttl` + `acl_allow` + `acl_mode` + `acl_pinned` in `DictEntry`
- Two VM flags: `emergency_console` (fault handler active) + `zuse_session` (superuser authenticated)
- `ACL.4th` is self-activating — `init.4th` only needs `S" ACL.4th" EXEC` (commented out by default)
- Pin (`ACL-PIN`) is one-way; inheritance clears pin, copies mode
- Two permanent console layers: emergency (`ok>`) and zuse (`zuse)ok>`)
- Superuser `zuse` defined by `capsules/zuse.4th`, loaded by `ACL.4th` at boot
- `emergency_console` bypass applies ONLY to bare `ok>` REPL — zuse sessions are subject to ACL

**Implementation phases:**
1. ✅ C Infrastructure — `DictEntry` fields + interpreter hook + `acl_recheck()`
2. ✅ `ACL.4th` — FORTH policy words + `ACL-INIT-PRIMITIVES` + self-activation
3. ✅ `capsules/zuse.4th` — bootstrap superuser skeleton; CA root placeholder in `ACL.4th`
4. ✅ `init.4th` opt-in toggle — `\ S" ACL.4th" EXEC` (comment out = no security)
5. ✅ POST tests + Isabelle/HOL proofs (5 `ACL_*.thy` theory files)
6. ✅ `EMERGENCY_CONSOLE_ENABLED` build flag + `vm_fault_handler` extension point
7. ✅ LithosAnanke kernel parity — **independently verified present in current `master`**:
   `acl_recheck()`/`zuse_session`/`emergency_console` wiring confirmed in
   `src/starkernel/vm/vm_core.c` (~lines 549, 608–633, 747–749, 906–908); the
   per-iteration `emergency_console = zuse_session ? 0 : 1` assignment confirmed in
   `src/starkernel/repl.c` (~lines 174, 219); the old `!vm->zuse_session` ACL-check bypass
   confirmed **absent** from `src/vm.c`. (The `feature/acl-rwt` branch this work was
   apparently done on is not traceable in `git log --all` — likely squash-merged without
   preserving the ref. The code is real and verified; the branch name is not.)
8. ⬜ PKI / thumbdrive — Ed25519 challenge-response; user minting by zuse. **This is the open
   item — pick up here next.**

**ACL-RWT DoE campaign (June 15–16 2026):**
- 3×3 Latin square: 3 seeds × amd64/aarch64/riscv64, 30 reps each
- Measured overhead: +0.0054%–+0.0088% across all 9 cells; CV = 0.000%
- Report confirmed to exist: `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf`
  (~2MB, with LaTeX source and figures) — patent support material

**Before writing or modifying any `.4th` capsule file**, read `experiments/bare_metal/README.md`
in full. The block namespace is shared across all loaded capsules; violations cause silent
word-definition collisions and corrupt the DoE. Block ranges (spot-checked against real
capsule files — accurate):
- `2048–2099` — `init.4th` only
- `2100–2199` — `doe.4th` only
- `3000–3999` — workload capsules
- `4000+` — user-defined capsules (`ACL.4th` uses 4000–4015, `zuse.4th` uses 4016–4018)
Each block header line counts against the 1024-byte limit. Any block exceeding 1024 bytes
is truncated silently at load time — verify with `wc -c` before committing.

---

## Project Overview

LithosAnanke ("stone" + "necessity") is a UEFI-bootable bare-metal microkernel that boots
directly from firmware, initializes memory and interrupts, then runs StarForth — a FORTH-79
virtual machine with a physics-driven adaptive runtime (Compudynamics) — as its sole
userspace runtime. No libc, no traditional OS underneath. It is the bare-metal target under
**StarshipOS**. (HISTORICAL: L4Re/Fiasco.OC was a supported platform target through mid-2026;
removed as an active target.)

**Current status: M7.1** — capsule birth protocol, Mama FORTH vocabulary, Tripod multi-VM
fleet (Hera/Hermes/Artemis), and word-level ACL (Phases 1–7) are live; POST at boot verifies
parity hash across amd64/aarch64/riscv64 with a 453-word Mama capsule dictionary.

**Key distinguishing features:**

- Embeds StarForth's physics-grounded self-adaptive runtime — 7 feedback loops + L8 Jacquard
  mode selector, formally proven deterministic (0.000% CV across 90 experimental runs)
- Content-addressed, immutable **capsules** as the primary organizational unit — no dynamic
  allocator in the traditional sense; identity is a content hash (XXHash64), mutation
  produces a new capsule
- **Tripod** — a named multi-VM fleet (Hera the Mama VM, two Hermes instances, Artemis)
  that births, runs, and re-births independently; verified booting live pre-REPL on all
  three architectures. See `.claude/TRIPOD.md`, `.claude/HERMES.md`, `.claude/ARTEMIS.md`.
- Word-level ACL security system with kernel parity (see above) — measured overhead three
  orders of magnitude below the measurement floor
- Kconfig-based build configuration (~40 discoverable symbols spanning physics/heartbeat/
  pipelining/kernel-only knobs), shared between the hosted and kernel build
- Patent pending (USPTO provisional, December 2025)

---

## Build Commands

### Kernel (primary)

```bash
# Build kernel for a given architecture (amd64 default)
make -f Makefile.starkernel ARCH=amd64
make -f Makefile.starkernel ARCH=aarch64
make -f Makefile.starkernel ARCH=riscv64

# Run in QEMU with OVMF
make -f Makefile.starkernel qemu
make -f Makefile.starkernel ARCH=aarch64 qemu
make -f Makefile.starkernel ARCH=riscv64 qemu

# Clean
make -f Makefile.starkernel clean
```

Output: `build/<arch>/kernel/starkernel_loader.efi` + `build/<arch>/kernel/starkernel_kernel.elf`.

Two independently tracked version strings flow into the generated `include/version.h`:
`VERSION` (`Makefile.starkernel` — the embedded StarForth engine version, currently `3.1.0`;
note this does **not** auto-sync with the standalone StarForth repo's own version) and
`LITHOS_VERSION` (`Makefile.starkernel` — the kernel version, currently `1.5.4`).

### Build configuration (Kconfig — real, wired, not vestigial)

Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared physics/heartbeat
family, etc.) is an optional Kconfig symbol defined across `Kconfig`, `Kconfig.arch`,
`Kconfig.heartbeat`, `Kconfig.kernel`, `Kconfig.physics`, `Kconfig.variant` (~40 symbols
total). `Makefile.starkernel` pulls its defaults from this system via a `kconfig_bool(...)`
mechanism — e.g. `STARFORTH_ENABLE_VM` defaults to **1** (confirmed at
`Makefile.starkernel:61`), meaning a plain `make -f Makefile.starkernel` already builds with
VM + capsule-birth + ACL active. A bare invocation uses the defaults it always has:

```bash
make -f Makefile.starkernel ARCH=amd64 menuconfig
make -f Makefile.starkernel ARCH=amd64 kernel_amd64_defconfig
```

### Hosted VM (vendored, for local sanity only)

```bash
make            # builds a standalone hosted `starforth` binary from the vendored source
make clean
```

There is **no `make test` here** — this is a compile-sanity convenience only, not a test
runner. Don't advertise it as one. The `bump-z`/`bump-y` targets (mirroring the standalone
StarForth repo) were removed 2026-08-15 — they referenced
`STARFORTH_VERSION_MAJOR`/`MINOR`/`PATCH`/`STARFORTH_VERSION_STRING` fields that never existed
in the actual generated `include/version.h` (which only has `STARFORTH_VERSION`,
`STARFORTH_ARCH`, `STARFORTH_TARGET`, `STARFORTH_TIMESTAMP`, `STARFORTH_VERSION_FULL`,
`LITHOS_VERSION`, `LITHOS_VERSION_STR`), so they could never have worked. Bump versions by hand-editing the `VERSION`/
`LITHOS_VERSION` variables in `Makefile.starkernel` instead. Report the broken targets if
asked, don't silently fix them.

### Important: Linker Configuration

The `fastest` target uses `-flto=auto -fuse-linker-plugin` instead of plain `-flto` to avoid
"ELF section name out of range" errors with large codebases.

---

## Running / Acceptance

### Kernel via QEMU

**ACCEPTANCE CRITERIA — non-negotiable:**
The ONLY valid acceptance test for any kernel change is booting all three
architectures in QEMU and capturing the serial log. There is no other test.
The vendored hosted `make` build (above) is NEVER used to validate kernel changes.

```bash
# Run in this exact order for every kernel change:
make -f Makefile.starkernel ARCH=amd64   clean qemu
make -f Makefile.starkernel ARCH=aarch64 clean qemu
make -f Makefile.starkernel ARCH=riscv64 clean qemu
```

**QEMU rule — non-negotiable:** Only ONE QEMU instance may run at a time, always in the
foreground (never backgrounded). All three instances use `accel=tcg` (software emulation);
concurrent runs compete for host CPU and corrupt the timing signal the DoE measures.
Run each architecture to completion before starting the next.

**Session keep-alive:** When running from a mobile device, ping the session every 15–20
minutes during a QEMU run or the session will idle out. amd64 is particularly slow under
TCG and is the most likely to outlast a silent interval. Captain Bob must stay engaged
during long runs (30-rep DoE ≈ 25–30 min per ISA).

Always pass `clean` before `qemu` — never build-only without clean.
Serial output is automatically captured to
`logs/YYYYMMDD-HHMMSS/<arch>/qemu-<arch>-YYYYMMDD-HHMMSS.log` — confirmed to be the real,
current convention (real timestamped log directories exist under `logs/`). These logs are
audit artifacts — they are committed to the repo. Do not delete them. There is also a
`logs2/` directory — a flatter, older archive predating or running parallel to the
timestamped convention (self-documented via its own README); not a contradiction, just a
second, less-structured log location.

Do not claim a change is accepted until all three architectures have booted
to `zuse)ok>` and their logs are present in `logs/`.

### CI

`.gitea/workflows/build.yml` runs three parallel jobs, each building a real bootable
artifact (not just compiling): `build-amd64-iso` (kernel build + El Torito ISO),
`build-aarch64-iso` (same, ARM boot file naming), `build-riscv64-img` (kernel build + raw
GPT/FAT32 disk image — riscv64 virt doesn't support El Torito ISO or `-bios` QEMU mode, so
it ships a raw disk image instead). No QEMU boot step in CI — artifact packaging only.

---

## Architecture

### Source Tree

```
src/
├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c   # Vendored VM core (see below)
├── repl.c, cli.c, io.c, log.c                                      # Vendored VM core
├── memory_management.c, dictionary_management.c, block_subsystem.c, blkio_*.c
├── stack_management.c, math_portable.c, profiler.c, compudynamics.c
├── heartbeat_export.c, ssm_jacquard.c, doe_metrics.c
├── physics_runtime.c, physics_hotwords_cache.c, physics_metadata.c,
│   physics_pipelining_metrics.c, physics_execution_hooks.c,
│   rolling_window_of_truth.c, inference_engine.c                   # 7 feedback loops
├── vm.c.bak, doe_metrics.c.bak, inference_engine.c.bak              # tracked but stale — flag, don't delete unprompted
│
├── word_source/                   # 31 files (vendored StarForth word_source PLUS
│   │                               #   kernel-side-only additions)
│   ├── (all of StarForth's 26: arithmetic, stack, control, defining, memory,
│   │    return_stack, double, logical, io, string, block, editor, format, system,
│   │    dictionary, dictionary_manipulation, dictionary_heat_diagnostic, vocabulary,
│   │    q48_16, starforth, acl, physics_benchmark, physics_diagnostic,
│   │    physics_freeze, physics_pipelining_diagnostic, mixed_arithmetic)
│   └── kernel-only additions: defer_words.c, inference_words.c,
│       lifecycle_words_hosted.c, log_words.c, q48_words.c
│
├── test_runner/                   # 23 test module files (matches StarForth's count)
│
├── platform/                      # Platform abstraction (hosted build)
│
└── starkernel/                    # ~74 files — the real, load-bearing kernel tree
    ├── kernel_main.c              # Kernel entry point (M0–M9 milestones)
    │                              #   NOTE: this file's own header comment claims
    │                              #   "M7: Not started" — that comment is STALE;
    │                              #   M7/M7.1/M7.pre logic is present and functional
    │                              #   (kernel_main.c ~lines 481–517). Don't propagate
    │                              #   the stale comment.
    ├── repl.c                     # Kernel REPL
    ├── arch/{amd64,aarch64,riscv64}/   # Per-arch: arch.c apic.c timer.c interrupts.c boot.S isr.S
    ├── boot/                      # uefi_loader.c elf_loader.c reloc_stub.c reloc.S
    ├── capsule/                   # capsule_birth.c capsule_run.c capsule_loader.c
    │                              #   capsule_find.c capsule_validate.c capsule_vm_hooks.c
    │                              #   capsule_vm_physics.c mama_forth_words.c
    ├── hal/                       # hal.c console.c memory.c host_services.c
    │                              #   framebuffer.c vt100.c font_8x16.c (VT100 console — live)
    ├── pci/pci.c                  # PCI enumeration
    ├── virtio/virtio_blk.c        # virtio block device (relates to roadmap's "M9 block
    │                              #   storage" item — implemented via virtio, not AHCI as
    │                              #   older docs describe; don't assume milestone-complete
    │                              #   from source presence alone, that hasn't been verified)
    ├── memory/                    # kmalloc.c pmm.c vmm.c
    ├── math/q48_16.c              # Q48.16 fixed-point (kernel build)
    ├── hash/xxhash64.c            # XXHash64 (content addressing)
    ├── doe_log.c
    └── vm/                        # Kernel VM subsystem
        ├── bootstrap/sk_vm_bootstrap.c
        ├── host/shim.c
        ├── vm_core.c vm_runtime.c vm_bootstrap.c q48_stubs.c
        ├── parity.c               # Birth/execution parity logging
        ├── arena.c                # Capsule arena allocator
        └── alloc_kernel.c
```

### Boot sequence

```
UEFI Firmware → uefi_loader.c (BOOTX64.EFI / BOOTAA64.EFI / BOOTRISCV64.EFI)
    ExitBootServices() → owns hardware
    BootInfo{memory map, ACPI, framebuffer}
    → kernel_main()
        M1: Console init (UART 16550 + framebuffer)
        M2: PMM (physical memory manager, bitmap)
        M3: VMM (4-level paging)
        M4: IDT + APIC/interrupt controller
        M5: Timer + heartbeat
        M6: kmalloc heap
        M7/M7.1: StarForth VM bootstrap + capsule birth (Tripod fleet) + word-level ACL
                 → "ok>" / "zuse)ok>" REPL
```

**Milestone status:**
- ✅ M0–M6: complete, v1.5.1-FINAL
- ✅ M7: StarForth VM integration + parity validation, complete
- 🔄 M7.1: capsule birth protocol · Mama FORTH vocabulary · Tripod fleet · word-level ACL —
  in progress (Phase 8 PKI is the open item, see ACL section above)
- Planned: M8 (REPL keyboard input), M9 (block storage — see the virtio note above; source
  exists but milestone-complete status not independently verified here)

### Capsule System

Capsules are immutable, content-addressed VM initialization payloads. A capsule
ID is its XXHash64 content hash — any mutation is detectable.

**Capsule types:**
- `(m) MAMA_INIT` — exactly one Mama VM initialization capsule
- `(p) PRODUCTION` — truth-bearing baby VM initializers
- `(e) EXPERIMENT` — DoE workload-only initializers

**Birth protocol:** locate by name → validate hash → allocate VM ID →
execute IDENTITY (capsule code) → execute PERSONALITY (block 1 from ramdrive)
→ log parity record (VM ID + capsule hash + dict hash).

**Capsule files:** `capsules/` has 23 `.4th` files (the `mkcapsule` build tool reports "26
capsule(s)" registered — some files apparently register more than one capsule entry; not
further investigated). Includes `init.4th`, `init-0.4th`–`init-9.4th`,
`init-l8-{stable,volatile,diverse,temporal,transition,omni}.4th`, plus `doe.4th`,
`doe-campaign.4th`, `lib.4th`, `process.4th`, `ACL.4th`, `zuse.4th` — more than the 17 older
docs claimed.

Tool `tools/mkcapsule.c` assembles `.4th` files into the binary capsule directory
format (`capsule_generated.c`) baked into the kernel image; it also regenerates
`capsules/BLOCK_MAP.md` as a manifest (expect that file to show as modified after any
kernel build — it's a generated artifact, not hand content).

### Physics-Driven Adaptive Runtime

Uses thermodynamic metaphors as modeling language (see `ONTOLOGY.md`):

1. **Loop #1 — Execution Heat** (`dictionary_heat_optimization.c`) — frequency counter per word
2. **Loop #2 — Rolling Window** (`rolling_window_of_truth.c`) — circular buffer, execution history
3. **Loop #3 — Linear Decay** — quiescent words lose heat over time
4. **Loop #4 — Pipelining** (`physics_pipelining_metrics.c`) — word-to-word transition prediction
5. **Loop #5 — Window Width Inference** (`inference_engine.c`) — Levene's test, binary chop
6. **Loop #6 — Decay Slope Inference** (`inference_engine.c`) — exponential regression
7. **Loop #7 — Adaptive Heartrate** (`HeartbeatState`) — background tick coordinator

**L8 Jacquard Mode Selector** (`ssm_jacquard.c`) — a 128-state, 7-bit loop-gate selector.
In this repo it now has a real per-VM heat channel into fleet-wide tuning (VM Fleet
Attractor physics — see `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md`),
replacing hardcoded compudynamics constants with a dynamically-inferred rate.

---

## Formal Verification

`proof/` contains 23 Isabelle/HOL theory files (same composition as the standalone StarForth
repo — 18 core VM/word-category theories + 5 ACL theories). Run `isabelle build -D proof/`
directly; neither `Makefile` nor `Makefile.starkernel` in this repo defines an
`isabelle-build`/`isabelle-check` target (unlike the standalone StarForth repo, which has a
broken one — this repo simply doesn't have the target at all, so there's nothing to
mistakenly invoke).

---

## Roadmap

`ROADMAP.md` and `docs/lithosananke/ROADMAP.md` contain real, LithosAnanke-specific phase
content (e.g. "PHASE 2: STARKERNEL (Months 3-5)", "StarKernel boots to 'ok' on QEMU ✅") —
not a copy of the standalone StarForth repo's roadmap. Prefer these when citing roadmap
status for kernel work.

---

## Code Standards

- **Strict ANSI C99** — No GNU extensions, no C++ features
- **Zero warnings target, with four explicit exceptions — corrected 2026-08-18, previous
  claim was wrong.** Build with `-Wall -Wextra -Werror`, but `Makefile.starkernel` carries
  `-Wno-error=unused-parameter -Wno-error=shift-negative-value -Wno-error=sign-compare
  -Wno-error=missing-field-initializers` — those four classes are enabled (still visible as
  warnings) but deliberately downgraded from fatal, everything else is. The previous version
  of this line claimed `-Wmissing-field-initializers` was isolated to one file
  (`vocabulary_words_test.c`) — that was never accurate; a full audit found it systemic
  across 20 files in `src/test_runner/modules/` (all missing the same later-added
  `TestCase.contract`/`WordTestSuite.suite_contract` trailing field, ~3,010 instances). Fixed
  in place across all 20 files (mechanical: added the missing `{0}` initializer, semantically
  a no-op since C99 already zero-fills unlisted trailing fields — the fix only silences the
  diagnostic). Verified clean on all three architectures. Remaining, still-open warnings as
  of the same audit: 26 `-Wunused-parameter` (scattered, several files, not yet fixed), 2
  `-Wsign-compare` (`control_words_test.c:127`), and 2 `-Wstringop-truncation` in
  `tools/mkcapsule.c` — that last one is a separate host build tool compiled via plain `cc
  -Wall -Wextra -O2` (no `-Werror` at all), never actually gated by this policy in the first
  place, genuinely unfixed rather than exempted.
- **No hidden state** — All VM state is explicit in the `VM` struct
- **Platform-agnostic** — Kernel code gated by `__STARKERNEL__` and `STARFORTH_ENABLE_VM`
- **Content-addressed immutability** — Capsule ID = content hash; any mutation is detectable

---

## Important Conventions

- Stack values are VM offsets (`vaddr_t`), not C pointers — use `VM_ADDR()` / `CELL()`
- `WORD_IMMEDIATE` flag = executes during compilation (not deferred)
- `WORD_PINNED` = execution heat cannot decay to zero
- `WORD_FROZEN` = execution heat does not decay at all
- `STRICT_PTR=1` enforces bounds checking (disable only for benchmarking)
- Kernel code uses `#ifdef __STARKERNEL__`; VM-enabled path uses `#ifdef STARFORTH_ENABLE_VM`
- Never add `acl_*` fields to `DictEntry` beyond the four already present

---

## Critical Implementation Details

### DoE CSV Output Suppression

Intentionally suppressed as of 2025-12-08. See `src/main.c:390-396`:
- Metrics still collected via `metrics_from_vm()`
- CSV row was redundant with internal VM metrics
- To re-enable: add a `--csv-export` flag or write to a file

### Heartbeat Instrumentation (Planned)

`HeartbeatTickSnapshot` and `tick_buffer` are declared in `include/vm.h`,
but `heartbeat_export_csv()` is **not yet implemented**.

### Word Statistics Output

`WORD-ENTROPY` prints execution heat statistics to stdout. Kept enabled in DoE mode
intentionally (diagnostic value outweighs noise cost).

### StarKernel M7 Parity

`parity.c` logs every VM birth and execution with: VM ID, capsule hash, dictionary hash.
This enables offline determinism verification — an independent system can load the same
capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance.

---

## Documentation

Key files (this repo has both the older `docs/03-architecture/` tree — still current for
ACL/Tripod specifically — and the newer restructured `docs/formal/`/`docs/working/`/
`docs/patent/` trees, plus a repo-specific `docs/lithosananke/` tree):

- `README.md` — project overview and quick start
- `docs/lithosananke/SYSTEM_ARCHITECTURE.md` — full kernel + VM design
- `docs/lithosananke/hal/` — HAL reference
- `docs/lithosananke/M7.1.md` — capsule birth protocol design
- `docs/lithosananke/ROADMAP.md` — milestone plan through self-hosting
- `docs/lithosananke/hosted-acceptance-test/README.md` — the hosted-VM acceptance test
  writeup referenced from the standalone StarForth repo's own docs
- `docs/03-architecture/tripod/`, `docs/03-architecture/word-acl/DESIGN.md`
- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` — Tripod/Hermes/Artemis
  physics + build-system history
- `docs/working/architecture/getting-started/DEVELOPER.md` — dev setup, Kconfig reference
- `ROADMAP.md`, `CHANGELOG.md`
- `experiments/bare_metal/README.md` — **mandatory read before touching capsules** (block
  namespace rules, see ACL section above)
- `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf` — DoE campaign report
- `sbom.spdx` / `sbom.spdx.json`

---

## License

See `./LICENSE` (Starship License 1.0, SPDX: `LicenseRef-Starship-1.0`). Commercial
license available.