docs(claude): trim .claude/CLAUDE.md; v3 and bare-metal notes load only where they apply

From /doctor's review: .claude/CLAUDE.md (40206 chars) was at the size
Claude Code warns about, and is read at the start of every session.
Now 30973.

Cut, as a session can read them from the tree itself: the Source Tree
listing, the boot-sequence diagram, "Key distinguishing features" and
License. The listing's two facts the code does not tell -- the stale
"M7: Not started" header in kernel_main.c, and virtio_blk.c not
meaning M9 is done -- are kept, as "Gotchas in the tree".

Moved, word for word, to files that load only when working there:
"Physics-Driven Adaptive Runtime" and "Critical Implementation
Details" to v3/CLAUDE.md; the superseded ACL-RWT DoE campaign
history to experiments/bare_metal/CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2
This commit is contained in:
rajames
2026-11-06 15:55:37 +00:00
co-authored by Claude Opus 5.5
parent 3b0fe81669
commit a26f177ac6
3 changed files with 69 additions and 169 deletions
+9 -169
View File
@@ -108,6 +108,14 @@ about "which line am I on."
RAM and calls `vm_interpret()` directly; with a 256-byte cap, everything past byte 255 is 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. silently dropped. 1025 = 1024 content bytes + 1 NUL terminator.
### Gotchas in the tree
- **`kernel/src/kernel_main.c`'s own header comment claims "M7: Not started" -- it is STALE.**
M7/M7.1/M7.pre logic is present and functional (`kernel_main.c` ~lines 481-517). Don't
propagate the stale comment.
- **`kernel/src/virtio/virtio_blk.c` relates to the 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.
### On Working Style ### On Working Style
- **When told to stop, stop immediately.** Do not make one more change. Do not commit "just to clean up". Stop. - **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. - **Show the plan and wait for yes before destructive operations** (force push, reset --hard, branch deletion). The user will say yes explicitly when ready.
@@ -154,21 +162,6 @@ The word-level ACL system is fully implemented, including kernel parity. Key con
Zuse eligibility list) was ruled not needed and removed, with the hole it carried Zuse eligibility list) was ruled not needed and removed, with the hole it carried
(`FABRIC-3.md` §XXXVII). (`FABRIC-3.md` §XXXVII).
**ACL-RWT DoE campaign (June 15–16 2026) — superseded, kept for historical record:**
- 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
- **Correction (found 2026-08-20/21, `FABRIC-1.md` §§M–T):** the "ACL-RWT" name itself was
wrong — the Rolling-Window-of-Truth mechanism it was named after was dead code, removed
2026-07-08 (`ACL-RECHECK-RW` was never reachable — `acl_recheck()` only ever looks up the
11-char `ACL-RECHECK`, never the 14-char `-RW` variant). What this campaign actually
measured was the live `ACL-TTL` mechanism under a misleading name, and at `-O0`, before
real compiler optimization landed. The corrected, current figure — same live mechanism,
correct name, re-run on the current substrate — is **+0.0603% ACL-TTL enforcement overhead,
architecture-independent, CV=0.000%** (`FABRIC-1.md` §T, memory
`project_acl_ttl_overhead_final.md`). Use that number, not the one above.
**Before writing or modifying any `.4th` capsule file**, read `experiments/bare_metal/README.md` **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 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 word-definition collisions and corrupt the DoE. Block ranges (spot-checked against real
@@ -205,24 +198,6 @@ hash across amd64/aarch64/riscv64 with a 526-word Mama capsule dictionary (word
2026-10-14, `FABRIC-3.md` §XXXVIII, hash `0x82f4ae7cb2e2d424`; verify against a live `PARITY:M7.1a word_count=` line before citing, it 2026-10-14, `FABRIC-3.md` §XXXVIII, hash `0x82f4ae7cb2e2d424`; verify against a live `PARITY:M7.1a word_count=` line before citing, it
changes with any new C word registration). changes with any new C word registration).
**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, Artemis, Hestia) that births, runs,
and re-births independently; verified booting live pre-REPL on all three architectures.
Hermes moved into the kernel as kernel-Hermes (`kernel/src/vm/kernel_hermes.c`) and is
no longer a Tripod VM — see `FABRIC-3.5.md`/`FABRIC-3.6.md`, not the archived
`.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 ## Build Commands
@@ -379,99 +354,12 @@ it ships a raw disk image instead). No QEMU boot step in CI — artifact packagi
## Architecture ## Architecture
### Source Tree
```
v3/ # hosted StarForth product AND the shared engine source
├── Makefile # hosted build (bare `make` at the repo root forwards here)
├── include/ # vm.h, version.h — the only VM headers (no top-level `include/`)
└── src/
├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c # Shared VM core (see below)
├── repl.c, cli.c, io.c, log.c # Shared 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
├── word_source/ # 35 files (StarForth word_source PLUS
│ │ # kernel-side-only additions)
│ ├── (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-side-only additions: defer_words.c, inference_words.c,
│ │ lifecycle_words_hosted.c, log_words.c, q48_words.c
│ └── console/input words: framebuffer_words.c, keyboard_words.c,
│ scroll_words.c, ttf_words.c
├── test_runner/ # 26 test module files
└── platform/ # Platform abstraction (hosted build)
kernel/ # LithosAnanke — the real, load-bearing kernel tree
├── Makefile # UEFI loader + kernel ELF + QEMU; embeds a subset of v3/src
├── include/starkernel/ # kernel-only headers
└── src/
├── 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 cmdline.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
├── artemis_sig.c homeblocks_sig.c heartbeat.c log_region.c # kernel services
├── crypto/ rng/ usb/ # PKI (Ed25519), entropy, USB
├── v4/sk_v4.c # bare-metal embed of the v4 engine (STARFORTH_V4=1)
└── vm/ # Kernel VM subsystem
├── bootstrap/sk_vm_bootstrap.c
├── host/shim.c
├── vm_core.c vm_runtime.c vm_bootstrap.c q48_stubs.c
├── kernel_hermes.c # kernel-Hermes (post-reshuffle)
├── session.c stadium.c stadium_blocks.c stadium_words.c switch.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:** **Milestone status:**
- ✅ M0–M6: complete, v1.5.1-FINAL - ✅ M0–M6: complete, v1.5.1-FINAL
- ✅ M7: StarForth VM integration + parity validation, complete - ✅ M7: StarForth VM integration + parity validation, complete
- 🔄 M7.1: capsule birth protocol · Mama FORTH vocabulary · Tripod fleet · word-level ACL — - 🔄 M7.1: capsule birth protocol · Mama FORTH vocabulary · Tripod fleet · word-level ACL —
in progress (Phase 8 PKI closed 2026-10-14, see ACL section above) in progress (Phase 8 PKI closed 2026-10-14, see ACL section above)
- Planned: M8 (REPL keyboard input), M9 (block storage — see the virtio note above; source - Planned: M8 (REPL keyboard input), M9 (block storage — see "Gotchas in the tree" above; source
exists but milestone-complete status not independently verified here) exists but milestone-complete status not independently verified here)
### Capsule System ### Capsule System
@@ -500,23 +388,6 @@ 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 `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). 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 ## Formal Verification
@@ -580,31 +451,6 @@ status for kernel work.
--- ---
## Critical Implementation Details
### DoE CSV Output Suppression
Intentionally suppressed as of 2025-12-08. See `v3/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 `v3/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 ## Documentation
@@ -633,9 +479,3 @@ current parts are in `docs/reference/`, the rest in `docs/working/archive/`.)
- `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf` -- DoE campaign report - `experiments/bare_metal/analysis/report/bare_metal_doe_report.pdf` -- DoE campaign report
- `sbom.spdx` / `sbom.spdx.json` - `sbom.spdx` / `sbom.spdx.json`
---
## License
See `./LICENSE` (Starship License 1.0, SPDX: `LicenseRef-Starship-1.0`). Commercial
license available.
+17
View File
@@ -0,0 +1,17 @@
# experiments/bare_metal/CLAUDE.md -- loaded when working under experiments/bare_metal/
# (moved from .claude/CLAUDE.md's word-level ACL section, 2026-11-06)
**ACL-RWT DoE campaign (June 15–16 2026) — superseded, kept for historical record:**
- 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
- **Correction (found 2026-08-20/21, `FABRIC-1.md` §§M–T):** the "ACL-RWT" name itself was
wrong — the Rolling-Window-of-Truth mechanism it was named after was dead code, removed
2026-07-08 (`ACL-RECHECK-RW` was never reachable — `acl_recheck()` only ever looks up the
11-char `ACL-RECHECK`, never the 14-char `-RW` variant). What this campaign actually
measured was the live `ACL-TTL` mechanism under a misleading name, and at `-O0`, before
real compiler optimization landed. The corrected, current figure — same live mechanism,
correct name, re-run on the current substrate — is **+0.0603% ACL-TTL enforcement overhead,
architecture-independent, CV=0.000%** (`FABRIC-1.md` §T, memory
`project_acl_ttl_overhead_final.md`). Use that number, not the one above.
+43
View File
@@ -0,0 +1,43 @@
# v3/CLAUDE.md -- loaded when working under v3/ (moved from .claude/CLAUDE.md, 2026-11-06)
## 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.
## Critical Implementation Details
### DoE CSV Output Suppression
Intentionally suppressed as of 2025-12-08. See `v3/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 `v3/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.