From a26f177ac67b4c469d8f46483e704cfa1c134608 Mon Sep 17 00:00:00 2001 From: rajames Date: Fri, 6 Nov 2026 15:55:37 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2 --- .claude/CLAUDE.md | 178 ++----------------------------- experiments/bare_metal/CLAUDE.md | 17 +++ v3/CLAUDE.md | 43 ++++++++ 3 files changed, 69 insertions(+), 169 deletions(-) create mode 100644 experiments/bare_metal/CLAUDE.md create mode 100644 v3/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index feccc74c..de0f9bc0 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -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 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 - **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. @@ -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 (`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` 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 @@ -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 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 @@ -379,99 +354,12 @@ it ships a raw disk image instead). No QEMU boot step in CI — artifact packagi ## 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:** - ✅ 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 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) ### 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 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 @@ -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 @@ -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 - `sbom.spdx` / `sbom.spdx.json` ---- - -## License - -See `./LICENSE` (Starship License 1.0, SPDX: `LicenseRef-Starship-1.0`). Commercial -license available. \ No newline at end of file diff --git a/experiments/bare_metal/CLAUDE.md b/experiments/bare_metal/CLAUDE.md new file mode 100644 index 00000000..6e4a6843 --- /dev/null +++ b/experiments/bare_metal/CLAUDE.md @@ -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. diff --git a/v3/CLAUDE.md b/v3/CLAUDE.md new file mode 100644 index 00000000..a9680202 --- /dev/null +++ b/v3/CLAUDE.md @@ -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.