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:
co-authored by
Claude Opus 5.5
parent
3b0fe81669
commit
a26f177ac6
+9
-169
@@ -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.
|
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user