rajames/LithosAnanke
1
1
Fork 0
Code Issues 42 Pull Requests Actions Packages Projects Releases Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+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
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.
experiments/bare_metal/CLAUDE.md
+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.
v3/CLAUDE.md
+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.