admin/LithosAnanake
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix stale path references in .claude/CLAUDE.md

Browse Source 
Re-root stale  references to actual locations:  (shared engine/hosted) and  (LithosAnanke). Update source tree diagram accordingly, correct / counts, and remove the obsolete  bullet. Also fix include paths (, ).

Surgical correction only; no behavioral changes.
This commit is contained in:
rajames
2026-10-09 19:34:30 -04:00
parent 2e6262c91f
commit ab96a9f2be
1 changed files with 69 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+69 -57
View File
@@ -26,7 +26,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
> track a codebase it no longer describes would defeat its purpose as a record. > track a codebase it no longer describes would defeat its purpose as a record.
> **Tripod/kernel reshuffle — Phases 0–4 COMPLETE (2026-09-22); Phase 5 close-out in > **Tripod/kernel reshuffle — Phases 0–4 COMPLETE (2026-09-22); Phase 5 close-out in
> progress.** Hermes moved into the kernel as kernel-Hermes (`src/starkernel/vm/kernel_ > progress.** Hermes moved into the kernel as kernel-Hermes (`kernel/src/vm/kernel_
> hermes.c`); the Tripod is now **Hera / Artemis / Hestia** — **the Hermes VM, `capsules/ > hermes.c`); the Tripod is now **Hera / Artemis / Hestia** — **the Hermes VM, `capsules/
> hermes/init.4th`, and `capsules/common/messaging.4th` no longer exist in this codebase.** > hermes/init.4th`, and `capsules/common/messaging.4th` no longer exist in this codebase.**
> Design is complete and ruled in **`FABRIC-3.5.md`** (authoritative); execution is tracked in > Design is complete and ruled in **`FABRIC-3.5.md`** (authoritative); execution is tracked in
@@ -39,10 +39,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
> **Scope:** This repo is LithosAnanke — the bare-metal UEFI kernel that boots StarForth > **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 > 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/`, > now. This repo vendors a full copy of the shared VM source (`v3/src/vm.c`,
> `capsules/`, `proof/`) because LithosAnanke embeds it as its execution engine — that vendored > `v3/src/word_source/`, `capsules/`, `proof/`) because LithosAnanke embeds it as its
> code is not a leftover or a second production target, it's load-bearing here. Kernel-specific > execution engine — that vendored code is not a leftover or a second production target, it's
> code lives in `src/starkernel/`. > load-bearing here. Kernel-specific code lives in `kernel/src/`.
--- ---
@@ -81,21 +81,24 @@ about "which line am I on."
- **`' BIRTH` in shared capsules breaks the hosted build** — BIRTH is kernel-only. `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. - **`' BIRTH` in shared capsules breaks the hosted build** — BIRTH is kernel-only. `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 ### On the Embedded VM vs. the Kernel
- **`src/vm.c`, `include/vm.h`, `capsules/`, `src/word_source/` are the shared/vendored VM - **`v3/src/vm.c`, `v3/include/vm.h`, `capsules/`, `v3/src/word_source/` are the
source.** They must compile and behave correctly both standalone (bare `make` here still shared/vendored VM source.** They must compile and behave correctly both standalone (bare
produces a plain hosted `starforth` binary for quick local sanity checks) and embedded in `make` here still produces a plain hosted `starforth` binary for quick local sanity checks)
the kernel build. Gate kernel-only code with `#ifdef __STARKERNEL__` or and embedded in the kernel build. Gate kernel-only code with `#ifdef __STARKERNEL__` or
`#ifdef STARFORTH_ENABLE_VM`. `#ifdef STARFORTH_ENABLE_VM`.
- **The vendored VM source has diverged from the standalone StarForth repo's copy** — it is - **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 not a byte-identical mirror. This repo's `v3/src/word_source/` has 35 files (StarForth's
26); the extras (`defer_words.c`, `inference_words.c`, `lifecycle_words_hosted.c`, has 26; the count was 31 in an earlier revision of this file — corrected 2026-10-09); the
`log_words.c`, `q48_words.c`) are kernel-side-only additions. Don't assume a fix made in extras (`defer_words.c`, `inference_words.c`, `lifecycle_words_hosted.c`, `log_words.c`,
the StarForth repo needs to be, or even can be cleanly, ported here — check first. `q48_words.c`) are kernel-side-only additions, as are the console/input words
Similarly `src/starkernel/` here is real and load-bearing (~74 files across arch/boot/ (`framebuffer_words.c`, `keyboard_words.c`, `scroll_words.c`, `ttf_words.c`). Don't assume
a fix made in the StarForth repo needs to be, or even can be cleanly, ported here — check
first. Similarly `kernel/src/` 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. 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 - **The `*.c.bak` files are gone.** `vm.c.bak`, `doe_metrics.c.bak`, and
tracked in git at the `src/` top level.** This looks like repo hygiene debt, not `inference_engine.c.bak` — previously tracked at the `v3/src/` top level per an older revision
intentional. Report it if it comes up; don't delete unprompted. of this file — no longer exist anywhere in the tree (verified 2026-10-09 via `git ls-files`
and a filesystem scan). The hygiene debt was cleaned up; nothing to report.
- **There is no `make test` target in this repo's hosted `Makefile`** (unlike the standalone - **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 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 changes is the three-arch QEMU boot (see below); bare `make` here is for quick compile
@@ -140,10 +143,10 @@ The word-level ACL system is fully implemented, including kernel parity. Key con
6. ✅ `EMERGENCY_CONSOLE_ENABLED` build flag + `vm_fault_handler` extension point 6. ✅ `EMERGENCY_CONSOLE_ENABLED` build flag + `vm_fault_handler` extension point
7. ✅ LithosAnanke kernel parity — **independently verified present in current `master`**: 7. ✅ LithosAnanke kernel parity — **independently verified present in current `master`**:
`acl_recheck()`/`zuse_session`/`emergency_console` wiring confirmed in `acl_recheck()`/`zuse_session`/`emergency_console` wiring confirmed in
`src/starkernel/vm/vm_core.c` (~lines 549, 608–633, 747–749, 906–908); the `kernel/src/vm/vm_core.c` (~lines 549, 608–633, 747–749, 906–908); the
per-iteration `emergency_console = zuse_session ? 0 : 1` assignment confirmed in 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 `kernel/src/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 confirmed **absent** from `v3/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 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.) 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 8. ⬜ PKI / thumbdrive — Ed25519 challenge-response; user minting by zuse. **This is the open
@@ -209,7 +212,7 @@ changes with any new C word registration).
produces a new capsule produces a new capsule
- **Tripod** — a named multi-VM fleet (Hera the Mama VM, Artemis, Hestia) that births, runs, - **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. and re-births independently; verified booting live pre-REPL on all three architectures.
Hermes moved into the kernel as kernel-Hermes (`src/starkernel/vm/kernel_hermes.c`) and is 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 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`. `.claude/TRIPOD.md`/`.claude/HERMES.md`/`.claude/ARTEMIS.md`.
- Word-level ACL security system with kernel parity (see above) — measured overhead three - Word-level ACL security system with kernel parity (see above) — measured overhead three
@@ -342,41 +345,45 @@ it ships a raw disk image instead). No QEMU boot step in CI — artifact packagi
### Source Tree ### Source Tree
``` ```
src/ v3/ # hosted StarForth product AND the shared engine source
├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c # Vendored VM core (see below) ├── Makefile # hosted build (bare `make` at the repo root forwards here)
├── repl.c, cli.c, io.c, log.c # Vendored VM core ├── include/ # vm.h, version.h — the only VM headers (no top-level `include/`)
├── memory_management.c, dictionary_management.c, block_subsystem.c, blkio_*.c └── src/
├── stack_management.c, math_portable.c, profiler.c, compudynamics.c ├── main.c, vm.c, vm_api.c, vm_bootstrap.c, vm_debug.c, vm_time.c # Shared VM core (see below)
├── heartbeat_export.c, ssm_jacquard.c, doe_metrics.c ├── repl.c, cli.c, io.c, log.c # Shared VM core
├── physics_runtime.c, physics_hotwords_cache.c, physics_metadata.c, ├── memory_management.c, dictionary_management.c, block_subsystem.c, blkio_*.c
│ physics_pipelining_metrics.c, physics_execution_hooks.c, ├── stack_management.c, math_portable.c, profiler.c, compudynamics.c
│ rolling_window_of_truth.c, inference_engine.c # 7 feedback loops ├── heartbeat_export.c, ssm_jacquard.c, doe_metrics.c
├── vm.c.bak, doe_metrics.c.bak, inference_engine.c.bak # tracked but stale — flag, don't delete unprompted ├── physics_runtime.c, physics_hotwords_cache.c, physics_metadata.c,
│ │ physics_pipelining_metrics.c, physics_execution_hooks.c,
├── word_source/ # 31 files (vendored StarForth word_source PLUS │ rolling_window_of_truth.c, inference_engine.c # 7 feedback loops
│ │ # kernel-side-only additions) ├── word_source/ # 35 files (StarForth word_source PLUS
│ ├── (all of StarForth's 26: arithmetic, stack, control, defining, memory, │ │ # kernel-side-only additions)
│ │ return_stack, double, logical, io, string, block, editor, format, system, │ ├── (StarForth's ~26: arithmetic, stack, control, defining, memory,
│ │ dictionary, dictionary_manipulation, dictionary_heat_diagnostic, vocabulary, │ │ return_stack, double, logical, io, string, block, editor, format, system,
│ │ q48_16, starforth, acl, physics_benchmark, physics_diagnostic, │ │ dictionary, dictionary_manipulation, dictionary_heat_diagnostic, vocabulary,
│ │ physics_freeze, physics_pipelining_diagnostic, mixed_arithmetic) │ │ q48_16, starforth, acl, physics_benchmark, physics_diagnostic,
│ └── kernel-only additions: defer_words.c, inference_words.c, │ │ physics_freeze, physics_pipelining_diagnostic, mixed_arithmetic)
│ lifecycle_words_hosted.c, log_words.c, q48_words.c │ ├── kernel-side-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) │ └── console/input words: framebuffer_words.c, keyboard_words.c,
│ │ scroll_words.c, ttf_words.c
├── platform/ # Platform abstraction (hosted build) ├── test_runner/ # 26 test module files
│ └── platform/ # Platform abstraction (hosted build)
└── starkernel/ # ~74 files — the real, load-bearing kernel tree
├── kernel_main.c # Kernel entry point (M0–M9 milestones) kernel/ # LithosAnanke — the real, load-bearing kernel tree
│ # NOTE: this file's own header comment claims ├── Makefile # UEFI loader + kernel ELF + QEMU; embeds a subset of v3/src
│ # "M7: Not started" — that comment is STALE; ├── include/starkernel/ # kernel-only headers
│ # M7/M7.1/M7.pre logic is present and functional └── src/
│ # (kernel_main.c ~lines 481–517). Don't propagate ├── kernel_main.c # Kernel entry point (M0–M9 milestones)
│ # the stale comment. │ # 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 ├── repl.c # Kernel REPL
├── arch/{amd64,aarch64,riscv64}/ # Per-arch: arch.c apic.c timer.c interrupts.c boot.S isr.S ├── 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 ├── 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/ # capsule_birth.c capsule_run.c capsule_loader.c
│ # capsule_find.c capsule_validate.c capsule_vm_hooks.c │ # capsule_find.c capsule_validate.c capsule_vm_hooks.c
│ # capsule_vm_physics.c mama_forth_words.c │ # capsule_vm_physics.c mama_forth_words.c
@@ -391,10 +398,15 @@ src/
├── math/q48_16.c # Q48.16 fixed-point (kernel build) ├── math/q48_16.c # Q48.16 fixed-point (kernel build)
├── hash/xxhash64.c # XXHash64 (content addressing) ├── hash/xxhash64.c # XXHash64 (content addressing)
├── doe_log.c ├── 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 └── vm/ # Kernel VM subsystem
├── bootstrap/sk_vm_bootstrap.c ├── bootstrap/sk_vm_bootstrap.c
├── host/shim.c ├── host/shim.c
├── vm_core.c vm_runtime.c vm_bootstrap.c q48_stubs.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 ├── parity.c # Birth/execution parity logging
├── arena.c # Capsule arena allocator ├── arena.c # Capsule arena allocator
└── alloc_kernel.c └── alloc_kernel.c
@@ -503,7 +515,7 @@ status for kernel work.
warnings) but deliberately downgraded from fatal, everything else is. The previous version warnings) but deliberately downgraded from fatal, everything else is. The previous version
of this line claimed `-Wmissing-field-initializers` was isolated to one file 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 (`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 across 20 files in `v3/src/test_runner/modules/` (all missing the same later-added
`TestCase.contract`/`WordTestSuite.suite_contract` trailing field, ~3,010 instances). Fixed `TestCase.contract`/`WordTestSuite.suite_contract` trailing field, ~3,010 instances). Fixed
in place across all 20 files (mechanical: added the missing `{0}` initializer, semantically 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 a no-op since C99 already zero-fills unlisted trailing fields — the fix only silences the
@@ -535,14 +547,14 @@ status for kernel work.
### DoE CSV Output Suppression ### DoE CSV Output Suppression
Intentionally suppressed as of 2025-12-08. See `src/main.c:390-396`: Intentionally suppressed as of 2025-12-08. See `v3/src/main.c:390-396`:
- Metrics still collected via `metrics_from_vm()` - Metrics still collected via `metrics_from_vm()`
- CSV row was redundant with internal VM metrics - CSV row was redundant with internal VM metrics
- To re-enable: add a `--csv-export` flag or write to a file - To re-enable: add a `--csv-export` flag or write to a file
### Heartbeat Instrumentation (Planned) ### Heartbeat Instrumentation (Planned)
`HeartbeatTickSnapshot` and `tick_buffer` are declared in `include/vm.h`, `HeartbeatTickSnapshot` and `tick_buffer` are declared in `v3/include/vm.h`,
but `heartbeat_export_csv()` is **not yet implemented**. but `heartbeat_export_csv()` is **not yet implemented**.
### Word Statistics Output ### Word Statistics Output