UM/MOD is assembled exactly as DECOMPOSITION.md section 4 gives it and
needs no change: it is exact for every uhi < ud at 32- and 64-bit cells.
It is checked against q*d + r = uhi:ulo with r < d through v4_umul, so
no second C divider has to be trusted. Coverage: all edge-vector triples
with uhi < ud plus 20000 pseudo-random cases (top-bit, small and
near-maximum divisors), optimised and under ASan+UBSan. Two hand
mutations each fail more than 15000 checks.
New headroom probe: runs a word with marked cells under the canary and
under its return address and reports how many survive, since the D-2
circular stacks overwrite silently instead of faulting. Measured:
UM* 6 data cells under its args, 4 return entries under its return
UM/MOD 3 data cells under its args, 3 return entries under its return
DECOMPOSITION.md: UM/MOD marked executed, with its defined range and
stack limits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UM* as first written in DECOMPOSITION.md section 4 was exact only while
u1 <= 2^(n-2): plain +* loses the carry out of T and its shift keeps T's
sign bit, so the loop is exact only while S and T stay in
[-2^(n-2), 2^(n-2)).
The rewrite multiplies by s = u1 2/, which always lies in that range,
starting T at t0 = u2 2/ when u1 is odd, so the loop yields
hi:lo = t0 + s*u2 exactly. Then
u1*u2 = 2*(hi:lo) + c_lo + c_hi*2^n
c_lo = u1 & u2 & 1
c_hi = (u1<0 ? u2 : 0) + (u1 odd and u2<0 ? 1 : 0)
restores the halved-away bits and the unsigned reading of both top bits.
test_foundation.c runs the new definition against v4_umul over every
pair of the edge vectors plus 20000 pseudo-random pairs, at 32- and
64-bit cells, optimised and under ASan+UBSan. The two pinned failing
cases are now ordinary exactness checks. Two hand mutations of the
correction step each fail more than 10000 checks at both widths.
DECOMPOSITION.md: section 4 UM* replaced, D-3 ruling text updated.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
First code for StarForth v4 (JUSTIFICATION.md section 10, step 1): one node
of the 32-instruction core as a C99 model, with cell width as a build
parameter.
- Node: P, A, B, F18 circular stacks (10 and 9 deep, D-2), word-addressed
memory (D-1), 5% guard bands on every bounded list.
- Instruction word: six 5-bit slots in 32 bits at every cell width.
- Executor: all 32 opcodes of DECOMPOSITION.md 1.3. Cell arithmetic wraps
explicitly; no signed overflow or implementation-defined shift.
- Heat: per-opcode and per-call-target counters and the anti-clock, driven
by instruction retirement (1.4, D-6 interim).
- Slot packer and runner for tests, and a reference unsigned multiply in
plain C99 with no 128-bit type.
Tests run at 32- and 64-bit cells, and under ASan and UBSan. They cover
every opcode and execute the first section 4 definitions (NIP SWAP OR
NEGATE ROT 0< 0= 2DUP - U<) against the C operation each stands for.
UM* as written in section 4 is exact only while u1 <= 2^(n-2). Two known
failing cases are pinned in test_foundation.c until it is rewritten.
DECOMPOSITION.md: record D-9, the instruction word is 32 bits at every
cell width (ruled 2026-10-02).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Source tree reorganization:
- Move StarForth v3 engine to v3/ (src/, include/, Makefile)
- Move kernel to kernel/ (src/, include/, linker/, Makefile)
- Create v4/ skeleton for F18-ISA golden model (DECOMPOSITION.md, JUSTIFICATION.md)
- Move FABRIC-0..4.md to docs/fabric/
- Move ONTOLOGY.md and ROADMAP.md to docs/
Board infrastructure:
- Add boards/ser5/, boards/raspi/, boards/milkv/, boards/zynq7020/
- Each board has board.mk (ISA, CPU flags, boot recipe) and README.md
- Root Makefile becomes thin dispatcher: boot_image, all, clean, docs take TARGET
- make boot_image TARGET=SER5|RASPI|MILKV builds one GPT/MBR image per board
- ZYNQ7020 target exists but stops with clear error (ARMv7 port not built yet)
- scripts/mkdiskimage.sh builds disk images for all boards
Docs pipeline:
- docs/book/ with LaTeX master (main.tex) and Makefile
- pandoc converts Markdown to LaTeX at build time
- Two Lua filters: table-widths.lua (wide tables wrap), code-breaks.lua (inline code breaks)
- make docs builds single PDF (754 pages, 0 missing characters)
- make docs TARGET=<board> adds board appendix
- build/docs/<book|board>/meta.tex stamps git commit into PDF
Bug fixes:
- 42 include paths that only worked by accident now use correct relative paths
- clang-18 hardcode replaced with configurable CC variable (fixed aarch64 build)
- Pi 5: kernel_2712.img linked at 0x80000, .bss zeroed, memory reserved
- Doxyfile, .clang-tidy, README.md, Kconfig paths updated
Verified:
- Hosted v3 build passes 1012 tests, 0 failures
- SER5 image boots in QEMU (OVMF), POST passes, K exact (65536 = Q48_ONE)
- Milk-V image boots in QEMU (OpenSBI + U-Boot + bootefi), POST passes
- make clean TARGET=<board> removes only that board and its ISA objects
- make all builds all boards, hosted v3, and docs in one run
Co-authored-by: Junie <junie@jetbrains.com>
D-1 word addressing; D-2 F18 circular stacks (10/9 deep), hidden, so
DEPTH/PICK/ROLL/.S/SP@/SP! are retired everywhere and the DSP register is
dropped; D-3 plain F18 +* (UM* flagged for revision); D-5 host width
matches the host CPU; D-7 moot; D-8 signed Q48.16; D-4 and D-6 deferred
to the hosted-mesh step. Adds a note that every CAP definition must be
re-checked against the 10/9 stack depths.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BY9HMwK5Cetz3caBgHGyds
JUSTIFICATION.md records why v4 exists and the reasoning behind each
major design decision. DECOMPOSITION.md assigns every v3 C primitive a
fate on the 32-instruction F18-derived core.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BY9HMwK5Cetz3caBgHGyds
5.1: Isabelle/HOL pass (52 theories, clean) -- restated the boundary rather
than just citing the green build: proof/ scope was already entirely
outside this reshuffle's footprint (src/starkernel/, capsules/*.4th),
so the boundary is unchanged, not moved.
5.2: Documentation sweep. CLAUDE.md's stale WIP banner and Tripod fleet
description updated now that Phases 0-4 have actually landed (Hera/
Artemis/Hestia, no Hermes). MANIFEST.md rides the strip -- hermes/init.4th's
block table replaced with a deletion note, init.4th/doe-campaign.4th/
hestia/init.4th entries corrected to match the post-strip live files.
Confirmed the TRIPOD.md/0.1 contradiction was already resolved (2026-08-13).
Settled the superseded-docs call explicitly: archive as-is, do not rewrite.
Fixed experiments/bare_metal/README.md's block-size framing (still said
1024-byte budget; real rule is 64 chars x 16 lines). K-qualification
checked clean against the two living documents; full retroactive sweep
of the closed archival FABRIC corpus explicitly declined as disproportionate.
5.3: make sbom. Installed syft (user-local, approved). Found and fixed a
real Makefile bug while at it -- the sbom target hardcoded
--source-name StarForth, so DocumentName was wrong even after regenerating.
5.4: LITHOS_VERSION 2.0.0 -> 2.1.0, engine VERSION 3.1.0 -> 3.2.0 (minor,
per the dictionary-visible-only rule). Replaced the stale version-comment
block in Makefile.starkernel (had the odd/even LTS rule backwards) and
docs/lithosananke/ROADMAP.md's retired versioning-policy section with the
ratified ladder. Verified on all three architectures; riscv64's first pass
hit a transient virtio_blk timeout during boot-time Zuse genesis mint,
reported and confirmed non-reproducing on an immediate clean retry.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC.md -> FABRIC-0.md
FABRIC-2.md -> FABRIC-1.md
FABRIC-3.md -> FABRIC-2.md (the current/living document)
FABRIC-4.md unchanged (new #3 to follow separately)
Every cross-reference repo-wide updated to match, including doc-comment
citations inside kernel source (.c/.h) files -- done via an ordered
placeholder substitution (FABRIC-3.md->placeholder2, FABRIC-2.md->
placeholder1, FABRIC.md->placeholder0, then placeholders resolved to
final names) in a single pass per file to avoid double-shifting
already-renamed references.
One line in capsules/font.4th grew past the 64-char block-format limit
as a side effect of the longer filename; shortened it and reverified
with mkcapsule --lint (34/34 pass) before rebuilding.
Verified 3-arch boot to ok> (amd64/aarch64/riscv64, each in the
foreground) after the fix; logs and DoE CSVs from this session's
verification runs included per this repo's own audit-artifact
convention.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var
Clarified 2026-08-29 with the author: "no hurry" is wrong for #1 and #2.
- #1 (Hosted StarForth): the provisional will expire before conversion. Its
priority claim is time-boxed (provisional filed ~Dec 2025, window ~Dec
2026); if the non-provisional isn't filed claiming benefit before the
window lapses the priority is lost and the same subject matter can't be
re-staked by refiling thereafter. Hard clock regardless of December scope.
- #2 (full StarshipOS): the December deliverable that keeps the flagship
covered; pending counsel confirmation it may also be the conversion
vehicle for #1's provisional.
Open point to resolve: is #2 (or the December delivery) the conversion vehicle
for #1, or is #1 converted by a filing separate from #2? Decision record only;
no filing made. Authoritative form in ROADMAP.md; FABRIC-3.md tracks it.
The three-product split is treated as three patent applications, each matched
to a trademark (decided 2026-08-29):
- Patent 1 + mark StarForth -> hosted/interpreted runtime
- Patent 2 + marks StarshipOS (canonical spelling; noted as "StarshopOS"
in the decision words) + LithosAnanke -> full standalone OS
- Patent 3 + mark Compudynamics -> Zynq steady-state machinery
with sealed executions, HOL-proven, anchored by the physics-adaptive runtime
Flagged open for counsel (not assumed/filed): the repo already carries a
"Patent pending" USPTO provisional filed Dec 2025 for the Compudynamics
physics-adaptive runtime (docs/patent/). Whether patent 3 is a continuation/
refinement of that provisional, and whether the three product applications are
additive to or fold it in, must be reconciled. Records intent only; no legal
text drafted or filed. Authoritative form in ROADMAP.md; FABRIC-3.md tracks it.
The Zynq FPGA is not a fourth platform to port to — it is the pivot that
forces the project into three distinct products, each with its own host,
delivery, and proof character (decided 2026-08-29):
1. Hosted StarForth - the existing hosted/interpreted StarForth runtime
(3-arch acceptance-tested), delivered as a portable embedded runtime.
2. A full StarshipOS - the standalone OS built on LithosAnanke
(LithosAnanke -> StarshipOS), a self-booting OS on general silicon
(SER5/RasPi/Milk-V line).
3. Hardware steady-state machinery with sealed executions, HOL-proven -
the FPGA-native product: hardware-enforced sealed executions and
steady-state machinery machine-checked in a proof assistant (HOL);
delivery is the bitstream + HOL proof artifacts, not just an OS port.
The coupling is the point: product 3 is born on the FPGA, and its existence
is what cleanly separates 1 from 2 from 3. Product 1 ships hosted on an OS,
product 2 as an OS on general silicon, product 3 as proven hardware. Per-
product gates and the even-major line carrying the three as separate tracks
are scoped at v2.5.0 close / during the coloring-in phase. Complements, and
does not retract, the existing hardware bare-metal release policy.
Authoritative form in ROADMAP.md; FABRIC-3.md tracks the same horizon.
The next big milestone after the three-board bare-metal cut (v2.5.0) is
transferring the battle-tested amd64/aarch64/riscv64 story to a Zynq (AMD
Xilinx) FPGA SoC — configurable silicon with soft/hard CPU cores, PL fabric,
and a non-standard memory map, a genuinely larger step than any prior board
(expected on a new even-major line). Between v2.5.0 and the Zynq sits a
"coloring in" period: hardening that thickens the shape of what exists rather
than adding silicon (USB BOT/xHCI + block robustness, live-entropy and
Zuse-cert hardening on real ASICs, SMP/multi-core + IRQ routing from the HAL
notes, driver breadth) so the FPGA carries a production-honest shape forward.
Authoritative form in ROADMAP.md "Beyond v2.5.0"; FABRIC-3.md tracks the same
horizon in the post-release section and re-points G.6's Next at the
v2.2.0/v2.4.0/v2.5.0 cadence.
Real silicon arrives incrementally (Beelink SER5 in hand now; RasPi 5 + Milk-V
orderable around Mon 2026-08-31), so the hardware release is split per board
in hand, each an even-minor LTS point-in-time cut on the same line:
- v2.2.0 amd64 bare metal — Beelink SER5 (two 16GB sticks: one boots the
thumbdrive image, one mints a real Zuse user)
- v2.4.0 aarch64 bare metal — Raspberry Pi 5
- v2.5.0 all three bare — adds Milk-V (riscv64)
Each closes only when its board's items are proven live (boot to ok>, block-
fence Zuse true, backend entropy non-deterministic), never build-only.
Records the decision in the authoritative Release Versioning Policy
(docs/lithosananke/ROADMAP.md, "Board-by-board hardware rollout, decided
2026-08-29") and re-maps G.4/G.5 in FABRIC-3.md onto the new cadence, noting
v2.0.0 was cut (tag v2.0.0).
Full BOT-spec stall recovery per FABRIC-3.md F.14: new STALL_ERROR handling,
Reset Endpoint + Set TR Dequeue Pointer commands, CLEAR_FEATURE(ENDPOINT_HALT),
escalating to Bulk-Only Mass Storage Reset, capped retries
(XHCI_BOT_STALL_MAX_RECOVERIES=2) mirroring bot_tur_retries, clean terminal
failure via xhci_stall_fail().
Purely additive recovery path off the non-success transfer-event branch; the
normal path is unchanged. Builds clean on amd64/aarch64/riscv64. QEMU amd64
boot regression passes: zero stalls, BOT attach (READ CAPACITY10 -> READ10 ->
home-blocks) completes, normal-path xHCI trace identical to baseline. Live
stall injection is not provable under qemu-xhci; deferred to v2.5.0 hardware.
FABRIC-3.md G.1 documented; ROADMAP release-versioning policy folded in.
- docs/lithosananke/ROADMAP.md + M7.1.md: fixed stale "Branch: lithosananke"
(no such branch post-split), M7.1's "Design Complete" status (shipped
and live, redirected to FABRIC*.md), the M8/success-criteria
self-contradiction (OBSOLETE marking vs. unqualified live criterion),
and the stale AHCI/SATA claim for M9 (real implementation is
virtio_blk.c) -- also corrected BLOCK/BUFFER/UPDATE/FLUSH and block
device abstraction to [x] since both are confirmed live in
src/word_source/block_words.c and block_subsystem.c.
- Top-level ROADMAP.md: marked OBSOLETE (Captain Bob's call -- more than
"stale," the architecture/branch topology/terminology it describes no
longer exist), pointing to docs/lithosananke/ROADMAP.md and
FABRIC*.md for current status.
- docs/03-architecture/word-acl/DESIGN.md: fixed the ACL Phase 7
contradiction -- Phase 7 (LithosAnanke kernel parity) is independently
verified complete per .claude/CLAUDE.md, not "remaining"; removed the
stale lithosananke-branch-parity framing.
- VM-FLEET-ATTRACTOR-DESIGN-20260705.md's doe-campaign.4th "broken" claim:
investigated, ran SMOKE-CAMPAIGN live (completes clean, fleet heat
conserved) -- initially read as contradicting the claim, corrected
directly by Captain Bob: a clean execution trace doesn't disprove the
doc's actual argument (no real controlled-experimental-factor
mechanism). Confirmed accurate, left untouched.
- Isabelle/HOL pipeline-metrics model/C-struct mismatch: confirmed a real
proof-modeling gap (pm_last_accuracy_num/den has no analogue in the
real PipelineGlobalMetrics struct), not stale prose -- tracked here
rather than fixed, matching the .thy file's own scope boundary and
this project's standing caution that each Isabelle gap needs its own
subsystem model.
ACL-RWT DoE overhead re-measurement (the 6th item) intentionally not
started -- a full multi-architecture DoE campaign, not a doc-text fix,
holding for explicit confirmation given the scale.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
Disabled capsules/artemis/init.4th block 4170's ART-STRESS-CAMPAIGN -- its
own comment already said to revert to disabled once the K-invariant/
heartbeat verification run (item 4.6, closed earlier this session) was
done. This was the actual ~25-30 minute wall blocking interactive REPL
access, unrelated to any DoE mechanism.
Verified capsules/turtle.4th and capsules/sdk.4th live in a gtk-display
QEMU session: a red hexagon (6 100 POLYGON) and a green self-intersecting
star (100 STAR) both render with correct geometry and color. Screenshot in
evidence/amd64/.
Two real obstacles found and worked around along the way: CS's full-
framebuffer PLOT loop is far slower under TCG than previously documented
(closer to 20+ minutes than "slow"), and the kernel's heartbeat CSV logging
draws to the same console surface PLOT writes pixels to, overwriting
drawings within a fraction of a second unless silenced first with the
existing HB-OFF word. Both HOWTOs updated to record this.
Re-verified full three-arch acceptance boot (POST, DoE, parity) with the
ART-STRESS-CAMPAIGN change: 1012/0/0 and matching dict_hash on all three,
identical to the pre-change baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Loads turtle.4th and doe.4th, defines SDK-VERSION/SDK-HELP into an SDK
vocabulary, then calls FENCE once everything is loaded -- protecting the
base wordset and both cookbook capsules from FORGET. Kernel-only (EXEC
doesn't exist hosted), REPL-invoked via S" sdk.4th" EXEC, not part of
init.4th's boot sequence.
Verified before writing the capsule, not assumed: VOCABULARY/DEFINITIONS
does not actually scope word visibility in this interpreter -- vm_find_word
is a flat dictionary scan that never consults CONTEXT/CURRENT. Documented
plainly in the HOWTO so this isn't mistaken for namespace isolation later.
Block range 5109-5115 -- discovered along the way that user-block space is
capped at [2048, 5120) by mkcapsule, tighter than expected.
Verified: mkcapsule --lint clean, hosted-build trace runs SDK-HELP with
zero attributable VM errors, zero build warnings and identical 1012/0/0
POST results with matching dict_hash on all three kernel architectures.
HOWTO: docs/working/architecture/SDK-HOWTO-20260819.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Documents capsules/doe.4th's word-level DOE/EXEC-DOE entry points, CSV
format, and a verified-not-fixed caveat: the rep column doesn't track
actual repetition count when n-reps differs from the file's fixed N-REPS=30
constant (cfg is unaffected, only rep is misleading -- use run_id instead).
Also surfaces, but does not fix, a real staleness finding in
experiments/bare_metal/README.md: its documented L8-DOE/WL-HI/WL-LO
entry point and workload-dispatch mechanism does not exist anywhere in the
current capsule set. What "DoE" actually names today is three separate
mechanisms (doe.4th's word-level DOE, doe-campaign.4th's fleet-touch
campaigns, and artemis/init.4th's auto-run ART-STRESS-CAMPAIGN) -- this
HOWTO documents only the first, per explicit scope decision.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
First entry in the "cookbook" track: a demo capsule plus HOWTO, per the
sequencing laid out after the POST-coverage sweep. Built entirely in FORTH
on top of existing primitives -- fabric.4th's LINE (raster Bresenham) and
Q.SIN/Q.COS (Q48.16 trig), plus PLOT/FB-WIDTH/FB-HEIGHT -- no new C words.
FORWARD/BACK/LEFT/RIGHT/PENUP/PENDOWN/HOME/SETXY/SETHEADING/SETCOLOR give
the classic turtle model; POLYGON and STAR compose FORWARD+turn into simple
demo shapes; TURTLE-DEMO is a one-call visual smoke test. Not wired into
init.4th -- REPL-invoked only, matching the original idea's own scope.
Verified: mkcapsule --lint clean, hosted-build logic trace shows zero VM
errors and correct stack balance through the whole vocabulary, zero build
warnings and capsule loads cleanly on all three kernel architectures.
Visual pixel-level confirmation not yet done (needs an interactive
gtk-display session or driving past the ~25-30 min DoE-before-REPL wall),
documented as an open item in the HOWTO.
HOWTO: docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC-2.md item 5.2: both lemmas described as deliberately oops-flagged
(ROLL semantics, pipeline pm_wf invariant) were actually resolved
2026-08-13, same day, but FABRIC-2.md was never updated to match --
found during a docs-tree maintainability sweep. Corrected both, and
flagged a real untracked finding the pipeline fix surfaced: the Isabelle
model's accuracy num/den fraction pair doesn't correspond to the real
PipelineGlobalMetrics C struct at all. Also reconciled the theory-count
drift (53/54 mid-sweep numbers vs. the actual current 52, matching
proof/COVERAGE.md; proof/FINDINGS.md's own stale "53" flagged but not
fixed, out of this pass's scope).
docs/CLAUDE.md described a docs/Makefile with docs-formal/docs-working/
docs-index/docs-audit targets that doesn't exist anywhere in the tree.
The real build is docs/formal/Makefile with a completely different
target set (vol1/vol2/vol3/books/standalone/doxygen/clean) -- corrected
to match, and noted docs/INDEX.md has no automation and goes stale
between manual triage passes.
doxygen installed on this machine (was missing entirely, blocking the
API-reference build target).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CHANGELOG.md: new 2026-08-18 entry for today's work, plus a post-split
note explaining the branch-tag convention no longer applies (this repo
is now LithosAnanke-only, master as sole production line).
docs/lithosananke/ROADMAP.md: M7.1 section predates all the real
Tripod/Stadium/ACL work and was silently stale -- added a dated
redirect to FABRIC.md/FABRIC-2.md (matching the doc's own existing
pattern for the M8 section) rather than rewriting the whole section.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Only Hera writes the shared physical timer period now, gated by
vm_uuid_is_hera(vm->stadium_vm_id) in vm_tick_inference_engine(). Every
other VM's Loop #7 still adapts its own tick_target_ns as before, it just
no longer races to re-arm the one physical timer.
Includes 3-arch acceptance run (amd64/aarch64/riscv64, all booted clean
to ok>) and regenerated capsule/DoE artifacts.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
No document like this existed. Covers every core C-primitive FORTH word
(~470 registrations, 435 unique names after collapsing double-registered
ones) across all 36 src/word_source/*.c files plus
src/starkernel/capsule/mama_forth_words.c, organized into 34 category
sections matching the module order in register_forth79_words().
Each entry has word name, stack effect, and a one-sentence description
pulled from the doc comment above its implementation (or inferred where
none existed). Explicitly scoped to core primitives, not the ~330
FORTH-defined words inside .4th capsules -- those track individual
experiments/policies rather than the language itself and would need
their own document with a different update cadence.
Resolved, not just noted, the two real name collisions in the live
dictionary: [ ] STATE (dictionary_manipulation_words.c vs.
defining_words.c) and MOD /MOD */ */MOD (arithmetic_words.c vs.
mixed_arithmetic_words.c) -- checked actual registration order in
word_registry.c against the newest-first FIND search to determine which
implementation is actually reachable by name, rather than guessing.
Includes a "keeping this current" section documenting how to extend it
when words are added/removed/re-registered.
Also includes BLOCK_MAP.md/artemis.img/amd64.csv regenerated by builds
during this session, and a qemu boot log/DoE run that weren't from any
command in this session -- kept per repo convention, logs are audit
artifacts, not deleted.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC.md: renumber Artemis-last boundary 4.4 -> 4.5, add new 4.4 REPL item
(console visual design scoped this session -- CANVAS is one shared region
above the REPL strip, 640x480 scroll box centered within it, stroke font,
ANSI color, VM-identity + ACL-identity prompt segments, ~1000-line
scrollback), linked to repl-mockup.png.
ROADMAP.md: mark M8 section OBSOLETE -- replaced by FABRIC.md 4.4, kept for
history only.
ttf_words.c: TTF-TEXT's y argument now Cartesian (origin bottom-left of the
physical framebuffer, y increasing upward) instead of raw framebuffer
coordinates, translated once via fb_height() - y. Verified via amd64
screendump (logs/20260811-070418/), text renders right-side-up with
increasing y moving up the screen.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Not implementation -- documentation-only. M8 is tracked outside Stadium
(FABRIC.md §27.5), so this scoping lives in docs/lithosananke/ROADMAP.md
rather than as new FABRIC.md 4.3.x items.
Read the code before scoping, not assumed: the REPL already works
interactively over serial (sk_repl_run(), repl.c) with working
backspace/echo, and its on-screen text already renders via the existing
VT100 console (vt100_init()/font_8x16.c) independent of both the stroke
font and TrueType work -- neither was ever a REPL-strip prerequisite.
What's actually missing: sk_readline()'s console_getc() is
serial-UART-only, never touches KEY-EVENT (4.3.5f); KEY/?TERMINAL
(io_words.c) are dead stubs (KEY calls a getchar() hardcoded to EOF in
shim.c, ?TERMINAL always returns false).
Resolved design decisions: minimal US-QWERTY scancode->ASCII layout
with shift-state tracking (KEY-EVENT carries no modifier state today);
merge keyboard into console_getc()'s poll with serial staying a
co-equal source, not replaced (the entire acceptance/DoE harness
injects over the serial socket -- breaking that breaks make qemu,
DOE_INJECT, and every screendump technique used throughout 4.3.x); wire
KEY/?TERMINAL to the same merged source for FORTH-79 compliance;
CANVAS viewport sizing last, since it's presentation not input
plumbing. Extended scancodes, autorepeat-as-character-repeat, arrow-key
history explicitly out of scope for the "minimal" bar.
FABRIC.md's existing "not yet scoped" notes (4.3.5f's landing-point
note, 4.3.7f's closing note) updated to point here rather than
duplicating the design content.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The 30-replicate Artemis surface-stress campaign ran across all three
architectures: 30 reps x 50 trials x 3 arches = 4500 trials, zero failures.
The block_words.c stale-pointer cache-aliasing fix holds at scale.
Adds ART-STRESS-CAMPAIGN (block 4174) plus ART-STRESS-REP rep-tagging in
the CSV header/summary emitters, so a multi-replicate run is distinguishable
in the serial log. Campaign auto-invoke is left enabled in block 4170 for
now; Makefile.starkernel's QEMU boot deadlines stay at 12h to accommodate
long-running experiments.
Adds docs/working/architecture/ARTEMIS-COMPUDYNAMICS-IMPLEMENTATION-PLAN-20260802.md,
which documents the real gap this campaign exposed: block heat and message
heat do not decay at all. ART-TICK has zero call sites anywhere in the tree,
and HERMES-TICK has zero C call sites -- every caller is Hera poking it by
hand. BLK-HEAT@/MSG-HEAT@ read a number nothing ages, so blocks never reap
by cooling and message TTL never expires on its own.
The plan mirrors word-level physics as the reference model: lazy decay at
each access point against vm->heartbeat.tick_count, plus a bounded
background sweep with a resumable cursor (the existing answer to "sweeping
22,998 blocks per tick is too expensive"). Phase 1 Artemis, Phase 2 Hermes,
Phase 3 K participation deferred behind the Logical BAM.
The plan's preamble also records a wrong turn taken while investigating:
chasing VM-fleet heat instead of block heat, and building synthetic
Hera-driven VM-EXEC calls to force a physics reading -- which TRIPOD.md
prohibits outright. That work was reverted; the record is kept so it isn't
repeated.
Status: plan approved in shape, NOT final and NOT started. Six open
questions need answers and further design discussion is pending.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ran the amd64 kernel acceptance leg 5 times back to back as the punch
list's action item asked. dict_hash was byte-identical across every run
for every VM (Artemis, both Hermes instances, Hera/MAMA_INIT), and
matched aarch64/riscv64 exactly each time. Not jitter, and not
stable-but-different either.
The underlying mechanism the hypothesis pointed at is still real and
unchanged (capsule_dict_hash_hook() still folds execution_heat into the
hash; amd64 still runs its timer in RELATIVE mode under this
hypervisor) — but PARITY:MAMA_INIT and the child-VM PARITY:BIRTH lines
all print before the heartbeat starts, and heat only decays on
heartbeat ticks, so there's no window for the timer's non-determinism to
reach execution_heat before any of these hashes get computed. Most
likely the original 2026-07-24 observation was a one-off (loaded host
machine, coincidental timing), not a real gap.
No code change. No amendment to CLAUDE.md's acceptance criteria needed —
"identical dict_hash across all three architectures" holds up under
repeated testing. Closure note added to the punch list; the 5 verification
runs' logs and DoE CSVs are kept as the supporting evidence.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Resolves item #3 of docs/working/archive/session-logs/2026-07-24-punch-list.md
("riscv64 hosted build isn't reachable via plain make"), the last open
item from that list. Decided against options (b) chasing GCC's riscv64
nanosleep-visibility failure at its root (undiagnosed, open-ended) and
(c) leaving it manual — instead wired the already-verified clang recipe
(commit 4485c38 / e287334) into the Makefile, mirroring the existing
rpi4-cross pattern.
Makefile: new riscv64-clang target. CFLAGS deliberately does not reuse
$(BASE_CFLAGS) (hardcodes -std=c99); clang needs -std=c11 -pthread here
instead. Registered in `make help` and .PHONY.
docs/lithosananke/hosted-acceptance-test/README.md: riscv64 section now
points at `make riscv64-clang` instead of the long manual invocation.
Updated Background section and commit list to reflect that all three
punch-list items touching this doc (#1 asm fix, #2 doc command, #3 make
target) are now resolved.
Verified: `make riscv64-clang` produces a binary with identical results
to the manual command it replaces (965 passed / 0 failed, "ALL
IMPLEMENTED TESTS PASSED!", "3 Goodbye!" for the piped acceptance script).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Addresses items #1 (partial) and #2 of
docs/working/archive/session-logs/2026-07-24-punch-list.md.
docs/lithosananke/hosted-acceptance-test/README.md:
- riscv64 leg used riscv64-linux-gnu-gcc, which fails to build this tree
(nanosleep visibility under -std=c99). Replaced with the working
clang-18 --target=riscv64-linux-gnu --sysroot=/usr/riscv64-linux-gnu
invocation, verified end-to-end.
- All three arch sections referenced a -c "<script>" flag that has never
existed in cli.c/main.c. Corrected to the working
`echo "..." | starforth -s` pattern, verified on all three architectures.
- Updated Prerequisites: qemu-user alone is sufficient (guest binaries are
static; qemu-user-static provides static *emulators*, not required here).
Source fixes (ported from the old pre-split monorepo's master, commit
4db9946a, where they were made but never carried over to this line):
- src/math_portable.c: `-100LL << 16` is UB (shifting a negative value)
under clang's -Wshift-negative-value; changed to `-(100LL << 16)`.
- src/physics_pipelining_metrics.c: removed dead q48_mul_q48()
(-Wunused-function under clang; GCC doesn't flag this by default).
- src/word_source/editor_words.c: removed dead set_scr() (same reason).
These three were required just to get the documented clang build to
compile at all. The punch list's higher-severity item — a genuine
SIGSEGV-causing register-reuse hazard in vm_pop_asm/vm_rpop_asm
(include/vm_asm_opt_riscv64.h) — is intentionally NOT included here; it's
a separate, more careful change and isn't required for this build to
succeed (latent only under clang; this repo's kernel build uses GCC).
Verified: all three hosted builds compile and run correctly (amd64
native, aarch64 via qemu-aarch64, riscv64 via qemu-riscv64), each
printing "3 Goodbye!" for the piped `1 2 + . BYE` script. All three
Makefile.starkernel builds (amd64/aarch64/riscv64) still compile cleanly
with these shared vendored-source changes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Write-up of the 2026-08-02 riscv64 boot crash investigation and fix
(commit 7366275), in the same style as docs/lithosananke/amd64-isr-fix.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
