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

Compare commits

base: admin/LithosAnanake:66b26f823c81226967a54fba745c0e0dee2befe4
Branches Tags
admin/LithosAnanake:master admin/LithosAnanake:StarForth-v4.0.0 admin/LithosAnanake:claude/starshipos-tripod-kernel-reshuffle-itbjns
admin/LithosAnanake:v2.1.0 admin/LithosAnanake:v2.0.0
...
compare: admin/LithosAnanake:StarForth-v4.0.0
Branches Tags
admin/LithosAnanake:StarForth-v4.0.0 admin/LithosAnanake:master admin/LithosAnanake:claude/starshipos-tripod-kernel-reshuffle-itbjns
admin/LithosAnanake:v2.1.0 admin/LithosAnanake:v2.0.0
67 Commits
66b26f823c ... StarForth-v4.0.0
Author SHA1 Message Date
rajamesandClaude Opus 5.5 63434f3762 docs: FABRIC-4 §3 as a null hypothesis 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 20:41:55 -04:00
rajamesandClaude Opus 5.5 0195631315 docs: FABRIC-4 §3, information state over information moment (Captain Bob's theory) 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 20:41:25 -04:00
rajamesandClaude Opus 5.5 7ad02bf72f fix(v4): a killed node's children become Hera's; Review Focus 4 checked 
From the final review of MESH step 7.  NODE-KILL left children whose parent
was the dead number, so a node born later under it inherited authority over
them; they are re-parented to Hera.  After UNIT-KILL Hera no longer lists the
removed centre, and a later KILL completes (shown to fail with GONE-DOWN's
unlisting taken out).  test_manage 45/45 both widths; test_host_unit 127/127.

Acceptance: amd64, aarch64, riscv64 clean qemu: ok>, POST 538/538,
dict_hash=0x248b4edc47f4357e on all three; test-32 0 failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 20:03:45 -04:00
rajamesandClaude Opus 5.5 9382df69e5 docs(v4): MESH step 7 done -- a second unit, PAUSE, RESUME, KILL; acceptance 
MESH.md step 7: what was built, the tests, the (DOWN) mend, the traced
(LOST) finding; 9a.5: a centre killed mid-birth, and birth authority not
yet tied to identity.  v4/README.md: births follow v3.

Acceptance at this commit's code: amd64, aarch64, riscv64 clean qemu, v4:
ok>, POST 538/538, dict_hash=0x248b4edc47f4357e on all three; test-32 0
failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 17:46:49 -04:00
rajamesandClaude Opus 5.5 4be9f37c12 logs: acceptance of MESH step 7 so far (529ba0fc): three boots and test-32 
amd64, aarch64, riscv64, clean qemu, v4 as built: ok>, POST 538/538,
PARITY:V4_SYSTEM word_count=318 dict_hash=0x248b4edc47f4357e on all three
(the same as the hosted build); Q./ answers 0 21845.  make -C v4 test-32:
0 failures.  BLOCK_MAP.md regenerated: centre.4th, hera.4th's new blocks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 14:59:25 -04:00
rajamesandClaude Opus 5.5 529ba0fc48 fix(v4): (DOWN) calls the GONE hook and puts (ONE) back; the hand-on swept 
Found by the depth sweep: a hook that sent a message about another node
overwrote (ONE), which AWAIT reads after believing a GONE, so the wait went
on.  (DOWN) now calls the hook through (RUN) and restores (ONE).

AWAIT ended by a GONE that is handed on: works to 26 values and 21 calls
deep, then a stack error and nothing else, at both widths.  Removal sweep:
node 11 or 12 removed, or the wire cut, at every step: 0 wrong.  hosted
dict_hash=0x248b4edc47f4357e on all three ISAs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 14:42:54 -04:00
rajamesandClaude Opus 5.5 3506747d5a test(v4): a second unit while the first runs; PAUSE, RESUME; GONE down the graph (MESH.md 9a.6) 
test_host_unit: 125 checks.  Shown to fail with the GONE hook taken out of
centre.4th, and with the Hera-only check taken out of manage.c.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 13:08:43 -04:00
rajamesandClaude Opus 5.5 c88af25e1e feat(v4): centre.4th and hera.4th; every node's kernel serves it (MESH.md 9a.3) 
What a birthing node needs is centre.4th; KILL, PAUSE, RESUME, UNIT-KILL and
CENTRE are Hera's.  An outer node births, as a v3 VM may, and may not kill.
A capsule is read by the node that opened it.  test_host_unit: 93 checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 11:59:47 -04:00
rajamesandClaude Opus 5.5 450dea9c24 feat(v4): a believed GONE is handed to the word in (GONE-HOOK) (MESH.md 9a) 
COLD takes out a hook it forgets.  The system changed, so dict_hash did:
hosted, all three ISAs, word_count=318 dict_hash=0x1b5c633fd6bdd143.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 11:04:28 -04:00
rajamesandClaude Opus 5.5 d154342314 feat(v4): the kernel keeps a registry of nodes and checks who may ask (MESH.md 9a.4) 
Any node may birth and wire its own; only Hera sleeps, wakes and kills, by
number.  Requests have fixed numbers, -6 to -18.  NODE-BORN takes the
number; NODE-KILL a number.  test_manage.c: 41 checks at both widths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 09:58:03 -04:00
rajamesandClaude Opus 5.5 bf97f339f6 docs(v4): MESH.md 9a, the rulings made while planning step 7 
Fixed request numbers; NODE-BORN takes the number; GONE handed on through
the system's (GONE-HOOK), so dict_hash changes; a reader per asker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 08:57:00 -04:00
rajamesandClaude Opus 5.5 f4f566bb37 docs(v4): the implementation plan for MESH step 7 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 08:52:27 -04:00
rajamesandClaude Opus 5.5 5283e67ded docs(v4): MESH.md 9a, step 7's design -- a second unit, PAUSE, RESUME, KILL 
Ruled 2026-10-16: Hera births the second centre and it births its own unit;
hera.4th split into centre.4th (BIRTH-AS, BIRTH, UNIT) and Hera's own
(KILL, PAUSE, RESUME, UNIT-KILL, CENTRE); the kernel keeps the registry and
checks who may ask; centres face each other on port 6; GONE goes down the
birth graph.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 08:31:32 -04:00
rajamesandClaude Opus 5.5 ba9d432a01 docs(v4): MESH.md ruling 7 points to the births ruling 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 08:15:02 -04:00
rajamesandClaude Opus 5.5 9842b9cd50 docs(v4): births follow v3 -- any node may birth, KILL stays Hera's 
MESH.md ruling 7 and section 9 said only Hera's requests are honoured.
Ruled 2026-10-16: v4 births behave as v3's (any VM may BIRTH, the child's
parent is its birther, its ACLs are copied from the parent's at birth,
KILL is Hera's alone).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 08:14:49 -04:00
rajamesandClaude Opus 5.5 1e41a68872 feat(v4): starshipos.4th, the STARSHIPOS vocabulary, with DOE typing the name back 
DOE only types its name for now, as asked 2026-10-15; the runner is still to be
built. Not yet a system capsule (MACHINE.md 6, step 3). With it, the two board
boots, amd64-pc and aarch64-rpi5, that tried it: DOE is unknown until
STARSHIPOS is in the search order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-16 07:57:52 -04:00
rajamesandClaude Opus 5.5 0d5139238d logs: the three acceptance boots of the mesh ROM 
amd64, aarch64, riscv64: ok>, POST 538/538, dict_hash=0xfec8c47cfc6f437f,
rom_hash=0x87b23d3ae2643c8d (2372 words) on all three; Q./ answers 0 21845.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 20:42:08 -04:00
rajamesandClaude Opus 5.5 924c48cece docs(v4): the ROMs' shared entries, and the mesh ROM as built 
DATASHEET-F18.md lists all 19 entries of the host ROM, the six shared ones
with the registers they use.  MACHINE.md 2.2: built; 277 words, not the
estimated 150-200; the system's words are address, push and ;.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 20:32:23 -04:00
rajamesandClaude Opus 5.5 d2df3679ac feat(v4): a node Hera births carries a mesh node's ROM 
MACHINE.md 2.2.  Hera carries the host's ROM; the four outer nodes the
shared math only, and compute UM*, U/MOD and Q./ with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 20:31:41 -04:00
rajamesandClaude Opus 5.5 afd9d46d29 feat(v4): the system's UM*, UM/MOD, D+, DNEGATE, Q.* and Q./ call the ROM 
MACHINE.md 2.2.  Each is its entry's address, push and ;.  Every node the
tests make carries the host ROM (host_load, Hera's births, the depth and
mesh tests' own nodes), and a division by zero inside the ROM returns to
the prompt (hosted-check).  test_host_quit's fetch outside memory moves
past the ROM's range: 16384 is the ROM's first word now the tests' system
has its ROM, as the product's always had.  dict_hash 0xfec8c47cfc6f437f.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 20:16:50 -04:00
rajamesandClaude Opus 5.5 11b5d402b1 feat(v4): the shared math in both ROMs, and a mesh node's ROM 
MACHINE.md 2.2.  UM*, UM/MOD, D+, DNEGATE, Q.* and Q./ are entries 0-5
of the host ROM and of a mesh node's ROM, from one source (rom/math.f18)
and one entry list (v4/rom_entries.h).  The host ROM starts at entry 18.
The mesh ROM is 277 words; the host ROM 2372.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 19:46:00 -04:00
rajamesandClaude Opus 5.5 473e105a69 docs(v4): the mesh ROM's implementation plan 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 19:23:31 -04:00
rajamesandClaude Opus 5.5 99c46eeda8 docs(v4): MACHINE.md's status line says what is built 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 19:14:10 -04:00
rajamesandClaude Opus 5.5 a6da45df53 docs(v4): the mesh ROM's design, MACHINE.md 2.2 
Shared math in a small ROM for mesh nodes: UM*, UM/MOD, D+, DNEGATE,
Q.* and Q./ as entries 0-5 of both ROMs, from one source; the host
ROM's assembler entries follow, and its start moves from 12 to 18.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 18:58:59 -04:00
rajamesandClaude Opus 5.5 39744473f3 logs: the DoE run files of the two acceptance boots of the final review's fixes 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 17:10:59 -04:00
rajamesandClaude Opus 5.5 a28b5f2230 fix(v4): the final review's six minors in the ROM boot 
- Text after start is refused, as text.c refuses it: before it jumps, the
  ROM reads on to the end of the source; blanks, comments and the ends of
  blobs may follow, a token is ERR-AFTER (26), "text after start".
- A token too long where a name, a target or a value is wanted is "name
  too long", as text.c says: (MISSING) reports "missing" only when no error
  came first.  `", keeps "missing", which is text.c's word for both.
- text.c's "address out of range" names the address, not the value.
- The system's source files are one list, v4/sys_files.h: boot.c, the
  harness and the nucleus test are made from it.
- The ROM's error codes and words are one list, v4/rom_errors.h: boot.c's
  messages, host_map.h's ROM_ERR_* and mkmap's ERR-* are made from it.
- node.h says what v4_node_store does with a ROM address (nothing, as for
  any address outside RAM, D-14); test_host_rom_range pins it.

ROM: 2095 words, rom_hash 0x06d0dcb7a0cb41a1.  dict_hash unchanged,
0xe5a57f3eb72ff94a.  make -C v4 test test-32 hosted-check pass.  QEMU:
amd64, aarch64, riscv64 to ok>, POST 538/538, POST: PASSED.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 17:10:45 -04:00
rajamesandClaude Opus 5.5 ff75e69e91 fix(v4): the final review's four defects in the ROM boot 
- The boot left the source's last new line in the console input, and the
  first KEY after the boot read it.  What the ROM has not read when it
  starts the system is taken back (boot.c, rom_harness.h).  hosted-check:
  KEY after the boot reads the key typed.
- A comment or macro left open at the end of a blob ran on into the next,
  and the ROM accepted source text.c refuses.  The loader ends each blob
  with FS (V4_ROM_BLOB_END) after its new line; the ROM ends a blob there
  as text.c ends a file: an open comment or macro is an error, and the word
  being assembled ends.  test_host_rom_asm: seven blob pairs against text.c.
- store to an address outside RAM faulted the ROM with no message.  It is
  now refused, as text.c refuses it: ERR-RANGE, "address out of range".
- The kernel build did not regenerate capsules/v4/sys/map-<w>.f18 before
  packing the capsule directory; it now does.

ROM: 2084 words, rom_hash 0x4c458c6e48b35456.  dict_hash unchanged,
0xe5a57f3eb72ff94a.  make -C v4 test test-32 hosted-check pass.  QEMU:
amd64, aarch64, riscv64 to ok>, POST 538/538, POST: PASSED.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 16:35:07 -04:00
rajamesandClaude Opus 5.5 a73580e949 feat(v4): the machine boots from its ROM; the prebuilt nucleus is gone 
The host node starts in its ROM (entry 12), and the boot feeds it the
system's source through the console: capsules/v4/sys/map-64.f18, the
fourteen .f18 blobs and end.f18, each found, hash-checked and
signature-checked as any capsule, then EOT.  The ROM assembles the system
and starts it at (IDLE); the host reads the image record
(v4_image_from_node) for what only the assembled system knows.  A ROM
error is reported with its blob, line and meaning, then PARITY:FAIL.

Deleted: v4/tools/mkimage.c, capsules/v4/nucleus-64.f18, v4/capsule/*.v4,
v4/tools/v4tof18.py.  The .f18 files are the source now.

- text.c speaks the rest of the ROM's language (set, here, store, start;
  v4_text_value, v4_text_start), so the oracle reads the same source:
  test_host_rom_nucleus compares the ROM against text.c on the .f18 files,
  word for word, image record included.  Host tests load the .f18 files.
- mkmap image writes v4_map_image (the map's description of the system);
  hosted and the kernel link the ROM and the map instead of v4_image_64.c.
- Hera (Captain Bob's ruling, option 1): births stream the system the ROM
  assembled, as assembled code; hera.4th is unchanged.
  test_host_unit's host builds the system with the ROM.
- New parity lines: PARITY:V4_F18 per blob, PARITY:V4_ROM words=2049
  rom_hash=0xa6c792b5821010b7 instructions=60725216.

Acceptance: amd64, aarch64, riscv64 boot to ok> with PARITY:V4_POST
tests=538 pass=538 fail=0, POST: PASSED, and PARITY:V4_SYSTEM
word_count=317 dict_hash=0xe5a57f3eb72ff94a on all three -- the same hash
as the prebuilt nucleus gave.  make -C v4 test test-32 hosted-check: all
pass.  Logs: logs/20261015-141648, -141938, -142350.

Startup cost under QEMU TCG, the ROM's assembly (last V4_F18 line to
V4_ROM): amd64 26.7 s of 132 s to ok>; aarch64 41.0 s of 195 s; riscv64
20.5 s of 101 s.  Hosted native: +0.85 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 14:26:02 -04:00
rajamesandClaude Opus 5.5 1bf19d6224 feat(v4): the ROM assembles the system's .f18 to the nucleus, word for word 
capsules/v4/sys: the nucleus's fourteen sources as .f18 blobs (made once by
v4/tools/v4tof18.py: header becomes the ROM's directives, every other token
and line kept), the memory map as map-<width>.f18 (mkmap sys, from one
table in host_map.h that host_load reads too), and end.f18, the switch-on
state mkimage.c set in C, the image record, and start (IDLE).

test_host_rom_nucleus.c: the ROM, fed those blobs through the console,
builds RAM identical word for word to mkimage.c's, outside its own state
and the image record, and starts at (IDLE), at both widths.  The cost:
60.7 million instructions, 1.5 s on the C model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 12:27:50 -04:00
rajamesandClaude Opus 5.5 084c520a54 feat(v4): the ROM assembles text as text.c does -- words, labels, macros, FOR, directives, start 
word.f18: (NEXT-TOKEN) reads the console or a macro being expanded; labels,
branches by name (a label of the word, or a word, now or later), the
table of branches waiting, end of word, FOR/NEXT/UNEXT, macros, &NAME,
CONST+N, and (ONE), which dispatches a token.  A forward branch to a name
not yet defined waits on a placeholder symbol, filled in by (DEFINE).
dir.f18: constant set here #, ", store, and start, which resolves, clears
the tables the ROM used and runs the word it names.  main.f18: the ROM
itself, entry 12; on an error it stops at (ROM-FAILED) with the code and
line in its state, for the loader to report.  sym.f18 generalized: any
counted string, placeholders, a hash of only a name's own cells.

test_host_rom_asm.c gives test_text.c's own texts (accepted and refused),
its four real definitions and the ROM's directives to text.c and to the
ROM: the same words, the same errors on the same lines, at both widths.
The ROM is 2036 words.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 12:24:08 -04:00
rajamesandClaude Opus 5.5 c233cb6536 feat(v4): the ROM's slot packer, word for word with asm.c 
(OP) (LIT) (BRANCH) (BRANCH>) (RESOLVE) (LABEL), entries 6-11: the code
generator of any language built on the machine (MACHINE.md 2.1).  asm.c's
layout rules with text.c's branch placement; 400 random sequences agree
word for word with asm.c at both widths, memory-full and out-of-reach are
refused on both sides, and a ref with no branch is refused, not looped on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:58:47 -04:00
rajamesandClaude Opus 5.5 07911dcf91 feat(v4): the ROM's symbol table 
(FIND) ( -- rec | 0 ), (DEFINE) ( value kind -- ) and (OPCODE) ( -- op | -1 ),
entries 3-5.  Names are refused as text.c's define refuses them, compared
case by case with text.c; a set variable may be set again.  256 hash heads,
records growing up and names growing down in dictionary space, used only
while the ROM assembles.  text.c gains the data directives #, and ", (the
ROM's language; its mnemonic and reserved-word tables are data); the
nucleus image is byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:54:15 -04:00
rajamesandClaude Opus 5.5 080811dbd2 feat(v4): the ROM reads numbers as text.c does 
(NUMBER) ( -- n flag ), entry 2: decimal with a leading -, or hex after $;
1 a number, 0 not one, -1 one that does not fit a cell.  Every case is also
given to text.c, the oracle, at both widths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:49:46 -04:00
rajamesandClaude Opus 5.5 0f82d8c22a feat(v4): mkrom -- the ROM built off the node; it reads tokens 
The ROM's source is F18 code in capsules/v4/rom, assembled off the node by
v4/tools/mkrom.c with the memory map's constants from v4/tools/mkmap.c
(MACHINE.md 2).  main.f18 is the entry table payloads call through (2.1);
in.f18 reads the console and splits it into tokens exactly as text.c does,
the token held packed as a counted string.  The ROM's state is a reserved
area of the map (host_map.h ROM_*).  text.c gains the constant directive,
so the off-node assembler and the ROM speak one language.  The map also
names (NUMBER)'s state, for the next task.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:49:05 -04:00
rajamesandClaude Opus 5.5 32753f5479 feat(v4): the machine has a ROM -- read and run, never written 
A read-only range of V4_ROM_WORDS words at V4_ROM_BASE, above RAM
(MACHINE.md 2, DATASHEET-F18.md 5).  Instruction fetch, @p and data fetches
read it; a running programme's store there is an address fault.  Attached by
the owner like every device; a reset detaches it.  The host node's range is
4096 words.  text.c places branches by the whole address space.  The
nucleus image is byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:25:24 -04:00
rajamesandClaude Opus 5.5 42f8a13914 docs(v4.0.0): the ROM is shared code, GA144-style -- an entry table, a permanent state area 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 11:10:08 -04:00
rajamesandClaude Opus 5.5 1ed56b93b4 docs(v4.0.0): DATASHEET-F18.md -- the machine: registers, stacks, memory, instruction word, opcodes, control unit, faults, I/O 
As built in the golden model (v4/src), with what is not yet as intended listed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 06:20:25 -04:00
rajamesandClaude Opus 5.5 952df0f44a docs(v4.0.0): plan for MACHINE.md steps 1-2 -- the ROM, and the .f18 trailer 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 06:01:54 -04:00
rajamesandClaude Opus 5.5 d0b0eee54b docs(v4.0.0): MACHINE.md -- what it is for: a multi-user, multitasking OS that init.4th brings up 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:52:47 -04:00
rajamesandClaude Opus 5.5 884721783a docs(v4.0.0): MACHINE.md -- forth79.4th names all 130 words; init.4th is the system's init 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:50:18 -04:00
rajamesandClaude Opus 5.5 528bed0874 docs(v4.0.0): MACHINE.md -- rulings: the VM is a machine; .f18 pretty-printed text; v3 deleted at parity; the whole system loads before POST 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:46:56 -04:00
rajamesandClaude Opus 5.5 3eca84e433 docs(v4.0.0): MACHINE.md -- the ROM is whatever size it takes; not a question 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:43:42 -04:00
rajamesandClaude Opus 5.5 e429d30a7e docs(v4.0.0): MACHINE.md -- the three .4th layers: forth79.4th (100 percent FORTH-79), starforth.4th, anything else 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:41:15 -04:00
rajamesandClaude Opus 5.5 58f3837498 docs(v4.0.0): MACHINE.md -- the machine, its ROM, and the capsule: one prebuilt F18 binary, the rest source 
For review; nothing built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-15 05:35:38 -04:00
rajamesandClaude Opus 5.5 c7bf68fe13 build: source SBOM regenerated 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 17:22:34 -04:00
rajamesandClaude Opus 5.5 3b49cb15a2 boards: the amd64 target is PC -- a generic x86-64 UEFI PC, not the SER5 
Captain Bob, 2026-10-14: "change to PC, not SER5. it's not supposed to be
specific, but PC generic."  boards/ser5 -> boards/pc, TARGET=PC,
lithos-pc.img; the image was never specific to one machine (the generic
UEFI/ACPI path, FABRIC-3 III).  The Beelink SER5 stays named where the text
means the unit on the bench (its Secure Boot, BIOS, serial header) and in
the records.  Built: lithos-pc.img, system=v4, with its SBOM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 17:22:32 -04:00
rajamesandClaude Opus 5.5 1ce8576b76 build: source SBOM regenerated 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 17:21:14 -04:00
rajamesandClaude Opus 5.5 79db0e8d88 build: v4 is the default build -- every kernel boots v4; acceptance is v4 on three ISAs and the 32-bit build 
Captain Bob, 2026-10-14: "v4 is the default build", "no, qemu to v4
too ... we are effectively trying to retire v3", "the 32 bit build needs
to go into the acceptance test too", "i don't care about v3".

- STARFORTH_V4 defaults on (Kconfig default y) and V4_DEFAULT=1
  everywhere: every kernel carries v4 and v3 and boots v4; system=v3 boots
  v3; STARFORTH_V4=0 builds v3 alone.  Board images write system=v4.
- Acceptance (CLAUDE.md): the three ISAs as built (v4, POST passed,
  V4_SYSTEM dict_hash equal) and make -C v4 test-32.  v3 is not part of
  it.

Acceptance run: amd64, aarch64, riscv64 -- PARITY:V4_POST 538/538,
dict_hash=0xe5a57f3eb72ff94a on all three, no unknown word; test-32: 30
suites, 0 failures.  The SER5 image under OVMF boots v4 as built, v3 after
the one-word edit.  README, BRINGUP, FABRIC-3 XLIII, the register updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 17:21:13 -04:00
rajamesandClaude Opus 5.5 7bc658bb83 build: the source SBOM, regenerated -- 809 files with their SHA-256 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 16:58:11 -04:00
rajamesandClaude Opus 5.5 fcb89b0695 build: an SPDX SBOM with every board image, and of the source tree, by syft 
make boot_image now ends by writing build/boards/<board>/<image>.spdx(.json):
the image and every file copied off it, each with its SHA-256 -- the SBOM
of what is on the medium.  It also refreshes sbom.spdx(.json), the source
SBOM: the tracked files the product is built from (kernel, v3, v4,
capsules, boards, tooling, proofs), staged to build/sbom/src so nothing
untracked in the working directory is swept in.  Versioned as the kernel
version and git describe.  mk/syft.yaml turns on file cataloging with
SHA-256 (a C tree has almost no packages for syft to find: the old SBOM
held one file with a zero checksum).  No syft: the build stops.

syft 1.52.0 installed in ~/.local/bin from its GitHub release, checked
against the release's published SHA-256.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 16:58:10 -04:00
rajamesandClaude Opus 5.5 f8fbc37698 docs: the 12 duplicates deleted; README rewritten to the system as it is 
Captain Bob's rulings, 2026-10-14: "delete" -- the duplicates listed in
DELETE-CANDIDATES.md are removed (the list stays as the record; the
formal tier's provenance comments repointed at the maintained copies) --
and "rewrite" the README: v2.1.0, the Tripod as Hera/Artemis/Hestia,
kernel-Hermes, identities on thumbdrives, the corrected ACL overhead,
1052-test POST and the current parity line, keyboards and storage, board
images carrying both systems and how to switch, and docs/README.md as
the way in.  The book is left as it is, to be reworked later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 16:45:39 -04:00
rajamesandClaude Opus 5.5 776c89457e docs: the map, a fresh index, and a register of dead ideas and revised claims 
docs/CLAUDE.md Phase 1 output, after the reorganisation.

- docs/README.md: rewritten as the map -- where each kind of document
  lives, which one to believe (CLAUDE.md, FABRIC, v4.0.0, reference/,
  BRINGUP, code), how to retire a document.
- docs/INDEX.md: regenerated from the tracked tree, 489 rows, every
  document with a status (the 2026-06-16 snapshot was stale).
- docs/DEAD-AND-REVISED.md (new): what was abandoned (L4Re, the hal_*
  contract, ACL RWT, the Hermes VM, elevation, the knowledge factor, ...)
  and what was corrected (ACL overhead, versions, block rules, parity
  baseline, ...), each with its date and record.
- docs/DELETE-CANDIDATES.md: 12 duplicates, awaiting a ruling; nothing
  deleted.
- CLAUDE.md: versions corrected (3.2.0 / 2.1.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 16:06:59 -04:00
rajamesandClaude Opus 5.5 7aed588f78 docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such 
docs/CLAUDE.md Phase 2, 2026-10-14.  All moves by git mv; every archived
file carries a header saying what it is, why, and where to look instead.

- docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL
  design, kernel args, hosted acceptance test, dictionary, primitives,
  ontology, L8 table -- previously spread over docs/, docs/lithosananke/
  and docs/03-architecture/.
- docs/working/archive/historical/: finished work (session plan, test-gap
  audit, birthing plan, fix write-ups, the January architecture draft).
- docs/working/archive/superseded/: the Hermes-VM Tripod docs and July
  Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working
  doc already flagged superseded or obsolete.
- docs/working/archive/dead/: the hal_* target contract (never adopted),
  L4Re, metrics-and-knobs.
- Papers and proposals into docs/working/papers/.
- References rewritten across the repo (not logs/, not docs/patent/);
  CLAUDE.md's documentation section rewritten.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 16:03:56 -04:00
rajamesandClaude Opus 5.5 1a4b163861 feat(boards): both systems on every board image, chosen at boot -- system=v3 or system=v4 
boards/BRINGUP.md A6, FABRIC-3 SXLIII (ruled: one image, switch at boot).
A STARFORTH_V4 kernel carries v3 too; system= in the boot arguments
chooses, else the build's default (V4_DEFAULT: 1 for plain STARFORTH_V4
builds as before, 0 for board images).  make boot_image builds both and
always writes starforth.cfg / cmdline.txt with system=v3 first, and cleans
its ISA's objects first -- that clean was removing build/<arch>/SER5, not
the kernel's objects, until fixed here.

Each ISA: v3 by default (hash unchanged), v4 with system=v4 (538/538).
The SER5 image under OVMF: v3 as built, v4 after a one-word edit on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 15:11:47 -04:00
rajamesandClaude Opus 5.5 e729c64ba3 feat(usb): every xHCI controller is driven, not only the first 
boards/BRINGUP.md A1, FABRIC-3 SXLII.  xhci.c keeps a table of controllers
(up to 8) and services each; kernel_main brings up index 0, 1, ... until
there is none.  repl.c's and blkio_usb.c's per-slot state is per
controller now (a slot ID is a controller's own), and each USB keyboard
keeps its own last report and lights; an unplugged keyboard releases what
it held.

Test first: keyboard and identity on a second controller behind a bridge,
Zuse on the first -- before, only Zuse; after, all three, on all three
ISAs.  Hot-plug and unplug on the second controller.  Acceptance unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 14:27:38 -04:00
rajamesandClaude Opus 5.5 739cb9c163 feat(usb): a USB keyboard -- a full one -- and no hang on a PC without PS/2 
boards/BRINGUP.md A3 and S3, FABRIC-3 SXLI.  A HID boot keyboard is
configured (interrupt IN endpoint, SET_PROTOCOL boot) and its reports
become the same Linux-keycode events as PS/2 and virtio (usb_kbd.c): the
full layout -- F-keys, navigation block, arrows, Num Lock, keypad.  The
console treats Caps and Num Lock as toggles shown on the keyboard's
lights, and the keypad as digits or navigation.  While a USB keyboard
runs, its event ring is serviced every tick, not once a second.

Found on the way: with no i8042 (port 0x64 reads 0xFF) the kernel hung at
boot in an endless drain -- a legacy-free PC would stop there.  Detected
and skipped now; drains bounded.

QEMU, amd64 with the USB keyboard the only one: 1 2 + . on main keys and
keypad, Caps Lock, Num Lock all right; aarch64/riscv64 configure it too.
Acceptance on three ISAs unchanged; identities hot-plug.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 14:04:33 -04:00
rajamesandClaude Opus 5.5 080b7012ba fix(usb): the xHCI controller is found by class on any bus, sized, taken from the firmware, and 64-byte contexts laid out 
boards/BRINGUP.md A1, FABRIC-3 SXL.  It was matched by QEMU's own IDs on
bus 0 alone, so no real board's was found.  Now pci_find_class() reads
every bus/slot/function; pci_bar_size() sizes BAR0; the USB Legacy Support
capability hands the controller over from the BIOS, SMIs off; CSZ=1
contexts are placed 64 bytes apart instead of refused.  XHCI_QEMU_ARGS
lets QEMU place the controller as real hardware does.

Test first: an NEC controller behind a PCIe root port -- no attach before,
Zuse minted after, on all three ISAs.  Standard acceptance unchanged; five
hot-plugged identities attach.  Not rehearsable: firmware handoff, CSZ=1.
Still open: only the first controller found is used.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 13:30:50 -04:00
rajamesandClaude Opus 5.5 0e2c60dac3 fix(raspi): the Pi 5's native path turns the MMU and caches on before any C; bounded mailbox; framebuffer address from dma-ranges 
boards/BRINGUP.md R2/R3, FABRIC-3 SXXXIX.  The entry stub cleans the cache
over the image, builds an identity map (the image's GiB Normal, the rest
Device) and enables MMU and caches at EL2 (or EL1); rpi5_mmu.c makes the
devicetree's RAM Normal and the framebuffer uncached.  Mailbox waits give
up after one second; the buffer is cleaned around the exchange; the
framebuffer address goes through dma-ranges, not a Pi 4 mask.

New rpi5-rehearsal target runs the native image on QEMU virt at EL2.  It
found three more that would each have stopped the board: the PL011 shift
(mine, c9519173; the host test asserted it), the GIC address not carried
through /soc's ranges (new fdt_reg_address(), checked against the real
Pi 5 DTB), and no timer IRQ at EL2 (HCR_EL2.IMO/FMO/AMO).

Rehearsal: POST 1052 passed, same parity hash as UEFI.  Standard acceptance
on three ISAs: POST 1052, hash 0x82f4ae7cb2e2d424.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 12:58:35 -04:00
rajamesandClaude Opus 5.5 4da370f492 feat(log): LOG-FLUSH -- a VM's log records reach Artemis's log ring; and the ring keeps its order when it grows 
FABRIC-3 SXXXII.4's deferred LOG-FLUSH, built to the 2026-10-14 rulings
(SXXXVIII): everything a VM logs, at or above the log level, goes into its
own buffer; it goes to Artemis on LOG-FLUSH, when full, and at once on an
ERROR, as one kernel-Hermes LOG_BATCH message she writes on her own turn,
the source being the sender the kernel stamped.  Records that cannot go yet
are counted and reported with the next flush.  LOG-SHOW (Hera only) reads
the ring back -- it had no reader.

Found by the first test that filled it: ring growth overwrote the oldest
record and put blank slots inside the live range.  Fixed test first.

Three ISAs: POST 1052 passed; new parity baseline word_count=526
hash=0x82f4ae7cb2e2d424 (deliberate).  CLAUDE.md: Phase 8 PKI closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 12:10:01 -04:00
rajamesandClaude Opus 5.5 5e26fad30d fix(security): no VM but Artemis and Hera can make Hera run text; a message runs once; word-ACL elevation removed 
Any identity could have arbitrary FORTH run as Zuse: KH-ELEVATE-SEND and
KH-BLK-ATTACH-SEND sent any text to Hera, from any VM (shown live).  And the
drain popped a message after running it, so a payload calling a colon word
ran twice.  Both fixed test first (FABRIC-3 SXXXVII):

- KH-BLK-ATTACH-SEND is ( dev-addr ok? -- sent? ), Artemis only; the kernel
  writes the reply text.  BLK-ATTACH-ACK is Hera's only.
- The drain pops before it runs.
- Elevation, ruled not needed: KH-ELEVATE-SEND, message type 8,
  zuse-eligibility.4th, ZUSE-ELIGIBLE?/ZUSE-ELIGIBILITY-ADD/
  ELEVATE-PUBKEY-UNPACK and the eligibility list removed; its disk area
  stays reserved, unused.  FABRIC-3.7 closed.

Three ISAs: POST 1052 passed; new parity baseline word_count=523
hash=0xb73b58052d591638 (deliberate).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 11:38:23 -04:00
rajamesandClaude Opus 5.5 029a8ed9cf fix(hermes): one delivery path -- a VM takes its own messages on its own turn, never on another's stack 
FABRIC-3.5 SXXXII, closing FABRIC-3 SXXIX bug 2 (SXXXVI).  A send marks the
receiver for the switch signal; the VM's own loop on its native stack takes
its messages and yields; Hera's idle beat makes the pending switch instead
of running other VMs' messages on her stack; every VM gets switcher turns
from birth; the drain refuses any call outside the VM's own context (the
test: it held every relayed line before, none now).

Found on the way: amd64's first-entry frame left rsp 8 bytes off the SysV
entry alignment (#GP on the first interpreter run on a VM's own stack), and
a VM yielding from its loop was marked SWITCHED_OUT, which stopped console
relay after one message and would have made KILL refuse it.

Relay of four lines to a WIREBIND identity on all three ISAs, five
hot-plugged identities, and standard acceptance (POST 1052, hash
0x08873e0f44b7cb2a) all pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 10:37:57 -04:00
rajamesandClaude Opus 5.5 b7e8e4b058 docs(fabric): §XIV no longer reproduces -- five minted drives attach at power-on and hot-plugged a second apart, all three ISAs 
Checked against a scratch artemis.img, Zuse drive and five identity drives
minted together at a live prompt; the committed images are all blank since
e56974e0 and cannot show the gap either way.  No code change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 08:48:03 -04:00
rajamesandClaude Opus 5.5 c15589b39e fix(vm): a text run from inside a line no longer takes the line's place -- LOAD and THRU go on with the rest of it 
FABRIC-3.md XXXIV.1, traced and fixed.  vm_interpret() copied each text
into the VM's one input buffer and reset the position.  LOAD runs its
block by calling it, so the block replaced the line LOAD was on and
nothing after LOAD or THRU on that line was ever interpreted; the same
for -->, a capsule's EXEC and a message kernel-Hermes delivers.
vm_interpret() now keeps what the outer text had not yet read when it is
called from inside another, and puts it back after, as FORTH-79's LOAD
keeps the input stream it interrupts.  In the kernel's VM and the hosted
one alike.

POST: LOAD.rest_of_line (1 LOAD 0 0 /) and THRU.rest_of_line
(1 2 THRU 0 0 /) failed without the fix (logs/20261014-061222) and pass
with it.  Three-ISA acceptance: logs/20261014-061508 (amd64), -061624
(aarch64), -061837 (riscv64), 1052 tests, none failed, zuse prompt,
hash 0x08873e0f44b7cb2a unchanged.  The hosted binary: 100 LOAD 1 + .
gives 8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-14 06:19:54 -04:00
rajamesandClaude Opus 5.5 9772ee8b68 fix(repl): the bring-up build's prompt waits for a line instead of answering itself without end 
Built with EMERGENCY_CONSOLE_ENABLED=1 and booted with no identity logged
in, the prompt printed "ok>  ok" without end, 1.4 million times in 200
seconds (logs/20261013-210442).  sk_console_readline() gave up at once
whenever no identity was present.  The production build answers that by
going silent until a login; the bring-up build, which needs no login,
took it as an empty line and asked again.  The give-up is now the
production build's only.

Found rehearsing boards/BRINGUP.md; it predates the console change of
c9519173 (the image built from the commit before that did the same).

The riscv64 bring-up build, no thumbdrive, three lines typed
(logs/20261013-235129): one prompt that waits, and 3, 56 and 81.
Acceptance of the production build, one QEMU at a time: amd64
(-235255), aarch64 (-235411), riscv64 (-235620) to the zuse prompt, no
unknown word, hash 0x08873e0f44b7cb2a on all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-13 23:57:29 -04:00
rajamesandClaude Opus 5.5 c95191736e fix(console): the serial line is found, not assumed -- from the devicetree on a board, COM1 by probe on a PC 
Each board has one serial line that is its console, the lowest common
denominator beside the screen and keyboard.  Its address was QEMU's,
fixed: on a Raspberry Pi 5 the aarch64 one is ordinary RAM, written to
with every character printed; on a Milk-V Mars the riscv64 one is the
board's UART with registers four bytes apart, and the UEFI loader would
have waited for ever on its first character; on a PC with no COM1 the
prompt read 0xFF for ever.

console_attach_serial(), called before anything prints: COM1 if a UART
answers there; elsewhere the UART that /chosen/stdout-path names
(fdt_uart.c: alias, path, the address carried up through each bus's
ranges, reg-shift and reg-io-width); with no devicetree, QEMU's.  A
devicetree that names no usable console gives no line, not a guess.  A
line that does not come ready is given up, not waited on.  The riscv64
loader's early serial does the same.

tools/fdt_uart_test.c, run by hand, 19 checks plain and under the
sanitizers: devicetrees shaped like the Mars's, the Pi 5's and QEMU's,
what must find nothing, and a block cut short at every length; and the
Pi 5's real devicetree gives a PL011 at 0x107d001000.

Acceptance, one QEMU at a time: v3 on amd64 (logs/20261013-204436),
aarch64 (-204803) and riscv64 (-205001) to the zuse prompt, no unknown
word, hash 0x08873e0f44b7cb2a on all three as before.  -204600 is an
aarch64 run during which the disk images were restored under it by a
script that had been refused a second QEMU; it passed and is kept, and
was run again.  v4 on the three ISAs (-211149, -211444, -211857): POST
538 of 538, dict_hash 0xe5a57f3eb72ff94a, the typed session unchanged.
The Mars image through OpenSBI and U-Boot in QEMU took its line and its
interrupt controller from the devicetree and passed POST.

Found on the way and not mended (boards/BRINGUP.md 1.6): built with
EMERGENCY_CONSOLE_ENABLED=1 the prompt floods with empty lines.  -210442
shows it; the commit before this does the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-13 21:21:32 -04:00
rajamesandClaude Opus 5.5 f4e359859a docs(boards): bring-up checklist for the four boards, and what stands between today and a first boot 
What to do on the day a board is on the bench: media, cabling, what to
watch for, what counts as a pass, what to keep.  Written before any board
has been booted.

Section 1 lists what was found in the code while writing it, none of it
fixed: the USB controller driver matches QEMU's controller only; the
production build shows no prompt without a thumbdrive login; there is no
USB keyboard driver and no disk driver but virtio; on the Pi 5 the console
writes every character to QEMU's UART address, which is RAM there; on the
Mars the console's UART register layout is probably not the board's; the
board images cannot build the v4 node.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 2026-10-13 20:22:30 -04:00
rajames 010cfc54e6 my shit 2026-10-13 20:20:49 -04:00
542 changed files with 856374 additions and 8058 deletions
Expand all files Collapse all files
.claude/CLAUDE.md
+56 -34
View File
@@ -119,9 +119,8 @@ about "which line am I on."
## Word-Level ACL System — Complete through Phase 7 (independently verified)
**Design doc:** `docs/03-architecture/word-acl/DESIGN.md` (this repo kept the old-style
`docs/03-architecture/` tree alongside the newer `docs/formal/`/`docs/working/` restructure —
both exist here; this path is still current for ACL specifically).
**Design doc:** `docs/reference/word-acl/DESIGN.md` (moved there from the old
`docs/03-architecture/` tree in the 2026-10-14 docs reorganisation).
The word-level ACL system is fully implemented, including kernel parity. Key constraints:
@@ -149,8 +148,11 @@ The word-level ACL system is fully implemented, including kernel parity. Key con
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
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
item — pick up here next.**
8. ✅ PKI / thumbdrive — closed 2026-10-14. User minting by Zuse is built (`MINT`, `MINT-SCRATCH`,
WIREBIND cert verification). Challenge-response against a cloned drive was ruled out by design
("there's only the drive", `FABRIC-3.7.md`). Runtime word-ACL elevation (`ELEVATE-GRANT`, the
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
@@ -199,8 +201,8 @@ removed as an active target.)
**Current status: M7.1** — capsule birth protocol, Mama FORTH vocabulary, Tripod multi-VM
fleet (Hera/Artemis/Hestia — Hermes moved into the kernel as kernel-Hermes, FABRIC-3.6.md
Phase 4, 2026-09-22), and word-level ACL (Phases 1–7) are live; POST at boot verifies parity
hash across amd64/aarch64/riscv64 with a 530-word Mama capsule dictionary (word count as of
the Phase 4 strip; verify against a live `PARITY:M7.1a word_count=` line before citing, it
hash across amd64/aarch64/riscv64 with a 526-word Mama capsule dictionary (word count as of
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:**
@@ -245,12 +247,13 @@ make -f kernel/Makefile clean
Output: `build/<arch>/kernel/starkernel_loader.efi` + `build/<arch>/kernel/starkernel_kernel.elf`.
Two independently tracked version strings flow into the generated `include/version.h`:
`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.1.0`;
`VERSION` (`kernel/Makefile` — the embedded StarForth engine version, currently `3.2.0`;
note this does **not** auto-sync with the standalone StarForth repo's own version) and
`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.0.0`**;
corrected 2026-09-19 — this file said `2.0.1`, but `FABRIC-3.md` §I.2 rolled it back to
`2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims hardware
progress not yet verified. The versioning policy is **semantic, not sequential** — see the
`LITHOS_VERSION` (`kernel/Makefile` — the kernel version, currently **`2.1.0`**, bumped at
the `v2.1.0` tag that closed FABRIC-3.6; corrected 2026-10-14 -- this file said `3.1.0` /
`2.0.0`. History: it said `2.0.1` until 2026-09-19, but `FABRIC-3.md` §I.2 had rolled that
back to `2.0.0` on 2026-09-04 because `2.0.1` names the SER5 hardware-track line and claims
hardware progress not yet verified. The versioning policy is **semantic, not sequential** — see the
roadmap table in `kernel/Makefile` before choosing any version).
### Build configuration (Kconfig — real, wired, not vestigial)
@@ -302,12 +305,23 @@ architectures in QEMU and capturing the serial log. There is no other test.
The vendored hosted `make` build (above) is NEVER used to validate kernel changes.
```bash
# Run in this exact order for every kernel change:
# Run in this exact order for every kernel change. v4 is the default (2026-10-14):
make -f kernel/Makefile ARCH=amd64 clean qemu
make -f kernel/Makefile ARCH=aarch64 clean qemu
make -f kernel/Makefile ARCH=riscv64 clean qemu
# ...and the 32-bit build -- v4 with 32-bit cells, the F18/Zynq (FPGA) case: its nucleus
# image and every v4 test at that width (no QEMU; not a substitute for the boots above):
make -C v4 test-32
```
**v4 is the default build (Captain Bob, 2026-10-14: "v4 is the default build ... no, qemu to v4
too ... we are effectively trying to retire v3").** Every kernel build carries v4 and v3 and
boots v4; `system=v3` in the boot arguments (`KERNEL_ARGS` for QEMU, `starforth.cfg` /
`cmdline.txt` on a board's medium) boots v3. `STARFORTH_V4=0` builds v3 alone. The boot prints
which system runs and why ("System: ..."). See `boards/BRINGUP.md` A6, `FABRIC-3.md` §XLIII.
**v3 is not part of acceptance** (Captain Bob, 2026-10-14: "i don't care about v3"). It is still
in the tree and `system=v3` still boots it, but nothing is accepted or refused on its account.
**QEMU rule — non-negotiable:** Only ONE QEMU instance may run at a time, always in the
foreground (never backgrounded). All three instances use `accel=tcg` (software emulation);
concurrent runs compete for host CPU and corrupt the timing signal the DoE measures.
@@ -327,8 +341,13 @@ audit artifacts — they are committed to the repo. Do not delete them. There is
timestamped convention (self-documented via its own README); not a contradiction, just a
second, less-structured log location.
Do not claim a change is accepted until all three architectures have booted
to `zuse)ok>` and their logs are present in `logs/`.
Do not claim a change is accepted until all three architectures have booted, and their logs are
present in `logs/`:
- **as built (v4)** to `ok> `, with `PARITY:V4_POST tests=538 pass=538 fail=0` (the count
grows with v4's POST) and `POST: PASSED`, and `PARITY:V4_SYSTEM ... dict_hash=` equal across
the three;
- **the 32-bit build** (Captain Bob, 2026-10-14: "the 32 bit build needs to go into the
acceptance test too"): `make -C v4 test-32` passes -- every test, `0 failures`.
### CI
@@ -433,7 +452,7 @@ UEFI Firmware → uefi_loader.c (BOOTX64.EFI / BOOTAA64.EFI / BOOTRISCV64.EFI)
- ✅ 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 is the open item, 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
exists but milestone-complete status not independently verified here)
@@ -498,7 +517,7 @@ mistakenly invoke).
## Roadmap
`ROADMAP.md` and `docs/lithosananke/ROADMAP.md` contain real, LithosAnanke-specific phase
`ROADMAP.md` and `docs/reference/ROADMAP.md` contain real, LithosAnanke-specific phase
content (e.g. "PHASE 2: STARKERNEL (Months 3-5)", "StarKernel boots to 'ok' on QEMU ✅") —
not a copy of the standalone StarForth repo's roadmap. Prefer these when citing roadmap
status for kernel work.
@@ -572,25 +591,28 @@ capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance.
## Documentation
Key files (this repo has both the older `docs/03-architecture/` tree — still current for
ACL/Tripod specifically — and the newer restructured `docs/formal/`/`docs/working/`/
`docs/patent/` trees, plus a repo-specific `docs/lithosananke/` tree):
**Start at `docs/README.md`** -- the map: where each kind of document lives and which one is
authoritative for what. `docs/INDEX.md` lists every document with its status;
`docs/DEAD-AND-REVISED.md` is the register of abandoned ideas and revised claims. (Reorganised
2026-10-14: the old `docs/03-architecture/` and `docs/lithosananke/` trees are gone -- their
current parts are in `docs/reference/`, the rest in `docs/working/archive/`.)
- `README.md` — project overview and quick start
- `docs/lithosananke/SYSTEM_ARCHITECTURE.md` — full kernel + VM design
- `docs/lithosananke/hal/` — HAL reference
- `docs/lithosananke/M7.1.md` — capsule birth protocol design
- `docs/lithosananke/ROADMAP.md` — milestone plan through self-hosting
- `docs/lithosananke/hosted-acceptance-test/README.md` — the hosted-VM acceptance test
writeup referenced from the standalone StarForth repo's own docs
- `docs/03-architecture/tripod/`, `docs/03-architecture/word-acl/DESIGN.md`
- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` — Tripod/Hermes/Artemis
physics + build-system history
- `docs/working/architecture/getting-started/DEVELOPER.md` — dev setup, Kconfig reference
- `ROADMAP.md`, `CHANGELOG.md`
- `experiments/bare_metal/README.md` — **mandatory read before touching capsules** (block
- `README.md` -- project overview and quick start
- `docs/fabric/` -- the design and work record (`FABRIC-3.md` living; the others closed)
- `docs/v4.0.0/` -- StarForth v4 design
- `docs/reference/` -- current reference: `ROADMAP.md` (roadmap and versioning policy),
`M7.1.md` (capsule birth protocol), `word-acl/DESIGN.md` (word-level ACL), `kernel-args/`,
`hosted-acceptance-test/`, `DICTIONARY.md`, `STARFORTH_PRIMITIVES.md`, `ONTOLOGY.md`
- `boards/BRINGUP.md` -- bare-metal bring-up checklist and blockers
- `kernel/src/hal/README.md` -- the HAL as built (the proposed `hal_*` contract was never
adopted; it is archived as dead)
- `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md` -- fleet physics and
build-system history (pre-reshuffle: it still names the Hermes VM)
- `docs/working/architecture/getting-started/DEVELOPER.md` -- dev setup, Kconfig reference
- `CHANGELOG.md`
- `experiments/bare_metal/README.md` -- **mandatory read before touching capsules** (block
namespace rules, see ACL section above)
- `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`
---
.gitignore
+2
View File
@@ -75,3 +75,5 @@ tools/kconfig/.qconf.*
# record) are NOT ignored — those are tracked deliberately.
/tools/capsule-claims.txt
/.directory
# Agent worktrees are never to be used in this repo (Captain Bob's Law); ignored so a stray one is never tracked.
/.claude/worktrees/
CHANGELOG.md
+5 -1
View File
@@ -1,5 +1,9 @@
# Changelog
## 2026-10-09 — StarForth v4.0.0 Step 6e review and wire refinement
Implemented whole-message handling on the engine wire (`d5cd6460`), ensured nodes only process one message at a time (`b1d09af0`), and refined message processing logic (`6a7d0aa2`, `f1419e73`). Fixed wake-up order, room checks, and overflow issues during message transit (`83694b18`).
Milestone-level achievements only — not a commit log. For full history see
`git log` on the relevant branch. Two products share this file:
**StarForth** (hosted FORTH-79 VM, `master`) and **LithosAnanke** (bare-metal
@@ -100,7 +104,7 @@ on both branches, plus the now-orphaned `scripts/pgo-workload.sh`. Verified
Also proved out and documented, for the first time, that the hosted VM
starts cleanly not just on amd64 but on aarch64 and riscv64 too (cross-built,
run under `qemu-{aarch64,riscv64}-static` user-mode emulation) —
`docs/lithosananke/hosted-acceptance-test/README.md`. This is what surfaced
`docs/reference/hosted-acceptance-test/README.md`. This is what surfaced
the `blk_ram` sizing bug above.
## 2026-07-07 – 2026-07-08 — Kconfig build-configuration system (both, committed on `lithosananke`)
CONTRIBUTING.md
+2 -2
View File
@@ -9,7 +9,7 @@ Thank you for your interest in contributing to StarForth! This document provides
3. **Run tests**: `make test` (all 780+ tests must pass)
4. **Read** [ONTOLOGY.md](ONTOLOGY.md) for formal definitions and terminology
5. **Read** `docs/CLAUDE.md` for project overview
6. **Explore** `docs/03-architecture/` for architecture details
6. **Explore** `docs/README.md` (the documentation map) for architecture details
**Important:** All contributors must use terminology from [ONTOLOGY.md](ONTOLOGY.md) in code comments and documentation. This ensures precise, academically rigorous language throughout the project.
@@ -36,7 +36,7 @@ void function_name(VM *vm) {
### Platform Abstraction
- **Never** call platform-specific APIs directly from VM code
- **Always** use HAL interfaces (`hal_time.h`, `hal_memory.h`, etc.)
- See `docs/03-architecture/hal/` for HAL documentation
- See `kernel/src/hal/README.md` for the HAL as built
### Memory Safety
- Use `vaddr_t` for VM addresses (not C pointers)
Kconfig.kernel
+9 -7
View File
@@ -14,15 +14,17 @@ config STARFORTH_ENABLE_VM
block in kernel/Makefile, not just a handful of -D flags.
config STARFORTH_V4
bool "Boot StarForth v4, the F18-derived engine, at a single prompt (STARFORTH_V4)"
default n
bool "Build StarForth v4, the F18-derived engine, in -- and boot it (STARFORTH_V4)"
default y
help
Instead of the v3 VM and its fleet, the kernel starts one StarForth
v4 host node after the M0-M6 hardware milestones: the golden model
The kernel carries StarForth v4 as well as v3 and boots v4: one
host node, after the M0-M6 hardware milestones, of the golden model
of the 32-opcode engine (v4/src) running the capsule image built
from v4/capsule, with its console on the kernel's serial console.
It reaches v4's "ok> " prompt and stays there. The v3 VM is still
compiled in but is not started. See docs/v4.0.0/DECOMPOSITION.md.
from v4/capsule, with its console on the kernel's serial console;
it reaches v4's "ok> " prompt. `system=v3` in the boot arguments
boots the v3 VM and its fleet instead. On by default since
2026-10-14: v3 is being retired. Off builds v3 alone. See
docs/v4.0.0/DECOMPOSITION.md and boards/BRINGUP.md A6.
config PARITY_MODE
bool "Deterministic parity harness mode (PARITY_MODE)"
Makefile
+68 -6
View File
@@ -8,7 +8,7 @@
# docs/book/Makefile -- the single LaTeX book (build/docs/*.pdf)
# Every sub-make runs from this directory, so paths are always repo-relative.
#
# TARGET is either a board (SER5 RASPI MILKV ZYNQ7020), a hosted v3 profile
# TARGET is either a board (PC RASPI MILKV ZYNQ7020), a hosted v3 profile
# (standard fast fastest turbo asan ...), or empty:
#
# make [all] every board that has a kernel port, the
@@ -16,7 +16,9 @@
# make [all] TARGET=<board> that board's boot image + its book
# make [all] TARGET=<profile> hosted v3 build with that profile
#
# make boot_image TARGET=<board> only the board's boot image
# make boot_image TARGET=<board> only the board's boot image, with its SBOM
# (build/boards/<board>/*.spdx*) and a fresh
# source SBOM -- needs syft
# make boot_images every board that has a kernel port
# make docs [TARGET=<board>] the book; a board adds its appendix
#
@@ -25,17 +27,18 @@
# make clean TARGET=<profile> build/<arch>/<profile> for every arch
# make clean-docs build/docs/
#
# make sbom SPDX SBOM of the source tree (sbom.spdx, sbom.spdx.json)
# make kernel ARCH=<arch> [GOAL=g] kernel/Makefile goal (default: all)
# make boards list boards and whether they can be built
# make <other goal> goes to v3/Makefile (make help-hosted)
# ==============================================================================
# Board name (as typed on the command line) -> boards/ directory.
BOARD_DIR_SER5 := ser5
BOARD_DIR_PC := pc
BOARD_DIR_RASPI := raspi
BOARD_DIR_MILKV := milkv
BOARD_DIR_ZYNQ7020 := zynq7020
BOARDS := SER5 RASPI MILKV ZYNQ7020
BOARDS := PC RASPI MILKV ZYNQ7020
empty :=
space := $(empty) $(empty)
@@ -53,7 +56,7 @@ BOARD_DIR := $(if $(TARGET),$(BOARD_DIR_$(TARGET)))
SUBMAKE := $(MAKE) --no-print-directory
.DEFAULT_GOAL := all
.PHONY: all boot_image boot_images docs clean clean-docs kernel boards help help-hosted
.PHONY: all boot_image boot_images docs clean clean-docs kernel boards help help-hosted sbom sbom-board
# ------------------------------------------------------------------------------
# all
@@ -95,8 +98,18 @@ boot_image:
echo " $(call board_field,$(TARGET),BOARD_DESC)"; \
exit 1; \
fi
@# Both systems in one image, v4 unless the boot arguments say system=v3
@# (boards/BRINGUP.md A6, ruled 2026-10-14; v4 the default, same day). A clean build every time: the
@# kernel objects are shared with `make qemu`, and make does not see a
@# change of compile flags -- an image could otherwise carry objects built
@# without v4, or without the bring-up console.
@$(SUBMAKE) -f kernel/Makefile ARCH=$(call board_arch,$(TARGET)) TARGET=kernel clean
@$(SUBMAKE) -f kernel/Makefile \
BOARD=$(BOARD_DIR) ARCH=$(call board_arch,$(TARGET)) TARGET=kernel boot_image
BOARD=$(BOARD_DIR) ARCH=$(call board_arch,$(TARGET)) TARGET=kernel \
STARFORTH_V4=1 V4_DEFAULT=1 boot_image
@# Its SBOM, and the source tree's, are part of the build (2026-10-14).
@$(SUBMAKE) sbom-board TARGET=$(TARGET)
@$(SUBMAKE) sbom
boot_images:
@for b in $(READY_BOARDS); do \
@@ -104,6 +117,55 @@ boot_images:
done
@$(foreach b,$(UNREADY_BOARDS),echo "Skipped $(b): needs kernel/src/arch/$(call board_arch,$(b)), which does not exist yet";)
# ------------------------------------------------------------------------------
# SBOMs (SPDX 2.3, by syft; config mk/syft.yaml) -- part of every board build
# ------------------------------------------------------------------------------
# The source SBOM covers what the product is built from: the tracked files of
# the kernel, v3, v4, capsules, boards, build tooling and proofs, each with its
# SHA-256 -- copied to build/sbom/src first, so nothing untracked in the
# working directory is ever swept in. Not logs, documents, experiment data or
# the disk images. A board's SBOM covers
# its image and every file on it, copied off the image, so the SBOM is of what
# is on the medium, not of what was meant to be. Versioned as the kernel
# version and the commit. No syft: the build stops, as for any missing tool.
SYFT ?= syft
SBOM_VERSION = $(shell sed -n 's/^LITHOS_VERSION *?= *//p' kernel/Makefile)+$(shell git describe --always --dirty 2>/dev/null)
# What the product is built from: tracked files only, in these places (never
# untracked or ignored files in the working directory).
SBOM_SOURCES := kernel v3 v4 capsules boards mk tools scripts proof configs \
Makefile Kconfig Kconfig.arch Kconfig.heartbeat Kconfig.kernel \
Kconfig.physics Kconfig.variant LICENSE NOTICE.md
GIT_PLAIN := git -c filter.lfs.process= -c filter.lfs.smudge=cat -c filter.lfs.required=false
define need_syft
@command -v $(SYFT) >/dev/null 2>&1 || { \
echo "Error: syft not found -- the SBOM is part of this build."; \
echo " Install a release from https://github.com/anchore/syft/releases"; \
echo " (verify it against the release's checksums), or SYFT=/path/to/syft."; exit 1; }
endef
sbom:
$(need_syft)
@echo " SBOM source tree -> sbom.spdx, sbom.spdx.json ($(SBOM_VERSION))"
@rm -rf build/sbom/src && mkdir -p build/sbom/src && \
$(GIT_PLAIN) ls-files -z -- $(SBOM_SOURCES) | xargs -0 cp --parents -t build/sbom/src && \
$(SYFT) -q -c mk/syft.yaml dir:build/sbom/src \
--source-name LithosAnanke --source-version "$(SBOM_VERSION)" \
-o spdx-json=sbom.spdx.json -o spdx=sbom.spdx
sbom-board:
$(need_syft)
@if [ -z "$(BOARD_DIR)" ]; then echo "Usage: make sbom-board TARGET=<$(subst $(space),|,$(BOARDS))>"; exit 1; fi
@img=build/boards/$(BOARD_DIR)/$(call board_field,$(TARGET),BOARD_IMAGE); \
if [ ! -f "$$img" ]; then echo "Error: $$img not built (make boot_image TARGET=$(TARGET))"; exit 1; fi; \
rm -rf build/boards/$(BOARD_DIR)/contents && mkdir -p build/boards/$(BOARD_DIR)/contents && \
mcopy -s -n -i "$$img@@1M" '::/*' build/boards/$(BOARD_DIR)/contents/ && \
echo " SBOM $$img -> $${img%.img}.spdx, $${img%.img}.spdx.json" && \
$(SYFT) -q -c mk/syft.yaml dir:build/boards/$(BOARD_DIR) \
--exclude './*.spdx' --exclude './*.spdx.json' \
--source-name "LithosAnanke-$(BOARD_DIR)" --source-version "$(SBOM_VERSION)" \
-o spdx-json=$${img%.img}.spdx.json -o spdx=$${img%.img}.spdx
# ------------------------------------------------------------------------------
# docs
# ------------------------------------------------------------------------------
README.md
+73 -69
View File
@@ -1,6 +1,7 @@
# LithosAnanke v2.0.1
# LithosAnanke v2.1.0
**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then runs the StarForth VM as its sole userspace runtime. No libc. No OS. Just stone and necessity.
**UEFI-bootable FORTH microkernel.** Boots from firmware, initialises memory and interrupts, then
runs StarForth as its sole userspace runtime. No libc. No OS. Just stone and necessity.
*Lithos* (foundation) + *Ananke* (necessity) — the kernel under StarshipOS.
@@ -13,54 +14,55 @@ StarForth v4 moves the engine onto a 32-instruction core derived from Chuck Moor
| Product | What it is |
|---|---|
| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64, on real hardware. |
| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA. It is the gateway to the rest: the foundation everything else is built up from. |
| **StarshipOS** | The bare-metal product: LithosAnanke running the v4 F18 engine. |
| **Hosted StarForth F18** | The v4 engine as a native Linux build, for amd64, arm64 and riscv64. |
| **FPGA StarForth F18** | A 32-bit build of the same engine loaded into the FPGA: the gateway to the rest, the foundation everything else is built up from. |
| **StarshipOS** | The bare-metal product: LithosAnanke running StarForth. |
FORTH-79 is recomposed on the F18 engine and stored as a capsule; the StarshipOS-specific
vocabulary gets the same treatment. The source tree will be reorganised around this split.
v3 remains the reference system until v4 meets its acceptance criteria
(`docs/v4.0.0/JUSTIFICATION.md` §16). Everything below describes v3 as it stands today.
vocabulary gets the same treatment. v3 remains the reference system until v4 meets its
acceptance criteria (`docs/v4.0.0/JUSTIFICATION.md` §16). **Both run on bare metal now:** every
board image carries v4 and v3, boots v4 as built, and one word in its boot configuration
chooses (see below).
---
## Status — M7.1 (Capsule System · Multi-VM Fleet)
## Status
| Milestone | | Status |
|---|---|---|
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console (v1.5.1-FINAL) | ✅ Complete |
| M0–M6 | UEFI boot · PMM · VMM · IDT · APIC · heap · framebuffer VT100 console | ✅ Complete |
| M7 | StarForth VM integration + parity validation | ✅ Complete |
| **M7.1** | **Capsule birth protocol · Mama FORTH vocabulary · Tripod multi-VM fleet (Hermes/Artemis) · Word-level ACL (Phases 1–7)** | 🔄 **In Progress** |
| M8 | REPL — keyboard input, interactive Forth | Planned |
| M9 | Block storage — AHCI driver | Planned |
| M7.1 | Capsule birth · Mama FORTH vocabulary · the Tripod fleet · kernel-Hermes · word-level ACL | ✅ Live |
| M8 | Keyboard input to the REPL — PS/2, virtio and **USB** keyboards (a full keyboard: Caps/Num Lock, keypad) | ✅ In QEMU, all three ISAs |
| M9 | Block storage — Artemis's disk on virtio-blk; identity thumbdrives on USB mass storage | ✅ In QEMU · real disks: no driver yet (`boards/BRINGUP.md` A4) |
| Bare metal | a generic PC (amd64; first on the bench: a Beelink SER5), Raspberry Pi 5 (aarch64), Milk-V Mars (riscv64); Zynq-7020 (ARMv7) not yet ported | Images build; first boots on the bench — `boards/BRINGUP.md` |
POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsule dictionary: 453 words**
**v4 is the default build, and v3 is being retired**: every kernel boots v4 unless its boot
arguments say `system=v3`. POST at boot, on all three ISAs: v4 — **538 tests**,
`PARITY:V4_SYSTEM word_count=317 dict_hash=0xe5a57f3eb72ff94a`; v3 — **1052 tests**,
`PARITY:M7.1a word_count=526 hash=0x82f4ae7cb2e2d424`.
### What's live in M7.1
### What's live
- **Tripod** — a named multi-VM fleet (Hera the Mama VM, Artemis, two Hermes
instances) births, runs, and re-births independently, verified booting
live pre-REPL on all three architectures.
- **Hermes** — a 17-block inter-VM messaging/channel layer between fleet
members, with async delivery and channel negotiation.
- **Artemis** — a Block Allocation Map (BAM) storage subsystem with Q48.16
block-heat tracking and cooldown/reclamation (`ART-COOL`/`ART-REAP`).
- **Word-level ACL** — every dictionary entry carries a TTL/allow/mode/pin
access-control record. Strict, TTL, and pinned modes; two console layers
(emergency `ok>` and superuser `zuse)ok>`). Phases 1–7 complete (C
infrastructure, FORTH policy layer, `zuse` bootstrap superuser, Isabelle
proof stubs, kernel parity); Phase 8 (Ed25519 PKI / thumbdrive
challenge-response) is the only item remaining. Measured overhead once
active on every check: **+0.0054%–+0.0088%**, CV = **0.000%**, across a
3×3 Latin-square DoE campaign (architecture × seed × 30 replicates) —
three orders of magnitude below the measurement floor.
- **VM Fleet Attractor physics** — the L8 Jacquard mode selector now has a
real per-VM heat channel into fleet-wide tuning, replacing hardcoded
compudynamics constants with a dynamically-inferred rate.
- **Kconfig build configuration** — every physics/heartbeat/pipelining/
kernel-only tuning knob (~40 total) is now a discoverable, optional
Kconfig symbol shared with the hosted VM build. See **Quick Start** below.
- **The Tripod** — a named multi-VM fleet: **Hera** (the Mama VM, the governor), **Artemis**
(block storage: a Block Allocation Map with Q48.16 block heat, cooldown and reclamation) and
**Hestia**, birthed, run and re-birthed independently on all three architectures.
- **kernel-Hermes** — messaging moved into the kernel (the Hermes VM is gone,
`docs/fabric/FABRIC-3.5.md`): every VM takes its own messages on its own turn, under a
cooperative switcher that every VM takes part in.
- **Identities on thumbdrives** — Zuse, the superuser, and every user is a minted USB
thumbdrive (Ed25519, Zuse-signed); plugging one in births that user's VMs, pulling it out
ends them. There is only the drive: no password, no PIN.
- **Word-level ACL** — every dictionary entry carries a TTL/allow/mode/pin access-control
record; strict, TTL and pinned modes; two console layers (emergency `ok>` and superuser
`zuse)ok>`). Measured overhead of the live ACL-TTL mechanism: **+0.0603%**, CV 0.000%,
architecture-independent (`docs/fabric/FABRIC-1.md` §T).
- **Logs that persist** — every VM's log records go to a ring on Artemis's disk (`LOG-FLUSH`,
`LOG-SHOW`).
- **The physics-driven runtime** — seven feedback loops and the L8 Jacquard mode selector, with
a per-VM heat channel into fleet-wide tuning (VM Fleet Attractor).
- **Kconfig build configuration** — about 40 physics, heartbeat, pipelining and kernel-only
knobs, shared with the hosted build.
---
@@ -68,48 +70,44 @@ POST at boot: **parity hash verified across amd64/aarch64/riscv64 · Mama capsul
```bash
# One boot image per physical target (output: build/boards/<board>/)
make boot_image TARGET=SER5 # Beelink SER5 -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=PC # any x86-64 UEFI PC -- GPT/ESP, BOOTX64.EFI
make boot_image TARGET=RASPI # Raspberry Pi 5 -- FAT, config.txt + kernel_2712.img + DTB
make boot_image TARGET=MILKV # Milk-V Mars -- GPT/ESP, BOOTRISCV64.EFI (U-Boot bootefi)
make boot_image TARGET=ZYNQ7020 # Zynq-7020 -- ARMv7 port in progress
make boards # list boards
make boards # list boards (the Zynq-7020 has no ARMv7 port yet)
# Each image carries v4 and v3. As built it boots v4; to boot v3, change the one word
# system=v4 -> system=v3
# in starforth.cfg on the PC's stick or the Mars's card, or cmdline.txt on the Pi 5's card.
# The same TARGET drives all, docs and clean (make help)
make # every board with a kernel port + hosted v3 + the book
make TARGET=RASPI # one board's image + build/docs/LithosAnanke-raspi.pdf
make docs # build/docs/LithosAnanke.pdf (LaTeX master: docs/book/main.tex)
make clean TARGET=RASPI # that board's outputs and build/aarch64/kernel
make clean # all of build/ except build/cache/
# Build kernel (requires cross-compilation toolchain, or native gcc)
make -f kernel/Makefile ARCH=amd64
# The kernel in QEMU (OVMF / AAVMF / EDK2), one architecture at a time -- boots v4
make -f kernel/Makefile ARCH=amd64 clean qemu
make -f kernel/Makefile ARCH=aarch64 clean qemu
make -f kernel/Makefile ARCH=riscv64 clean qemu
make -f kernel/Makefile ARCH=amd64 KERNEL_ARGS=system=v3 clean qemu # v3, while it remains
# Run in QEMU with OVMF
make -f kernel/Makefile qemu
# Other architectures
make -f kernel/Makefile ARCH=aarch64 qemu
make -f kernel/Makefile ARCH=riscv64 qemu
# The Pi 5's native boot path, rehearsed on QEMU's virt machine at EL2
make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal
```
Artifacts: `build/amd64/kernel/starkernel_loader.efi` · `build/amd64/kernel/starkernel_kernel.elf`
Artifacts: `build/<arch>/kernel/starkernel_loader.efi` · `build/<arch>/kernel/starkernel_kernel.elf`
Tree: `kernel/` (LithosAnanke: `Makefile`, `src/`, `include/starkernel/`, `linker/`),
`v3/` (StarForth v3 engine and hosted build: `Makefile`, `src/`, `include/`),
`v4/` (StarForth v4, see `docs/v4.0.0/`), `boards/<board>/` (`board.mk` + boot files).
Every makefile runs from the repo root; the root `Makefile` forwards any other goal to
`v3/Makefile` (hosted build).
`v3/` (StarForth v3 engine and hosted build), `v4/` (StarForth v4, see `docs/v4.0.0/`),
`boards/<board>/` (`board.mk` + boot files), `capsules/` (the FORTH capsules). Every makefile
runs from the repo root; the root `Makefile` forwards any other goal to `v3/Makefile`.
For the hosted VM by itself (Linux, no cross-compiler needed, no bare-metal tooling): see
the separate **StarForth** repository — LithosAnanke used to be a branch inside that repo,
now it's its own project with its own `master`.
For the hosted v3 VM by itself, see the separate **StarForth** repository — LithosAnanke used to
be a branch inside it, and is now its own project.
### Build configuration (optional)
Every kernel-only knob (`STARFORTH_ENABLE_VM`, `PARITY_MODE`, the shared
physics/heartbeat family, etc.) is an optional Kconfig symbol — a plain
`make -f kernel/Makefile` uses the same defaults it always has unless
you opt in:
Every kernel-only knob is an optional Kconfig symbol; a plain `make -f kernel/Makefile` uses
the defaults unless you opt in:
```bash
make -f kernel/Makefile ARCH=amd64 menuconfig
@@ -120,15 +118,21 @@ make -f kernel/Makefile ARCH=amd64 kernel_amd64_defconfig
## Documentation
**Start at [docs/README.md](docs/README.md)** — the map: where each kind of document lives and
which to believe. Among them:
| | |
|---|---|
| [System Architecture](docs/lithosananke/SYSTEM_ARCHITECTURE.md) | Full kernel + VM design |
| [HAL Reference](docs/lithosananke/hal/) | Hardware abstraction layer interfaces |
| [Capsule System — M7.1](docs/lithosananke/M7.1.md) | Capsule birth protocol design |
| [VM Fleet Attractor design log](docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md) | Tripod/Hermes/Artemis physics + build-system history |
| [Getting Started / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both build targets |
| [The FABRIC record](docs/fabric/) | Every design decision and the work as it happened (`FABRIC-3.md` is the living one) |
| [StarForth v4](docs/v4.0.0/) | The F18-derived engine |
| [Board bring-up](boards/BRINGUP.md) | Getting onto a PC, the Pi 5 and the Mars |
| [Roadmap and versioning](docs/reference/ROADMAP.md) | Milestone plan and release-versioning policy |
| [Capsule System — M7.1](docs/reference/M7.1.md) | Capsule birth protocol |
| [Word-level ACL](docs/reference/word-acl/DESIGN.md) | The access-control design |
| [HAL, as built](kernel/src/hal/README.md) | Hardware abstraction layer |
| [Developer guide / Kconfig reference](docs/working/architecture/getting-started/DEVELOPER.md#build-configuration-kconfig) | Full symbol reference for both builds |
| [Dead ideas and revised claims](docs/DEAD-AND-REVISED.md) | What is no longer true, and since when |
| [Changelog](CHANGELOG.md) | Milestone-level history |
| [Roadmap](docs/lithosananke/ROADMAP.md) | Milestone plan through self-hosting |
---
boards/BRINGUP.md
+292
View File
@@ -0,0 +1,292 @@
# Board bring-up checklist
Written 2026-10-13, before any of the four boards has been booted. It is what to do on the day
a board is on the bench, and what has to be true before that day is worth having.
Nothing here has been done on hardware. Every statement about the code was checked in the code
on the date above; where it comes from a document instead, the document is named. When a board
has been booted, its results go in `docs/fabric/FABRIC-3.md` (sections III, IV, V) and its
`README.md` here, and this file is corrected.
The four boards: `PC` (amd64, any x86-64 UEFI PC; the one on the bench is a Beelink SER5 -- the target was named `SER5` until 2026-10-14), `RASPI` (Pi 5, aarch64), `MILKV` (Mars, riscv64), `ZYNQ7020`
(ARMv7, no port yet). See `boards/README.md` for what each image is.
---
## 1. What stands between today and a first boot
Found while writing this checklist. Items marked **blocks first boot** will stop a board
showing anything, or stop it being typed to; they are worth closing before the bench day.
None has been fixed: each needs your word.
### 1.1 All boards
| # | What | Where | Effect on hardware |
|---|---|---|---|
| A1 | **Fixed 2026-10-14.** The USB controller was matched by QEMU's own IDs (`1B36:000D`) on PCI bus 0 alone. Now: found by its PCI class (`0C/03/30`) on any bus, slot and function; its register window mapped at the size its BAR reports; taken from the firmware through the USB Legacy Support capability (SMIs off); and 64-byte contexts (`CSZ=1`, common on real controllers) laid out instead of refused. Every controller is driven, up to 8 (since 2026-10-14, `FABRIC-3.md` XLII): a stick or keyboard may be in any port. | `kernel/src/usb/xhci.c`, `kernel/src/pci/pci.c`; `FABRIC-3.md` XL | Rehearsed in QEMU with another vendor's controller behind a bridge, all three ISAs. Not rehearsable: the firmware handoff and 64-byte contexts (QEMU's controller has neither). |
| A2 | **No prompt without a login.** The production default, `EMERGENCY_CONSOLE_ENABLED=n`, keeps the system headless until an identity logs in by thumbdrive. | `Kconfig.heartbeat:68`; `FABRIC-3.md` VIII.1 | With A1, the v3 system never shows a prompt on hardware. A bring-up build must set `EMERGENCY_CONSOLE_ENABLED=1`. |
| A3 | **Fixed 2026-10-14.** A USB boot-protocol keyboard is driven (xHCI interrupt endpoint, `SET_PROTOCOL(boot)`), its reports become the same key events as the PS/2 and virtio keyboards, and the console treats a full keyboard as one: Caps Lock and Num Lock as toggles shown on the keyboard's lights, the keypad as digits or navigation, the arrows and navigation block mapped (the line editor itself still has no cursor movement). While a USB keyboard runs, the console services its reports every timer tick. | `kernel/src/usb/usb_kbd.c`, `kernel/src/usb/xhci.c`, `kernel/src/repl.c`; `FABRIC-3.md` XLI | Rehearsed in QEMU on all three ISAs; on amd64 with the USB keyboard the only keyboard. Limits: a keyboard whose first interface is not the keyboard is not used; no key repeat. Several keyboards, on any controllers, each its own. |
| A4 | **The only disk driver is virtio.** | `kernel/src/virtio/virtio_blk.c`; `kernel_main.c:493` | On hardware Artemis finds no disk ("Artemis: no virtio-blk disk"). What the fleet then does has not been tried even in QEMU: see step 3.3. |
| A5 | **Entropy:** RDRAND on amd64 only. aarch64 and riscv64 have virtio-rng alone. | `kernel/src/rng/rng.c` | Pi 5 and Mars print the "no entropy backend available" warning; anything that needs random bytes is refused. Minting needs them. |
| A6 | **Fixed 2026-10-14.** Every board image carries both systems, v3 and v4, and the boot arguments choose: `system=v4` (as built: v4 is the default) or `system=v3` -- one word in `starforth.cfg` on the SER5's and the Mars's stick or card, in `cmdline.txt` on the Pi 5's card. No rebuild to switch. | root `Makefile`, `kernel/Makefile`, `kernel/src/kernel_main.c`, `kernel/src/boot/cmdline.c`; `FABRIC-3.md` XLIII | The SER5 image itself, booted under OVMF: v3 as built, v4 after the one-word edit. The boot says which system runs and why ("System: ..."). |
### 1.2 PC (the SER5 on the bench)
| # | What | Where | Effect |
|---|---|---|---|
| S1 | HPET address fixed at `0xFED00000`, not read from ACPI. | `FABRIC-3.md` III item 6, finding 1 | Wrong only on a machine that puts it elsewhere. Most do not. |
| S2 | Local APIC address fixed at `0xFEE00000`; the MADT's override entry is not parsed. | finding 2 | The same. |
| S3 | **Half fixed 2026-10-14.** The i8042: a PC without one (port 0x64 reads 0xFF) hung the kernel at boot, in a drain loop that never ended -- found rehearsing A3 with QEMU's `i8042=off`. Now detected and skipped, every drain bounded. Still open: the legacy PIC is written to with no check that it exists. | `kernel/src/arch/amd64/i8042.c`; finding 3; `FABRIC-3.md` XLI | A legacy-free SER5 no longer stops at the I/O APIC. The PIC: unknown on a machine without one. |
| S4 | `BYE` resets through the i8042, not the ACPI reset register. | finding 4 | `BYE` may do nothing. It does not hang. |
| S5 | Whether the SER5 has a serial header is not known. | `FABRIC-3.md` III | Without one, and with A3, the SER5 can be watched over HDMI and not typed to. |
The loader probes COM1 before using it, and since 2026-10-13 so does the kernel's console.
Before that, on a board with no COM1 the status port read all ones: writes went nowhere, and
the prompt was told a key was waiting on every poll and read `0xFF` for ever.
### 1.3 Raspberry Pi 5
| # | What | Where | Effect |
|---|---|---|---|
| R1 | **Fixed 2026-10-13.** Every character the console printed was also written to a PL011 at `0x09000000`, QEMU's address, which on a Pi 5 is ordinary RAM. The console now finds its serial line from the devicetree's `/chosen/stdout-path`: on the Pi 5 that is `serial10`, the debug connector, a PL011 at `0x107d001000`. | `kernel/src/hal/console.c`, `kernel/src/hal/fdt_uart.c`; `tools/fdt_uart_test.c` reads the board's real devicetree | Checked off the board only. The first run is the board's. |
| R2 | **Fixed 2026-10-14.** Entry is at EL2 with the MMU off, where every access is Device memory: unaligned accesses and atomics fault, nothing is cached. The entry stub now cleans the cache over the image, turns the MMU and caches on before any C (identity map: the image's GiB Normal in 2 MiB blocks, the rest Device), and routes interrupts to EL2; C then makes the rest of the devicetree's RAM Normal. Rehearsing it found and fixed three more: the PL011 register shift, the GIC address (not carried through `/soc`'s `ranges`), and the EL2 timer interrupt never being taken. | `native_rpi5_entry.S`, `rpi5_mmu.c`, `fdt.c` (`fdt_reg_address`), `apic.c`; `FABRIC-3.md` XXXIX | Rehearsed on QEMU virt at EL2 (section 3.2): POST passes, same parity hash. Not yet on the board. |
| R3 | **Partly fixed 2026-10-14.** The address returned is now carried through the devicetree's `dma-ranges` (on the Pi 5 it is already physical; the old `& 0x3FFFFFFF` was the Pi 4's rule), every mailbox wait gives up after one second, the request buffer is cleaned to RAM and back around the exchange, and the framebuffer is mapped uncached. Still unverified: the size field of the allocate tag. The mode is fixed at 1920x1080x32. | `rpi5_mailbox.c`, `rpi5_mmu.c`; `FABRIC-3.md` IV.3 item 3, XXXIX | QEMU virt has no mailbox: none of this runs before the board. No picture shows as no framebuffer, not a hang. |
| R4 | USB, Ethernet and GPIO are behind the RP1 chip on PCIe, which needs a Broadcom-specific driver that is not written. | `FABRIC-3.md` IV.3 item 5 | No USB on the Pi 5 whatever is done about A1. |
| R5 | No hardware entropy source is known for the BCM2712. | `FABRIC-3.md` IV.2 | A5 stands. |
### 1.4 Milk-V Mars
| # | What | Where | Effect |
|---|---|---|---|
| M1 | **Fixed 2026-10-13.** The console, and the UEFI loader before it, wrote to a 16550 at `0x10000000` with registers one byte apart. The JH7110's UART is at that address with `reg-shift = <2>` and `reg-io-width = <4>` (mainline `jh7110.dtsi`): the loader would have waited for ever on its first character. Both now take the layout from the devicetree. | `kernel/src/hal/console.c`, `kernel/src/boot/uefi_loader.c` | Rehearsed in QEMU through U-Boot, which hands over a devicetree: "serial line is a 16550 at 0x10000000 (named by the devicetree)". QEMU's UART is byte-spaced, so the four-byte layout itself is checked by the host test only. |
| M2 | The display depends on U-Boot offering a framebuffer to the EFI loader. | `boards/milkv/README.md` | Unknown. With M1 unfixed there is then no channel at all. |
| M3 | USB is behind the JH7110's PCIe controller; whether that is plain ECAM has not been looked up. | `FABRIC-3.md` V.3 item 5 | No USB until it is. |
| M4 | `FABRIC-3.md` V describes a native entry at `0x40000000`; the image built today is the UEFI loader run by U-Boot's `bootefi`. The README here is the newer and is what the build does. | `boards/milkv/README.md` | None; noted so the two are not confused on the day. |
| M5 | Whether the U74 has the entropy instruction is not known. | `FABRIC-3.md` V.2 | A5 stands. |
### 1.5 Zynq-7020
No image can be built. Needed first, in order: the board chosen (it fixes `BOOT.BIN`); an ARMv7
port, `kernel/src/arch/armv7` (entry, MMU, GIC, private timer); and the four files that use
`__int128` or have no ARMv7 branch (`boards/zynq7020/README.md` names them). It is the host for
the v4 mesh, so it also waits on A6.
### 1.6 Found in rehearsal, and fixed, 2026-10-13: the bring-up build flooded its prompt
Built with `EMERGENCY_CONSOLE_ENABLED=1` and booted with no thumbdrive, the prompt printed
`ok> ok` without end: 1.4 million times in 200 seconds. The line reader
(`kernel/src/repl.c`, `sk_console_readline()`) gave up at once whenever no identity was logged
in, which the production build answers by going silent; the bring-up build took it as an
empty line and asked again. It now gives up only in the production build. Rehearsed on
riscv64 (`logs/20261013-235129`): one prompt, which waits, and three typed lines answered.
### 1.7 What I would close before the bench day
In this order, each as a design for approval first:
1. ~~R1 and M1: a console that finds its UART from the devicetree, and does nothing when
there is none.~~ Done 2026-10-13, and 1.6, the flood.
2. A6: the v4 switch in the board images. The v4 node needs only a console to reach a prompt;
it has no login, no fleet and no disk to wait for, so it is the shorter road to a first
prompt on each board.
3. A1: find the USB controller by its class code, not one vendor's number. That gives the SER5
thumbdrives. The Pi 5 and the Mars need R4 and M3 as well.
4. A serial cable for every board (section 2).
---
## 2. Before the day
**To have on the bench**
- [ ] A USB-to-serial adapter with 3.3 V logic levels, and jumper wires. It is the one channel
that survives a framebuffer failure, and with A3 it is the one way to type. FABRIC-3
decided HDMI only for the Pi 5 and the Mars because no adapter was to hand; that
decision is worth revisiting before the day.
- [ ] HDMI display and cable (micro-HDMI for the Pi 5).
- [ ] A USB stick for the SER5; a microSD card each for the Pi 5 and the Mars; a card reader.
- [ ] A PS/2 keyboard if the SER5 turns out to have a PS/2 port; otherwise serial.
- [ ] A camera, for the screen: when there is no serial log, photographs are the record.
- [ ] The identity thumbdrives (`disk/README.md`), once A1 is closed.
**To know before starting**
- [ ] SER5: Secure Boot is off (`FABRIC-3.md` III says it is on this unit); which key opens
the firmware's boot menu; whether there is a serial header.
- [ ] Pi 5: the EEPROM firmware is recent enough to honour `kernel_address` and `os_check`
(boot Raspberry Pi OS once and note the version).
- [ ] Mars: the SPI flash holds a U-Boot that scans the SD card for an EFI loader; the boot
switches select SPI flash. Stop U-Boot at its prompt once and save `printenv`, then
`fdt addr ${fdtcontroladdr}` and the output of `fdt print /soc/serial@10000000`: that
settles M1.
---
## 3. Build, and rehearse in QEMU
### 3.1 Build
```
make boot_image TARGET=PC EMERGENCY_CONSOLE_ENABLED=1
make boot_image TARGET=RASPI EMERGENCY_CONSOLE_ENABLED=1
make boot_image TARGET=MILKV EMERGENCY_CONSOLE_ENABLED=1
```
- [ ] ~~`make clean TARGET=<board>` first.~~ `make boot_image` now cleans its ISA's kernel
objects itself (2026-10-14): make does not see a change of compile flags, and an image
built over old objects booted headless (2026-10-13) or would have lacked v4.
- [ ] The images boot v4. To boot v3 instead: change `system=v4` to `system=v3` in
`starforth.cfg` (PC, Mars) or `cmdline.txt` (Pi 5) on the medium. The boot prints "System: ..." with the choice.
- [ ] Each ends with its image in `build/boards/<board>/`. Record `sha256sum` of each.
- [ ] Confirm the switch took: the image booted in QEMU (3.2) shows a prompt with no
thumbdrive attached. After a clean build it does (tried on `MILKV`).
- [ ] The Pi 5 build fetches the board's DTB once from the pinned firmware release; with no
network, pass `RPI5_DTB=/path/to/bcm2712-rpi-5-b.dtb`.
- [ ] Put back `v3/include/version.h` and `capsules/BLOCK_MAP.md` afterwards: the build
rewrites both.
### 3.2 Rehearse each image as its own disk
One QEMU at a time. Use a copy of the image: the kernel writes to its disk.
- [ ] **PC:** q35 with OVMF, the image as the only disk, no `-cdrom`, no virtio disk, no
thumbdrive. This is the machine the README's "booted in QEMU" refers to.
- [ ] **MILKV:** the command in `boards/milkv/README.md` (OpenSBI, U-Boot, `bootefi`).
- [ ] **RASPI:** there is no QEMU model of the Pi 5, but its native path -- raw image, entry
at EL2 with the MMU off, devicetree in x0 -- is rehearsed on QEMU virt:
`make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal`
(log under `logs/<TS>/aarch64-rpi5/`). Not rehearsed: the mailbox and framebuffer, the
Pi 5's own UART and GIC addresses (checked against its real devicetree by
`tools/fdt_uart_test.c` instead), and PCI (virt's needs ACPI, the Pi 5's is R4).
### 3.3 What to settle in the rehearsal
- [ ] With no virtio disk and no thumbdrive, how far does the v3 system get, and what does it
print? (A4. Not tried.)
- [ ] Note the verdict lines of that boot (section 5). They are what the board is compared
with.
- [ ] Type a line over the serial port. If it is not taken in QEMU it will not be on the
board.
---
## 4. On the bench
Do one board at a time, in this order: SER5, then the Mars, then the Pi 5. The SER5's path is
the one QEMU exercises most closely, and the Pi 5's can be rehearsed only in part (3.2).
### 4.1 Writing the media, every board
- [ ] `lsblk` before and after inserting the stick or card. Write down the device name and its
size. **`dd` to the wrong device destroys a disk.**
- [ ] `sudo dd if=build/boards/<board>/<image> of=/dev/sdX bs=4M conv=fsync status=progress`
- [ ] Read it back and compare: `sudo cmp -n $(stat -c %s <image>) <image> /dev/sdX`.
### 4.2 PC (the SER5)
- [ ] Serial, if there is a header: 115200 8N1, logged to a file from before power-on.
- [ ] HDMI and keyboard connected. Stick in a rear port.
- [ ] Power on, open the boot menu, choose the stick.
- [ ] Watch for, in order: `StarKernel UEFI Loader`; `GOP: linear framebuffer found`;
`LithosAnanke v...`; `PMM initialized.`; `VMM initialized`; `APIC: init done`;
`Timer: init done`; `Kernel heap initialized.`; `Stadium: ...`; POST; the verdict lines.
- [ ] `rng: backend = rdrand`. In QEMU it says `virtio-rng`; this line is new on hardware.
- [ ] The timer lines differ from QEMU's by design: no hypervisor, so the HPET path runs for
the first time. S1 is the finding to remember if it stops there.
### 4.3 Milk-V Mars
- [ ] Serial on the 40-pin header's UART, 115200 8N1, logged from before power-on. U-Boot
talks on it, so it shows whether the board reached U-Boot even if the kernel prints
nothing.
- [ ] Card in, HDMI connected, power on.
- [ ] U-Boot finds `EFI/BOOT/BOOTRISCV64.EFI` and starts it. If it does not, at its prompt:
`load mmc 1:1 ${kernel_addr_r} EFI/BOOT/BOOTRISCV64.EFI` then
`bootefi ${kernel_addr_r} ${fdtcontroladdr}` (the device number may differ: `mmc list`).
- [ ] The lines of 4.2, with `PLIC:` in place of `APIC:`. For the first time the interrupt
controller's address and the timer's frequency should come from the devicetree: the
QEMU lines "no DTB PLIC node" and "FALLBACK, no devicetree" should **not** appear.
- [ ] `satp.MODE` is printed at entry. Under U-Boot it may be 0 where QEMU shows `0xa`.
### 4.4 Raspberry Pi 5
- [ ] Serial on the debug connector between the HDMI ports (needs the Pi debug probe or a
matching cable), 115200 8N1. The firmware prints there before the kernel runs.
- [ ] Card in, HDMI in the port nearest the USB-C socket, power on.
- [ ] The firmware loads `kernel_2712.img` at `0x80000`. If the screen stays on the firmware's
diagnostic page, the firmware did not accept the image: note what it says.
- [ ] Then the lines of 4.2 from `LithosAnanke v...` on (there is no UEFI loader), with
`GICv2:` in place of `APIC:`. The line "no DTB GIC node -- using QEMU virt-machine
defaults" should **not** appear.
- [ ] Expect `PCI: MCFG parse failed on aarch64 -- no ECAM`: that is R4 and is not a failure
of the boot.
---
## 5. What counts as a pass
Record which level each board reached. A board is not "booted" on the strength of level 1.
| Level | What was seen | Compared with |
|---|---|---|
| 1 | The kernel's first line, on any channel | - |
| 2 | Every milestone line through `Kernel heap initialized.` | The QEMU log of the same build |
| 3 | `POST: PASSED` and `PARITY:OK` | The same test count as QEMU |
| 4 | The `PARITY:M7.1a` line's `word_count` and `hash` equal QEMU's for the same ISA | The rehearsal boot of 3.2 |
| 5 | A prompt, and a typed line answered: `1 2 + .` gives `3` | - |
| 6 | Entropy from hardware; an identity minted on a thumbdrive and attached again after a power cycle | The gates of `FABRIC-3.md` III, IV, V |
Level 4 is the one that says the board runs the same system as QEMU. Levels 5 and 6 wait on
section 1: today no board can reach 6, and only the SER5 with a serial header can reach 5.
For the v4 node, once A6 is built, the lines are `PARITY:V4_POST tests=538 pass=538 fail=0`,
`PARITY:V4_SYSTEM word_count=... dict_hash=...` equal to the hosted programs', `PARITY:OK`,
`POST: PASSED`, and the prompt `ok> `.
---
## 6. If it stops
| What is seen | Look at |
|---|---|
| Nothing at all, any board | Is the firmware reaching the image? Serial shows the firmware's own output on the Mars and the Pi 5. On the SER5, try the UEFI shell: `startup.nsh` is in the image. |
| Pi 5: firmware runs, then nothing | R1, then R2, then R3. |
| Mars: U-Boot starts the loader, then nothing on serial | M1. HDMI may still show the boot if M2 holds. |
| SER5: stops in the `Timer:` lines | S1. |
| Stops at `APIC` / `GICv2` / `PLIC` | The controller's address: S2 on the SER5; on the others, whether the devicetree node was found (the line says). |
| Runs through POST, then silence | A2: the build is headless. Rebuild with `EMERGENCY_CONSOLE_ENABLED=1`. |
| A prompt that takes no keys | A3. Type over serial. |
| `Artemis: no virtio-blk disk` | A4. Expected on every board today. |
| `rng: WARNING -- no entropy backend available` | A5. Expected on the Pi 5 and the Mars today. |
Write down the last line shown, exactly, and photograph the screen. Do not change two things
between attempts.
---
## 7. What to keep
- [ ] The serial transcript of every attempt, passed or failed, under `logs/` with the date,
the board and the image's `sha256` in its name. Logs are kept and committed, as QEMU's
are.
- [ ] Photographs of the screen where there was no serial.
- [ ] The firmware versions: SER5 BIOS, Pi 5 EEPROM, Mars U-Boot and OpenSBI.
- [ ] The Mars's `printenv` and devicetree, and the Pi 5's DTB as used.
- [ ] The results written into `FABRIC-3.md` (each section ends with "update this section with
results") and each board's `README.md` status line.
---
## 8. Before the builds are cut
The administrative work that is yours to call, listed so it is not found on the day:
- [ ] The kernel's release number. `kernel/Makefile` holds a table that gives each hardware
gate its own number (SER5, then the Pi 5, then the Mars); it is still to be ruled.
- [ ] The uncommitted change to `kernel/Makefile` that adds the ISA to the version line: it
needs a three-ISA acceptance run in the v3 configuration before it is committed.
- [ ] `CHANGELOG.md`: nothing between 2026-08-18 and the uncommitted entry of 2026-10-09.
- [ ] `sbom.spdx` and `sbom.spdx.json` brought up to date.
- [ ] The merge of `StarForth-v4.0.0` to `master`, and the tags `LithosAnanke v2.0.0` and
`StarForth v4.0.0`: only when you say.
- [ ] `.claude/CLAUDE.md` still describes the build before `boards/` existed.
boards/README.md
+3 -2
View File
@@ -6,7 +6,7 @@ that board's boot medium into `build/boards/<board>/`.
| TARGET | Directory | ISA | Boot path | Image |
|---|---|---|---|---|
| `SER5` | `ser5/` | amd64 | UEFI firmware, removable-media path | GPT + FAT32 ESP: `EFI/BOOT/BOOTX64.EFI` |
| `PC` | `pc/` | amd64 | UEFI firmware, removable-media path -- any x86-64 PC | GPT + FAT32 ESP: `EFI/BOOT/BOOTX64.EFI` |
| `RASPI` | `raspi/` | aarch64 | Pi 5 EEPROM firmware, native | MBR + FAT32: `config.txt`, `kernel_2712.img`, `bcm2712-rpi-5-b.dtb` |
| `MILKV` | `milkv/` | riscv64 | SPI-flash U-Boot + OpenSBI, `bootefi` | GPT + FAT32 ESP: `EFI/BOOT/BOOTRISCV64.EFI` |
| `ZYNQ7020` | `zynq7020/` | armv7 | BootROM, `BOOT.BIN`, U-Boot | not yet: needs `kernel/src/arch/armv7` |
@@ -24,6 +24,7 @@ devices. `KERNEL_ARGS="..."` is written as `starforth.cfg` (UEFI boards) or `cmd
image size; the default is 128.
Hardware status: none of these images has been booted on real silicon from this build. The
SER5 image has been booted in QEMU (q35 + OVMF, from its own disk) through POST. The Pi 5
PC image has been booted in QEMU (q35 + OVMF, from its own disk) through POST. (`PC` was named
`SER5` until 2026-10-14, after the first PC on the bench; the image was never specific to it.) The Pi 5
native path (`raspi/README.md`) and the JH7110 peripherals have still only been checked by
compiling.
boards/pc/README.md
+20
View File
@@ -0,0 +1,20 @@
# PC boot media (generic x86-64, UEFI)
`make boot_image TARGET=PC` builds `build/boards/pc/lithos-pc.img`: a GPT disk with one FAT32
EFI System Partition, for any x86-64 PC whose UEFI firmware boots a removable medium. Write it to
a USB stick with `dd`. The partition holds:
- `EFI/BOOT/BOOTX64.EFI`: the amd64 monolithic loader, with the whole kernel embedded. Firmware
finds it through the UEFI removable-media path, so no boot entry has to be created.
- `startup.nsh`: runs the loader if the firmware drops into the UEFI shell.
- `starforth.cfg`: the boot arguments -- `system=v4` as built; change the word to `system=v3` to
boot v3 (and `KERNEL_ARGS="..."` adds to it).
Beside the image, `lithos-pc.spdx` / `.spdx.json`: its SBOM, every file on it with its SHA-256.
Nothing in the image is specific to one machine: it follows the generic UEFI/ACPI path in
FABRIC-3.md §III. Until 2026-10-14 this target was named `SER5`, after the first PC to be brought
up -- a Beelink SER5 (AMD Ryzen), which is still the one on the bench (`boards/BRINGUP.md`).
Status: booted in QEMU (q35 + OVMF, from this image as its own disk): v4 as built, v3 with
`system=v3`. Not yet booted on real hardware.
boards/pc/board.mk
+12
View File
@@ -0,0 +1,12 @@
# boards/pc/board.mk -- a generic PC: x86-64, UEFI firmware, ACPI.
#
# Not one machine: the standards-compliant UEFI path (FABRIC-3.md §III), so
# any x86-64 PC whose firmware boots a UEFI removable medium. (The first to be
# brought up on the bench is a Beelink SER5, an AMD Ryzen mini-PC -- see
# boards/BRINGUP.md.) The monolithic loader embeds the whole kernel, so the
# image is a GPT disk with one FAT32 EFI System Partition holding
# EFI/BOOT/BOOTX64.EFI. Write it to a USB stick with dd.
BOARD_DESC := Generic PC (x86-64, UEFI, ACPI)
BOARD_ARCH := amd64
BOARD_BOOT := uefi-esp
BOARD_IMAGE := lithos-pc.img
boards/ser5/README.md
-14
View File
@@ -1,14 +0,0 @@
# Beelink SER5 boot media
`make boot_image TARGET=SER5` builds `build/boards/ser5/lithos-ser5.img`: a GPT disk with one
FAT32 EFI System Partition. Write it to a USB stick with `dd`. The partition holds:
- `EFI/BOOT/BOOTX64.EFI`: the amd64 monolithic loader, with the whole kernel embedded. Firmware
finds it through the UEFI removable-media path, so no boot entry has to be created.
- `startup.nsh`: runs the loader if the firmware drops into the UEFI shell.
- `starforth.cfg`: only present when `KERNEL_ARGS="..."` is given.
Nothing in the image is SER5-specific. It follows the generic UEFI/ACPI path in FABRIC-3.md §III.
Status: booted in QEMU (q35 + OVMF, from this image as its own disk) through POST, with Stadium
conservation exact (sum 65536 = `Q48_ONE`). Not yet booted on the SER5 itself.
boards/ser5/board.mk
-10
View File
@@ -1,10 +0,0 @@
# boards/ser5/board.mk -- Beelink SER5 (AMD Ryzen, x86-64, UEFI/ACPI).
#
# Generic standards-compliant UEFI path (FABRIC-3.md §III): nothing in the
# image is SER5-specific. The monolithic loader embeds the whole kernel, so
# the image is a GPT disk with one FAT32 EFI System Partition holding
# EFI/BOOT/BOOTX64.EFI. Write it to a USB stick with dd.
BOARD_DESC := Beelink SER5 (AMD Ryzen, x86-64, UEFI)
BOARD_ARCH := amd64
BOARD_BOOT := uefi-esp
BOARD_IMAGE := lithos-ser5.img
capsules/BLOCK_MAP.md
+78 -75
View File
@@ -1,5 +1,5 @@
# Capsule Block Manifest — Auto-generated
<!-- Generated by mkcapsule --manifest 2026-10-08T00:35:37Z -->
<!-- Generated by mkcapsule --manifest 2026-10-16T18:51:39Z -->
<!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh. -->
<!-- Hand-written justifications and immutability notes live -->
<!-- in MANIFEST.md alongside this auto-generated index. -->
@@ -10,7 +10,7 @@
|---------|----------------|----------|--------|
| `ACL.4th` | 4000, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 4015 | `0xf8890c05c0d8f921` | n/a |
| `acl-std79.4th` | 4023, 4024, 4025, 4026, 4027, 4028, 4029, 4030, 4031, 4032, 4033, 4034, 4035, 4036, 4037, 4038, 4039, 4040, 4041, 4042, 4043, 4044, 4045, 4046, 4047, 4048 | `0x773bf9209df191d1` | n/a |
| `artemis:init.4th` | 4110, 4111, 4112, 4113, 4122, 4123, 4124, 4125, 4126, 4127, 4128, 4129, 4130, 4131, 4132, 4133, 4134, 4135, 4136, 4137, 4138, 4139, 4140, 4141, 4160, 4161, 4162, 4163, 4164, 4165, 4166, 4167, 4168, 4169, 4170, 4171, 4172, 4173, 4174, 4177, 4178, 4179, 4180, 4181, 4182, 4851, 4852, 4853, 4854, 4856, 4857, 4858, 4860 | `0xe6fba9ae56e1c916` | n/a |
| `artemis:init.4th` | 4110, 4111, 4112, 4113, 4122, 4123, 4124, 4125, 4126, 4127, 4128, 4129, 4130, 4131, 4132, 4133, 4134, 4135, 4136, 4137, 4138, 4139, 4140, 4141, 4160, 4161, 4162, 4163, 4164, 4165, 4166, 4167, 4168, 4169, 4170, 4171, 4172, 4173, 4174, 4177, 4178, 4179, 4180, 4181, 4182, 4851, 4852, 4853, 4854, 4856, 4860 | `0x7ba120e2a6aab239` | n/a |
| `block-acl.4th` | 4019, 4020 | `0xf6cc2a59e3a6734e` | n/a |
| `doe-campaign.4th` | 4060, 4061, 4062, 4063, 4064, 4065 | `0x26fb485e5c9dc6ff` | n/a |
| `doe.4th` | 2100, 2101, 2102, 2103, 2104, 2105, 2106, 2107 | `0xf154616d248e861f` | n/a |
@@ -23,14 +23,16 @@
| `init-l8-temporal.4th` | 4830, 4831 | `0x51abd4c138246651` | n/a |
| `init-l8-transition.4th` | 4840, 4841, 4842 | `0xbcc1a81976f0a4c9` | n/a |
| `init-l8-volatile.4th` | 4810, 4811, 4812, 4813 | `0x98caabbbd92abac4` | n/a |
| `init.4th` | 2049, 2050, 2057 | `0xea038ba684c53443` | n/a |
| `init.4th` | 2049, 2050, 2057 | `0xd09db9461b336431` | n/a |
| `lib.4th` | 4050 | `0x4b216635c359ef73` | n/a |
| `multiuser-doe.4th` | 5044, 5045, 5046, 5047, 5048, 5049, 5050, 5051, 5052, 5053, 5054, 5055 | `0x22140588ee7c39e6` | n/a |
| `sdk.4th` | 5109, 5110, 5111, 5112, 5113, 5114, 5115 | `0x008fdbbb62c94a3a` | n/a |
| `turtle.4th` | 5100, 5101, 5102, 5103, 5104, 5105, 5106, 5107, 5108 | `0x4d470418ca543365` | n/a |
| `user-font-demo.4th` | 4200, 4201, 4202 | `0xce1fd7d1b581a56d` | n/a |
| `v4:centre.4th` | 8100, 8101, 8102, 8103, 8104, 8105, 8106, 8107, 8108 | `0x7b60682500afa138` | n/a |
| `v4:forth79.4th` | 6000, 6001, 6002 | `0x4055641ee17d176b` | n/a |
| `v4:hera.4th` | 8000, 8001, 8002, 8003, 8004, 8005, 8006 | `0x1c5ea12a9341e796` | n/a |
| `v4:hera.4th` | 8000, 8001 | `0xee06b95cae3e3bb4` | n/a |
| `v4:starshipos.4th` | 7000, 7001 | `0xb74bfa51f8d4719a` | n/a |
| `workload-0.4th` | 2200, 2201 | `0x93f86f60aeba8feb` | n/a |
| `workload-1-lite.4th` | 5058, 5059 | `0x44a7a7e3176dcc8d` | n/a |
| `workload-1.4th` | 4406, 4415, 4425, 4435 | `0x63e251adb0a03613` | n/a |
@@ -44,8 +46,7 @@
| `workload-8.4th` | 2160 | `0x56b7f2f0efa000df` | n/a |
| `workload-9.4th` | 4706, 4715, 4725, 4735, 4745 | `0x3f2bec73142aa424` | n/a |
| `workload-calib1.4th` | 5043 | `0x3b9f2d17b554fabc` | n/a |
| `zuse-eligibility.4th` | 4021, 4022 | `0x7b28f4776a32e0b7` | n/a |
| `zuse.4th` | 4016, 4017, 4018 | `0xa14d5a7a88791cf6` | n/a |
| `zuse.4th` | 4016, 4017, 4018 | `0x490ded9be257a90b` | n/a |
*Signed column is `n/a`: this manifest run had no `--sign-key`. Re-run with `--sign-key <path>` to check signing status (does not modify or require rebuilding capsule_generated.c).*
@@ -53,9 +54,9 @@
| LBN | Capsule | xxHash64 | Status |
|-----|---------|----------|--------|
| 2049 | `init.4th` | `0xea038ba684c53443` | ok |
| 2050 | `init.4th` | `0xea038ba684c53443` | ok |
| 2057 | `init.4th` | `0xea038ba684c53443` | ok |
| 2049 | `init.4th` | `0xd09db9461b336431` | ok |
| 2050 | `init.4th` | `0xd09db9461b336431` | ok |
| 2057 | `init.4th` | `0xd09db9461b336431` | ok |
| 2064 | `init-l8-omni.4th` | `0x5979e314d6452045` | ok |
| 2065 | `init-l8-omni.4th` | `0x5979e314d6452045` | ok |
| 2066 | `init-l8-omni.4th` | `0x5979e314d6452045` | ok |
@@ -113,13 +114,11 @@
| 4007 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
| 4008 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
| 4015 | `ACL.4th` | `0xf8890c05c0d8f921` | ok |
| 4016 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
| 4017 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
| 4018 | `zuse.4th` | `0xa14d5a7a88791cf6` | ok |
| 4016 | `zuse.4th` | `0x490ded9be257a90b` | ok |
| 4017 | `zuse.4th` | `0x490ded9be257a90b` | ok |
| 4018 | `zuse.4th` | `0x490ded9be257a90b` | ok |
| 4019 | `block-acl.4th` | `0xf6cc2a59e3a6734e` | ok |
| 4020 | `block-acl.4th` | `0xf6cc2a59e3a6734e` | ok |
| 4021 | `zuse-eligibility.4th` | `0x7b28f4776a32e0b7` | ok |
| 4022 | `zuse-eligibility.4th` | `0x7b28f4776a32e0b7` | ok |
| 4023 | `acl-std79.4th` | `0x773bf9209df191d1` | ok |
| 4024 | `acl-std79.4th` | `0x773bf9209df191d1` | ok |
| 4025 | `acl-std79.4th` | `0x773bf9209df191d1` | ok |
@@ -153,51 +152,51 @@
| 4063 | `doe-campaign.4th` | `0x26fb485e5c9dc6ff` | ok |
| 4064 | `doe-campaign.4th` | `0x26fb485e5c9dc6ff` | ok |
| 4065 | `doe-campaign.4th` | `0x26fb485e5c9dc6ff` | ok |
| 4110 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4111 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4112 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4113 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4122 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4123 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4124 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4125 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4126 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4127 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4128 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4129 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4130 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4131 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4132 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4133 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4134 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4135 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4136 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4137 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4138 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4139 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4140 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4141 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4160 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4161 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4162 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4163 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4164 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4165 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4166 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4167 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4168 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4169 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4170 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4171 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4172 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4173 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4174 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4177 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4178 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4179 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4180 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4181 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4182 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4110 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4111 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4112 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4113 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4122 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4123 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4124 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4125 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4126 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4127 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4128 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4129 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4130 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4131 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4132 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4133 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4134 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4135 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4136 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4137 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4138 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4139 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4140 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4141 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4160 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4161 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4162 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4163 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4164 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4165 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4166 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4167 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4168 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4169 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4170 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4171 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4172 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4173 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4174 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4177 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4178 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4179 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4180 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4181 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4182 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4200 | `user-font-demo.4th` | `0xce1fd7d1b581a56d` | ok |
| 4201 | `user-font-demo.4th` | `0xce1fd7d1b581a56d` | ok |
| 4202 | `user-font-demo.4th` | `0xce1fd7d1b581a56d` | ok |
@@ -235,14 +234,12 @@
| 4840 | `init-l8-transition.4th` | `0xbcc1a81976f0a4c9` | ok |
| 4841 | `init-l8-transition.4th` | `0xbcc1a81976f0a4c9` | ok |
| 4842 | `init-l8-transition.4th` | `0xbcc1a81976f0a4c9` | ok |
| 4851 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4852 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4853 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4854 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4856 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4857 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4858 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4860 | `artemis:init.4th` | `0xe6fba9ae56e1c916` | ok |
| 4851 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4852 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4853 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4854 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4856 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4860 | `artemis:init.4th` | `0x7ba120e2a6aab239` | ok |
| 4900 | `fabric.4th` | `0x9d9489cbeca4099b` | ok |
| 4901 | `fabric.4th` | `0x9d9489cbeca4099b` | ok |
| 4902 | `fabric.4th` | `0x9d9489cbeca4099b` | ok |
@@ -371,17 +368,23 @@
| 6000 | `v4:forth79.4th` | `0x4055641ee17d176b` | ok |
| 6001 | `v4:forth79.4th` | `0x4055641ee17d176b` | ok |
| 6002 | `v4:forth79.4th` | `0x4055641ee17d176b` | ok |
| 8000 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8001 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8002 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8003 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8004 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8005 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 8006 | `v4:hera.4th` | `0x1c5ea12a9341e796` | ok |
| 7000 | `v4:starshipos.4th` | `0xb74bfa51f8d4719a` | ok |
| 7001 | `v4:starshipos.4th` | `0xb74bfa51f8d4719a` | ok |
| 8000 | `v4:hera.4th` | `0xee06b95cae3e3bb4` | ok |
| 8001 | `v4:hera.4th` | `0xee06b95cae3e3bb4` | ok |
| 8100 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8101 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8102 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8103 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8104 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8105 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8106 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8107 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
| 8108 | `v4:centre.4th` | `0x7b60682500afa138` | ok |
## Conflicts
None.
---
*38 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
*39 capsule(s) scanned. Re-run `mkcapsule --manifest <dir>` to refresh.*
capsules/MANIFEST.md
+2 -2
View File
@@ -49,7 +49,7 @@ Blocks: **2049–2052, 2057**
| Block | Immutable | Justification |
|-------|-----------|---------------|
| 2049 | No | Hera VM init: `VM-TREE`/`VM-PARENT`/`VM-CHILDREN`; loads `ACL.4th`, `block-acl.4th`, `zuse-eligibility.4th`, `lib.4th`. **Corrected 2026-09-19 (three times)** — first pass removed a stale listing of `compudynamics`/`common:msg`/`fleet-k`/`process` (none loaded here; two already-deleted, two stripped in the same pass, FABRIC-3.6.md tasks 0.2/0.3). Second pass (same day): `fabric.4th`/`font.4th` **removed** from this list — relocated to `hestia/init.4th` (FABRIC-3.6.md tasks 1.6/1.7), Hera no longer loads either. Third pass (2026-09-22, FABRIC-3.6.md Phase 4 Stage E): `common:messaging.4th` + `MSG-CD-INIT` **removed** — the file itself is deleted (see "Deleted capsules" below); every FORTH-owned message type was cut over to kernel-Hermes first (Phase 3) |
| 2049 | No | Hera VM init: `VM-TREE`/`VM-PARENT`/`VM-CHILDREN`; loads `ACL.4th`, `block-acl.4th`, `lib.4th` (`zuse-eligibility.4th` removed 2026-10-14 with word-ACL elevation — FABRIC-3.md §XXXVII). **Corrected 2026-09-19 (three times)** — first pass removed a stale listing of `compudynamics`/`common:msg`/`fleet-k`/`process` (none loaded here; two already-deleted, two stripped in the same pass, FABRIC-3.6.md tasks 0.2/0.3). Second pass (same day): `fabric.4th`/`font.4th` **removed** from this list — relocated to `hestia/init.4th` (FABRIC-3.6.md tasks 1.6/1.7), Hera no longer loads either. Third pass (2026-09-22, FABRIC-3.6.md Phase 4 Stage E): `common:messaging.4th` + `MSG-CD-INIT` **removed** — the file itself is deleted (see "Deleted capsules" below); every FORTH-owned message type was cut over to kernel-Hermes first (Phase 3) |
| 2050 | No | BOOT-BANNER call — separated so the banner block can be swapped without touching init logic |
| 2051 | No | TRIPOD-TEST — 6 acceptance gates per TRIPOD.md. Dead EVENT-WAIT step replaced with HERMES-TICK liveness check (`3436d564`) |
| 2052 | No | TRIPOD-TEST invocation block |
@@ -350,7 +350,7 @@ three-architecture acceptance for the deletion: `logs/20260922-181141/amd64/`,
Phase 4 entry for the full account, including one found-not-fixed collateral
defect (`SEND-ELEVATE-REQUEST`, this file's own former caller into
`zuse-eligibility.4th`'s `ELEVATE-GRANT`, is now unreachable — Captain Bob's
2026-09-22 decision: leave it, Phase 8 PKI will build its own entrypoint).
2026-09-22 decision: leave it, Phase 8 PKI will build its own entrypoint). Removed 2026-10-14: elevation was ruled not needed, and `zuse-eligibility.4th` (blocks 4021–4022), its C words and the eligibility list went with it (FABRIC-3.md §XXXVII).
Former blocks 4100–4153 (ex-Artemis-gaps) are now UNASSIGNED — see Unassigned
Ranges below. The per-block justification table this section used to carry
(arena allocator ABI, message/channel field accessors, the VM-name routing
capsules/README.md
+1 -1
View File
@@ -34,6 +34,6 @@ Each block is limited to 1024 bytes. Verify with `wc -c` before committing.
## See also
- [`experiments/bare_metal/README.md`](../experiments/bare_metal/README.md) — DoE protocols and block namespace rules
- [`docs/03-architecture/word-acl/DESIGN.md`](../docs/03-architecture/word-acl/DESIGN.md) — ACL system design
- [`docs/reference/word-acl/DESIGN.md`](../docs/reference/word-acl/DESIGN.md) — ACL system design
- [`tools/mkcapsule.c`](../tools/mkcapsule.c) — assembles capsules into `capsule_generated.c`
- [Project root](../README.md)
capsules/artemis/init.4th
+12 -36
View File
@@ -498,47 +498,23 @@ Block 4854
STARTUP-BANNER
Block 4856
( Storage-attach ack builder. Hera sends "<dev-addr> )
( HERA-BLK-ATTACH-REQ"; reply is "<dev-addr> <ok?> )
( BLK-ATTACH-ACK" so identity birth only proceeds once )
( storage is confirmed (repl.c's BLK-ATTACH-ACK). Bob, )
( 2026-09-07. )
CREATE ATTACH-ACK-BUF 64 ALLOT
VARIABLE ATTACH-ACK-LEN
: ACK-APPEND ( src-addr len -- )
DUP >R
ATTACH-ACK-BUF ATTACH-ACK-LEN @ +
SWAP CMOVE
ATTACH-ACK-LEN @ R> + ATTACH-ACK-LEN ! ;
Block 4857
: ACK-APPEND-CHAR ( char -- )
ATTACH-ACK-BUF ATTACH-ACK-LEN @ + C!
ATTACH-ACK-LEN @ 1+ ATTACH-ACK-LEN ! ;
: ACK-APPEND-NUM ( n -- )
0 SWAP <# #S #> ACK-APPEND ;
Block 4858
( HERA-BLK-ATTACH-REQ ( dev-addr -- ): VM-EXEC'd by MSG- )
( DELIVER when Hera's request arrives. Runs BLK-ATTACH on )
( Artemis's own dictionary, then replies to Hera via kernel- )
( Hermes's KH-BLK-ATTACH-SEND (repl.c) -- FABRIC-3.6.md task )
( 3.8 Stage C, FORTH Hermes no longer sees this message type. )
( HERA-BLK-ATTACH-REQ, dev-addr -- : Hera's storage-attach )
( request, VM-EXEC'd into Artemis. Runs BLK-ATTACH here, then )
( replies with KH-BLK-ATTACH-SEND, dev-addr ok? -- sent? : )
( the kernel writes the reply text for Hera itself, from the )
( two numbers, for Artemis only -- so identity birth only )
( proceeds once storage is confirmed. Until 2026-10-14 )
( Artemis built that text here and the word sent any text )
( from any VM, which Hera ran as Zuse: FABRIC-3.md SXXXVII. )
: HERA-BLK-ATTACH-REQ ( dev-addr -- )
0 ATTACH-ACK-LEN !
DUP ACK-APPEND-NUM
BL ACK-APPEND-CHAR
DUP BLK-ATTACH ACK-APPEND-NUM
DROP
BL ACK-APPEND-CHAR
S" BLK-ATTACH-ACK" ACK-APPEND
ATTACH-ACK-BUF ATTACH-ACK-LEN @ KH-BLK-ATTACH-SEND DROP ;
DUP BLK-ATTACH KH-BLK-ATTACH-SEND DROP ;
Block 4860
( LOG-APPEND ( level ts msg-addr msg-u -- ) )
( FABRIC-3.md SXXVI follow-on Step 4, 2026-09-13: real per-VM )
( log persistence, reached via a sender's LOG-FLUSH/MSG-SEND )
( round trip, or by hand at the console for a smoke test. )
( log persistence, by hand at the console for a smoke test. )
( LOG-FLUSH does not come through here: since 2026-10-14 a )
( VM's records reach the ring in C, vm_log_buffer.c. )
( Thin wrapper -- kernel-only (LOG-APPEND-RAW) (log_words.c/ )
( log_region.c) does the real disk write; never calls )
( log_message() (see log_region.c's own doc comment on why). )
capsules/init.4th
-1
View File
@@ -15,7 +15,6 @@ Block 2049
: VM-CHILDREN ( -- ) ." (none)" CR ;
S" ACL.4th" EXEC
S" block-acl.4th" EXEC
S" zuse-eligibility.4th" EXEC
S" lib.4th" EXEC
( FABRIC-3.6.md Phase 4, Stage E: common:messaging.4th/ )
( MSG-CD-INIT removed -- no longer exists, no longer needed. )
capsules/v4/centre.4th
+117
View File
@@ -0,0 +1,117 @@
Block 8100
( centre.4th -- what a node that births others needs. )
( docs/v4.0.0/MESH.md 9a. Births follow v3: any node may )
( birth on its own ports, and is its children's parent. )
( The kernel's requests, by their numbers in manage.h: )
-6 KERNEL-WORD NODE-ME -7 KERNEL-WORD NODE-BORN
-8 KERNEL-WORD NODE-WIRE -9 KERNEL-WORD NODE-UNWIRE
-13 KERNEL-WORD NODE-PARITY -14 KERNEL-WORD CAPSULE-OPEN
-15 KERNEL-WORD CAPSULE-CELL -16 KERNEL-WORD CAPSULE-LINE
-17 KERNEL-WORD NODE-CHILD -18 KERNEL-WORD NODE-PLACE
( Text for another node is built in PAD. )
VARIABLE (T#)
: (T0) ( -- ) 0 (T#) ! ;
: (TC) ( c -- ) PAD (T#) @ + C! 1 (T#) +! ;
: (TS) ( baddr u -- )
DUP IF 0 DO DUP I + C@ (TC) LOOP DROP ELSE DROP DROP THEN ;
Block 8101
: (TN) ( n -- ) 0 <# #S #> (TS) 32 (TC) ;
: (T) ( -- baddr u ) PAD (T#) @ ;
( The node being born: its number, its place, the port of )
( this node that leads to it, its own port that leads here, )
( and its personality: a capsule's name, or none. )
VARIABLE (KID) VARIABLE (KID#) VARIABLE (KIDP)
VARIABLE (KIDC) VARIABLE (PERS) VARIABLE (PERS#)
: (FAIL) ( -- )
." BIRTH: node " (KID#) @ . ." did not do as it was told" CR
-1 NODE-ERROR ! ;
: (TOLD) ( how -- ) 1 - IF (FAIL) THEN ;
: (TELL) ( baddr u -- ) (KID#) @ SEND (KID#) @ AWAIT (TOLD) ;
Block 8102
( the system, a capsule of F18 code, cell by cell to its port )
: (NUCLEUS) ( -- )
S" v4:nucleus-64.f18" CAPSULE-OPEN 0= IF (FAIL) THEN
BEGIN CAPSULE-CELL WHILE (KIDP) @ PORT! REPEAT DROP ;
( a capsule of FORTH blocks, a line at a time )
: (LINES) ( baddr u -- ) CAPSULE-OPEN 0= IF (FAIL) THEN
BEGIN PAD CAPSULE-LINE DUP 0< 0= WHILE PAD SWAP (TELL) REPEAT
DROP ;
Block 8103
( The nodes this one has had born: for each its number and )
( the port of this node it is on. Sixteen at most. )
CREATE (KIDS) 32 ALLOT VARIABLE (KIDS#) 0 (KIDS#) !
: (KID@) ( i -- addr ) 2 * (KIDS) + ;
: (NOTE) ( number port -- )
(KIDS#) @ 16 < IF
(KIDS#) @ (KID@) SWAP OVER 1+ ! ! 1 (KIDS#) +!
ELSE DROP DROP THEN ;
: (WHICH) ( number -- i | -1 )
-1 SWAP (KIDS#) @ DUP IF 0 DO
DUP I (KID@) @ = IF SWAP DROP I SWAP THEN
LOOP ELSE DROP THEN DROP ;
: (UNLIST) ( i -- )
(KIDS#) @ 1- DUP (KIDS#) ! (KID@) DUP @ SWAP 1+ @
ROT (KID@) SWAP OVER 1+ ! ! ;
Block 8104
( Who it is, where its printing goes, which of its ports )
( leads to everything it is not told of, and who is there. )
: (WHO) ( -- )
(T0) (KID#) @ (TN) S" (ME) ! " (TS)
(CONSOLE) @ (TN) S" (CONSOLE) ! " (TS)
(KIDC) @ (TN) S" DEFAULT-ROUTE " (TS)
(ME) @ (TN) (KIDC) @ (TN) S" NEIGHBOUR" (TS)
(T) 0 (KIDP) @ SEND-ON (KID#) @ AWAIT (TOLD) ;
Block 8105
( number port childport baddr u -- place A NODE IS BORN, )
( its port childport joined to this one's port: empty, then )
( the system, FORTH-79, and its personality if u is not 0. )
: BIRTH-AS
(PERS#) ! (PERS) ! (KIDC) ! (KIDP) ! (KID#) !
(KID#) @ NODE-BORN DUP 0< IF (FAIL) THEN (KID) !
NODE-ME (KIDP) @ (KID) @ (KIDC) @ NODE-WIRE 0= IF (FAIL) THEN
(NUCLEUS)
(KID#) @ (KIDP) @ ROUTE (KID#) @ (KIDP) @ NEIGHBOUR (WHO)
S" v4:forth79.4th" (LINES)
(PERS#) @ IF (PERS) @ (PERS#) @ (LINES) THEN
S" (SEAL)" (TELL)
(KID) @ (KID#) @ NODE-PARITY
(KID#) @ (KIDP) @ (NOTE)
(KID) @ ;
Block 8106
( number port childport -- place a node with no capsule )
: BIRTH 0 0 BIRTH-AS ;
( Two outer nodes are joined: port 3 of X to port 4 of Y, )
( and each is told the other is there. )
VARIABLE (XP) VARIABLE (XN) VARIABLE (YP) VARIABLE (YN)
: (X) ( place number -- ) (XN) ! (XP) ! ;
: (Y) ( place number -- ) (YN) ! (YP) ! ;
: (SAY) ( them port me -- ) (KID#) !
(T0) OVER (TN) DUP (TN) S" ROUTE " (TS)
SWAP (TN) (TN) S" NEIGHBOUR" (TS) (T) (TELL) ;
: (JOIN) ( -- )
(XP) @ 3 (YP) @ 4 NODE-WIRE 0= IF (FAIL) THEN
(YN) @ 3 (XN) @ (SAY) (XN) @ 4 (YN) @ (SAY) ;
Block 8107
( n -- A UNIT: four outer nodes, n+1 to n+4, on ports 2 )
( to 5 of this one, each by its own port 2, and joined in a )
( square: 1-2, 2-4, 4-3, 3-1. )
VARIABLE (U)
VARIABLE (P1) VARIABLE (P2) VARIABLE (P3) VARIABLE (P4)
: (N) ( k -- number ) (U) @ + ;
: UNIT ( n -- ) (U) !
1 (N) 2 2 BIRTH (P1) ! 2 (N) 3 2 BIRTH (P2) !
3 (N) 4 2 BIRTH (P3) ! 4 (N) 5 2 BIRTH (P4) !
(P1) @ 1 (N) (X) (P2) @ 2 (N) (Y) (JOIN)
(P2) @ 2 (N) (X) (P4) @ 4 (N) (Y) (JOIN)
(P4) @ 4 (N) (X) (P3) @ 3 (N) (Y) (JOIN)
(P3) @ 3 (N) (X) (P1) @ 1 (N) (Y) (JOIN) ;
Block 8108
( n -- NODE n IS GONE: every node this one birthed is told, )
( as from this one, and n leaves the list if it was there. )
( The system calls this when it believes a GONE, through )
( GONE-HOOK in quit.f18; Hera calls it from KILL. )
: GONE-DOWN ( n -- )
DUP (WHICH) DUP 0< IF DROP ELSE (UNLIST) THEN
(KIDS#) @ DUP IF 0 DO DUP I (KID@) @ GONE LOOP
ELSE DROP THEN DROP ;
' GONE-DOWN (GONE-HOOK) !
capsules/v4/hera.4th
+28 -109
View File
@@ -1,111 +1,30 @@
Block 8000
( hera.4th -- Hera: the node that has the others born and )
( manages them. docs/v4.0.0/MESH.md sections 9 and 10. )
( She asks whoever holds the fabric for a node, wires it, )
( and sends it its capsules through the port that joins )
( them. The unit rule is here and nowhere else: four outer )
( nodes round a centre, an outer node wired only inside its )
( unit. )
( Text for another node is built in PAD. )
VARIABLE (T#)
: (T0) ( -- ) 0 (T#) ! ;
: (TC) ( c -- ) PAD (T#) @ + C! 1 (T#) +! ;
: (TS) ( baddr u -- )
DUP IF 0 DO DUP I + C@ (TC) LOOP DROP ELSE DROP DROP THEN ;
: (TN) ( n -- ) 0 <# #S #> (TS) 32 (TC) ;
: (T) ( -- baddr u ) PAD (T#) @ ;
Block 8001
( The node being born: its place in the fabric, the number )
( it is to have, and the port of this node that leads to it. )
VARIABLE (KID) VARIABLE (KID#) VARIABLE (KIDP)
: (FAIL) ( -- )
." BIRTH: node " (KID#) @ . ." did not do as it was told" CR
-1 NODE-ERROR ! ;
: (TOLD) ( how -- ) 1 - IF (FAIL) THEN ;
: (TELL) ( baddr u -- ) (KID#) @ SEND (KID#) @ AWAIT (TOLD) ;
( the nucleus, a capsule of F18 code, cell by cell to its port )
: (NUCLEUS) ( -- )
S" v4:nucleus-64.f18" CAPSULE-OPEN 0= IF (FAIL) THEN
BEGIN CAPSULE-CELL WHILE (KIDP) @ PORT! REPEAT DROP ;
( a capsule of FORTH blocks, a line at a time )
: (LINES) ( baddr u -- ) CAPSULE-OPEN 0= IF (FAIL) THEN
BEGIN PAD CAPSULE-LINE DUP 0< 0= WHILE PAD SWAP (TELL) REPEAT
DROP ;
Block 8002
( The nodes this one has had born: for each its number and )
( its place in the fabric. Sixteen at most. )
CREATE (KIDS) 32 ALLOT VARIABLE (KIDS#) 0 (KIDS#) !
: (KID@) ( i -- addr ) 2 * (KIDS) + ;
: (NOTE) ( number place -- )
(KIDS#) @ 16 < IF
(KIDS#) @ (KID@) SWAP OVER 1+ ! ! 1 (KIDS#) +!
ELSE DROP DROP THEN ;
( which of them has that number: its place in the list, or -1 )
: (WHICH) ( number -- i | -1 )
-1 SWAP (KIDS#) @ DUP IF 0 DO
DUP I (KID@) @ = IF SWAP DROP I SWAP THEN
LOOP ELSE DROP THEN DROP ;
Block 8003
( who it is, where its printing goes, and that everything )
( not told of goes by its port 2, where this node is )
: (WHO) ( -- )
(T0) (KID#) @ (TN) S" (ME) ! " (TS)
(CONSOLE) @ (TN) S" (CONSOLE) ! 2 DEFAULT-ROUTE " (TS)
(ME) @ (TN) S" 2 NEIGHBOUR" (TS)
(T) 0 (KIDP) @ SEND-ON (KID#) @ AWAIT (TOLD) ;
( number port -- place A NODE IS BORN on that port of )
( this one: empty, then the nucleus, then FORTH-79. )
: BIRTH ( number port -- place )
(KIDP) ! (KID#) !
NODE-BORN DUP 0< IF (FAIL) THEN (KID) !
NODE-ME (KIDP) @ (KID) @ 2 NODE-WIRE 0= IF (FAIL) THEN
(NUCLEUS)
(KID#) @ (KIDP) @ ROUTE (KID#) @ (KIDP) @ NEIGHBOUR (WHO)
S" v4:forth79.4th" (LINES)
Block 8004
S" (SEAL)" (TELL)
(KID) @ (KID#) @ NODE-PARITY
(KID#) @ (KID) @ (NOTE)
(KID) @ ;
( Two outer nodes are joined: port 3 of X to port 4 of Y, )
( and each is told the other is there. )
VARIABLE (XP) VARIABLE (XN) VARIABLE (YP) VARIABLE (YN)
: (X) ( place number -- ) (XN) ! (XP) ! ;
: (Y) ( place number -- ) (YN) ! (YP) ! ;
: (SAY) ( them port me -- ) (KID#) !
(T0) OVER (TN) DUP (TN) S" ROUTE " (TS)
SWAP (TN) (TN) S" NEIGHBOUR" (TS) (T) (TELL) ;
: (JOIN) ( -- )
(XP) @ 3 (YP) @ 4 NODE-WIRE 0= IF (FAIL) THEN
(YN) @ 3 (XN) @ (SAY) (XN) @ 4 (YN) @ (SAY) ;
Block 8005
( n -- A UNIT: four outer nodes, n+1 to n+4, on ports 2 )
( to 5 of this one, and joined in a square: 1-2, 2-4, 4-3, )
( 3-1. The corners across from each other are not wired: )
( what one sends the other goes by this node. )
VARIABLE (U)
VARIABLE (P1) VARIABLE (P2) VARIABLE (P3) VARIABLE (P4)
: (N) ( k -- number ) (U) @ + ;
: UNIT ( n -- ) (U) !
1 (N) 2 BIRTH (P1) ! 2 (N) 3 BIRTH (P2) !
3 (N) 4 BIRTH (P3) ! 4 (N) 5 BIRTH (P4) !
(P1) @ 1 (N) (X) (P2) @ 2 (N) (Y) (JOIN)
(P2) @ 2 (N) (X) (P4) @ 4 (N) (Y) (JOIN)
(P4) @ 4 (N) (X) (P3) @ 3 (N) (Y) (JOIN)
(P3) @ 3 (N) (X) (P1) @ 1 (N) (Y) (JOIN) ;
Block 8006
( n -- KILL: node n is removed, whatever it was doing. )
( This node forgets the way to it, and every other node it )
( has had born is told that n is gone: each forgets its way )
( to n, and one that is waiting for n's answer stops. )
( docs/v4.0.0/MESH.md 7b.5. As v3's KILL, by number. )
: (UNLIST) ( i -- )
(KIDS#) @ 1- DUP (KIDS#) ! (KID@) DUP @ SWAP 1+ @
ROT (KID@) SWAP OVER 1+ ! ! ;
( hera.4th -- what is Hera's alone, beside centre.4th, which )
( she loads first. docs/v4.0.0/MESH.md 9a. She decides )
( which nodes there are and which are awake: KILL, PAUSE and )
( RESUME, by number, through the kernel's registry, are hers )
( and no other node's, as v3's KILL is Hera's alone. )
-10 KERNEL-WORD NODE-SLEEP -11 KERNEL-WORD NODE-WAKE
-12 KERNEL-WORD NODE-KILL
( n -- n flag a node there is, and not Hera herself )
: (THERE?) DUP (ME) @ = 0= OVER NODE-PLACE 0< 0= AND ;
: (NO-NODE) ( n -- ) DROP ." no such node" CR -1 NODE-ERROR ! ;
( n -- KILL: node n is removed, whatever it was doing; this )
( node forgets the way to it, and GONE goes down the graph. )
: KILL ( n -- )
DUP (WHICH) DUP 0< IF
DROP DROP ." KILL: no such node" CR -1 NODE-ERROR ! THEN
DUP (KID@) 1+ @ NODE-KILL (UNLIST)
DUP NO-ROUTE
(KIDS#) @ DUP IF 0 DO DUP I (KID@) @ GONE LOOP ELSE DROP THEN
DROP ;
(THERE?) 0= IF ." KILL: " (NO-NODE) THEN
DUP NODE-KILL DUP NO-ROUTE GONE-DOWN ;
Block 8001
: PAUSE ( n -- )
(THERE?) 0= IF ." PAUSE: " (NO-NODE) THEN NODE-SLEEP ;
: RESUME ( n -- )
(THERE?) 0= IF ." RESUME: " (NO-NODE) THEN NODE-WAKE ;
( n -- a unit is removed: each of n's children, then n )
: UNIT-KILL ( n -- )
BEGIN DUP 0 NODE-CHILD ?DUP WHILE KILL REPEAT KILL ;
( n -- A SECOND CENTRE, node n, from its port 6 to Hera's )
( port 6, given centre.4th; it births its unit, n+1 to n+4. )
: CENTRE ( n -- )
DUP 6 6 S" v4:centre.4th" BIRTH-AS DROP
5 1 DO DUP I + 6 ROUTE LOOP DROP
(T0) (KID#) @ (TN) S" UNIT" (TS) (T) (TELL) ;
capsules/v4/nucleus-64.f18
BIN
View File
Binary file not shown.
capsules/v4/rom/dir.f18
+145
View File
@@ -0,0 +1,145 @@
\ dir.f18 -- the ROM's directives, and the end of the system's source.
\
\ What the prebuilt nucleus's mkimage.c (gone) and text.c's header did in C
\ is said in the source with
\ these (MACHINE.md, the ROM's language). Each is a machine notion -- an
\ address, a cell, a value -- and none is FORTH.
\ constant NAME VALUE NAME is the number VALUE
\ set NAME VALUE an assembler variable: may be set again
\ #, VALUE one cell of data at the next word address
\ ", TOKEN TOKEN, whatever its characters, as a counted string
\ store ADDR VALUE ADDR := VALUE, anywhere in RAM
\ start NAME the end: every branch must have its target; the
\ tables the ROM used are cleared; then NAME runs
\ A VALUE is a number, a constant, a set variable, CONST+N, here (the next
\ word address) or &NAME of a word already defined.
\ ( -- v 1 | 0 0 ) the token as a VALUE; "not a value" if it is none
: (VALUE)
(NUMBER) if NN
-if NUMOK drop drop ERR-BIG (FAIL) 0 0 ;
NUMOK: drop 1 ;
NN: drop drop
&(RESERVED) (WALK) 8 xor if HR drop
0 (CHAR@) 38 xor if AMPV drop
(FIND) if NOSYM
dup 2 + a! @ 2 xor if CV drop
dup 2 + a! @ 4 xor if CV drop
drop jump BAD
CV: drop 3 + a! @ 1 ;
NOSYM: drop
(CONST+N) if BAD0 ;
BAD0: drop drop
BAD: ERR-VALUE (FAIL) 0 0 ;
HR: drop (LABEL) 1 ;
AMPV: drop (TOKN) a! @ -1 + if ONEV drop
(TOK-SAVE) 1 (MLEN) a! @ -1 + (TOK-SUB)
(FIND) if BADA
dup 2 + a! @ 1 xor if OKA drop drop jump BADA0
OKA: drop 3 + a! @ 1 ;
BADA: drop
BADA0: ERR-AMP (FAIL) 0 0 ;
ONEV: drop jump BAD
\ ( -- v 1 | 0 0 ) the next token as a VALUE
: (NEXT-VALUE)
(NEXT-TOKEN) if MISS drop jump (VALUE)
MISS: drop (MISSING) 0 0 ;
: (H-CONSTANT)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-TOKEN) if MISS drop
(TOK) (TSAVE) 16 (COPY)
(NEXT-TOKEN) if MISS drop
(NUMBER) if NAN
-if NUM drop drop ERR-BIG jump (FAIL)
NUM: drop (NAME-BACK) 2 jump (DEFINE)
NAN: drop drop ERR-VALUE jump (FAIL)
MISS: drop jump (MISSING)
: (H-SET)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-TOKEN) if MISS drop
(TOK) (TSAVE) 16 (COPY)
(NEXT-VALUE) if BADV drop
(NAME-BACK) 4 jump (DEFINE)
BADV: drop drop ;
MISS: drop jump (MISSING)
\ here alone is not something to assemble: only a VALUE
: (H-HERE) ERR-TARGET jump (FAIL)
: (H-CELL)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-VALUE) if BADV drop
(LABEL) drop jump (EMIT)
BADV: drop drop ;
: (H-STRING)
(IN-MACRO?) if OK drop ;
OK: drop
(RAW-TOKEN) if MISS drop
(LABEL) drop
(TOKN) a! @ 4 + 2/ 2/ (T1) a! ! 0 (T2) a! !
L: (T2) a! @ (T1) a! @ xor if D drop
(T2) a! @ (TOK) + a! @ (EMIT)
(T2) a! @ 1 + ! jump L
D: drop ;
\ text.c says "without a string, or one too long" for both: missing
MISS: drop ERR-MISSING jump (FAIL)
\ store ADDR VALUE: ADDR must be in RAM, as text.c requires
: (H-STORE)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-VALUE) if BADV drop (T1) a! !
(NEXT-VALUE) if BADV drop
(T1) a! @ -if LO
drop drop ERR-RANGE jump (FAIL)
LO: RAM-WORDS inv 1 + + -if HI
drop (T1) a! @ b! !b ;
HI: drop drop ERR-RANGE jump (FAIL)
BADV: drop drop ;
\ ( -- ) clear the tables the ROM uses only while it assembles: the symbol
\ table in dictionary space, the branches, labels and names in the block
\ window, the saved token and macro body in the text input buffer
: (CLEAR)
DICT-W a! DICT-END DICT-W inv 1 + + -1 + FOR 0 !+ NEXT
BUF0 a! 1023 FOR 0 !+ NEXT
TIB-W a! 259 FOR 0 !+ NEXT
0 (RECN) a! ! 0 (POOLN) a! ! 0 (NREF) a! ! 0 (NLAB) a! !
0 (WNP) a! ! 0 (NFOR) a! ! 0 (RDEPTH) a! ! ;
\ start NAME: the system's source has ended; NAME, a word, is where it starts
: (H-START)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-TOKEN) if MISS drop
(TOK) (TSAVE) 16 (COPY)
(END-WORD)
(FAILED) a! @ if F0 drop ;
F0: drop
(NREF) a! @ if NOREF drop
ERR-UNDEFINED (FAIL) (REFS) 1 + a! @ (ERRLINE) a! ! ;
NOREF: drop
(LABEL) drop
(NAME-BACK)
(FIND) if NOTW
dup 2 + a! @ 1 xor if ISW drop drop jump NOTW0
ISW: drop 3 + a! @ (T1) a! !
\ nothing may follow start but blanks, comments and the ends of blobs,
\ up to the end of all
A1: (TOKEN) if A2
drop ERR-AFTER jump (FAIL)
A2: drop (FAILED) a! @ if A3 drop ;
A3: drop (EOF) a! @ if A1 drop
(CLEAR)
0 DSTACK-REG a! ! 0 RSTACK-REG a! !
(T1) a! @ push ;
NOTW: drop
NOTW0: ERR-START jump (FAIL)
MISS: drop jump (MISSING)
capsules/v4/rom/in.f18
+125
View File
@@ -0,0 +1,125 @@
\ in.f18 -- the ROM's input: characters from the console, and tokens.
\
\ The text the ROM assembles arrives at the console's receive registers,
\ a character at a time. Each blob of it ends with a new line and FS (28,
\ V4_ROM_BLOB_END), where a file ends for text.c: a comment still open there
\ is an error, and (TOKEN) gives 0 there as at the end. The end of all of
\ it is EOT (4), which the loader sends after the last blob. A token is what v4/src/text.c's next_token makes
\ of the same text: blanks are space, tab, CR and LF; a token is at most 63
\ characters; `\` as a whole token skips to the end of the line, and `(` as a
\ whole token to the next `)`.
\
\ State, in the ROM's area of the memory map (MACHINE.md 2.1):
\ (TOK) the token, as a counted string: its count byte, then its
\ characters, four to a cell, low byte first, zero-padded --
\ the form `",` lays down and (FIND) compares; 16 cells
\ (TOKN) its length
\ (PEEK) a character put back, plus one; 0: none
\ (LINE) how many new lines have been read
\ (EOF) non-zero once EOT has been read
\ (FAILED) 0, or the code of the error that stopped the ROM
\ (ERRLINE) (LINE) when it failed
\ (RAW) 1 while a token is read raw: ( and \ are then names
\ Every routine here uses A.
\ ( -- c ) wait for a character, then take it
: (KEY)
W: CONSOLE-STATUS a! @ if Z drop CONSOLE-RX a! @ ;
Z: drop jump W
\ ( -- c ) the character put back, if there is one; else the next
: (GETC)
(PEEK) a! @ if NONE 0 ! -1 + ;
NONE: drop jump (KEY)
\ ( c -- ) put a character back, to be the next one read
: (BACK) 1 + (PEEK) a! ! ;
\ ( -- ) one more new line
: (LF+) (LINE) a! @ 1 + ! ;
\ ( code -- ) stop with an error, noting the line
: (FAIL) (FAILED) a! ! (LINE) a! @ (ERRLINE) a! ! ;
\ ( -- ) "missing": a name, a target or a value was wanted and there is
\ none -- unless an error came first, a token too long or a comment not
\ closed, which stands, as text.c's first error does
: (MISSING)
(FAILED) a! @ if M drop ;
M: drop ERR-MISSING jump (FAIL)
\ ( c -- ) one more character of the token: byte (TOKN)+1 of (TOK), into
\ a cell whose byte there is still zero
: (PUT)
(TOKN) a! @ 1 +
dup 2/ 2/ (TOK) + push
3 and
S: if SD push 2* 2* 2* 2* 2* 2* 2* 2* pop -1 + jump S
SD: drop pop a! @ xor !
(TOKN) a! @ 1 + ! ;
\ ( i -- c ) character i of the token, from 0
: (CHAR@)
1 + dup 2/ 2/ (TOK) + a! @
push 3 and
S: if SD -1 + pop 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ push jump S
SD: drop pop 255 and ;
\ ( -- len ) the next token into (TOK), its length into (TOKN). 0: the end
\ of a blob, the end of all ((EOF) set), or an error, which is in (FAILED).
: (TOKEN)
(EOF) a! @ if GO drop 0 ;
GO: drop
SKIP: (GETC)
dup 4 xor if END
drop dup 28 xor if BLOB
drop dup 10 xor if NL
drop dup 32 xor if SP
drop dup 9 xor if SP
drop dup 13 xor if SP
drop 0 (TOKN) a! !
(TOK) a! 15 FOR 0 !+ NEXT
READ: (TOKN) a! @ 63 xor if LONG
drop (PUT) (GETC)
dup 4 xor if TEND
drop dup 28 xor if TEND
drop dup 10 xor if TEND
drop dup 32 xor if TEND
drop dup 9 xor if TEND
drop dup 13 xor if TEND
drop jump READ
TEND: drop (BACK)
(TOKN) a! @ (TOK) a! @ xor !
(RAW) a! @ if COOKED drop (TOKN) a! @ ;
COOKED: drop
(TOKN) a! @ 1 xor if ONE
drop (TOKN) a! @ ;
ONE: drop 0 (CHAR@)
dup 92 xor if BSL
drop dup 40 xor if PAREN
drop drop 1 ;
BSL: drop drop
B1: (GETC)
dup 10 xor if BEND
drop dup 28 xor if BEND
drop dup 4 xor if BEND
drop drop jump B1
BEND: drop (BACK) jump SKIP
PAREN: drop drop
P1: (GETC)
dup 41 xor if PCLOSE
drop dup 10 xor if PNL
drop dup 28 xor if PEOF
drop dup 4 xor if PEOF
drop drop jump P1
PNL: drop drop (LF+) jump P1
PCLOSE: drop drop jump SKIP
PEOF: drop drop ERR-COMMENT (FAIL) 0 ;
END: drop drop 1 (EOF) a! ! 0 ;
BLOB: drop drop 0 ;
NL: drop drop (LF+) jump SKIP
SP: drop drop jump SKIP
LONG: drop drop ERR-TOO-LONG (FAIL) 0 ;
\ ( -- len ) the next token, raw: ( and \ are names, not comments
: (RAW-TOKEN) 1 (RAW) a! ! (TOKEN) 0 (RAW) a! ! ;
capsules/v4/rom/main.f18
+54
View File
@@ -0,0 +1,54 @@
\ main.f18 -- the ROM's entry table.
\
\ docs/v4.0.0/MACHINE.md 2.1. The ROM is shared code: a payload calls its
\ routines through this table and never to an address inside the ROM, so a
\ rebuilt ROM breaks no payload. It is at the ROM's base, one jump a word,
\ in a fixed order that only ever grows at its end. Entry i is at the ROM's
\ base plus i. Entries 0-5 are the shared math, the same in a mesh node's
\ ROM (mesh.f18, MACHINE.md 2.2). DATASHEET-F18.md lists each routine's
\ stack effect.
: (ENTRIES)
(MATH-ENTRIES) \ 0-5 the shared math (math.f18; v4/rom_entries.h)
jump (KEY) \ 6 ( -- c )
jump (TOKEN) \ 7 ( -- len )
jump (NUMBER) \ 8 ( -- n flag )
jump (FIND) \ 9 ( -- rec | 0 )
jump (DEFINE) \ 10 ( value kind -- )
jump (OPCODE) \ 11 ( -- op | -1 )
jump (OP) \ 12 ( op -- )
jump (LIT) \ 13 ( v -- )
jump (BRANCH) \ 14 ( op target -- )
jump (BRANCH>) \ 15 ( op -- ref )
jump (RESOLVE) \ 16 ( ref target -- )
jump (LABEL) \ 17 ( -- addr )
jump (ROM) \ 18 the ROM itself: where the machine starts (V4_ROM_START)
\ ( -- ) the state the ROM begins from: code goes to ORIGIN, nothing read,
\ nothing defined
: (INIT)
(CLEAR)
ORIGIN (HERE) a! ! 0 (CUR) a! ! 0 (SLOT) a! ! 0 (NLIT) a! !
0 (FAILED) a! ! 0 (ERRLINE) a! ! 0 (LINE) a! ! 0 (EOF) a! !
0 (PEEK) a! ! 0 (RAW) a! ! ;
\ the ROM: assemble the system's source from the console, blob by blob,
\ until its start runs it; on an error, stop at (ROM-FAILED) with the error's code in
\ (FAILED) and its line in (ERRLINE), for the loader to report
: (ROM)
(INIT)
L: (NEXT-TOKEN) if END drop
(ONE)
(FAILED) a! @ if L0 drop jump (ROM-FAILED)
L0: drop jump L
END: drop
(FAILED) a! @ if NS drop jump (ROM-FAILED)
NS: drop (EOF) a! @ if BLOB drop ERR-NO-START (FAIL) jump (ROM-FAILED)
\ the end of a blob: the word being assembled ends, as at the end of a
\ file for text.c
BLOB: drop (END-WORD)
(FAILED) a! @ if L0 drop jump (ROM-FAILED)
: (ROM-FAILED)
H: jump H
capsules/v4/rom/math.f18
+143
View File
@@ -0,0 +1,143 @@
\ math.f18 -- the ROM's shared math (docs/v4.0.0/MACHINE.md 2.2).
\
\ Six routines a payload calls through the ROM's entry table, as a GA144
\ application calls its node ROM's multiply and divide steps, and their
\ helpers. Both ROMs carry them: the host node's and a mesh node's. They
\ were the system's (capsules/v4/sys: core.f18, numout.f18, qmath.f18) and
\ do exactly what they did there; the system's words of those names now call
\ these. No names, no headers, no FORTH.
\
\ Constants from the map (tools/mkmap.c): N-1 NODE-ERROR MSB MAXHI 2N+15
\ N-18 N-17, and (Q/), Q./'s five scratch cells, fixed in the memory map
\ (MACHINE.md 2.1).
\
\ ERRORS. Q./ by zero leaves the result D-11 gives and stores 11, "Division
\ by zero", into NODE-ERROR (D-18).
macro SWAP over push push drop pop pop endmacro
macro - push inv pop + inv endmacro \ x y -- x-y
macro NIP push drop pop endmacro
macro ROT push SWAP pop SWAP endmacro
macro OR over inv and xor endmacro
\ ( u1 u2 -- ulo uhi ) entry 0
: (UM*)
over 1 and inv 1 + over 2/ and \ u1 u2 t0 t0 = u2 2/ if u1 odd
over a! N-1 push \ A: u2 R: loop count
push over 2/ pop \ u1 u2 s t0 s = u1 2/
L: +* unext \ u1 u2 s hi A: lo
push drop pop \ u1 u2 hi
2* a -if L0 drop 1 + jump L1 L0: drop L1: push
over -if L2 drop dup jump L3 L2: drop 0 L3: push
dup -if L4 drop over 1 and jump L5 L4: drop 0 L5:
pop + pop + push
and 1 and a 2* + pop ;
\ ( ulo uhi ud -- urem uquot ) entry 1. One step a bit, the divisor in
\ A. Exact for uhi < ud.
: (UM/MOD)
a! N-1 FOR
-if L0
2* over -if L1 drop 1 + jump L2
L1: drop L2: push 2* pop
jump SUB
L0:
2* over -if L3 drop 1 + jump L4
L3: drop L4: push 2* pop
dup a xor -if L5
drop -if NOSUB jump SUB
L5: drop dup inv a + inv -if L6
drop jump NOSUB
L6: push drop pop jump SETBIT
SUB: inv a + inv
SETBIT: push 1 + pop
NOSUB:
NEXT
over push push drop pop pop ;
\ ( d1 d2 -- d3 ) entry 2
: (D+)
push over push push drop pop \ al bl R: bh ah
over over xor -if L1
drop + -if C1 jump C0
L1: drop over -if L2
drop + jump C1
L2: drop +
C0: pop pop + ;
C1: pop pop + 1 + ;
\ ( d -- -d ) entry 3
: (DNEGATE)
inv over if L1 drop push inv 1 + pop ;
L1: drop 1 + ;
\ ( q -- n ) the system's Q.TO-INT, which Q.* needs
: (Q>INT) push a! 0 pop 15 FOR +* UNEXT drop drop a ;
\ ( a b -- c ) entry 4
: (Q.*)
SWAP push over over (UM*) drop
push push over pop
-if L1 SWAP jump L2 L1: SWAP drop 0 L2:
pop SWAP - push
push over pop (UM*) pop +
ROT pop dup push
over -if L3 drop dup jump L4 L3: drop 0 L4:
push (UM*) pop - (D+)
ROT pop (UM*)
SWAP push 0 (D+) pop
push over pop SWAP (Q>INT) push (Q>INT) pop SWAP ;
: (QERR11) NODE-ERROR b! 11 !b ;
: (D2*C) ( lo hi cin -- lo' hi' cout )
a! dup -if L1 drop 1 jump L2 L1: drop 0 L2: push
over -if L3 drop 1 jump L4 L3: drop 0 L4:
over + +
push 2* a + pop pop ;
: (UQ/) ( a0 a1 b0 b1 -- q0 q1 )
(Q/)+2 a! SWAP !+ ! (Q/) a! SWAP !+ ! 0 0 0
2N+15 FOR
push (Q/) a! @+ @ pop (D2*C)
push (Q/)+1 a! ! (Q/) a! ! pop (D2*C)
if CMP drop jump TAKE
CMP: drop (Q/)+3 b! @b
over over xor if EQH -if SAMEH
drop drop -if NT1 jump TAKE NT1: jump NOTAKE
SAMEH: drop over SWAP push inv pop + inv
-if T2 drop jump NOTAKE T2: drop jump TAKE
EQH: drop drop over (Q/)+2 b! @b
over over xor -if SAMEL
drop drop -if NT3 drop jump TAKEL NT3: drop jump NOTAKEL
SAMEL: drop push inv pop + inv
-if T4 drop jump NOTAKEL T4: drop jump TAKEL
TAKEL: drop (Q/)+2 b! @b push inv pop + inv 0 1 jump END
NOTAKEL: 0 jump END
TAKE: push (Q/)+2 b! @b over over push inv pop + inv push
over over xor -if SB drop NIP -if NB drop 1 jump BD NB: drop 0 jump BD
SB: drop push inv pop + inv -if NB2 drop 1 jump BD NB2: drop 0
BD: pop pop (Q/)+3 b! @b push inv pop + inv
push SWAP pop SWAP - 1 jump END
NOTAKE: 0
END:
NEXT
push (Q/) a! @+ @ pop (D2*C) drop push push drop drop pop pop ;
: (Q./) ( a b -- q ) \ entry 5
over over OR if ZERO drop
push over pop SWAP over xor (Q/)+4 b! !b
-if L1 (DNEGATE) L1: push push -if L2 (DNEGATE) L2: pop pop
dup if CHK drop jump DIV
CHK: drop over -131072 and if CHK2 drop jump DIV
CHK2: drop push push dup pop dup push N-18 FOR 2* UNEXT
over over xor -if SAME drop drop -if NOOV jump OV
SAME: drop push inv pop + inv -if OV
NOOV: drop pop pop jump DIV
OV: drop drop drop pop pop drop drop
(Q/)+4 b! @b -if OVP drop 0 MSB ; OVP: drop -1 MAXHI ;
DIV: (UQ/) (Q/)+4 b! @b -if L3 drop (DNEGATE) ; L3: drop ;
ZERO: drop drop drop
over over OR if Z0 drop -if ZP drop drop 0 MSB jump (QERR11)
ZP: drop drop -1 MAXHI jump (QERR11)
Z0: drop jump (QERR11)
capsules/v4/rom/mesh.f18
+10
View File
@@ -0,0 +1,10 @@
\ mesh.f18 -- a mesh node's ROM: its entry table (docs/v4.0.0/MACHINE.md 2.2).
\
\ A mesh node's ROM is the shared math (math.f18) and nothing else. It has
\ no start: a mesh node at reset blocks on its ports and executes what
\ arrives (docs/v4.0.0/MESH.md 4.2 and 5). Its entries are the first of
\ the host ROM's, at the same numbers: (MATH-ENTRIES), which tools/mkmap.c
\ writes from v4/include/v4/rom_entries.h.
: (ENTRIES)
(MATH-ENTRIES)
capsules/v4/rom/num.f18
+67
View File
@@ -0,0 +1,67 @@
\ num.f18 -- the ROM reads numbers.
\
\ (NUMBER) ( -- n flag ) looks at the token (TOKEN) read, as v4/src/text.c's
\ number_of does: decimal with an optional leading `-`, or hexadecimal after
\ `$` (a-f in either case). flag 1: the whole token is a number, n its
\ value; 0: it is not one; -1: it is one, and does not fit a cell, read as
\ signed or as unsigned. A token that has a character that is not a digit
\ is not a number, even when its digits so far did not fit.
\
\ State, in the ROM's area (MACHINE.md 2.1): (NBASE) 10 or 16, (NNEG) 1 after
\ a `-`, (NI) the next character, (NU) the value so far, unsigned, (NBIG) 1
\ once it has not fitted. Width constants from the map: MSB, the cell's top
\ bit; DEC-LIMIT, the largest unsigned cell over 10; DEC-NLAST, minus one
\ more than its remainder; HEX-HIGH, the top four bits. Uses A. The
\ token's characters are read with in.f18's (CHAR@).
\ ( c -- d | -1 ) the digit c is in the base, or -1
: (DIGIT)
dup -48 + -if D1 drop drop -1 ; \ below '0'
D1: dup -10 + -if D2 drop push drop pop ; \ '0' .. '9'
D2: drop drop
(NBASE) a! @ 16 xor if HEXL drop drop -1 ;
HEXL: drop
dup -97 + -if LOW drop
dup -65 + -if UP drop drop -1 ; \ below 'A'
UP: dup -6 + -if BAD drop push drop pop 10 + ;
LOW: dup -6 + -if BAD drop push drop pop 10 + ;
BAD: drop drop drop -1 ;
\ ( d -- ) (NU) := (NU) * base + d, or (NBIG) := 1 if that does not fit
: (ACC)
(NU) a! @
(NBASE) a! @ 16 xor if X16 drop
dup -if DPOS drop jump DBIG \ the top bit is set
DPOS: drop
dup inv 1 + DEC-LIMIT + -if DLE drop jump DBIG
DLE: if DEQ drop jump MUL10
DEQ: drop over DEC-NLAST + -if DBIG3 drop jump MUL10
DBIG3: drop
DBIG: 1 (NBIG) a! ! drop drop ;
MUL10: 2* dup 2* 2* + + (NU) a! ! ;
X16: drop
dup HEX-HIGH and if HOK drop jump DBIG
HOK: drop 2* 2* 2* 2* + (NU) a! ! ;
\ ( -- n flag )
: (NUMBER)
0 (NBIG) a! ! 0 (NNEG) a! ! 0 (NU) a! ! 0 (NI) a! ! 10 (NBASE) a! !
0 (CHAR@)
dup 36 xor if HEX drop
dup 45 xor if NEG drop drop jump DIGITS
HEX: drop drop 16 (NBASE) a! ! 1 (NI) a! ! jump DIGITS
NEG: drop drop 1 (NNEG) a! ! 1 (NI) a! !
DIGITS: (NI) a! @ (TOKN) a! @ xor if NONE drop
L: (NI) a! @ (CHAR@) (DIGIT)
-if OK drop 0 0 ;
OK: (ACC)
(NI) a! @ 1 + dup ! (TOKN) a! @ xor if DONE drop jump L
DONE: drop
(NBIG) a! @ if FITS drop 0 -1 ;
FITS: drop (NNEG) a! @ if POS drop
(NU) a! @ -if NEGOK
MSB xor if EXACT drop 0 -1 ;
EXACT: drop MSB 1 ;
NEGOK: inv 1 + 1 ;
POS: drop (NU) a! @ 1 ;
NONE: drop 0 0 ;
capsules/v4/rom/pack.f18
+140
View File
@@ -0,0 +1,140 @@
\ pack.f18 -- the ROM's slot packer: how code is laid down.
\
\ The rules are v4/src/asm.c's, with text.c's branch placement
\ (DATASHEET-F18.md section 6):
\ - opcodes fill slots 0 .. 5 left to right; a full word is written out and
\ a new one begun, unused slots padded with nop
\ - a literal is @p in a slot and its value in the word after the
\ instruction word, several in the order they were given
\ - ; and ex end the word: nothing after them executes
\ - a branch ends the word, the bits to its right being its address; it is
\ put only in a slot that reaches the whole address space (ADDR-TOP),
\ otherwise in a new word; a target it cannot reach is "does not fit"
\ This is the code generator of whatever language is built on the machine
\ (MACHINE.md 2.1). State, in the ROM's area: (HERE) the next word address,
\ (CUR) the word being built, (SLOT) its next slot, (LITS) the (NLIT)
\ literals it owes. (PI) (RS) (RN) are working cells. Uses A and B.
\ ( op -- f ) 1 if op is a branch: jump call next if -if
: (BRANCH-OP?)
dup -2 + if Y drop dup -3 + if Y drop dup -5 + if Y drop
dup -6 + if Y drop dup -7 + if Y drop drop 0 ;
Y: drop drop 1 ;
\ ( s -- m ) the address bits a branch in slot s replaces
: (MASK)
if S0 -1 + if S1 -1 + if S2 -1 + if S3 -1 + if S4 drop 3 ;
S0: drop $7FFFFFF ;
S1: drop $3FFFFF ;
S2: drop $1FFFF ;
S3: drop $FFF ;
S4: drop $7F ;
\ ( w s -- op ) the opcode in slot s of the instruction word w
: (SLOT-OP)
dup 2* 2* + inv 1 + 27 +
S: if SD push 2/ pop -1 + jump S
SD: drop 31 and ;
\ ( op -- ) op into the next slot
: (PUT-OP)
(SLOT) a! @ dup 2* 2* + inv 1 + 27 +
S: if SD push 2* pop -1 + jump S
SD: drop (CUR) a! @ xor !
(SLOT) a! @ 1 + ! ;
\ ( v -- ) v at (HERE), which then moves on; past RAM, "does not fit"
: (EMIT)
(HERE) a! @ dup RAM-WORDS inv 1 + + -if FULL
drop b! !b (HERE) a! @ 1 + ! ;
FULL: drop drop drop ERR-FIT jump (FAIL)
\ ( -- ) write out the word being built, padded with nop, then its literals
: (FLUSH)
(SLOT) a! @ if NONE drop
P: (SLOT) a! @ 6 xor if PADDED drop 28 (PUT-OP) jump P
PADDED: drop
(CUR) a! @ (EMIT)
0 (PI) a! !
L: (PI) a! @ (NLIT) a! @ xor if LD drop
(PI) a! @ (LITS) + a! @ (EMIT)
(PI) a! @ 1 + ! jump L
LD: drop
0 (CUR) a! ! 0 (SLOT) a! ! 0 (NLIT) a! ! ;
NONE: drop ;
\ ( op -- ) an opcode that is neither a branch nor @p
: (OP)
dup -32 + -if BAD
drop dup 8 xor if BAD
drop dup (BRANCH-OP?) if GOOD
BAD: drop drop ERR-OPCODE jump (FAIL)
GOOD: drop
dup (PUT-OP)
if CLOSE
-1 + if CLOSE
drop (SLOT) a! @ 6 xor if CLOSE drop ;
CLOSE: drop jump (FLUSH)
\ ( v -- ) @p and its value
: (LIT)
(NLIT) a! @ (LITS) + b! !b
(NLIT) a! @ 1 + !
8 (PUT-OP)
(SLOT) a! @ 6 xor if FL drop ;
FL: drop jump (FLUSH)
\ ( -- ) text.c's place_branch: begin a new word unless the next slot
\ reaches the whole address space
: (PLACE)
(SLOT) a! @ if NONE
dup -4 + -if NEW drop
(MASK) ADDR-TOP inv 1 + + -if KEEP drop jump (FLUSH)
KEEP: drop ;
NEW: drop drop jump (FLUSH)
NONE: drop ;
\ ( -- addr ) end the word being built; the next word address
: (LABEL) (FLUSH) (HERE) a! @ ;
\ ( op -- ref ) a branch whose target comes later: ref is the word it is in
: (BRANCH>)
dup (BRANCH-OP?) if BAD drop
(PLACE)
(SLOT) a! @ -4 + -if FL drop jump GO
FL: drop (FLUSH)
GO: (HERE) a! @ push
(PUT-OP)
6 (SLOT) a! !
(FLUSH) pop ;
BAD: drop drop ERR-OPCODE (FAIL) 0 ;
\ ( ref target -- ) give the branch in the word at ref its target. The
\ branch is the first branch opcode in the word; the literals before it are
\ what P has passed when it executes. A word with no branch in slots
\ 0 .. 3 is not a ref, and is refused.
: (RESOLVE)
(FAILED) a! @ if GO drop drop drop ;
GO: drop
0 (RS) a! ! 0 (RN) a! !
L: (RS) a! @ -4 + -if BADREF drop
over a! @ (RS) a! @ (SLOT-OP)
dup (BRANCH-OP?) if NB drop drop jump FOUND
NB: drop 8 xor if ISLIT drop jump NXT
ISLIT: drop (RN) a! @ 1 + !
NXT: (RS) a! @ 1 + ! jump L
BADREF: jump (NOB)
FOUND:
over 1 + (RN) a! @ +
over xor (RS) a! @ (MASK) inv and
if OKR drop drop drop ERR-FIT jump (FAIL)
OKR: drop
(RS) a! @ (MASK) and
over a! @ (RS) a! @ (MASK) inv and
xor over a! ! drop ;
\ (a word with no branch in slots 0 .. 3 is not a ref: refused)
: (NOB) drop drop drop ERR-FIT jump (FAIL)
\ ( op target -- ) a branch to a known target
: (BRANCH) push (BRANCH>) pop jump (RESOLVE)
capsules/v4/rom/sym.f18
+158
View File
@@ -0,0 +1,158 @@
\ sym.f18 -- the ROM's symbol table.
\
\ A name the ROM assembles is given a kind and a value: 1 a word (its
\ address), 2 a constant, 3 a macro, 4 a set variable. Kind 0 is a name
\ only branched to so far: a placeholder that the forward branches to it
\ wait on (word.f18), which (DEFINE) fills in. The rules are
\ v4/src/text.c's define: a name may not be an opcode, a reserved word, a
\ label (NAME:), a number or start with &; nothing is defined twice, except
\ that a set variable may be set again and a placeholder be defined.
\
\ The table is used only while the ROM assembles, and lives in dictionary
\ space: 256 hash heads at (SYMH); records of four cells -- link, name,
\ kind, value -- growing up from SYMREC; names and macro bodies, growing
\ down from POOLTOP. When the two would meet, "too many names". (RECN) and
\ (POOLN) count the cells used, so an empty table is all zeroes. Names are
\ counted strings, the form the token is held in, compared a cell at a time.
\ (REC) (CNT) (PTR) (I) (WI) are working cells. Every routine uses A; some B.
\ ( p q -- f ) 1 if the counted strings at p and q are the same
: (SAME2?)
(I) a! ! (PTR) a! !
(PTR) a! @ a! @ 255 and 4 + 2/ 2/
L: (PTR) a! @ b! @b (I) a! @ a! @ xor if EQ drop drop 0 ;
EQ: drop (PTR) a! @ 1 + ! (I) a! @ 1 + !
-1 + if DONE jump L
DONE: drop 1 ;
\ ( addr -- f ) 1 if the counted string at addr is the token
: (SAME?) (TOK) jump (SAME2?)
\ ( table -- i | -1 ) which counted string of a table the token is; the
\ table ends with a zero cell
: (WALK)
0 (WI) a! !
L: dup a! @ if END
drop dup (SAME?) if NO
drop drop (WI) a! @ ;
NO: drop dup a! @ 255 and 4 + 2/ 2/ +
(WI) a! @ 1 + ! jump L
END: drop drop -1 ;
\ the opcodes' names, in the order of their numbers
: (MNEMONICS)
", ; ", ex ", jump ", call ", unext ", next ", if ", -if
", @p ", @+ ", @b ", @ ", !p ", !+ ", !b ", !
", +* ", 2* ", 2/ ", inv ", + ", and ", xor ", drop
", dup ", pop ", over ", a ", nop ", push ", b! ", a!
#, 0
\ the ROM's reserved words: its notation and its directives
: (RESERVED)
", : ", macro ", endmacro ", FOR ", NEXT ", UNEXT
", constant ", set ", here ", #, ", ", ", store
", start
#, 0
\ ( -- op | -1 ) which opcode the token names
: (OPCODE) &(MNEMONICS) jump (WALK)
\ ( -- f ) 1 if the token is a reserved word
: (RESERVED?) &(RESERVED) (WALK) -if Y drop 0 ;
Y: drop 1 ;
\ ( p -- h ) the hash, 0 .. 255, of the counted string at p, from its
\ first cell, and its second if the name runs into it (4 characters or more:
\ the cell after a shorter name is not its own)
: (HASH-AT)
a! @+ dup 255 and -4 + -if TWO drop jump MIX
TWO: drop @ xor
MIX: dup 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ +
dup 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ +
255 and ;
\ ( p -- rec | 0 ) the newest record whose name is the counted string at p,
\ placeholders included
: (FIND-AT)
dup (T3) a! ! (HASH-AT) (SYMH) + a! @
L: if NONE
dup (REC) a! ! 1 + a! @ (T3) a! @ (SAME2?) if NO
drop (REC) a! @ ;
NO: drop (REC) a! @ a! @ jump L
NONE: ;
\ ( -- rec | 0 ) the token's record, placeholders included
: (FIND0) (TOK) jump (FIND-AT)
\ ( -- rec | 0 ) the token's record, if it has been defined
: (FIND)
(FIND0) if NONE
dup 2 + a! @ if PH drop ;
PH: drop drop 0 ;
NONE: ;
\ ( n -- addr | 0 ) n cells of the pool, below what it holds; 0 if they
\ would meet the records ("too many names")
: (ALLOC)
dup (CNT) a! !
POOLTOP (POOLN) a! @ inv 1 + + (CNT) a! @ inv 1 + +
dup SYMREC (RECN) a! @ + 4 + inv 1 + +
-if ROOM drop drop drop ERR-NAMES (FAIL) 0 ;
ROOM: drop push drop
(POOLN) a! @ (CNT) a! @ + (POOLN) a! !
pop ;
\ ( from to n -- ) copy n cells, n at least 1
: (COPY)
(CN) a! ! (CTO) a! ! (CFROM) a! !
L: (CN) a! @ if D drop
(CFROM) a! @ a! @ (CTO) a! @ b! !b
(CFROM) a! @ 1 + ! (CTO) a! @ 1 + ! (CN) a! @ -1 + ! jump L
D: drop ;
\ ( value kind p -- rec | 0 ) a new record for the counted string at p,
\ the name copied into the pool; 0 if there is no room
: (NEW-REC)
dup (T3) a! !
a! @ 255 and 4 + 2/ 2/ (ALLOC)
if FULL
dup (T4) a! !
push (T3) a! @ pop (T3) a! @ a! @ 255 and 4 + 2/ 2/ (COPY)
SYMREC (RECN) a! @ + (REC) a! !
(T4) a! @ (REC) a! @ 1 + a! !
(REC) a! @ 2 + a! !
(REC) a! @ 3 + a! !
(T4) a! @ (HASH-AT) (SYMH) + dup a! @ (REC) a! @ a! !
(REC) a! @ over a! ! drop
(RECN) a! @ 4 + !
(REC) a! @ ;
FULL: drop drop drop 0 ;
\ ( -- f ) 1 if the token cannot be a name
: (BADNAME?)
(OPCODE) -if BAD
drop (RESERVED?) if NOTRES drop 1 ;
NOTRES: drop (NUMBER) push drop pop if NOTNUM drop 1 ;
NOTNUM: drop 0 (CHAR@) 38 xor if AMP
drop (TOKN) a! @ -1 + if ONE
(CHAR@) 58 xor if COLON drop 0 ;
COLON: drop 1 ;
ONE: drop 0 ;
AMP: drop 1 ;
BAD: drop 1 ;
\ ( value kind -- ) give the token a kind and a value. A placeholder is
\ filled in, and the branches waiting on it are told (word.f18, (DEFINED)).
: (DEFINE)
(BADNAME?) if OKNAME drop drop drop ERR-BAD-NAME jump (FAIL)
OKNAME: drop
(FIND0) if NEW
dup 2 + a! @ if FILL drop
over 4 xor if K4 drop drop drop drop ERR-DEFINED jump (FAIL)
K4: drop 2 + a! @ 4 xor if BOTH drop drop drop ERR-DEFINED jump (FAIL)
BOTH: drop drop (REC) a! @ 3 + a! ! ;
FILL: drop dup (REC) a! !
2 + a! !
(REC) a! @ 3 + a! !
(REC) a! @ jump (DEFINED)
NEW: drop (TOK) (NEW-REC) drop ;
capsules/v4/rom/word.f18
+390
View File
@@ -0,0 +1,390 @@
\ word.f18 -- the ROM assembles words: names, labels, branches, macros, FOR.
\
\ The rules are v4/src/text.c's one_token, end_word and branch:
\ : NAME a word begins at the next instruction word
\ NAME: a label of the word being assembled
\ jump X call X if X -if X next X
\ a branch to X: a label of this word, before or after the
\ branch, if it has one of that name; otherwise a word
\ X a call to the word X, defined already or later
\ &X the address of the word X, already defined, as a literal
\ 123 $FF CONST CONST+N a literal
\ a macro its tokens, read in its place
\ FOR ... NEXT FOR ... UNEXT
\ A branch to a label not yet seen waits, local to its word, in the table
\ of branches (REFS); when the word ends, a name that is not a label of it
\ must be a word, and the branch then waits on that name's symbol -- a
\ placeholder if it has none yet (sym.f18) -- until it is defined.
\
\ State, in the ROM's area: (NREF) (NLAB) (WNP) (NFOR) (FORS) (RDEPTH)
\ (RPTRS). Tables, used only while assembling: (REFS) four cells an entry
\ -- the word, the line, a symbol record (or, while local, a name), 1 if
\ local; (LABELS) a name and an address; (WNAMES) the word's names. Uses
\ A and B, and the working cells (T1) .. (T6), (MLEN).
\ ---- reading: the console, or a macro being expanded ----------------------
\ ( -- len ) the next token, from the innermost macro being expanded, or
\ from the console. A macro's body is its tokens as counted strings, then
\ a zero cell.
: (NEXT-TOKEN)
L: (RDEPTH) a! @ if SRC
-1 + (RPTRS) + dup (T1) a! ! a! @
dup a! @ if EOM
255 and dup (TOKN) a! !
4 + 2/ 2/ dup (T2) a! !
push (TOK) pop (COPY)
(T1) a! @ a! @ (T2) a! @ + (T1) a! @ a! !
(TOKN) a! @ ;
EOM: drop drop (RDEPTH) a! @ -1 + ! jump L
SRC: drop jump (TOKEN)
\ ---- the token, taken apart ------------------------------------------------
\ ( -- ) save the token's characters, a character to a cell, in (MTEMP)
: (TOK-SAVE)
(TOKN) a! @ (MLEN) a! ! 0 (T5) a! !
L: (T5) a! @ (MLEN) a! @ xor if D drop
(T5) a! @ (CHAR@) (T5) a! @ (MTEMP) + b! !b
(T5) a! @ 1 + ! jump L
D: drop ;
\ ( start len -- ) the token becomes characters start .. start+len-1 of
\ the one saved by (TOK-SAVE)
: (TOK-SUB)
(T6) a! ! (T5) a! !
(TOK) a! 15 FOR 0 !+ NEXT
0 (TOKN) a! !
L: (T6) a! @ if D drop
(T5) a! @ (MTEMP) + a! @ (PUT)
(T5) a! @ 1 + ! (T6) a! @ -1 + ! jump L
D: drop (TOKN) a! @ (TOK) a! @ xor ! ;
\ ( -- f ) 1 if the token is a label's definition: NAME:
: (LABELFORM?)
(TOKN) a! @ -1 + if NO
(CHAR@) 58 xor if YES drop 0 ;
YES: drop 1 ;
NO: drop 0 ;
\ ---- the word's names: labels, and names branched to before they are seen --
\ ( -- p | 0 ) the token, copied into the word's name area
: (WNAME)
(TOKN) a! @ 4 + 2/ 2/ (T6) a! !
(WNP) a! @ (T6) a! @ + WN-SIZE inv 1 + + -1 + -if FULL drop
(WNAMES) (WNP) a! @ +
(TOK) over (T6) a! @ (COPY)
(WNP) a! @ (T6) a! @ + (WNP) a! ! ;
FULL: drop ERR-NAMES (FAIL) 0 ;
\ ( -- addr | -1 ) the address of the word's label named by the token
: (LAB-FIND)
0 (T5) a! !
L: (T5) a! @ (NLAB) a! @ xor if NONE drop
(T5) a! @ 2* (LABELS) + a! @ (SAME?) if NO
drop (T5) a! @ 2* (LABELS) + 1 + a! @ ;
NO: drop (T5) a! @ 1 + ! jump L
NONE: drop -1 ;
\ ---- the branches waiting for a target -------------------------------------
\ ( word sym local -- ) one more branch waiting
: (REF-ADD)
(NREF) a! @ REFS-MAX inv 1 + + -if FULL drop
(NREF) a! @ 2* 2* (REFS) + (T5) a! !
(T5) a! @ 3 + a! !
(T5) a! @ 2 + a! !
(T5) a! @ a! !
(LINE) a! @ (T5) a! @ 1 + a! !
(NREF) a! @ 1 + ! ;
FULL: drop drop drop drop ERR-REFS jump (FAIL)
\ ( i target -- ) the waiting branch i gets its target, and stops waiting:
\ the last entry takes its place. A branch that cannot reach is reported
\ at the line it was written on.
: (REF-RESOLVE)
(T4) a! !
2* 2* (REFS) + dup (T3) a! !
a! @ (T4) a! @ (RESOLVE)
(FAILED) a! @ if OK drop
(T3) a! @ 1 + a! @ (ERRLINE) a! ! ;
OK: drop
(NREF) a! @ -1 + dup (NREF) a! !
2* 2* (REFS) + (T3) a! @ 4 (COPY) ;
\ ( addr -- ) a label has been defined at addr: the branches in this word
\ waiting on its name, the token, get it
: (LOCAL-RESOLVE)
(T1) a! ! 0 (T2) a! !
L: (T2) a! @ (NREF) a! @ xor if DONE drop
(FAILED) a! @ if GO drop ;
GO: drop
(T2) a! @ 2* 2* (REFS) +
dup 3 + a! @ if SKIP drop
2 + a! @ (SAME?) if NX
drop (T2) a! @ (T1) a! @ (REF-RESOLVE) jump L
SKIP: drop drop jump NX1
NX: drop
NX1: (T2) a! @ 1 + ! jump L
DONE: drop ;
\ ( rec -- ) the symbol rec has been defined (sym.f18, (DEFINE)): if it is
\ a word, the branches waiting on it get its address
: (DEFINED)
dup 2 + a! @ 1 xor if W drop drop ;
W: drop (T1) a! ! 0 (T2) a! !
L: (T2) a! @ (NREF) a! @ xor if DONE drop
(FAILED) a! @ if GO drop ;
GO: drop
(T2) a! @ 2* 2* (REFS) +
dup 3 + a! @ if NL drop drop jump NX
NL: drop 2 + a! @ (T1) a! @ xor if MATCH drop jump NX
MATCH: drop (T2) a! @ (T1) a! @ 3 + a! @ (REF-RESOLVE) jump L
NX: (T2) a! @ 1 + ! jump L
DONE: drop ;
\ ( -- ) the word being assembled ends: a FOR left open is an error; the
\ branches still local to it wait on their names' symbols, unless the name
\ is a word, which they then get; its labels and names go.
: (END-WORD)
(NFOR) a! @ if F0 drop 0 (NFOR) a! ! ERR-FOR jump (FAIL)
F0: drop
0 (T1) a! !
L: (T1) a! @ (NREF) a! @ xor if DONE drop
(FAILED) a! @ if GO drop ;
GO: drop
(T1) a! @ 2* 2* (REFS) +
dup 3 + a! @ if SKIP drop
0 over 3 + a! !
dup 2 + a! @ (FIND-AT)
if MK
dup 2 + a! @ 1 xor if RES drop
over 2 + a! ! drop jump NX
RES: drop push drop (T1) a! @ pop 3 + a! @ (REF-RESOLVE) jump L
MK: drop dup 2 + a! @ push 0 0 pop (NEW-REC)
over 2 + a! ! drop jump NX
SKIP: drop drop
NX: (T1) a! @ 1 + ! jump L
DONE: drop
0 (NLAB) a! ! 0 (WNP) a! ! ;
\ ---- branches by name ------------------------------------------------------
\ ( op local -- ) a branch to the name in the token. local: written after
\ a branch mnemonic, so it may be a label of this word, before or after.
: (BRANCH-NAME)
(T6) a! !
(T6) a! @ if CHK
drop (LAB-FIND) -if TOLAB drop jump CHK1
TOLAB: jump (BRANCH)
CHK: drop
(FIND) if CHK0
dup 2 + a! @ 1 xor if NOW drop drop jump BAD
NOW: drop 3 + a! @ jump (BRANCH)
CHK0: drop
CHK1:
(FIND) if C2
2 + a! @ 1 xor if C3 drop jump BAD
C3: drop jump C4
C2: drop
C4: (OPCODE) -if BAD1 drop
(RESERVED?) if C5 drop jump BAD
C5: drop (LABELFORM?) if C6 drop jump BAD
C6: drop (NUMBER) push drop pop if C7 drop jump BAD
C7: drop
(T6) a! @ if GLOBAL drop
(BRANCH>) (WNAME) 1 jump (REF-ADD)
GLOBAL: drop
(BRANCH>) (FIND0) if NEWPH
0 jump (REF-ADD)
NEWPH: drop 0 0 (TOK) (NEW-REC) 0 jump (REF-ADD)
BAD1: drop
BAD: drop ERR-TARGET jump (FAIL)
\ ---- labels ----------------------------------------------------------------
\ ( addr -- ) a label of this word, named by the token, at addr; the
\ branches already waiting on it get it
: (LAB-ADD)
(LAB-FIND) -if DUP drop
(NLAB) a! @ -64 + -if FULL drop
(WNAME) if FAILP
(NLAB) a! @ 2* (LABELS) + a! !
dup (NLAB) a! @ 2* (LABELS) + 1 + a! !
(NLAB) a! @ 1 + !
jump (LOCAL-RESOLVE)
DUP: drop drop ERR-LABEL-DUP jump (FAIL)
FULL: drop drop ERR-LABELS jump (FAIL)
FAILP: drop drop ;
\ ( -- ) NAME: -- a label at the next instruction word
: (LABEL-DEF)
(TOK-SAVE) 0 (MLEN) a! @ -1 + (TOK-SUB)
(LABEL) jump (LAB-ADD)
\ ---- FOR ... NEXT, FOR ... UNEXT --------------------------------------------
: (H-FOR)
(NFOR) a! @ -8 + -if DEEP drop
29 (OP) (LABEL) (NFOR) a! @ (FORS) + a! !
(NFOR) a! @ 1 + ! ;
DEEP: drop ERR-FOR jump (FAIL)
: (H-NEXT)
(NFOR) a! @ if NONE
-1 + dup (NFOR) a! ! (FORS) + a! @
push 5 pop jump (BRANCH)
NONE: drop ERR-FOR jump (FAIL)
\ unext repeats the word it is in: it must still be the word the body
\ began, with a slot left, owing no literal
: (H-UNEXT)
(NFOR) a! @ if NONE
-1 + dup (NFOR) a! ! (FORS) + a! @
(HERE) a! @ xor if SAMEW drop jump BAD
SAMEW: drop
(SLOT) a! @ if BAD0
-6 + -if BAD0 drop
(NLIT) a! @ if OK drop jump BAD
OK: drop 4 jump (OP)
BAD0: drop
BAD: ERR-UNEXT jump (FAIL)
NONE: drop ERR-FOR jump (FAIL)
\ ---- macros ----------------------------------------------------------------
\ ( -- ) restore the name (TSAVE) holds into the token
: (NAME-BACK) (TSAVE) (TOK) 16 (COPY) (TOK) a! @ 255 and (TOKN) a! ! ;
\ ( -- f ) 0 if not in a macro; else "not allowed in a macro", and 1
: (IN-MACRO?)
(RDEPTH) a! @ if NO drop ERR-IN-MACRO (FAIL) 1 ;
NO: ;
\ macro NAME ... endmacro: the tokens between, as counted strings, then a
\ zero cell, into the pool; NAME the macro, its value where they are. One
\ left open is reported at the line it began on, as text.c reports it.
: (H-MACRO)
(IN-MACRO?) if OK drop ;
OK: drop
(LINE) a! @ (T4) a! !
(NEXT-TOKEN) if NONAME drop
(TOK) (TSAVE) 16 (COPY)
0 (T1) a! !
L: (NEXT-TOKEN) if EOF drop
&(RESERVED) (WALK)
dup -2 + if END drop
dup if BAD2 drop
-1 + if BAD1 drop
(LABELFORM?) if APP drop jump BAD
APP: drop
(TOKN) a! @ 4 + 2/ 2/ dup (T2) a! !
(T1) a! @ + 1 + MBODY-SIZE inv 1 + + -1 + -if FULLM drop
(TOK) (MBODY) (T1) a! @ + (T2) a! @ (COPY)
(T1) a! @ (T2) a! @ + (T1) a! !
jump L
END: drop drop
0 (MBODY) (T1) a! @ + b! !b
(T1) a! @ 1 + (ALLOC) if FAILP
(MBODY) over (T1) a! @ 1 + (COPY)
(NAME-BACK)
3 jump (DEFINE)
FAILP: drop ;
BAD2: drop
BAD1: drop
BAD: ERR-IN-MACRO jump (FAIL)
FULLM: drop ERR-NAMES jump (FAIL)
EOF: drop ERR-MACRO (FAIL) (T4) a! @ (ERRLINE) a! ! ;
NONAME: drop ERR-MACRO jump (FAIL)
: (H-ENDMACRO) ERR-MACRO jump (FAIL)
\ ( body -- ) read a macro's tokens in its place
: (USE-MACRO)
(RDEPTH) a! @ -8 + -if DEEP drop
(RDEPTH) a! @ (RPTRS) + a! !
(RDEPTH) a! @ 1 + ! ;
DEEP: drop drop ERR-DEEP jump (FAIL)
\ ---- CONST+N ---------------------------------------------------------------
\ ( -- v 1 | 0 0 ) the token as a constant and a number after its last +;
\ if it is not one, the token is left as it was
: (CONST+N)
(TOK-SAVE)
(MLEN) a! @ -1 + (T1) a! !
L: (T1) a! @ -if GO drop jump NOPE
GO: (MTEMP) + a! @ 43 xor if FOUND drop
(T1) a! @ -1 + ! jump L
FOUND: drop
(T1) a! @ if NOPE0 drop
(T1) a! @ (MLEN) a! @ -1 + xor if NOPE0 drop
0 (T1) a! @ (TOK-SUB)
(FIND) if NOPE0
dup 2 + a! @ 2 xor if ISC drop drop jump NOPE
ISC: drop 3 + a! @ (T2) a! !
(T1) a! @ 1 + (MLEN) a! @ (T1) a! @ inv 1 + + -1 + (TOK-SUB)
(NUMBER) 1 xor if OKN drop drop jump NOPE
OKN: drop (T2) a! @ + 1 ;
NOPE0: drop
NOPE: 0 (MLEN) a! @ (TOK-SUB) 0 0 ;
\ ---- one token -------------------------------------------------------------
\ the reserved words' handlers, in (RESERVED)'s order
: (DISPATCH)
jump (H-COLON) jump (H-MACRO) jump (H-ENDMACRO)
jump (H-FOR) jump (H-NEXT) jump (H-UNEXT)
jump (H-CONSTANT) jump (H-SET) jump (H-HERE)
jump (H-CELL) jump (H-STRING) jump (H-STORE)
jump (H-START)
\ : NAME end the word before, and begin NAME at the next instruction word
: (H-COLON)
(IN-MACRO?) if OK drop ;
OK: drop
(NEXT-TOKEN) if NONAME drop
(END-WORD) (LABEL) 1 jump (DEFINE)
NONAME: drop jump (MISSING)
\ ( -- ) assemble the token
: (ONE)
&(RESERVED) (WALK) -if RES drop
(LABELFORM?) if NLD drop jump (LABEL-DEF)
NLD: drop
(OPCODE) -if OPC drop
0 (CHAR@) 38 xor if AMP drop
AFTERAMP:
(NUMBER) if NN
-if NUMOK drop drop ERR-BIG jump (FAIL)
NUMOK: drop jump (LIT)
NN: drop drop
(FIND) if NOSYM
dup 2 + a! @
dup 3 xor if MAC drop
dup 2 xor if CV drop
4 xor if CV0
drop drop 3 0 jump (BRANCH-NAME)
MAC: drop drop 3 + a! @ jump (USE-MACRO)
CV: drop drop 3 + a! @ jump (LIT)
CV0: drop 3 + a! @ jump (LIT)
NOSYM: drop
(CONST+N) if CALL drop jump (LIT)
CALL: drop drop 3 0 jump (BRANCH-NAME)
RES: &(DISPATCH) + push ;
OPC: dup 8 xor if FP drop
dup (BRANCH-OP?) if PLAIN drop
(NEXT-TOKEN) if NOTGT drop
1 jump (BRANCH-NAME)
PLAIN: drop jump (OP)
FP: drop drop ERR-FETCH-P jump (FAIL)
NOTGT: drop drop jump (MISSING)
AMP: drop (TOKN) a! @ -1 + if ONECH drop
(TOK-SAVE) 1 (MLEN) a! @ -1 + (TOK-SUB)
(FIND) if BADA
dup 2 + a! @ 1 xor if OKA drop drop jump BADA0
OKA: drop 3 + a! @ jump (LIT)
BADA: drop
BADA0: ERR-AMP jump (FAIL)
ONECH: drop jump AFTERAMP
capsules/v4/starshipos.4th
+14
View File
@@ -0,0 +1,14 @@
Block 7000
( starshipos.4th -- the StarshipOS words, in their own )
( vocabulary, STARSHIPOS: not FORTH-79, so not in FORTH. )
( Loaded when the system boots, after forth79.4th. )
( Blocks 7000 up. New definitions still go into FORTH; the )
( search starts in STARSHIPOS, then FORTH. )
VOCABULARY STARSHIPOS STARSHIPOS DEFINITIONS
Block 7001
( DOE baddr u -- as S" name" DOE )
( Intended: run the DoE of that name, from the capsule of )
( that name. As yet it only types the name back -- asked for )
( so, 2026-10-15; the runner is still to be built. )
: DOE ( baddr u -- ) TYPE ;
FORTH DEFINITIONS STARSHIPOS
v4/capsule/acl.v4 → capsules/v4/sys/acl.f18
+15 -15
View File
@@ -1,11 +1,11 @@
\ acl.v4 -- word-level access control: the fields of an entry.
\ acl.f18 -- word-level access control: the fields of an entry.
\
\ DECOMPOSITION.md 5.20, as v3: ACL-MODE@ ACL-MODE! ACL-TTL@ ACL-TTL! ACL-ALLOW@
\ ACL-ALLOW! ACL-PINNED? ACL-PIN ACL-INHERIT ACL-INIT-PRIMITIVES ACL-HEAT@
\ ACL-WORD-ID. These are all the capsule does itself; the policy -- what is
\ strict, how long a TTL is, what is pinned -- is FORTH source, ACL.fth, as
\ it is ACL.4th in v3. The fields and the check are described in
\ compile.v4. Rests on compile.v4, quit.v4 and system.v4.
\ compile.f18. Rests on compile.f18, quit.f18 and system.f18.
\
\ An xt of 0 is an error (code 16, "Not a word"). A pinned word's fields are
\ not changed by the ! words: they do nothing, as in v3.
@@ -18,25 +18,25 @@
\ ( xt -- flag ) non-zero if it is pinned. A holds the flags' address.
: (PINNED) -3 + a! @ 64 and ;
header ACL-HOOK inline : ACL-HOOK' (ACL-HOOK) ;
set HDR-NFA here ", ACL-HOOK #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : ACL-HOOK' (ACL-HOOK) ;
header ACL-MODE@
set HDR-NFA here ", ACL-MODE@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-MODE@ ( xt -- mode ) (ACL-XT) -3 + a! @ 8/ 255 and ;
header ACL-TTL@
set HDR-NFA here ", ACL-TTL@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-TTL@ ( xt -- n ) (ACL-XT) -3 + a! @ 8/ 8/ 65535 and ;
header ACL-ALLOW@
set HDR-NFA here ", ACL-ALLOW@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-ALLOW@ ( xt -- flag ) (ACL-XT) -3 + a! @ 32 and if YES drop 0 ; YES: drop -1 ;
header ACL-PINNED?
set HDR-NFA here ", ACL-PINNED? #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-PINNED? ( xt -- flag ) (ACL-XT) (PINNED) if NO drop -1 ; NO: ;
header ACL-PIN
set HDR-NFA here ", ACL-PIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-PIN ( xt -- ) (ACL-XT) -3 + a! @ 64 OR ! ;
header ACL-MODE!
set HDR-NFA here ", ACL-MODE! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-MODE! ( mode xt -- )
(ACL-XT) (PINNED) if FREE drop drop ;
FREE: drop 255 and 8* @ -65281 and + ! ;
\ as v3: below 0 is 0. The TTL is sixteen bits here: above 65535 is 65535.
header ACL-TTL!
set HDR-NFA here ", ACL-TTL! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-TTL! ( n xt -- )
(ACL-XT) (PINNED) if FREE drop drop ;
FREE: drop
@@ -44,7 +44,7 @@ header ACL-TTL!
POS: dup -65536 and if SMALL drop drop 65535 jump SET
SMALL: drop
SET: 8* 8* @ 65535 and + ! ;
header ACL-ALLOW!
set HDR-NFA here ", ACL-ALLOW! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-ALLOW! ( flag xt -- )
(ACL-XT) (PINNED) if FREE drop drop ;
FREE: drop if DENY drop @ -33 and ! ;
@@ -52,7 +52,7 @@ header ACL-ALLOW!
\ ( src dst -- ) as v3: dst takes src's mode; it is not pinned, its TTL
\ is 0 and it is allowed. This is the one word that unpins.
header ACL-INHERIT
set HDR-NFA here ", ACL-INHERIT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-INHERIT
(ACL-XT) SWAP (ACL-XT) \ dst src
-3 + a! @ $FF00 and \ dst mode
@@ -67,7 +67,7 @@ header ACL-INHERIT
NXT: -1 + a! @ jump L
DONE: drop ;
\ ( -- ) as v3: do that to every word in the dictionary, in every vocabulary
header ACL-INIT-PRIMITIVES
set HDR-NFA here ", ACL-INIT-PRIMITIVES #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-INIT-PRIMITIVES
(LATEST) a! @ (ACL-INIT)
VOC-LINK a! @
@@ -76,8 +76,8 @@ header ACL-INIT-PRIMITIVES
\ ( xt -- heat ) how often the word has been used. The node's heat
\ counters are not readable from a programme yet (D-6): 0.
header ACL-HEAT@
set HDR-NFA here ", ACL-HEAT@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-HEAT@ (ACL-XT) drop 0 ;
\ ( xt -- n ) a number for the word that never changes: its address
header ACL-WORD-ID
set HDR-NFA here ", ACL-WORD-ID #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ACL-WORD-ID (ACL-XT) ;
v4/capsule/blocks.v4 → capsules/v4/sys/blocks.f18
+14 -14
View File
@@ -1,4 +1,4 @@
\ blocks.v4 -- mass storage: blocks of 1024 characters, and text loaded from them.
\ blocks.f18 -- mass storage: blocks of 1024 characters, and text loaded from them.
\
\ DECOMPOSITION.md 5.11, FORTH-79: BLOCK BUFFER UPDATE SAVE-BUFFERS
\ EMPTY-BUFFERS LIST LOAD SCR BLK, and v3's FLUSH THRU and --> . Part of the
@@ -23,10 +23,10 @@
\ Constants the loader supplies:
\ BLOCK# BUFFER# UPDATE# SAVE-BUFFERS# EMPTY-BUFFERS# the requests' numbers
\ SCR word address of the variable: the block LIST showed last
\ BLK (SRC) (SRC-HOOK) see input.v4
\ BLK (SRC) (SRC-HOOK) see input.f18
header SCR inline : SCR' SCR ;
header BLK inline : BLK' BLK ;
set HDR-NFA here ", SCR #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : SCR' SCR ;
set HDR-NFA here ", BLK #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : BLK' BLK ;
\ ( status -- ) a request that did not work is an error
: (B-ERR)
@@ -41,27 +41,27 @@ header BLK inline : BLK' BLK ;
\ ( n -- baddr ) FORTH-79: the address of a buffer assigned to block n.
\ What the buffer holds is not read from storage.
header BUFFER
set HDR-NFA here ", BUFFER #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BUFFER BUFFER# (PORT) b! !b jump (B-GOT)
\ ( n -- baddr ) FORTH-79: the address of a buffer that holds block n,
\ read from storage if it is not already in one.
header BLOCK
set HDR-NFA here ", BLOCK #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BLOCK BLOCK# (PORT) b! !b jump (B-GOT)
\ FORTH-79: mark the block most recently asked for as changed, so that it is
\ written before its buffer is used for another.
header UPDATE
set HDR-NFA here ", UPDATE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: UPDATE UPDATE# (PORT) b! !b jump (B-ERR)
\ FORTH-79: write every block that has been UPDATEd.
header SAVE-BUFFERS
set HDR-NFA here ", SAVE-BUFFERS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SAVE-BUFFERS SAVE-BUFFERS# (PORT) b! !b jump (B-ERR)
\ As v3: the same.
header FLUSH
set HDR-NFA here ", FLUSH #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: FLUSH jump SAVE-BUFFERS
\ FORTH-79: forget what is in the buffers; nothing is written.
header EMPTY-BUFFERS
set HDR-NFA here ", EMPTY-BUFFERS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: EMPTY-BUFFERS EMPTY-BUFFERS# (PORT) b! !b ;
\ ---- LIST ----------------------------------------------------------------------
@@ -69,7 +69,7 @@ header EMPTY-BUFFERS
\ characters, each after its number, and an empty line. SCR is left holding n. A character
\ that is not printable is shown as a blank. (Q)+0 is the line, (Q)+1 the
\ column, (Q)+2 the block's number.
header LIST
set HDR-NFA here ", LIST #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LIST
dup (Q)+2 a! ! BLOCK drop \ an error here leaves nothing behind
(Q)+2 a! @ dup SCR a! !
@@ -101,7 +101,7 @@ header LIST
TERM: drop ;
\ ( n -- ) FORTH-79: interpret block n, then go on with what follows.
header LOAD
set HDR-NFA here ", LOAD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LOAD
-if POS jump BAD
POS: if BAD
@@ -114,13 +114,13 @@ header LOAD
\ ( -- ) go on with the next block. Only in a block being loaded: at the
\ terminal it is an error (code 14).
header --> immediate
set HDR-NFA here ", --> #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NEXT-BLOCK
BLK a! @ if TERM 1 + ! 0 >IN a! ! ;
TERM: drop NODE-ERROR b! 14 !b ;
\ ( first last -- ) as v3: LOAD each block from first to last.
header THRU
set HDR-NFA here ", THRU #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: THRU
push
L: dup inv pop dup push + 1 + -if GO drop drop pop drop ; \ last - first
v4/capsule/codegen.v4 → capsules/v4/sys/codegen.f18
+2 -2
View File
@@ -1,4 +1,4 @@
\ codegen.v4 -- the code generator: opcodes, literals and branches packed into
\ codegen.f18 -- the code generator: opcodes, literals and branches packed into
\ instruction words at HERE.
\
\ This is what the compiling words ( : ; IF LOOP LITERAL ... ) are built on.
@@ -18,7 +18,7 @@
\ An instruction word is 32 bits at every cell width (D-9): slot k is the five
\ bits whose lowest is bit 27 - 5k, and a branch there has 27 - 5k address bits.
\
\ Rests on core.v4 and dict.v4. Constants the loader supplies:
\ Rests on core.f18 and dict.f18. Constants the loader supplies:
\ (CG) word address of fourteen cells of scratch for this file
\ CG-BSLOTS how many slots, counted from slot 0, may hold a branch
v4/capsule/compile.v4 → capsules/v4/sys/compile.f18
+41 -41
View File
@@ -1,15 +1,15 @@
\ compile.v4 -- the interpreter's inner loop, and the defining and compiling
\ compile.f18 -- the interpreter's inner loop, and the defining and compiling
\ words.
\
\ DECOMPOSITION.md 5.17 and 5.18: STATE [ ] : ; EXIT IMMEDIATE LITERAL COMPILE
\ [COMPILE] ' EXECUTE CREATE VARIABLE CONSTANT DOES>, the control structures
\ IF ELSE THEN BEGIN UNTIL AGAIN WHILE REPEAT DO ?DO LOOP +LOOP, and INTERPRET,
\ which they cannot be run without. Part of the compiler capsule. Rests on
\ core.v4, input.v4, dict.v4 and codegen.v4.
\ core.f18, input.f18, dict.f18 and codegen.f18.
\
\ HOW A WORD IS COMPILED. v4 code is native: a colon definition is
\ instruction words, and compiling a word into one lays down a call to it.
\ Two flags on an entry (dict.v4) change that:
\ Two flags on an entry (dict.f18) change that:
\ inline its code is a straight run of opcodes and literals ending
\ in ; -- that run is copied in place of a call. Everything
\ that touches the return stack must be, since a call would
@@ -46,9 +46,9 @@ macro ROT push SWAP pop SWAP endmacro
\ ( -- ) give up the line: stop compiling, forget the word being built and
\ whatever control structures were open, skip the rest of the input, and set
\ NODE-ERROR. A definition that was under way stays hidden. It returns to
\ whatever called INTERPRET, which is QUIT (quit.v4): QUIT sees NODE-ERROR
\ whatever called INTERPRET, which is QUIT (quit.f18): QUIT sees NODE-ERROR
\ and prints ERROR.
\ (ABANDON-AS) is the same with an error code (core.v4) for the prompt to
\ (ABANDON-AS) is the same with an error code (core.f18) for the prompt to
\ print the message of.
: (ABANDON-AS) ( code -- )
(C)+9 a! !
@@ -143,14 +143,14 @@ macro ROT push SWAP pop SWAP endmacro
\ ( -- ) print the word WORD has just left
: (.WORD) WBUF COUNT jump TYPE
header EXECUTE
set HDR-NFA here ", EXECUTE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: EXECUTE ( xt -- ) push ;
\ ---- the interpreter's inner loop ---------------------------------------------
\ ( -- n flag ) the word WORD has just left, as a single-cell number in the
\ current BASE, and -1; or 0 0 if it is not one. A leading minus sign is
\ allowed. This is what the interpreter uses: NUMBER (input.v4) makes a
\ allowed. This is what the interpreter uses: NUMBER (input.f18) makes a
\ double and needs more of the stack than can be spared here.
\ (P)+2 the number so far, (P)+3 where it is in the word, (P)+4 the word's
\ length, (P)+5 the sign, (P)+6 the base.
@@ -181,7 +181,7 @@ header EXECUTE
\ on the stack, or compiled as a literal. What is neither, or a compile-only
\ word met while interpreting, abandons the line, with v3's message:
\ UNKNOWN WORD: 'xxx' xxx: compile-only
header INTERPRET
set HDR-NFA here ", INTERPRET #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: INTERPRET
L: 32 WORD dup C@ if EOL
drop (LOOKUP) if NUM
@@ -204,25 +204,25 @@ header INTERPRET
\ ---- state ---------------------------------------------------------------------
header [ immediate
set HDR-NFA here ", [ #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LEFT-BRACKET 0 STATE a! ! ;
header ]
set HDR-NFA here ", ] #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: RIGHT-BRACKET -1 STATE a! ! ;
\ ( x -- ) FORTH-79: if compiling, compile x as a literal
header LITERAL immediate
set HDR-NFA here ", LITERAL #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LITERAL STATE a! @ if NO drop jump (LIT,) NO: drop ;
\ ( -- addr ) FORTH-79: the next word's parameter field address; if
\ compiling, compiled as a literal
header ' immediate
set HDR-NFA here ", ' #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: TICK (') jump LITERAL
\ ['] xxx the same inside a definition, whatever STATE is; and [LITERAL],
\ which v3 has as another name for LITERAL.
header ['] immediate compile-only
set HDR-NFA here ", ['] #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BRACKET-TICK (') jump (LIT,)
header [LITERAL] immediate
set HDR-NFA here ", [LITERAL] #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BRACKET-LITERAL jump LITERAL
\ ---- colon definitions -----------------------------------------------------------
@@ -230,7 +230,7 @@ header [LITERAL] immediate
\ FORTH-79: start a definition; it cannot be found until ; ends it. The
\ CONTEXT vocabulary is set to the CURRENT one.
\ (C)+2 holds LATEST while the entry is made, to tell whether one was.
header :
set HDR-NFA here ", : #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: COLON
CURRENT a! @ CONTEXT a! !
LATEST (C)+2 a! !
@@ -240,7 +240,7 @@ header :
NONE: drop jump (ABANDON) \ no entry: the rest of the line is not a definition
\ FORTH-79: compile the return, let the word be found, stop compiling
header ; immediate compile-only
set HDR-NFA here ", ; #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SEMICOLON
0 (OP,)
LATEST (FLAGS) a! @ -3 and !
@@ -255,27 +255,27 @@ header ; immediate compile-only
\ what a word that is a C function in v3 -- BIRTH, BLOCK, BYE -- is on a
\ node. Not FORTH-79 and not in v3, where such a word is registered from C.
\ The constant (PORT) is the port's word address.
header KERNEL-WORD
set HDR-NFA here ", KERNEL-WORD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: KERNEL-WORD
COLON (LIT,) (PORT) (LIT,) 30 (OP,) 14 (OP,) \ n port b! !b
jump SEMICOLON
\ FORTH-79: return from the definition at this point
header EXIT immediate compile-only
set HDR-NFA here ", EXIT #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: EXIT 0 jump (OP,)
header IMMEDIATE
set HDR-NFA here ", IMMEDIATE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: IMMEDIATE LATEST if NONE (FLAGS) a! @ 1 OR ! ; NONE: drop ;
\ COMPILE xxx FORTH-79: when the word this is in runs, xxx is compiled
header COMPILE immediate compile-only
set HDR-NFA here ", COMPILE #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: COMPILE
32 WORD (LOOKUP) if MISSING
(LIT,) &(COMPILE,) jump (CALL,)
MISSING: drop (UNKNOWN) drop jump (ABANDON)
\ [COMPILE] xxx FORTH-79: compile xxx even though it is immediate
header [COMPILE] immediate compile-only
set HDR-NFA here ", [COMPILE] #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BRACKET-COMPILE
32 WORD (LOOKUP) if MISSING jump (COMPILE,)
MISSING: drop (UNKNOWN) drop jump (ABANDON)
@@ -303,16 +303,16 @@ header [COMPILE] immediate compile-only
NONE: drop ;
\ FORTH-79: an entry whose word leaves the address of its parameter field
header CREATE
set HDR-NFA here ", CREATE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CREATE &(DOVAR) (C)+3 a! ! jump (DATA)
\ FORTH-79: CREATE and one cell. The standard leaves its first value to the
\ programme; here it is 0.
header VARIABLE
set HDR-NFA here ", VARIABLE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: VARIABLE &(DOVAR) (C)+3 a! ! (DATA) (C)+8 a! @ if NONE drop 0 jump , NONE: drop ;
\ ( n -- ) FORTH-79: an entry whose word leaves n
header CONSTANT
set HDR-NFA here ", CONSTANT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CONSTANT &(DOCON) (C)+3 a! ! (DATA) (C)+8 a! @ if NONE drop jump , NONE: drop drop ;
\ FORTH-79: in : DEFINER CREATE ... DOES> ... ; the words after DOES> become
@@ -321,7 +321,7 @@ header CONSTANT
\ call to the code after it and leaves DEFINER; that code starts with pop,
\ which fetches the parameter field address the call left.
: (DOES) pop 402653184 + LATEST a! ! ; \ 402653184 is `call` in slot 0
header DOES> immediate compile-only
set HDR-NFA here ", DOES> #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DOES> &(DOES) (CALL,) 25 jump (OP,)
\ ---- control structures (5.18, section 2) ---------------------------------------------
@@ -341,15 +341,15 @@ header DOES> immediate compile-only
\ Native if leaves the flag, so both ways out of it drop it (section 2):
\ IF a THEN if L1 drop a jump L2 L1: drop L2:
\ IF a ELSE b THEN if L1 drop a jump L2 L1: drop b L2:
header IF immediate compile-only
set HDR-NFA here ", IF #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: IF 6 (BRANCH>) >CF 23 (OP,) 1 jump >CF
header ELSE immediate compile-only
set HDR-NFA here ", ELSE #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ELSE
CF> 1 (PAIR) CF> (C)+6 a! ! \ the if
2 (BRANCH>) >CF \ the jump over the else part
(C)+6 a! @ (HERE!) 23 (OP,)
2 jump >CF
header THEN immediate compile-only
set HDR-NFA here ", THEN #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: THEN
CF> dup -1 + if PLAIN
drop 2 (PAIR) CF> jump (HERE!)
@@ -365,19 +365,19 @@ header THEN immediate compile-only
\ BEGIN a WHILE b REPEAT jump L0 Ld: drop L0: a if Lx drop b jump L0 Lx: drop
\ BEGIN a AGAIN jump L0 Ld: drop L0: a jump L0
\ The control-flow stack holds Ld, L0 and 3.
header BEGIN immediate compile-only
set HDR-NFA here ", BEGIN #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BEGIN
2 (BRANCH>) (C)+6 a! !
(LABEL) >CF 23 (OP,)
(LABEL) dup >CF (C)+6 a! @ (RESOLVE)
3 jump >CF
header UNTIL immediate compile-only
set HDR-NFA here ", UNTIL #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: UNTIL CF> 3 (PAIR) CF> drop CF> 6 (BRANCH,) 23 jump (OP,)
header AGAIN immediate compile-only
set HDR-NFA here ", AGAIN #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: AGAIN CF> 3 (PAIR) CF> (JUMP,) CF> drop ;
header WHILE immediate compile-only
set HDR-NFA here ", WHILE #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: WHILE CF> 3 (PAIR) 3 >CF 6 (BRANCH>) >CF 23 (OP,) 4 jump >CF
header REPEAT immediate compile-only
set HDR-NFA here ", REPEAT #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: REPEAT
CF> 4 (PAIR) CF> (C)+6 a! ! \ the while
CF> 3 (PAIR) CF> (JUMP,) CF> drop
@@ -391,16 +391,16 @@ header REPEAT immediate compile-only
\ value for, with END after it. The control-flow stack holds the jumps to
\ END, how many there are, and 7; inside a clause, the jump to N and 8.
: (of) over xor ;
header CASE immediate compile-only
set HDR-NFA here ", CASE #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CASE 0 >CF 7 jump >CF
header OF immediate compile-only
set HDR-NFA here ", OF #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: OF
CF> 7 (PAIR)
&(of) (INLINE,) 6 (BRANCH>) (C)+6 a! ! \ if M
23 (OP,) 2 (BRANCH>) >CF \ drop, jump N
(C)+6 a! @ (HERE!) 23 (OP,) 23 (OP,) \ M: drop drop
8 jump >CF
header ENDOF immediate compile-only
set HDR-NFA here ", ENDOF #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ENDOF
CF> 8 (PAIR) CF> (C)+6 a! ! \ the jump to N
CF> (C)+7 a! ! \ how many jumps to END so far
@@ -408,7 +408,7 @@ header ENDOF immediate compile-only
(C)+7 a! @ 1 + >CF
(C)+6 a! @ (HERE!) \ N:
7 jump >CF
header ENDCASE immediate compile-only
set HDR-NFA here ", ENDCASE #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ENDCASE
CF> 7 (PAIR) CF> (C)+7 a! !
23 (OP,)
@@ -456,11 +456,11 @@ header ENDCASE immediate compile-only
(C)+6 a! @ jump (HERE!)
PLAIN: drop ;
header DO immediate compile-only
set HDR-NFA here ", DO #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DO &(do) (INLINE,) (LABEL) >CF 5 jump >CF
header ?DO immediate compile-only
set HDR-NFA here ", ?DO #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ?DO &(?do) (INLINE,) 6 (BRANCH>) >CF 23 (OP,) &(do) (INLINE,) (LABEL) >CF 6 jump >CF
header LOOP immediate compile-only
set HDR-NFA here ", LOOP #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LOOP &(inc) (INLINE,) 0 (C)+5 a! ! jump (LOOPS)
header +LOOP immediate compile-only
set HDR-NFA here ", +LOOP #, 17 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: +LOOP &(+inc) (INLINE,) &(a-xor) (C)+5 a! ! jump (LOOPS)
v4/capsule/core.v4 → capsules/v4/sys/core.f18
+22 -41
View File
@@ -1,4 +1,5 @@
\ core.v4 -- the core words the host-node capsules rest on.
set HDR-LINK 0 \ the newest dictionary entry: none yet
\ core.f18 -- the core words the host-node capsules rest on.
\
\ Each is the definition DECOMPOSITION.md gives and the golden-model tests
\ execute (test_foundation.c, test_strings.c, test_terminal.c, test_pictured.c),
@@ -12,7 +13,7 @@
\ ERRORS (D-18). A word that finds an error takes its arguments off the stack
\ and stores a code in NODE-ERROR. On a node with a prompt that store is a
\ trap: the word goes no further, and the prompt prints the message for the
\ code and ERROR (quit.v4, (RAISED)). The codes:
\ code and ERROR (quit.f18, (RAISED)). The codes:
\ 1 Negative count 2 Not a number 3 Number too long
\ 4 Not a character 5 Dictionary full 6 Name missing
\ 7 Control structure mismatch 8 Control structures too deep
@@ -31,35 +32,15 @@ macro NEGATE inv 1 + endmacro
macro NIP push drop pop endmacro
\ ---- section 4: multiply ------------------------------------------------
header UM*
: UM* ( u1 u2 -- ulo uhi )
over 1 and inv 1 + over 2/ and \ u1 u2 t0 t0 = u2 2/ if u1 odd
over a! N-1 push \ A: u2 R: loop count
push over 2/ pop \ u1 u2 s t0 s = u1 2/
L: +* unext \ u1 u2 s hi A: lo
push drop pop \ u1 u2 hi
2* a -if L0 drop 1 + jump L1 L0: drop L1: push
over -if L2 drop dup jump L3 L2: drop 0 L3: push
dup -if L4 drop over 1 and jump L5 L4: drop 0 L5:
pop + pop + push
and 1 and a 2* + pop ;
set HDR-NFA here ", UM* #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: UM* ROM-UM* push ; \ ( u1 u2 -- ulo uhi ) the ROM's entry 0 (MACHINE.md 2.2)
\ ---- section 5.7: doubles ------------------------------------------------
header D+
: D+ ( d1 d2 -- d3 )
push over push push drop pop \ al bl R: bh ah
over over xor -if L1
drop + -if C1 jump C0
L1: drop over -if L2
drop + jump C1
L2: drop +
C0: pop pop + ;
C1: pop pop + 1 + ;
set HDR-NFA here ", D+ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D+ ROM-D+ push ; \ ( d1 d2 -- d3 ) the ROM's entry 2
header DNEGATE
: DNEGATE ( d -- -d )
inv over if L1 drop push inv 1 + pop ;
L1: drop 1 + ;
set HDR-NFA here ", DNEGATE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DNEGATE ROM-DNEGATE push ; \ ( d -- -d ) the ROM's entry 3
\ ---- section 5.3: bytes --------------------------------------------------
\ The shifts are written out, eight to a line, where DECOMPOSITION.md 5.3 has
@@ -69,7 +50,7 @@ header DNEGATE
macro 8/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ 2/ endmacro
macro 8* 2* 2* 2* 2* 2* 2* 2* 2* endmacro
header C@
set HDR-NFA here ", C@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: C@ ( baddr -- c )
dup 2/ 2/ a! 3 and
if K0 -1 + if K1 -1 + if K2
@@ -78,7 +59,7 @@ header C@
K1: drop @ 8/ 255 and ;
K0: drop @ 255 and ;
header C!
set HDR-NFA here ", C! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: C! ( c baddr -- )
dup 2/ 2/ a! 3 and
if K0 -1 + if K1 -1 + if K2
@@ -88,7 +69,7 @@ header C!
K0: drop 255 and @ -256 and + ! ;
\ ---- section 5.9: strings ------------------------------------------------
header CMOVE
set HDR-NFA here ", CMOVE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CMOVE ( src dst u -- )
-if OK drop drop drop NODE-ERROR b! 1 !b ;
OK: if DONE push
@@ -109,7 +90,7 @@ header CMOVE
\ is the port it came on, by its number; (ME) is this node's number.
\
\ Characters are kept in (OUT), 256 of them, a character to a cell, and sent
\ when it is full and when the text has been done with (quit.v4). (OUT^)
\ when it is full and when the text has been done with (quit.f18). (OUT^)
\ is where the next goes.
\
\ THE STACK. What prints may be run with the data stack all but full: EMIT
@@ -153,7 +134,7 @@ header CMOVE
\ list of refusals owed, and messages written and read a word at a time
\ (MESH.md 7a, 7b, 7c.6). The ports themselves are still written a word at
\ a time for the two things that are not messages: a newborn node's
\ nucleus (PORT!, quit.v4) and a node's requests to its kernel.
\ nucleus (PORT!, quit.f18) and a node's requests to its kernel.
\
\ THE STACKS. All of this runs on the stacks the node's text is using.
\ (SERVE) and what it calls keep to four cells of the data stack and four
@@ -227,7 +208,7 @@ header CMOVE
\ words are in (IN), is refused. A refusal for this node itself -- its own
\ message came back to it -- is counted in (REFUSED) as one that came by a
\ wire would be; or, if it is about the node this one is waiting on,
\ (A-SELF) is set for AWAIT to find (quit.v4).
\ (A-SELF) is set for AWAIT to find (quit.f18).
\ (WIRE) is not what it was afterwards: the NACK went by another.
\ If the drop does not drop -- the wire was cut after the message was looked
\ at, which let it go already -- nothing is counted and no one is told.
@@ -391,7 +372,7 @@ header CMOVE
\ ( -- ) send what has been printed, to where (PRINT-TO) says, by the port
\ (PRINT-PORT): a message of type 2, its characters four to a word, the
\ first lowest. quit.v4 sets those two when text for this node arrives.
\ first lowest. quit.f18 sets those two when text for this node arrives.
\ It waits for room on the wire, and for the 8 cells kept as well when the
\ wire is the one the answer goes by. The characters are made ready in
\ (OUT-TEXT), not where they are: until the message is on the wire the
@@ -440,7 +421,7 @@ header CMOVE
\ next is that fault's own message: put where (OUT^) points, it would go
\ past the buffer's end, and (OUT^) would never again be at the end to be
\ flushed (MESH.md 7c.6).
header EMIT
set HDR-NFA here ", EMIT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: EMIT ( c -- )
255 and a push push \ A, and then the character, to the return stack
(OUT^) b! @b (OUT)+256 xor if STALE drop jump PUT
@@ -449,18 +430,18 @@ header EMIT
(OUT^) b! @b a! pop !+ a !b \ the character goes where (OUT^) points, which moves on
a (OUT)+256 xor if FULL drop pop a! ;
FULL: drop (FLUSH-OUT) pop a! ;
header KEY
set HDR-NFA here ", KEY #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: KEY ( -- c )
L: CONSOLE-STATUS b! @b if WAIT drop CONSOLE-RX b! @b ;
WAIT: drop jump L
header CR
set HDR-NFA here ", CR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CR ( -- ) 10 jump EMIT
header SPACE
set HDR-NFA here ", SPACE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SPACE ( -- ) 32 jump EMIT
header COUNT
set HDR-NFA here ", COUNT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: COUNT ( baddr -- baddr+1 c ) dup C@ push 1 + pop ;
header TYPE
set HDR-NFA here ", TYPE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: TYPE ( baddr u -- )
-if OK drop drop NODE-ERROR b! 1 !b ;
OK: if DONE over C@ EMIT push 1 + pop -1 + jump OK
v4/capsule/dict.v4 → capsules/v4/sys/dict.f18
+24 -24
View File
@@ -1,9 +1,9 @@
\ dict.v4 -- the dictionary: its space, its entries, and looking a name up.
\ dict.f18 -- the dictionary: its space, its entries, and looking a name up.
\
\ DECOMPOSITION.md 5.12 and 5.13: HERE ALIGN ALLOT , C, 2, PAD LATEST, FIND ' ,
\ and the entry-field words >LINK LFA LINK> >NAME NFA NAME> CFA PFA >BODY
\ TRAVERSE SMUDGE HIDDEN. Part of the compiler capsule: it runs on the host
\ node. Rests on core.v4 and input.v4.
\ node. Rests on core.f18 and input.f18.
\
\ AN ENTRY. A word's execution address (xt) is the address of its code, and
\ everything else is found from it:
@@ -63,15 +63,15 @@ macro OR over inv and xor endmacro
LOW: drop dup inv DLIMIT + 1 + -if HIGH drop drop jump (DERR) \ DLIMIT - new
HIGH: drop DP b! !b -1 ;
header HERE
set HDR-NFA here ", HERE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: HERE ( -- addr ) DP b! @b 3 + 4/ ;
header ALIGN
set HDR-NFA here ", ALIGN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ALIGN ( -- ) DP b! @b 3 + -4 and !b ;
header ALLOT
set HDR-NFA here ", ALLOT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ALLOT ( n -- ) ALIGN 4* (DP+) drop ;
\ , calls nothing: the code generator calls it from as deep as anything goes.
header ,
set HDR-NFA here ", , #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: , ( x -- )
a!
DP b! @b 3 + -4 and \ the next whole cell, as a byte address
@@ -79,57 +79,57 @@ header ,
drop drop NODE-ERROR b! 5 !b ;
ROOM: drop dup 4 + !b \ DP is past it
4/ b! a !b ;
header C,
set HDR-NFA here ", C, #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: C, ( c -- )
a! 1 (DP+) if FULL
drop a DP b! @b -1 + jump C!
FULL: drop ;
header 2,
set HDR-NFA here ", 2, #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2, ( lo hi -- ) SWAP , , ; \ the low cell first, as v3
header LATEST
set HDR-NFA here ", LATEST #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LATEST ( -- xt ) CURRENT a! @ a! @ ; \ the newest entry of the CURRENT vocabulary
\ ---- the fields of an entry (5.13) -----------------------------------------
: (FLAGS) ( xt -- addr ) -3 + ;
header >LINK
set HDR-NFA here ", >LINK #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: >LINK ( xt -- addr ) -1 + ;
header LFA
set HDR-NFA here ", LFA #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LFA ( xt -- addr ) jump >LINK
header LINK>
set HDR-NFA here ", LINK> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LINK> ( addr -- xt ) a! @ ;
header >NAME
set HDR-NFA here ", >NAME #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: >NAME ( xt -- baddr ) -2 + a! @ 4* ;
header NFA
set HDR-NFA here ", NFA #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NFA ( xt -- baddr ) jump >NAME
header NAME>
set HDR-NFA here ", NAME> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NAME> ( baddr -- xt ) dup C@ 31 and 4 + 4/ push 4/ pop + 3 + ;
header CFA
set HDR-NFA here ", CFA #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CFA ( xt -- xt ) ;
header PFA
set HDR-NFA here ", PFA #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: PFA ( xt -- addr ) dup (FLAGS) a! @ 4 and if CODE drop 1 + ; CODE: drop ;
header >BODY
set HDR-NFA here ", >BODY #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: >BODY ( xt -- addr ) jump PFA
\ ( baddr n -- baddr' ) as v3: for n > 0, from a name's count byte to the
\ byte after its last character; otherwise the address unchanged.
header TRAVERSE
set HDR-NFA here ", TRAVERSE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: TRAVERSE
-if NN drop ;
NN: if ZERO drop dup C@ 31 and + 1 + ;
ZERO: drop ;
header SMUDGE
set HDR-NFA here ", SMUDGE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SMUDGE ( -- ) LATEST if NONE (FLAGS) a! @ 2 xor ! ; NONE: drop ;
header HIDDEN
set HDR-NFA here ", HIDDEN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: HIDDEN ( -- ) LATEST if NONE (FLAGS) a! @ 2 OR ! ; NONE: drop ;
\ ---- telling the kernel (docs/v4.0.0/ENGINE.md 3b) ------------------------------
\ A word's code is here on the node; its accounts are a record its kernel
\ keeps. So the kernel has to be told of every entry that is made and of
\ every entry that goes. An entry is made in one place, (HEADER); entries go
\ in two, FORGET and COLD (system.v4). Each tells through a variable that
\ in two, FORGET and COLD (system.f18). Each tells through a variable that
\ holds the xt of a word to run, or 0 for a node whose host keeps no records:
\ (WORD-DEFINED) ( xt -- ) an entry has been made; its code will be at xt
\ (WORD-FORGOTTEN) ( w -- ) every entry at word address w or above is gone
@@ -216,12 +216,12 @@ header HIDDEN
\ ( -- xt | 0 ) FORTH-79: the compilation address of the next word in the
\ input stream, or 0 if it is not in the dictionary.
header FIND
set HDR-NFA here ", FIND #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: FIND 32 WORD jump (LOOKUP)
\ ( -- addr ) FORTH-79: the parameter field address of the next word in the
\ input stream. Not found is an error: 0, and NODE-ERROR is set. This is '
\ when interpreting; compile.v4 adds what ' does when compiling.
\ when interpreting; compile.f18 adds what ' does when compiling.
\ ( -- 0 ) say that the word WORD has just left is not known, as v3 does:
\ UNKNOWN WORD: 'xxx'
: (UNKNOWN)
capsules/v4/sys/end.f18
+36
View File
@@ -0,0 +1,36 @@
\ end.f18 -- the end of the system's source: the state it is switched on in.
\
\ What was set in C when the nucleus was prebuilt (v4/tools/mkimage.c, gone
\ since the machine's ROM assembles the system), said with the
\ ROM's directives (MACHINE.md, the ROM's language). RAM is all zeroes
\ when the machine starts, so only what is not zero is stored. Then the
\ image record (map: (IMG)), the addresses a host needs (v4/image.h), and
\ start: the ROM clears what it used and the node waits for a message.
\ the dictionary: empty, at DBASE; the newest entry, the nucleus's last
store DP DBASE
store (LATEST) HDR-LINK
\ the control-flow stack, the number base, the log level
store (CFP) CFBASE
store BASE 10
store (LOG-LEVEL) 2
\ one vocabulary, FORTH, whose head cell is LATEST; new words go into it
store CONTEXT (LATEST)
store CURRENT (LATEST)
\ the text interpreted is the terminal's
store (SRC) TIB
\ what COLD comes back to, and the lowest FORGET goes: the nucleus as it is
store (BOOT) DBASE
store (BOOT)+1 HDR-LINK
store FENCE DICT-W
\ nothing has ended badly; nothing has been printed
store (LINE-STATUS) 1
store (OUT^) (OUT)
\ the image record: where the node waits, its fault table, KEY's code
store (IMG) &(IDLE)
store (IMG)+1 &(FAULTS)
store (IMG)+2 &KEY
store (IMG)+3 &CR
start (IDLE)
v4/capsule/forth.v4 → capsules/v4/sys/forth.f18
+60 -60
View File
@@ -1,23 +1,23 @@
\ forth.v4 -- the first words of the FORTH vocabulary: the ones that are
\ forth.f18 -- the first words of the FORTH vocabulary: the ones that are
\ opcodes or short runs of them, and the variables that are in-line addresses.
\
\ Each is the definition DECOMPOSITION.md gives (sections 4, 5.1 - 5.5, 5.18).
\ A word flagged inline is copied into a definition in place of a call; the
\ ones that touch the return stack are compile-only as well. Rests on core.v4,
\ compile.v4's loader constants, and quit.v4, which the division words leave
\ ones that touch the return stack are compile-only as well. Rests on core.f18,
\ compile.f18's loader constants, and quit.f18, which the division words leave
\ through when the divisor is zero. (F) is seven cells of scratch for
\ this file.
\ ---- stack ----
header DUP inline : DUP dup ;
header DROP inline : DROP drop ;
header OVER inline : OVER over ;
header SWAP inline : SWAP' SWAP ;
header ROT inline : ROT' ROT ;
header -ROT inline : -ROT SWAP push SWAP pop ;
header ?DUP : ?DUP if Z dup ; Z: ;
header 2DUP inline : 2DUP over over ;
header 2DROP inline : 2DROP drop drop ;
set HDR-NFA here ", DUP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : DUP dup ;
set HDR-NFA here ", DROP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : DROP drop ;
set HDR-NFA here ", OVER #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : OVER over ;
set HDR-NFA here ", SWAP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : SWAP' SWAP ;
set HDR-NFA here ", ROT #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : ROT' ROT ;
set HDR-NFA here ", -ROT #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : -ROT SWAP push SWAP pop ;
set HDR-NFA here ", ?DUP #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : ?DUP if Z dup ; Z: ;
set HDR-NFA here ", 2DUP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2DUP over over ;
set HDR-NFA here ", 2DROP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2DROP drop drop ;
\ ---- the stack as a whole (D-16) ----
\ DEPTH reads the stack register. PICK and ROLL reach under the top of a
@@ -28,7 +28,7 @@ header 2DROP inline : 2DROP drop drop ;
\ anything while n is still there, and never more than one cell after.
\ FORTH-79: how many values were on the stack before DEPTH
header DEPTH
set HDR-NFA here ", DEPTH #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DEPTH DSTACK-DEPTH b! @b ;
\ ( name -- ) "xxxx: Invalid index", and the line ends with ERROR
@@ -60,7 +60,7 @@ header DEPTH
\ ( n -- x ) FORTH-79: a copy of the n-th value, not counting n itself.
\ 1 PICK is DUP, 2 PICK is OVER. n less than one is an error.
header PICK
set HDR-NFA here ", PICK #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: PICK
-if POS jump BAD
POS: if BAD
@@ -72,7 +72,7 @@ header PICK
\ ( n -- ) FORTH-79: the n-th value, not counting n itself, is taken out
\ and put on top. 3 ROLL is ROT, 2 ROLL is SWAP, 1 ROLL does nothing. n
\ less than one is an error.
header ROLL
set HDR-NFA here ", ROLL #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ROLL
-if POS jump BAD
POS: if BAD
@@ -82,36 +82,36 @@ header ROLL
BAD: drop $4C4C4F52 jump (INDEX)
\ ---- return stack: in line, and only inside a definition ----
header >R inline compile-only : >R push ;
header R> inline compile-only : R> pop ;
header R@ inline compile-only : R@ pop dup push ;
header I inline compile-only : I pop dup push ;
header J inline compile-only : J pop pop pop dup push a! push push a ;
header LEAVE inline compile-only : LEAVE pop pop drop dup push push ;
header UNLOOP inline compile-only : UNLOOP pop drop pop drop ;
set HDR-NFA here ", >R #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : >R push ;
set HDR-NFA here ", R> #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : R> pop ;
set HDR-NFA here ", R@ #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : R@ pop dup push ;
set HDR-NFA here ", I #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : I pop dup push ;
set HDR-NFA here ", J #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : J pop pop pop dup push a! push push a ;
set HDR-NFA here ", LEAVE #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LEAVE pop pop drop dup push push ;
set HDR-NFA here ", UNLOOP #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : UNLOOP pop drop pop drop ;
\ ---- memory ----
header @ inline : FETCH a! @ ;
header ! inline : STORE a! ! ;
header +! inline : +! a! @ + ! ;
header CELLS inline : CELLS ; \ an address unit is a cell (D-1)
set HDR-NFA here ", @ #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : FETCH a! @ ;
set HDR-NFA here ", ! #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : STORE a! ! ;
set HDR-NFA here ", +! #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : +! a! @ + ! ;
set HDR-NFA here ", CELLS #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : CELLS ; \ an address unit is a cell (D-1)
\ ---- arithmetic ----
header + inline : PLUS + ;
header - inline : MINUS - ;
set HDR-NFA here ", + #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : PLUS + ;
set HDR-NFA here ", - #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : MINUS - ;
\ The low cell of the product, by N steps of +* with nothing but the count on
\ the return stack. UM* drop gives the same cell but needs two more return
\ entries, which a word inside two DO loops does not have (D-2). The low
\ cell is exact: what +* loses at the top of T (D-3) takes N shifts to reach
\ the bit that moves into A, and the loop ends first.
header * : STAR a! 0 N-1 FOR +* UNEXT drop drop a ;
header NEGATE inline : NEGATE' NEGATE ;
header 1+ inline : 1+ 1 + ;
header 1- inline : 1- -1 + ;
header 2+ inline : 2+ 2 + ;
header 2- inline : 2- -2 + ;
header 2* inline : TWO* 2* ;
header 2/ inline : TWO/ 2/ ;
set HDR-NFA here ", * #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : STAR a! 0 N-1 FOR +* UNEXT drop drop a ;
set HDR-NFA here ", NEGATE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : NEGATE' NEGATE ;
set HDR-NFA here ", 1+ #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 1+ 1 + ;
set HDR-NFA here ", 1- #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 1- -1 + ;
set HDR-NFA here ", 2+ #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2+ 2 + ;
set HDR-NFA here ", 2- #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2- -2 + ;
set HDR-NFA here ", 2* #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : TWO* 2* ;
set HDR-NFA here ", 2/ #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : TWO/ 2/ ;
\ ---- division (sections 4 and 5.6) ----
\ Division by zero is guarded (D-15): each word tests its divisor before it
@@ -163,11 +163,11 @@ header 2/ inline : TWO/ 2/ ;
(F)+1 a! @ -if L2 drop push inv 1 + pop jump L3 L2: drop L3:
(F) a! @ -if L4 drop inv 1 + ; L4: drop ;
header S>D
set HDR-NFA here ", S>D #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: S>D ( n -- d ) dup -if P drop -1 ; P: drop 0 ;
\ The product's sign waits in (F), not on the return stack, for the same
\ reason as SM/REM's.
header M*
set HDR-NFA here ", M* #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: M* ( n1 n2 -- d )
over over xor (F) a! ! -if A inv 1 + A: push -if B inv 1 + B: pop UM*
(F) a! @ -if P drop jump DNEGATE P: drop ;
@@ -181,49 +181,49 @@ header M*
(F) a! @ -if P drop DNEGATE jump Q P: drop Q:
(F)+2 a! @ jump SM/REM
header /MOD
set HDR-NFA here ", /MOD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: /MOD ( n1 n2 -- rem quot )
if Z push S>D pop jump SM/REM
Z: drop drop 0 $444F4D2F jump (DIV0)
header /
set HDR-NFA here ", / #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: / ( n1 n2 -- quot )
if Z push S>D pop SM/REM NIP ;
Z: drop drop 0 $2F jump (DIV0)
header MOD
set HDR-NFA here ", MOD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: MOD ( n1 n2 -- rem )
if Z push S>D pop SM/REM drop ;
Z: drop drop 0 $444F4D jump (DIV0)
header */MOD
set HDR-NFA here ", */MOD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: */MOD ( n1 n2 n3 -- rem quot )
if Z jump (*/MOD)
Z: drop drop drop $44 $4F4D2F2A jump (DIV0)
header */
set HDR-NFA here ", */ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: */ ( n1 n2 n3 -- quot )
if Z (*/MOD) NIP ;
Z: drop drop drop 0 $2F2A jump (DIV0)
header M/MOD
set HDR-NFA here ", M/MOD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: M/MOD ( d n -- rem quot )
if Z jump SM/REM
Z: drop drop drop $44 $4F4D2F4D jump (DIV0)
\ ---- logic and comparison ----
header AND inline : AND and ;
header XOR inline : XOR xor ;
header OR inline : OR' OR ;
header 0= : 0= if L1 drop 0 ; L1: drop -1 ;
header 0< : 0< -if L1 drop -1 ; L1: drop 0 ;
header NOT : NOT jump 0=
header = : EQUALS xor jump 0=
header < : LESS
set HDR-NFA here ", AND #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : AND and ;
set HDR-NFA here ", XOR #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : XOR xor ;
set HDR-NFA here ", OR #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : OR' OR ;
set HDR-NFA here ", 0= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 0= if L1 drop 0 ; L1: drop -1 ;
set HDR-NFA here ", 0< #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 0< -if L1 drop -1 ; L1: drop 0 ;
set HDR-NFA here ", NOT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : NOT jump 0=
set HDR-NFA here ", = #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : EQUALS xor jump 0=
set HDR-NFA here ", < #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LESS
over over xor -if SAME drop drop jump 0<
SAME: drop - jump 0<
header > : GREATER SWAP jump LESS
set HDR-NFA here ", > #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : GREATER SWAP jump LESS
\ ---- in-line addresses and constants ----
header BL inline : BL' BL ;
header TIB inline : TIB' TIB ;
header >IN inline : >IN' >IN ;
header SPAN inline : SPAN' SPAN ;
header BASE inline : BASE' BASE ;
header PAD inline : PAD' PAD ;
header STATE inline : STATE' STATE ;
set HDR-NFA here ", BL #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : BL' BL ;
set HDR-NFA here ", TIB #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : TIB' TIB ;
set HDR-NFA here ", >IN #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : >IN' >IN ;
set HDR-NFA here ", SPAN #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : SPAN' SPAN ;
set HDR-NFA here ", BASE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : BASE' BASE ;
set HDR-NFA here ", PAD #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : PAD' PAD ;
set HDR-NFA here ", STATE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : STATE' STATE ;
v4/capsule/input.v4 → capsules/v4/sys/input.f18
+13 -13
View File
@@ -1,10 +1,10 @@
\ input.v4 -- reading a line and splitting it into words and numbers.
\ input.f18 -- reading a line and splitting it into words and numbers.
\
\ DECOMPOSITION.md 5.9: TIB >IN SPAN SOURCE BL EXPECT QUERY WORD ENCLOSE
\ CONVERT NUMBER, and the comment words ( and \ of 5.15 (named PAREN and
\ BACKSLASH here, since the text assembler reads those two characters as its
\ own comments; the dictionary will give them their names). Part of the compiler
\ capsule: it runs on the host node. Rests on core.v4.
\ capsule: it runs on the host node. Rests on core.f18.
\
\ Constants the loader supplies:
\ TIB byte address of the text input buffer; QUERY fills at most 81 bytes
@@ -14,7 +14,7 @@
\ WBUF byte address of WORD's buffer, 257 bytes
\ (P) word address of eight cells of scratch for this file
\ (SRC) word address of the variable: the byte address of the text being
\ interpreted. QUERY makes it TIB; LOAD (blocks.v4) makes it a
\ interpreted. QUERY makes it TIB; LOAD (blocks.f18) makes it a
\ block buffer. >IN is an offset from it and SPAN its length.
\ (SRC-HOOK) word address of a variable: 0, or the address of a word
\ that WORD calls before it looks at the text, to make sure (SRC)
@@ -27,7 +27,7 @@
macro BL 32 endmacro
\ ( -- baddr u ) the input buffer and how much of it is in use
header SOURCE
set HDR-NFA here ", SOURCE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SOURCE (SRC) a! @ SPAN a! @ -if P drop 0 P: ;
\ ( baddr n -- ) FORTH-79: characters from the terminal are stored from
@@ -40,7 +40,7 @@ header SOURCE
\ on the stack beneath it, so it works in (P) -- (P)+0 where the next
\ character goes, (P)+1 how many more may come, (P)+2 where the first went --
\ and has at most three cells of its own on the data stack (D-2).
header EXPECT
set HDR-NFA here ", EXPECT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: EXPECT
-if NN drop drop ; \ n < 0
NN: if ZERO
@@ -57,7 +57,7 @@ header EXPECT
ZERO: drop drop ;
\ ( -- ) FORTH-79: up to 80 characters, or a line, into TIB; >IN to 0.
header QUERY
set HDR-NFA here ", QUERY #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: QUERY TIB (SRC) a! ! TIB 80 EXPECT 0 >IN a! ! ;
\ ---- WORD ------------------------------------------------------------------
@@ -122,7 +122,7 @@ macro (STEP) (P)+6 a! @ 1 + ! endmacro
RANOUT: drop 0 (P)+2 a! @ WBUF+1 + C!
(P)+6 a! @ >IN a! ! WBUF ;
header WORD
set HDR-NFA here ", WORD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: WORD
(WORD-SET)
SK: (LEFT) -if SKE drop (CH) if SKS drop jump (WORD-TAKE) \ past delimiters
@@ -146,7 +146,7 @@ header WORD
\ ( baddr c -- baddr n1 n2 n3 ) in the zero-terminated string at baddr:
\ n1 the offset of the first character that is not c, n2 the offset of the
\ first c after it, n3 the offset of the first character after that run of c.
header ENCLOSE
set HDR-NFA here ", ENCLOSE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ENCLOSE
255 and (P) a! ! dup (P)+1 a! !
0 (ESKIP) dup (ESCAN) dup (ESKIP) ;
@@ -167,7 +167,7 @@ header ENCLOSE
\ it is multiplied by BASE, until one is not a digit; baddr2 is its address.
\ (P)+2 holds the digit while the double is multiplied and (P)+5 the address,
\ so nothing waits on the return stack across the calls.
header CONVERT
set HDR-NFA here ", CONVERT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CONVERT
L: 1 + dup (P)+5 a! ! C@ (DIGIT) \ lo hi n
-if DIG drop (P)+5 a! @ ;
@@ -201,17 +201,17 @@ header CONVERT
ERR0: 0 0 0 ;
\ ( baddr -- d ) FORTH-79. What is not a number gives 0 and sets NODE-ERROR.
header NUMBER
set HDR-NFA here ", NUMBER #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NUMBER
(NUMBER?) if BAD drop ;
BAD: drop NODE-ERROR b! 2 !b ;
\ ---- comments (5.15) -------------------------------------------------------
\ PAREN skips to the closing parenthesis; BACKSLASH skips the rest of the line.
header ( immediate
set HDR-NFA here ", ( #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: PAREN 41 WORD drop ;
header \ immediate
\ In a block a line is 64 characters: skip to the start of the next.
set HDR-NFA here ", \ #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BACKSLASH
BLK a! @ if TERM drop >IN a! @ -64 and 64 + ! ;
TERM: drop SPAN a! @ >IN a! ! ;
v4/capsule/log.v4 → capsules/v4/sys/log.f18
+20 -20
View File
@@ -1,10 +1,10 @@
\ log.v4 -- logging, as v3: a message has a level, and is printed if the
\ log.f18 -- logging, as v3: a message has a level, and is printed if the
\ level is at or below LOG-LEVEL.
\
\ DECOMPOSITION.md 5.25: the level constants LOG-ERROR LOG-WARN LOG-INFO
\ LOG-TEST LOG-DEBUG (0 .. 4), LOG-LEVEL! LOG-LEVEL@, LOG-ERROR" ... LOG-DEBUG"
\ and LOG-ERROR-STR ... LOG-DEBUG-STR. Part of the compiler capsule; rests
\ on core.v4, codegen.v4 and quit.v4.
\ on core.f18, codegen.f18 and quit.f18.
\
\ WHAT IS PRINTED is v3's line without its time of day, which a node has
\ not got: the level's colour, the level's name and a colon, the colour off,
@@ -16,16 +16,16 @@
\ Constants the loader supplies:
\ (LOG-LEVEL) word address of the variable: 2, LOG-INFO, at switch-on
header LOG-ERROR inline : LOG-ERROR 0 ;
header LOG-WARN inline : LOG-WARN 1 ;
header LOG-INFO inline : LOG-INFO 2 ;
header LOG-TEST inline : LOG-TEST 3 ;
header LOG-DEBUG inline : LOG-DEBUG 4 ;
set HDR-NFA here ", LOG-ERROR #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-ERROR 0 ;
set HDR-NFA here ", LOG-WARN #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-WARN 1 ;
set HDR-NFA here ", LOG-INFO #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-INFO 2 ;
set HDR-NFA here ", LOG-TEST #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-TEST 3 ;
set HDR-NFA here ", LOG-DEBUG #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-DEBUG 4 ;
header LOG-LEVEL@
set HDR-NFA here ", LOG-LEVEL@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LOG-LEVEL@ ( -- n ) (LOG-LEVEL) a! @ ;
\ ( n -- ) as v3: a level below 0 is 0, one above 4 is 4
header LOG-LEVEL!
set HDR-NFA here ", LOG-LEVEL! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LOG-LEVEL!
-if POS drop 0 jump SET
POS: dup -5 + -if BIG drop jump SET
@@ -45,15 +45,15 @@ header LOG-LEVEL!
P4: drop $34335B1B (EMIT4) $6D (EMIT4) $55424544 (EMIT4) $203A47 (EMIT4) $6D305B1B (EMIT4) jump OUT
OUT: TYPE jump CR
header LOG-ERROR-STR : LOG-ERROR-STR ( baddr u -- ) 0 jump (LOG)
header LOG-WARN-STR : LOG-WARN-STR ( baddr u -- ) 1 jump (LOG)
header LOG-INFO-STR : LOG-INFO-STR ( baddr u -- ) 2 jump (LOG)
header LOG-TEST-STR : LOG-TEST-STR ( baddr u -- ) 3 jump (LOG)
header LOG-DEBUG-STR : LOG-DEBUG-STR ( baddr u -- ) 4 jump (LOG)
set HDR-NFA here ", LOG-ERROR-STR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-ERROR-STR ( baddr u -- ) 0 jump (LOG)
set HDR-NFA here ", LOG-WARN-STR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-WARN-STR ( baddr u -- ) 1 jump (LOG)
set HDR-NFA here ", LOG-INFO-STR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-INFO-STR ( baddr u -- ) 2 jump (LOG)
set HDR-NFA here ", LOG-TEST-STR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-TEST-STR ( baddr u -- ) 3 jump (LOG)
set HDR-NFA here ", LOG-DEBUG-STR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-DEBUG-STR ( baddr u -- ) 4 jump (LOG)
\ ( level -- ) the run time of LOG-xxx" : the text is after the call, as
\ for ." ; log it at that level and go on after it.
header (LOG") compile-only
set HDR-NFA here ", (LOG") #, 16 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: (LOG")
pop 4* dup C@ over + 4/ 1 + push \ level baddr R: the cell after the text
COUNT ROT jump (LOG)
@@ -65,8 +65,8 @@ header (LOG") compile-only
STATE a! @ if NOW
drop (Q)+3 a! @ (LIT,) &(LOG") (CALL,) jump (STRING,)
NOW: drop WBUF COUNT (Q)+3 a! @ jump (LOG)
header LOG-ERROR" immediate : LOG-ERROR-QUOTE 0 jump (LOG-QUOTE)
header LOG-WARN" immediate : LOG-WARN-QUOTE 1 jump (LOG-QUOTE)
header LOG-INFO" immediate : LOG-INFO-QUOTE 2 jump (LOG-QUOTE)
header LOG-TEST" immediate : LOG-TEST-QUOTE 3 jump (LOG-QUOTE)
header LOG-DEBUG" immediate : LOG-DEBUG-QUOTE 4 jump (LOG-QUOTE)
set HDR-NFA here ", LOG-ERROR" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-ERROR-QUOTE 0 jump (LOG-QUOTE)
set HDR-NFA here ", LOG-WARN" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-WARN-QUOTE 1 jump (LOG-QUOTE)
set HDR-NFA here ", LOG-INFO" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-INFO-QUOTE 2 jump (LOG-QUOTE)
set HDR-NFA here ", LOG-TEST" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-TEST-QUOTE 3 jump (LOG-QUOTE)
set HDR-NFA here ", LOG-DEBUG" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here : LOG-DEBUG-QUOTE 4 jump (LOG-QUOTE)
capsules/v4/sys/map-32.f18
+125
View File
@@ -0,0 +1,125 @@
\ map-32.f18 -- the memory map the system's source is assembled with, 32-bit cells.
\ Generated by v4/tools/mkmap.c (mkmap sys) from v4/tests/host_map.h -- do not edit.
constant N-1 31
constant NODE-ERROR 16382
constant CONSOLE-TX 16380
constant CONSOLE-RX 16378
constant CONSOLE-STATUS 16377
constant BASE 16376
constant TIB 63776
constant >IN 16375
constant SPAN 16374
constant WBUF 64856
constant (P) 16360
constant DP 16373
constant (LATEST) 16372
constant DBASE 32768
constant DLIMIT 55296
constant PAD 63656
constant (D) 16352
constant (CG) 16336
constant CG-BSLOTS 3
constant STATE 16371
constant (C) 16322
constant (CFP) 16370
constant (Q) 14708
constant (F) 16279
constant (S) 15812
constant (W) 16285
constant (X) 15792
constant (BOOT) 15750
constant (LOG-LEVEL) 14707
constant (ACL-HOOK) 14706
constant SCR 15742
constant BLK 15743
constant (SRC) 15744
constant (SRC-HOOK) 15745
constant (LINE-STATUS) 14703
constant (PORT) 14572
constant (ME) 14699
constant (CONSOLE) 14696
constant (ROUTE#) 14695
constant (ROUTE-DEFAULT) 14694
constant (LOST) 14693
constant (PRINT-TO) 14692
constant (PRINT-PORT) 14679
constant (DONE-PORT) 14678
constant (ROUTES) 14616
constant -PORTS -8
constant (NEAR) 14648
constant (AWAIT-FROM) 14673
constant (WIRE) 14584
constant (WIRE-A) 14585
constant (WIRE-B) 14586
constant (WIRE-DO) 14587
constant (WIRE-HOW) 14588
constant (WIRE-HAVE) 14589
constant (S-HAVE) 14677
constant (S-MASK) 14676
constant (S-WIRE) 14675
constant (S-ON) 14674
constant (KEEP) 14672
constant (DEFER) 14671
constant (D-MASK) 14704
constant (IN) 14656
constant (ONE) 14663
constant (OUT-HDR) 14600
constant (W-NEED) 14607
constant (W-PORT) 14608
constant (P-WAY) 14609
constant (P-NEED) 14612
constant (H-PORT) 14613
constant (H-NEED) 14614
constant (H-MASK) 14615
constant (A-SELF) 14610
constant (SEND^) 14611
constant (OUT-TEXT) 14248
constant (SEND-TEXT) 13912
constant (QUIET) 14702
constant (REFUSED) 14705
constant (OUT^) 14698
constant (REPLY) 14697
constant (MSG) 14664
constant (OUT) 14312
constant (WORD-DEFINED) 14701
constant (WORD-FORGOTTEN) 14700
constant (GONE-HOOK) 14691
constant BLOCK# -1
constant BUFFER# -2
constant UPDATE# -3
constant SAVE-BUFFERS# -4
constant EMPTY-BUFFERS# -5
constant (Q/) 15752
constant (QE) 15757
constant (QR) 15765
constant (QL) 15770
constant (QT) 15777
constant (QP) 15783
constant (DP) 15787
constant ADDR-DIGITS 8
constant MSB -2147483648
constant MAXHI 2147483647
constant HIMASK 65535
constant 2N+15 79
constant N-18 14
constant N-17 15
constant MAX-INT 2147483647
constant HLD 16359
constant FENCE 16358
constant CONTEXT 16320
constant CURRENT 16321
constant VOC-LINK 16334
constant HEND 63248
constant -HFLOOR -63186
constant DSTACK-DEPTH 16369
constant RSTACK-DEPTH 16368
constant CFBASE 16288
constant CFEND 16320
constant ROM-UM* 16384
constant ROM-UM/MOD 16385
constant ROM-D+ 16386
constant ROM-DNEGATE 16387
constant ROM-Q.* 16388
constant ROM-Q./ 16389
constant DICT-W 8192
constant (IMG) 14593
capsules/v4/sys/map-64.f18
+125
View File
@@ -0,0 +1,125 @@
\ map-64.f18 -- the memory map the system's source is assembled with, 64-bit cells.
\ Generated by v4/tools/mkmap.c (mkmap sys) from v4/tests/host_map.h -- do not edit.
constant N-1 63
constant NODE-ERROR 16382
constant CONSOLE-TX 16380
constant CONSOLE-RX 16378
constant CONSOLE-STATUS 16377
constant BASE 16376
constant TIB 63776
constant >IN 16375
constant SPAN 16374
constant WBUF 64856
constant (P) 16360
constant DP 16373
constant (LATEST) 16372
constant DBASE 32768
constant DLIMIT 55296
constant PAD 63656
constant (D) 16352
constant (CG) 16336
constant CG-BSLOTS 3
constant STATE 16371
constant (C) 16322
constant (CFP) 16370
constant (Q) 14708
constant (F) 16279
constant (S) 15812
constant (W) 16285
constant (X) 15792
constant (BOOT) 15750
constant (LOG-LEVEL) 14707
constant (ACL-HOOK) 14706
constant SCR 15742
constant BLK 15743
constant (SRC) 15744
constant (SRC-HOOK) 15745
constant (LINE-STATUS) 14703
constant (PORT) 14572
constant (ME) 14699
constant (CONSOLE) 14696
constant (ROUTE#) 14695
constant (ROUTE-DEFAULT) 14694
constant (LOST) 14693
constant (PRINT-TO) 14692
constant (PRINT-PORT) 14679
constant (DONE-PORT) 14678
constant (ROUTES) 14616
constant -PORTS -8
constant (NEAR) 14648
constant (AWAIT-FROM) 14673
constant (WIRE) 14584
constant (WIRE-A) 14585
constant (WIRE-B) 14586
constant (WIRE-DO) 14587
constant (WIRE-HOW) 14588
constant (WIRE-HAVE) 14589
constant (S-HAVE) 14677
constant (S-MASK) 14676
constant (S-WIRE) 14675
constant (S-ON) 14674
constant (KEEP) 14672
constant (DEFER) 14671
constant (D-MASK) 14704
constant (IN) 14656
constant (ONE) 14663
constant (OUT-HDR) 14600
constant (W-NEED) 14607
constant (W-PORT) 14608
constant (P-WAY) 14609
constant (P-NEED) 14612
constant (H-PORT) 14613
constant (H-NEED) 14614
constant (H-MASK) 14615
constant (A-SELF) 14610
constant (SEND^) 14611
constant (OUT-TEXT) 14248
constant (SEND-TEXT) 13912
constant (QUIET) 14702
constant (REFUSED) 14705
constant (OUT^) 14698
constant (REPLY) 14697
constant (MSG) 14664
constant (OUT) 14312
constant (WORD-DEFINED) 14701
constant (WORD-FORGOTTEN) 14700
constant (GONE-HOOK) 14691
constant BLOCK# -1
constant BUFFER# -2
constant UPDATE# -3
constant SAVE-BUFFERS# -4
constant EMPTY-BUFFERS# -5
constant (Q/) 15752
constant (QE) 15757
constant (QR) 15765
constant (QL) 15770
constant (QT) 15777
constant (QP) 15783
constant (DP) 15787
constant ADDR-DIGITS 16
constant MSB -9223372036854775808
constant MAXHI 9223372036854775807
constant HIMASK 281474976710655
constant 2N+15 143
constant N-18 46
constant N-17 47
constant MAX-INT 9223372036854775807
constant HLD 16359
constant FENCE 16358
constant CONTEXT 16320
constant CURRENT 16321
constant VOC-LINK 16334
constant HEND 63248
constant -HFLOOR -63186
constant DSTACK-DEPTH 16369
constant RSTACK-DEPTH 16368
constant CFBASE 16288
constant CFEND 16320
constant ROM-UM* 16384
constant ROM-UM/MOD 16385
constant ROM-D+ 16386
constant ROM-DNEGATE 16387
constant ROM-Q.* 16388
constant ROM-Q./ 16389
constant DICT-W 8192
constant (IMG) 14593
v4/capsule/numout.v4 → capsules/v4/sys/numout.f18
+24 -42
View File
@@ -1,10 +1,10 @@
\ numout.v4 -- printing numbers: pictured output, the . words, and .S
\ numout.f18 -- printing numbers: pictured output, the . words, and .S
\
\ DECOMPOSITION.md 5.8: <# # #S HOLD SIGN #> . .R U. U.R D. D.R ? SPACES
\ DECIMAL HEX OCTAL, each the definition given there and executed on the mesh
\ node by test_pictured.c, test_numout.c and test_printing.c; and .S, which
\ D-16 makes possible again. Part of the compiler capsule. Rests on core.v4
\ and forth.v4.
\ D-16 makes possible again. Part of the compiler capsule. Rests on core.f18
\ and forth.f18.
\
\ Constants the loader supplies:
\ HEND byte address just past the hold buffer, which is 64 bytes
@@ -17,56 +17,38 @@
macro (-ROT) SWAP push SWAP pop endmacro
\ ---- unsigned division (section 4) ----
\ One step a bit, the divisor in A. Exact for uhi < ud.
: UM/MOD ( ulo uhi ud -- urem uquot )
a! N-1 FOR
-if L0
2* over -if L1 drop 1 + jump L2
L1: drop L2: push 2* pop
jump SUB
L0:
2* over -if L3 drop 1 + jump L4
L3: drop L4: push 2* pop
dup a xor -if L5
drop -if NOSUB jump SUB
L5: drop dup inv a + inv -if L6
drop jump NOSUB
L6: push drop pop jump SETBIT
SUB: inv a + inv
SETBIT: push 1 + pop
NOSUB:
NEXT
over push push drop pop pop ;
\ Exact for uhi < ud. The ROM's entry 1 (MACHINE.md 2.2).
: UM/MOD ROM-UM/MOD push ; \ ( ulo uhi ud -- urem uquot )
\ ---- pictured output ----
header <#
set HDR-NFA here ", <# #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: <# ( -- ) HEND HLD b! !b ;
header HOLD
set HDR-NFA here ", HOLD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: HOLD ( c -- )
dup -256 and if OKC drop drop NODE-ERROR b! 4 !b ; \ not a character
OKC: drop HLD b! @b -HFLOOR + -if ROOM
drop drop NODE-ERROR b! 3 !b ; \ the buffer is full
ROOM: drop HLD b! @b -1 + dup !b jump C!
header SIGN
set HDR-NFA here ", SIGN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SIGN ( n -- ) -if L1 drop 45 jump HOLD L1: drop ;
header #
set HDR-NFA here ", # #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: # ( ud1 -- ud2 )
0 (BASE) UM/MOD (-ROT) \ qhi lo rem1
(BASE) UM/MOD (-ROT) \ qlo qhi rem
dup -10 + -if L1 drop 48 + jump L2 L1: drop 55 + L2: jump HOLD
header #S
set HDR-NFA here ", #S #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: #S ( ud -- 0 0 ) L: # over over OR if L1 drop jump L L1: drop ;
header #>
set HDR-NFA here ", #> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: #> ( ud -- baddr u ) drop drop HLD b! @b HEND over push inv pop + inv ;
\ ---- spaces and the number base ----
header SPACES
set HDR-NFA here ", SPACES #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SPACES ( n -- ) -if L drop ; L: if DONE SPACE -1 + jump L DONE: drop ;
header DECIMAL
set HDR-NFA here ", DECIMAL #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DECIMAL 10 BASE a! ! ;
header HEX
set HDR-NFA here ", HEX #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: HEX 16 BASE a! ! ;
header OCTAL
set HDR-NFA here ", OCTAL #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: OCTAL 8 BASE a! ! ;
\ ---- numbers ----
@@ -87,28 +69,28 @@ header OCTAL
: (D.BODY) ( d width -- )
(W) b! !b dup push -if A DNEGATE A: <# #S pop SIGN #> jump (.TAIL)
header .R
set HDR-NFA here ", .R #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DOT-R ( n width -- ) 0 (W)+1 b! !b jump (.BODY)
header .
set HDR-NFA here ", . #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DOT ( n -- ) -1 (W)+1 b! !b 0 jump (.BODY)
header U.R
set HDR-NFA here ", U.R #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: U-DOT-R ( u width -- ) 0 (W)+1 b! !b jump (U.BODY)
header U.
set HDR-NFA here ", U. #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: U-DOT ( u -- ) -1 (W)+1 b! !b 0 jump (U.BODY)
header D.R
set HDR-NFA here ", D.R #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D-DOT-R ( d width -- ) 0 (W)+1 b! !b jump (D.BODY)
header D.
set HDR-NFA here ", D. #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D-DOT ( d -- ) -1 (W)+1 b! !b 0 jump (D.BODY)
\ ( addr -- ) print what the cell holds
header ?
set HDR-NFA here ", ? #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: QUESTION a! @ jump DOT
\ ( -- ) as v3: the depth between < and >, then every value on the stack,
\ the deepest first, each followed by a blank; then a new line. The stack is
\ left as it was. It reads each value with PICK, so it needs a few cells of
\ the stack free to work in.
header .S
set HDR-NFA here ", .S #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DOT-S
60 EMIT DEPTH 0 U-DOT-R 62 EMIT SPACE
DEPTH (W)+2 b! !b
@@ -123,7 +105,7 @@ header .S
\ Everything it keeps between words is in (DP): the saved BASE, the address,
\ the count and the column. ADDR-DIGITS is two for each byte of a cell.
: (DB) ( -- c ) (DP)+1 b! @b (DP)+3 b! @b + jump C@
header DUMP
set HDR-NFA here ", DUMP #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DUMP
-if OK drop drop NODE-ERROR b! 1 !b ;
OK: (DP)+2 b! !b (DP)+1 b! !b
v4/capsule/qmath.v4 → capsules/v4/sys/qmath.f18
+31 -90
View File
@@ -1,10 +1,10 @@
\ qmath.v4 -- Q48.16 fixed point: a signed double with sixteen bits of
\ qmath.f18 -- Q48.16 fixed point: a signed double with sixteen bits of
\ fraction (D-8, D-10).
\
\ DECOMPOSITION.md 5.26. Each word is the definition given there and
\ executed on the mesh node by test_foundation.c and test_printing.c, here in
\ the host node's vocabulary. Rests on core.v4, forth.v4, numout.v4 and
\ words.v4.
\ the host node's vocabulary. Rests on core.f18, forth.f18, numout.f18 and
\ words.f18.
\
\ ERRORS. Q./ by zero, and Q.SQRT and Q.LOG outside their domain, leave the
\ result D-11 and D-12 give and then raise an error (D-18): codes 11,
@@ -15,106 +15,47 @@
\ HIMASK every bit but the top sixteen
\ 2N+15 N-18 N-17 loop counts, N the cell width in bits
\ (Q/) (QE) (QR) (QL) (QT) (QP) word addresses of the words' scratch
\ cells: 5, 8, 5, 7, 6 and 4 of them
\ cells: 5, 8, 5, 7, 6 and 4 of them; (Q/) is the ROM's Q./'s
\ ROM-Q.* ROM-Q./ the ROM's entries (MACHINE.md 2.2)
\ the logical double shift right: one +* step with S = 0, the top bit cleared
macro (UD2/) push a! 0 pop +* MAXHI and push drop a pop endmacro
: (QERR11) NODE-ERROR b! 11 !b ;
: (QERR12) NODE-ERROR b! 12 !b ;
\ ---- conversion and constants ----
header Q.FROM-INT
set HDR-NFA here ", Q.FROM-INT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.FROM-INT ( n -- q ) push 0 a! 0 pop N-17 FOR +* UNEXT push drop a pop ;
header Q.TO-INT
set HDR-NFA here ", Q.TO-INT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.TO-INT ( q -- n ) push a! 0 pop 15 FOR +* UNEXT drop drop a ;
header Q.1 inline : Q.1 65536 0 ;
header Q.0 inline : Q.0 0 0 ;
header Q.SCALE inline : Q.SCALE 65536 0 ;
set HDR-NFA here ", Q.1 #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.1 65536 0 ;
set HDR-NFA here ", Q.0 #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.0 0 0 ;
set HDR-NFA here ", Q.SCALE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.SCALE 65536 0 ;
\ ---- the double words under other names ----
header Q.+ : Q.+ jump D+
header Q.- : Q.- jump D-
header Q.ABS : Q.ABS jump DABS
header Q.NEG : Q.NEG jump DNEGATE
header Q.= : Q.= jump D=
header Q.< : Q.< jump D<
header Q.> : Q.> 2SWAP jump D<
header Q.0= : Q.0= jump D0=
header Q.MAX : Q.MAX jump DMAX
header Q.MIN : Q.MIN jump DMIN
set HDR-NFA here ", Q.+ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.+ jump D+
set HDR-NFA here ", Q.- #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.- jump D-
set HDR-NFA here ", Q.ABS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.ABS jump DABS
set HDR-NFA here ", Q.NEG #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.NEG jump DNEGATE
set HDR-NFA here ", Q.= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.= jump D=
set HDR-NFA here ", Q.< #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.< jump D<
set HDR-NFA here ", Q.> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.> 2SWAP jump D<
set HDR-NFA here ", Q.0= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.0= jump D0=
set HDR-NFA here ", Q.MAX #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.MAX jump DMAX
set HDR-NFA here ", Q.MIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here : Q.MIN jump DMIN
\ ---- multiply ----
header Q.*
: Q.* ( a b -- c )
SWAP push over over UM* drop
push push over pop
-if L1 SWAP jump L2 L1: SWAP drop 0 L2:
pop SWAP - push
push over pop UM* pop +
ROT pop dup push
over -if L3 drop dup jump L4 L3: drop 0 L4:
push UM* pop - D+
ROT pop UM*
SWAP push 0 D+ pop
push over pop SWAP Q.TO-INT push Q.TO-INT pop SWAP ;
set HDR-NFA here ", Q.* #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.* ROM-Q.* push ; \ ( a b -- c ) the ROM's entry 4 (MACHINE.md 2.2)
\ ---- divide ----
: D2*C ( lo hi cin -- lo' hi' cout )
a! dup -if L1 drop 1 jump L2 L1: drop 0 L2: push
over -if L3 drop 1 jump L4 L3: drop 0 L4:
over + +
push 2* a + pop pop ;
\ D2*C and (UQ/), Q./'s core, are the ROM's (capsules/v4/rom/math.f18).
: (UQ/) ( a0 a1 b0 b1 -- q0 q1 )
(Q/)+2 a! SWAP !+ ! (Q/) a! SWAP !+ ! 0 0 0
2N+15 FOR
push (Q/) a! @+ @ pop D2*C
push (Q/)+1 a! ! (Q/) a! ! pop D2*C
if CMP drop jump TAKE
CMP: drop (Q/)+3 b! @b
over over xor if EQH -if SAMEH
drop drop -if NT1 jump TAKE NT1: jump NOTAKE
SAMEH: drop over SWAP push inv pop + inv
-if T2 drop jump NOTAKE T2: drop jump TAKE
EQH: drop drop over (Q/)+2 b! @b
over over xor -if SAMEL
drop drop -if NT3 drop jump TAKEL NT3: drop jump NOTAKEL
SAMEL: drop push inv pop + inv
-if T4 drop jump NOTAKEL T4: drop jump TAKEL
TAKEL: drop (Q/)+2 b! @b push inv pop + inv 0 1 jump END
NOTAKEL: 0 jump END
TAKE: push (Q/)+2 b! @b over over push inv pop + inv push
over over xor -if SB drop NIP -if NB drop 1 jump BD NB: drop 0 jump BD
SB: drop push inv pop + inv -if NB2 drop 1 jump BD NB2: drop 0
BD: pop pop (Q/)+3 b! @b push inv pop + inv
push SWAP pop SWAP - 1 jump END
NOTAKE: 0
END:
NEXT
push (Q/) a! @+ @ pop D2*C drop push push drop drop pop pop ;
header Q./
: Q./ ( a b -- q )
over over OR if ZERO drop
push over pop SWAP over xor (Q/)+4 b! !b
-if L1 DNEGATE L1: push push -if L2 DNEGATE L2: pop pop
dup if CHK drop jump DIV
CHK: drop over -131072 and if CHK2 drop jump DIV
CHK2: drop push push dup pop dup push N-18 FOR 2* UNEXT
over over xor -if SAME drop drop -if NOOV jump OV
SAME: drop push inv pop + inv -if OV
NOOV: drop pop pop jump DIV
OV: drop drop drop pop pop drop drop
(Q/)+4 b! @b -if OVP drop 0 MSB ; OVP: drop -1 MAXHI ;
DIV: (UQ/) (Q/)+4 b! @b -if L3 drop DNEGATE ; L3: drop ;
ZERO: drop drop drop
over over OR if Z0 drop -if ZP drop drop 0 MSB jump (QERR11)
ZP: drop drop -1 MAXHI jump (QERR11)
Z0: drop jump (QERR11)
set HDR-NFA here ", Q./ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q./ ROM-Q./ push ; \ ( a b -- q ) the ROM's entry 5
\ ---- e to the x ----
header Q.EXP
set HDR-NFA here ", Q.EXP #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.EXP ( q -- e )
over over OR if ONE drop
dup (QE)+6 b! !b -if L1 DNEGATE L1:
@@ -139,7 +80,7 @@ header Q.EXP
ONE: drop drop drop 65536 0 ;
\ ---- square root ----
header Q.SQRT
set HDR-NFA here ", Q.SQRT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.SQRT ( q -- r )
dup -if POS drop drop drop 0 0 jump (QERR12)
POS: drop over over OR if ZERO drop
@@ -159,7 +100,7 @@ header Q.SQRT
ONE: drop ;
\ ---- natural logarithm ----
header Q.LOG
set HDR-NFA here ", Q.LOG #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.LOG ( x -- ln x )
dup -if POS drop jump ERR
POS: drop over over OR if ZERO drop 0 (QL)+2 b! !b
@@ -218,13 +159,13 @@ header Q.LOG
END: (QT)+3 b! @b (QT) b! @b -if PR drop inv 1 + jump SD PR: drop
SD: dup -if SP drop -1 ; SP: drop 0 ;
header Q.SIN
set HDR-NFA here ", Q.SIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.SIN ( x -- sin x )
(Q.REDUCE) dup (QT) b! !b -if A1 inv 1 + A1:
dup (QT)+2 b! !b dup (QT)+3 b! !b
0 over 0 Q.* drop (QT)+1 b! !b
3 (QT)+4 b! !b -1 (QT)+5 b! !b jump (TRIG)
header Q.COS
set HDR-NFA here ", Q.COS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.COS ( x -- cos x )
(Q.REDUCE) -if A1 inv 1 + A1:
0 (QT) b! !b 0 over 0 Q.* drop (QT)+1 b! !b
@@ -233,7 +174,7 @@ header Q.COS
\ ---- printing ----
\ The integer part, a point, five digits, a blank; always in decimal.
header Q.PRINT
set HDR-NFA here ", Q.PRINT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: Q.PRINT ( q -- )
dup (QP)+3 b! !b -if A DNEGATE A: (QP)+2 b! !b dup (QP)+1 b! !b
BASE b! @b (QP) b! !b 10 BASE b! !b
v4/capsule/quit.v4 → capsules/v4/sys/quit.f18
+59 -37
View File
@@ -1,4 +1,4 @@
\ quit.v4 -- a line of text, interpreted; how it ends; and the words that
\ quit.f18 -- a line of text, interpreted; how it ends; and the words that
\ print text written in the source.
\
\ DECOMPOSITION.md 5.15 and 5.10: QUIT ABORT ABORT" (ABORT") ." (."). Part of
@@ -32,10 +32,10 @@
\
\ Constants the loader supplies:
\ (LINE-STATUS) word address of the variable: how the last text ended
\ (MSG) (REPLY) (ME) (OUT) (OUT^) see core.v4, "what a node prints"
\ (MSG) (REPLY) (ME) (OUT) (OUT^) see core.f18, "what a node prints"
\ (PORT) word address of the node's port 0
\ (Q) word address of four cells of scratch, which system.v4 and
\ blocks.v4 use too
\ (Q) word address of four cells of scratch, which system.f18 and
\ blocks.f18 use too
\ DSTACK-DEPTH RSTACK-DEPTH word addresses of the stack registers
\ ( -- ) empty the return stack. `a` is only something to store: any
@@ -80,18 +80,39 @@ macro R-CLEAR RSTACK-DEPTH b! a !b endmacro
OK: drop 1 jump (FINISH)
GO: drop 0 jump (FINISH)
\ ( -- ) a GONE has been believed: the word whose xt is in (GONE-HOOK), if
\ there is one, is given the number of the node that is gone, in (ONE), so
\ that the GONE goes on down the birth graph (MESH.md 9a.2, ruling 7;
\ capsules/v4/centre.4th, GONE-DOWN). 0 there, as at switch-on: nothing.
\ The word is called, not jumped to, and (ONE) is put back when it
\ returns: what called this -- AWAIT, with the node it waits on -- reads
\ (ONE) after, and a GONE the word sends writes it. (Found by the depth
\ sweep of MESH.md 9a.6: a word that handed on a GONE about another node
\ left AWAIT waiting for ever.)
\ ( n xt -- ) the word whose xt it is, given n. It returns to whoever
\ called this, as (DEFINED) does (dict.f18).
: (RUN) push ;
: (DOWN)
(GONE-HOOK) b! @b if NONE
drop (ONE) a! @ dup push (GONE-HOOK) b! @b (RUN)
pop (ONE) a! ! ;
NONE: drop ;
\ ( -- flag ) A GONE has been taken: its seven words are in (IN), the
\ node it is about in (ONE), and (S-WIRE) is the wire it came by. It is
\ believed only if it came by the port that leads to this node's centre
\ and says it is from the centre (MESH.md 7b.4): the way to the node is
\ then forgotten, and the flag is -1. Otherwise nothing is done, and 0.
\ (As first built only what it said it was from was looked at, and one
\ that came by another port was believed.)
\ that came by another port was believed.) Believed, it is handed on:
\ (DOWN).
: (GONE?)
(CENTRE) if NOT (IN)+1 a! @ xor if FROM drop 0 ;
NOT: ;
FROM: drop (ROUTE-DEFAULT) a! @ (PORT) - (S-WIRE) a! @ xor if YES drop 0 ;
YES: drop (ONE) a! @ NO-ROUTE -1 ;
YES: drop (ONE) a! @ NO-ROUTE (DOWN) -1 ;
\ ( -- ) WAITING (MESH.md 7d.4). A node with nothing to do passes on
\ what has come for other nodes, (SERVE), and then goes through what has
@@ -199,7 +220,7 @@ macro R-CLEAR RSTACK-DEPTH b! a !b endmacro
\ Not FORTH-79 and not in v3: v3's VMs are sent to through the kernel.
\ ( node port -- ) the port, by its number, leads toward that node
header ROUTE
set HDR-NFA here ", ROUTE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ROUTE
(ROUTE#) a! @ -16 + if FULL drop
(PORT) + (ROUTE#) a! @ 2* (ROUTES) + a!
@@ -211,20 +232,20 @@ header ROUTE
\ 0: none, or a device. Whoever wires the node tells it, and tells it again
\ when the wiring changes. It is how a node knows who its centre is, the
\ one node whose GONE it believes: (CENTRE).
header NEIGHBOUR
set HDR-NFA here ", NEIGHBOUR #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NEIGHBOUR
dup -if POS jump BAD
POS: -PORTS + -if BAD drop (NEAR) + a! ! ;
BAD: drop drop drop NODE-ERROR b! 12 !b ;
\ ( port -- ) the port, by its number, leads toward every node not told of
header DEFAULT-ROUTE
set HDR-NFA here ", DEFAULT-ROUTE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DEFAULT-ROUTE (PORT) + (ROUTE-DEFAULT) a! ! ;
\ ( node -- ) forget the way to that node, if one is known: what is for it
\ then goes by the way for every node not told of, if there is one. The
\ last way in the table takes its place.
header NO-ROUTE
set HDR-NFA here ", NO-ROUTE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NO-ROUTE
(ROUTE#) a! @ if NONE -1 + (ROUTES) a!
FOR dup @+ xor if HIT drop @+ drop NEXT
@@ -252,11 +273,11 @@ header NO-ROUTE
\ ( n node -- ) tell the node that node n is gone. It acts on that only
\ if this node is its centre: it forgets the way to n, and if it is waiting
\ for n's answer the wait ends.
header GONE
set HDR-NFA here ", GONE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: GONE 5 jump (SEND1)
\ ( -- ) forget every way: for when the wiring has changed
header NO-ROUTES
set HDR-NFA here ", NO-ROUTES #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: NO-ROUTES 0 (ROUTE#) a! ! 0 (ROUTE-DEFAULT) a! ! ;
\ ( baddr u node port -- ) send the node u characters of text to
@@ -298,7 +319,7 @@ header NO-ROUTES
\ ( baddr u node -- ) send the node u characters of text to interpret,
\ by the way this node knows to it. What it prints there goes to that
\ node's console. With no way to the node it is error 12.
header SEND
set HDR-NFA here ", SEND #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SEND
dup (WAY) -if GO drop drop drop drop NODE-ERROR b! 12 !b ;
GO: jump (SEND-ON)
@@ -306,7 +327,7 @@ header SEND
\ ( baddr u node port -- ) the same by a port this node names, by its
\ number, whatever ways it knows: for a neighbour that has no number of
\ its own yet, to which text is sent as to node 0.
header SEND-ON
set HDR-NFA here ", SEND-ON #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SEND-ON
dup -if POS jump BAD
POS: -PORTS + -if BAD drop jump (SEND-ON)
@@ -356,9 +377,9 @@ header SEND-ON
\ WHAT HAS COME ALREADY is on the wires and is found the first time
\ through: the node looks before it sleeps. A message it left on a wire
\ does not keep it awake.
\ The stack what it does needs is tried first, (ROOM), core.v4: text that
\ The stack what it does needs is tried first, (ROOM), core.f18: text that
\ has left too little ends "Stack overflow" with nothing taken off a wire.
header AWAIT
set HDR-NFA here ", AWAIT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: AWAIT
(ONE) a! ! (ROOM) \ if this faults, no one is waited for:
(ONE) a! @ (AWAIT-FROM) a! ! 0 (A-SELF) a! ! \ (AWAIT-FROM) is set only when the stack has been tried
@@ -391,7 +412,7 @@ header AWAIT
\ the neighbour has taken it. This is how a node is sent a capsule of F18
\ code (docs/v4.0.0/MESH.md section 5): the cells go as they are, not as a
\ message, to a node that is executing from its ports.
header PORT!
set HDR-NFA here ", PORT! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: PORT!
dup -if POS jump BAD
POS: -PORTS + -if BAD drop (PORT) + b! !b ;
@@ -399,8 +420,8 @@ header PORT!
\ ( -- ) WHAT IS IN THE DICTIONARY NOW IS THE SYSTEM: COLD comes back to
\ it and FORGET will not go below it. Whoever has loaded a node's capsules
\ has it do this (system.v4, (BOOT) and FENCE).
header (SEAL)
\ has it do this (system.f18, (BOOT) and FENCE).
set HDR-NFA here ", (SEAL) #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: (SEAL)
DP a! @ (BOOT) a! !
(LATEST) a! @ (BOOT)+1 a! !
@@ -411,23 +432,24 @@ header (SEAL)
\ NODE-ERROR, by name: how a definition written in FORTH raises an error.
\ A store of a code that is not zero is the trap of D-18 -- the word goes no
\ further, the message for the code is printed (-1: the word has printed
\ its own) and the line ends with ERROR. The codes are listed in core.v4.
header NODE-ERROR inline : NODE-ERROR' NODE-ERROR ;
header (ME) inline : (ME)' (ME) ;
header (CONSOLE) inline : (CONSOLE)' (CONSOLE) ;
header (LOST) inline : (LOST)' (LOST) ;
header (REFUSED) inline : (REFUSED)' (REFUSED) ;
header (WORD-DEFINED) inline : (WORD-DEFINED)' (WORD-DEFINED) ;
header (WORD-FORGOTTEN) inline : (WORD-FORGOTTEN)' (WORD-FORGOTTEN) ;
\ its own) and the line ends with ERROR. The codes are listed in core.f18.
set HDR-NFA here ", NODE-ERROR #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : NODE-ERROR' NODE-ERROR ;
set HDR-NFA here ", (ME) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (ME)' (ME) ;
set HDR-NFA here ", (CONSOLE) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (CONSOLE)' (CONSOLE) ;
set HDR-NFA here ", (LOST) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (LOST)' (LOST) ;
set HDR-NFA here ", (REFUSED) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (REFUSED)' (REFUSED) ;
set HDR-NFA here ", (WORD-DEFINED) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (WORD-DEFINED)' (WORD-DEFINED) ;
set HDR-NFA here ", (WORD-FORGOTTEN) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (WORD-FORGOTTEN)' (WORD-FORGOTTEN) ;
set HDR-NFA here ", (GONE-HOOK) #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : (GONE-HOOK)' (GONE-HOOK) ;
header QUIT
set HDR-NFA here ", QUIT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: QUIT R-CLEAR (RESET) CR 0 jump (DONE)
\ FORTH-79: clear the data and return stacks, set execution mode, return
\ control to the terminal. As v3, the line it stops ends with " ok".
\ Both are emptied before anything is called: ABORT may be run with the
\ return stack full.
header ABORT
set HDR-NFA here ", ABORT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ABORT R-CLEAR DSTACK-DEPTH b! a !b (RESET) 1 jump (DONE)
\ ---- faults (D-14, D-16) -------------------------------------------------------
@@ -453,7 +475,7 @@ header ABORT
2 jump (DONE)
\ A word has stored an error code in NODE-ERROR (D-18; the codes are listed
\ in core.v4). Print its message -- a negative code means the word printed
\ in core.f18). Print its message -- a negative code means the word printed
\ its own -- and end the line with ERROR. The return stack has been
\ emptied; the data stack is as the word left it.
\ (QUIET) is 1 while the node is doing something that is no text's doing:
@@ -508,7 +530,7 @@ header ABORT
\ The three run-time words have names, as v3's have, so that SEE can tell a
\ string in a definition from code; they cannot be used from the prompt.
\ ." and ABORT" take the text up to the next " , which may be none at all
\ (input.v4's (PARSE)); with no closing " it is the rest of the line. Inside a definition they lay
\ (input.f18's (PARSE)); with no closing " it is the rest of the line. Inside a definition they lay
\ down a call to their run-time word and, after it, the text as a counted
\ string: the count byte and the characters, four to a cell, the last cell
\ filled with zeros. The run-time word finds the string by the return
@@ -530,7 +552,7 @@ header ABORT
\ It takes the return address off before it calls anything and keeps the
\ count there instead, so a word that prints text goes no deeper than one
\ that calls any other word.
header (.") compile-only
set HDR-NFA here ", (.") #, 16 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: (.")
pop 4* dup C@ \ baddr n
L: if DONE
@@ -539,7 +561,7 @@ header (.") compile-only
\ FORTH-79: ." text" prints the text -- now, if interpreting; when the word
\ it is compiled into runs, if compiling.
header ." immediate
set HDR-NFA here ", ." #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DOT-QUOTE
34 (PARSE) drop
STATE a! @ if NOW
@@ -549,7 +571,7 @@ header ." immediate
\ ( flag -- ) the run time of ABORT" : if the flag is not zero print the
\ string after the call, start a new line and ABORT; otherwise go on after
\ the string.
header (ABORT") compile-only
set HDR-NFA here ", (ABORT") #, 16 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: (ABORT")
if NO
drop pop 4* R-CLEAR COUNT TYPE CR jump ABORT
@@ -557,7 +579,7 @@ header (ABORT") compile-only
\ ( flag -- ) ABORT" text" as v3 (it is FORTH-83's, not FORTH-79's): if
\ the flag is not zero, print the text and ABORT.
header ABORT" immediate
set HDR-NFA here ", ABORT" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ABORT-QUOTE
34 (PARSE) drop
STATE a! @ if NOW
@@ -568,7 +590,7 @@ header ABORT" immediate
\ The run time of S" : leave the address and length of the string after the
\ call, and go on after it.
header (S") compile-only
set HDR-NFA here ", (S") #, 16 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: (S")
pop 4* dup C@ \ baddr n
over over + 4/ 1 + push \ the cell after the last character
@@ -577,7 +599,7 @@ header (S") compile-only
\ ( -- baddr u ) S" text" as v3. In a definition the text is compiled
\ into it. At the prompt it is copied to PAD, where it stays until PAD is
\ used again: WORD's buffer is overwritten by the very next word of the line.
header S" immediate
set HDR-NFA here ", S" #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: S-QUOTE
34 (PARSE) drop
STATE a! @ if NOW
v4/capsule/system.v4 → capsules/v4/sys/system.f18
+28 -23
View File
@@ -1,7 +1,7 @@
\ system.v4 -- words about the dictionary as a whole: WORDS, FORGET, FENCE.
\ system.f18 -- words about the dictionary as a whole: WORDS, FORGET, FENCE.
\
\ DECOMPOSITION.md 5.13 and 5.15. Part of the compiler capsule; rests on
\ dict.v4, quit.v4 and forth.v4.
\ dict.f18, quit.f18 and forth.f18.
\
\ Constants the loader supplies:
\ FENCE word address of the variable: FORGET will not remove an entry
@@ -9,27 +9,27 @@
\ VOC-LINK word address of the variable: the newest vocabulary, or 0
\ (BOOT) word address of two cells: DP and (LATEST) as the loader left them
header FENCE inline : FENCE' FENCE ;
set HDR-NFA here ", FENCE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : FENCE' FENCE ;
\ ---- vocabularies (FORTH-79) ----------------------------------------------------
\ A vocabulary is two cells: its head -- the xt of its newest entry, or 0 --
\ and the address of the vocabulary defined before it, or 0. VOC-LINK holds
\ the newest one's address. FORTH's head is (LATEST) and it is in no chain.
header CONTEXT inline : CONTEXT' CONTEXT ;
header CURRENT inline : CURRENT' CURRENT ;
set HDR-NFA here ", CONTEXT #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : CONTEXT' CONTEXT ;
set HDR-NFA here ", CURRENT #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : CURRENT' CURRENT ;
\ FORTH-79: the primary vocabulary; it becomes the CONTEXT vocabulary.
header FORTH immediate
set HDR-NFA here ", FORTH #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: FORTH (LATEST) CONTEXT a! ! ;
\ FORTH-79: new definitions go into the CONTEXT vocabulary from now on.
header DEFINITIONS
set HDR-NFA here ", DEFINITIONS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DEFINITIONS CONTEXT a! @ CURRENT a! ! ;
\ VOCABULARY xxx FORTH-79: xxx is a new, empty list of words; executing
\ xxx makes it the CONTEXT vocabulary. When a search of it finds nothing,
\ FORTH is searched.
: (DOVOC) pop CONTEXT a! ! ;
header VOCABULARY
set HDR-NFA here ", VOCABULARY #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: VOCABULARY
&(DOVOC) (C)+3 a! ! (DATA) (C)+8 a! @ if NONE drop
0 , VOC-LINK a! @ , HERE -2 + VOC-LINK a! ! ;
@@ -41,7 +41,7 @@ header VOCABULARY
F: drop drop $54524F46 (EMIT4) $48 (EMIT4) ;
\ ( -- ) as v3's, but true: where names are looked for, and where new ones go
header ORDER
set HDR-NFA here ", ORDER #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ORDER
$72616553 (EMIT4) $6F206863 (EMIT4) $72656472 (EMIT4) $203A (EMIT4)
CONTEXT a! @ dup (.VOC) SPACE
@@ -54,7 +54,7 @@ header ORDER
\ ( -- ) the names in the CONTEXT vocabulary, the newest first, a blank after
\ each, a new line whenever one has passed column 64. Hidden entries -- a
\ definition under way -- are not shown. (Q)+0 is the column.
header WORDS
set HDR-NFA here ", WORDS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: WORDS
0 (Q) a! !
CONTEXT a! @ a! @
@@ -68,7 +68,7 @@ header WORDS
WRAP: drop CR 0 (Q) a! !
NXT: -1 + a! @ jump L
DONE: drop jump CR
header VLIST
set HDR-NFA here ", VLIST #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: VLIST jump WORDS
\ ( cell -- ) take off a vocabulary's list every entry at or above the
@@ -85,7 +85,7 @@ header VLIST
\ goes is no longer CONTEXT or CURRENT: FORTH is. A word that is not there
\ is an error, and so is one below FENCE, which is where the capsule's own
\ words are (code 10, "Protected word").
header FORGET
set HDR-NFA here ", FORGET #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: FORGET
32 WORD (LOOKUP) if MISSING
-2 + a! @ \ where its name starts
@@ -104,7 +104,7 @@ header FORGET
C1: drop (LATEST) CONTEXT a! !
C2: CURRENT a! @ (Q) a! @ inv + 1 + -if C3 drop jump TOLD
C3: drop (LATEST) CURRENT a! !
TOLD: (Q) a! @ jump (FORGOTTEN) \ the kernel's records of them go too (dict.v4)
TOLD: (Q) a! @ jump (FORGOTTEN) \ the kernel's records of them go too (dict.f18)
MISSING: drop (UNKNOWN) drop ;
\ ---- the system as a whole -------------------------------------------------------
@@ -113,21 +113,21 @@ header FORGET
\ FORTH-79: execute to be sure a FORTH-79 system is there. It is: nothing
\ happens. (v3's prints two lines and leaves a flag.)
header 79-STANDARD
set HDR-NFA here ", 79-STANDARD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 79-STANDARD ;
\ ( -- ) which system this is, and its cell width
header VERSION
set HDR-NFA here ", VERSION #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: VERSION
$72617453 (EMIT4) $74726F46 (EMIT4) $34762068 (EMIT4) $302E302E (EMIT4) $38314620 (EMIT4) $20 (EMIT4)
N-1 1 + 0 U-DOT-R $7469622D (EMIT4) CR ;
\ ( -- ) clear the screen and put the cursor at the top, as v3: ESC [2J ESC [H
header PAGE
set HDR-NFA here ", PAGE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: PAGE 27 EMIT 91 EMIT 50 EMIT 74 EMIT 27 EMIT 91 EMIT 72 jump EMIT
\ ( -- ) as v3's message, and then ABORT: both stacks emptied, the prompt
header WARM
set HDR-NFA here ", WARM #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: WARM
$54524F46 (EMIT4) $39372D48 (EMIT4) $72615720 (EMIT4) $7453206D (EMIT4) $747261 (EMIT4) CR
$74737953 (EMIT4) $72206D65 (EMIT4) $61747365 (EMIT4) $64657472 (EMIT4) $2E (EMIT4) CR
@@ -135,15 +135,20 @@ header WARM
\ ( -- ) the system as it was when the capsule had just been loaded:
\ everything defined since is gone, there is one vocabulary, numbers are
\ decimal, the block buffers are empty. Then as WARM.
header COLD
\ decimal, the block buffers are empty. A word in (GONE-HOOK) that COLD
\ forgets is taken out of it (quit.f18, (DOWN)). Then as WARM.
set HDR-NFA here ", COLD #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: COLD
(BOOT) a! @ DP a! !
(BOOT)+1 a! @ (LATEST) a! !
(BOOT) a! @ 2/ 2/ FENCE a! !
(LATEST) CONTEXT a! ! (LATEST) CURRENT a! ! 0 VOC-LINK a! !
10 BASE a! ! 0 SCR a! ! 2 (LOG-LEVEL) a! ! 0 (ACL-HOOK) a! ! EMPTY-BUFFERS
(BOOT) a! @ 2/ 2/ (FORGOTTEN) \ the kernel's records of what has gone go too (dict.v4)
(BOOT) a! @ 2/ 2/ (FORGOTTEN) \ the kernel's records of what has gone go too (dict.f18)
(GONE-HOOK) a! @ (BOOT) b! @b 2/ 2/ inv 1 + + \ the hook's xt less the sealed HERE, in cells
-if CLEAR drop jump KEPT \ below the sealed system: it stays (0 is below)
CLEAR: drop 0 (GONE-HOOK) a! ! \ at or above it: forgotten with what COLD forgets
KEPT:
$54524F46 (EMIT4) $39372D48 (EMIT4) $6C6F4320 (EMIT4) $74532064 (EMIT4) $747261 (EMIT4) CR
$74737953 (EMIT4) $69206D65 (EMIT4) $6974696E (EMIT4) $7A696C61 (EMIT4) $2E6465 (EMIT4) CR
jump ABORT
@@ -155,15 +160,15 @@ header COLD
: (DODEFER)
pop a! @ if UNSET push ; \ go to it: it returns to xxx's caller
UNSET: drop NODE-ERROR b! 15 !b ;
header DEFER
set HDR-NFA here ", DEFER #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DEFER &(DODEFER) (C)+3 a! ! (DATA) (C)+8 a! @ if NONE drop 0 jump , NONE: drop ;
: (is!) a! ! ;
: (defer@) a! @ ;
header IS immediate
set HDR-NFA here ", IS #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: IS
(') STATE a! @ if NOW drop (LIT,) &(is!) jump (CALL,)
NOW: drop jump (is!)
header DEFER@ immediate
set HDR-NFA here ", DEFER@ #, 1 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DEFER@
(') STATE a! @ if NOW drop (LIT,) &(defer@) jump (CALL,)
NOW: drop jump (defer@)
v4/capsule/words.v4 → capsules/v4/sys/words.f18
+51 -51
View File
@@ -1,67 +1,67 @@
\ words.v4 -- more of the FORTH vocabulary: the stack, comparison, double,
\ words.f18 -- more of the FORTH vocabulary: the stack, comparison, double,
\ mixed, shift and string words that are short runs of opcodes or small loops.
\
\ Each is the definition DECOMPOSITION.md gives (sections 4, 5.1 - 5.7, 5.9)
\ and the mesh-node tests execute (test_cells.c, test_foundation.c,
\ test_strings.c), here as words of the host node's vocabulary. Rests on
\ core.v4, forth.v4 and numout.v4.
\ core.f18, forth.f18 and numout.f18.
\
\ Constants the loader supplies:
\ MAX-INT the largest positive number: every bit but the top one
\ (X) word address of four cells of scratch for COMPARE and SEARCH
\ ---- stack ----
header 2SWAP
set HDR-NFA here ", 2SWAP #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2SWAP ( a b c d -- c d a b ) ROT push ROT pop ;
header 2OVER
set HDR-NFA here ", 2OVER #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2OVER ( a b c d -- a b c d a b ) push push over over pop pop jump 2SWAP
header 2ROT
set HDR-NFA here ", 2ROT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2ROT ( a b c d e f -- c d e f a b ) push push 2SWAP pop pop jump 2SWAP
header 2>R inline compile-only : 2>R SWAP push push ;
header 2R> inline compile-only : 2R> pop pop SWAP ;
header 2R@ inline compile-only : 2R@ pop pop over over push push SWAP ;
header NOP inline : NOP' nop ;
header TRUE inline : TRUE -1 ;
header FALSE inline : FALSE 0 ;
header INVERT inline : INVERT inv ;
set HDR-NFA here ", 2>R #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2>R SWAP push push ;
set HDR-NFA here ", 2R> #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2R> pop pop SWAP ;
set HDR-NFA here ", 2R@ #, 24 #, HDR-NFA #, HDR-LINK set HDR-LINK here : 2R@ pop pop over over push push SWAP ;
set HDR-NFA here ", NOP #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : NOP' nop ;
set HDR-NFA here ", TRUE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : TRUE -1 ;
set HDR-NFA here ", FALSE #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : FALSE 0 ;
set HDR-NFA here ", INVERT #, 8 #, HDR-NFA #, HDR-LINK set HDR-LINK here : INVERT inv ;
\ ---- memory ----
header 2@
set HDR-NFA here ", 2@ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2@ ( addr -- lo hi ) a! @+ @ ;
header 2!
set HDR-NFA here ", 2! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 2! ( lo hi addr -- ) a! SWAP !+ ! ;
header -!
set HDR-NFA here ", -! #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: -! ( n addr -- ) a! NEGATE @ + ! ;
\ ---- comparison ----
header 0<>
set HDR-NFA here ", 0<> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 0<> if Z drop -1 ; Z: ;
header 0>
set HDR-NFA here ", 0> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: 0> -if NN drop 0 ; NN: if Z drop -1 ; Z: ;
header <>
set HDR-NFA here ", <> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: <> xor jump 0<>
header <=
set HDR-NFA here ", <= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: <= GREATER jump 0=
header >=
set HDR-NFA here ", >= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: >= LESS jump 0=
header U<
set HDR-NFA here ", U< #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: U< over over xor -if SAME drop NIP jump 0<
SAME: drop - jump 0<
header U>
set HDR-NFA here ", U> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: U> SWAP jump U<
header ABS
set HDR-NFA here ", ABS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ABS -if P inv 1 + P: ;
header MAX
set HDR-NFA here ", MAX #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: MAX over over LESS if A drop push drop pop ; A: drop drop ;
header MIN
set HDR-NFA here ", MIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: MIN over over LESS if B drop drop ; B: drop push drop pop ;
header WITHIN
set HDR-NFA here ", WITHIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: WITHIN ( n low high -- flag ) push over pop LESS push LESS inv pop and ;
\ ---- shifts ----
\ As v3, a count that is negative or as large as the cell is wide is an
\ error (code 9, "Shift count out of range").
header LSHIFT
set HDR-NFA here ", LSHIFT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: LSHIFT ( x n -- x' )
-if NN jump BAD
NN: dup N-1 inv + -if BAD2 drop
@@ -69,7 +69,7 @@ header LSHIFT
DONE: drop ;
BAD2: drop
BAD: drop drop NODE-ERROR b! 9 !b ;
header RSHIFT
set HDR-NFA here ", RSHIFT #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: RSHIFT ( x n -- x' ) \ zeros come in at the top
-if NN jump BAD
NN: dup N-1 inv + -if BAD2 drop
@@ -79,23 +79,23 @@ header RSHIFT
BAD: drop drop NODE-ERROR b! 9 !b ;
\ ---- doubles and mixed ----
header D-
set HDR-NFA here ", D- #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D- DNEGATE jump D+
header DABS
set HDR-NFA here ", DABS #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DABS -if P jump DNEGATE P: ;
header D0=
set HDR-NFA here ", D0= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D0= OR jump 0=
header D0<
set HDR-NFA here ", D0< #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D0< push drop pop jump 0<
header D=
set HDR-NFA here ", D= #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D= D- jump D0=
header D2*
set HDR-NFA here ", D2* #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D2* 2* over -if P drop 1 + jump J P: drop J: push 2* pop ;
header D2/
set HDR-NFA here ", D2/ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D2/ push a! 0 pop +* push drop a pop ;
header M+
set HDR-NFA here ", M+ #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: M+ S>D jump D+
header M-
set HDR-NFA here ", M- #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: M- S>D DNEGATE jump D+
\ ( d1 d2 -- d1 d2 flag ) the flag's top bit is set exactly when d1 < d2
@@ -110,18 +110,18 @@ header M-
LS: drop push inv pop + inv
S2: -if N2 drop -1 jump D2 N2: drop 0
D2: pop pop ROT ;
header D<
set HDR-NFA here ", D< #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: D< (D<) push drop drop drop drop pop ;
header DMAX
set HDR-NFA here ", DMAX #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DMAX (D<) if L drop push push drop drop pop pop ; L: drop drop drop ;
header DMIN
set HDR-NFA here ", DMIN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: DMIN (D<) if L drop drop drop ; L: drop push push drop drop pop pop ;
\ ---- strings and memory ----
header ?TERMINAL
set HDR-NFA here ", ?TERMINAL #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ?TERMINAL ( -- flag ) CONSOLE-STATUS b! @b ;
header CMOVE>
set HDR-NFA here ", CMOVE> #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: CMOVE> ( src dst u -- )
-if OK drop drop drop NODE-ERROR b! 1 !b ;
OK: if DONE -1 + push
@@ -131,31 +131,31 @@ header CMOVE>
DONE: drop drop drop ;
\ FORTH-79: n cells from addr1 to addr2, the cell at addr1 first.
header MOVE
set HDR-NFA here ", MOVE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: MOVE ( addr1 addr2 n -- )
-if OK drop drop drop ;
OK: if DONE push over a! @ over a! ! 1 + push 1 + pop pop -1 + jump OK
DONE: drop drop drop ;
header FILL
set HDR-NFA here ", FILL #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: FILL ( baddr u c -- )
SWAP push SWAP pop \ c baddr u
-if OK drop drop drop NODE-ERROR b! 1 !b ;
OK: if DONE push over over C! 1 + pop -1 + jump OK
DONE: drop drop drop ;
header ERASE
set HDR-NFA here ", ERASE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: ERASE ( baddr u -- ) 0 jump FILL
header BLANK
set HDR-NFA here ", BLANK #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: BLANK ( baddr u -- ) 32 jump FILL
header -TRAILING
set HDR-NFA here ", -TRAILING #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: -TRAILING ( baddr u -- baddr u' )
-if L drop 0 ;
L: if DONE over over + -1 + C@ -32 + if SP drop ;
SP: drop -1 + jump L
DONE: ;
header COMPARE
set HDR-NFA here ", COMPARE #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: COMPARE ( a1 u1 a2 u2 -- n )
-if A drop 0 A: (X)+1 b! !b
SWAP -if B drop 0 B: dup (X) b! !b
@@ -173,7 +173,7 @@ header COMPARE
NN: if ZZ drop 1 ;
ZZ: ;
header SEARCH
set HDR-NFA here ", SEARCH #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SEARCH ( a1 u1 a2 u2 -- a3 u3 flag )
-if A drop 0 A: (X)+1 b! !b (X) b! !b
-if B drop 0 B: dup (X)+3 b! !b over (X)+2 b! !b
@@ -186,14 +186,14 @@ header SEARCH
SAME: drop 1 + push 1 + pop pop -1 + jump I
MATCH: drop drop drop -1 ;
header SCAN
set HDR-NFA here ", SCAN #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SCAN ( baddr u c -- baddr' u' )
255 and push -if L drop 0
L: if DONE over C@ pop dup push xor if FOUND
drop push 1 + pop -1 + jump L
FOUND: drop
DONE: pop drop ;
header SKIP
set HDR-NFA here ", SKIP #, 0 #, HDR-NFA #, HDR-LINK set HDR-LINK here
: SKIP ( baddr u c -- baddr' u' )
255 and push -if L drop 0
L: if DONE over C@ pop dup push xor if SAME drop jump DONE
capsules/zuse-eligibility.4th
-26
View File
@@ -1,26 +0,0 @@
Block 4021
( zuse-eligibility.4th - H.5/H.8 elevation grant )
( C prims: ZUSE-ELIGIBILITY-ADD ZUSE-ELIGIBLE? )
( NAME>XT ELEVATE-PUBKEY-UNPACK )
( Policy word this file: ELEVATE-GRANT. Runs in )
( Hera's own dict -- delivered here by kernel-Hermes's own )
( drain checkpoint (FABRIC-3.6.md task 3.10), not FORTH )
( MSG-DELIVER (messaging.4th, removed Phase 4 Stage E). )
( FABRIC-2.md H.12 step 21, 2026-09-03. )
CREATE ELEVATE-PK-BUF 32 ALLOT
Block 4022
( ELEVATE-GRANT ( waddr wu pk0 pk1 pk2 pk3 -- ) )
( Reconstructs the caller's pubkey, checks Zuse's )
( eligibility list, and on match grants the named )
( word ACL-ALLOW!/ACL-TTL! via the same reused )
( ACL-TTL mechanism H.5 decided on. No grant, no )
( error, on any mismatch -- silent refusal. )
: ELEVATE-GRANT ( waddr wu pk0 pk1 pk2 pk3 -- )
ELEVATE-PK-BUF ELEVATE-PUBKEY-UNPACK
ELEVATE-PK-BUF ZUSE-ELIGIBLE? IF
NAME>XT DUP IF
1 OVER ACL-ALLOW!
ACL-BASE-TTL SWAP ACL-TTL!
ELSE DROP THEN
ELSE 2DROP THEN ;
capsules/zuse.4th
-4
View File
@@ -12,8 +12,6 @@ Block 4016
( >BODY-then-store, so a pinned CONSTANT isn't tamper-proof. )
( Read with ZUSE-PUBKEY@ / ZUSE-CERT-INSTALLED? -- both C )
( primitives, read-only; the seed has no FORTH access at all. )
( ZUSE-ELIGIBILITY-ADD denied by default -- see block 4017. )
0 ['] ZUSE-ELIGIBILITY-ADD ACL-ALLOW!
Block 4017
( ACL-ZUSE-BOOT ( -- ) re-invokable: capsule_zuse_boot.c )
@@ -25,8 +23,6 @@ Block 4017
: ACL-ZUSE-BOOT ( -- )
ZUSE-CERT-INSTALLED? IF
ZUSE-AUTHENTICATE
1 ['] ZUSE-ELIGIBILITY-ADD ACL-ALLOW!
['] ZUSE-ELIGIBILITY-ADD ACL-PIN
LOG-INFO" zuse: activated"
ELSE
LOG-INFO" zuse: NOT activated -- no cert installed"
docs/DEAD-AND-REVISED.md
+50
View File
@@ -0,0 +1,50 @@
# Dead ideas and revised claims
A register, started 2026-10-14 by the docs triage. An idea that was abandoned, or a claim that
turned out wrong, keeps its documents (archived, with a header) — this page says, in one place,
what is no longer true, since when, and where the decision is recorded. Add to it whenever a
document is superseded or a claim corrected.
## Dead — abandoned, removed, or never adopted
| Idea | Since | What happened | Recorded in |
|---|---|---|---|
| L4Re / Fiasco.OC as a platform target | mid-2026 | Removed as an active target; LithosAnanke is its own kernel. | `.claude/CLAUDE.md` (Project Overview); docs archived in `working/archive/dead/l4re/` |
| The `hal_*` interface contract and its migration plan | flagged 2026-10-09 | Never adopted; the kernel grew its own HAL. | `working/archive/dead/hal-target-contract/`; the HAL as built: `kernel/src/hal/README.md` |
| ACL "Rolling Window of Truth" (`ACL-RECHECK-RW`) | removed 2026-07-08 | Dead code from the start: `acl_recheck()` only ever looked up `ACL-RECHECK`. | `fabric/FABRIC-1.md` §M–T |
| The Hermes VM and FORTH messaging (`messaging.4th`, `MSG-TICK`) | 2026-09-22 | Messaging moved into the kernel as kernel-Hermes; the Tripod is Hera / Artemis / Hestia. | `fabric/FABRIC-3.5.md`, `FABRIC-3.6.md`; old docs in `working/archive/superseded/2026-08-tripod/` and `.claude/HERMES.md` (frozen) |
| Running a VM's messages from Hera's idle loop (a second delivery path) | 2026-10-14 | One path: a VM takes its own messages on its own turn. | `fabric/FABRIC-3.md` §XXXVI |
| Word-ACL elevation on request (`ELEVATE-GRANT`, `KH-ELEVATE-SEND`) and Zuse's eligibility list | 2026-10-14 | Ruled not needed: privilege comes from the drive. Removed, with the hole it carried; the list's disk area is reserved, unused. | `fabric/FABRIC-3.md` §XXXVII; `fabric/FABRIC-3.7.md` (closed) |
| A knowledge factor for identity (PIN, passphrase) | 2026-09-23 | Built, tested, reverted: "there's only the drive." | `fabric/FABRIC-3.7.md` §4 |
| Defending against a byte-for-byte cloned identity drive | 2026-09-23 | Accepted by design, not a gap. (Copying from *within* StarshipOS is blocked.) | `fabric/FABRIC-3.7.md` §4 |
| The StarForth-era roadmap (VM -> kernel -> OS -> FPGA, 2025-12) | flagged 2026-08-26 | Overtaken; the architecture and terms it uses no longer exist. | `working/archive/superseded/2025-12-14-starforth-roadmap.md`; now `reference/ROADMAP.md` |
| The complete 2^6 factorial DoE | flagged 2026-10-09 | Obsolete. | `working/archive/superseded/factorial-doe/` |
| "Everything is a VM" system architecture, draft 0.1 | 2026-01-27 | A vision draft; what was built is in the FABRIC record. | `working/archive/historical/2026-01-27-system-architecture-draft.md` |
**Deferred, not dead:**
- **The multiuser/multitasking DoE campaign** (`fabric/FABRIC-3.md` §XXXIII–XXXV). Deferred past
bare metal, 2026-10-14. Its original 30-reps-per-cell design (about 10.3 days) had already been
replaced, in §XXXIV.4, by a segmented per-ISA design.
- **Keyboard VMs.** A concept only (2026-10-14), not designed.
## Revised — claims that were corrected
| Was | Is | Since | Recorded in |
|---|---|---|---|
| ACL overhead "+0.0054%–+0.0088%" (the "ACL-RWT" campaign) | **+0.0603%**, the live ACL-TTL mechanism, CV 0.000% | 2026-08-21 | `fabric/FABRIC-1.md` §T |
| Kernel version 2.0.1 | rolled back to 2.0.0 on 2026-09-04 (2.0.1 names the SER5 hardware line), now **2.1.0** (tag `v2.1.0`) | 2026-09-22 | `fabric/FABRIC-3.md` §I.2; `kernel/Makefile` |
| Capsule blocks must be in `[2048, 5120)` | **2048 or more**, no upper bound | 2026-10-05 | `v4.0.0/NUCLEUS.md` §5.2 |
| A capsule block is a 1024-byte budget | **64 characters x 16 lines** (`mkcapsule --lint`) | 2026-09-19 | `.claude/CLAUDE.md` (block format) |
| Parity baseline: 530 words, hash `0x08873e0f44b7cb2a` | **526 words, `0x82f4ae7cb2e2d424`** (elevation words out, `LOG-FLUSH`/`LOG-SHOW` in) | 2026-10-14 | `fabric/FABRIC-3.md` §XXXVII, §XXXVIII |
| Identity drives attached together are dropped (§XIV) | **no longer reproduces**, all three ISAs | 2026-10-14 | `fabric/FABRIC-3.md` §XIV |
| `THRU`/`LOAD` lose the rest of their line | **fixed** | 2026-10-14 | `fabric/FABRIC-3.md` §XXXIV.1 |
| The log ring's growth is "safe regardless of wrap state" | **it was not**; fixed | 2026-10-14 | `fabric/FABRIC-3.md` §XXXVIII |
| The Pi 5's GIC is under `/axi` with two-cell addresses; its framebuffer address needs `& 0x3FFFFFFF` | **under `/soc`, one cell**, read through `ranges`; the address **goes through `dma-ranges`** | 2026-10-14 | `fabric/FABRIC-3.md` §XXXIX |
| The old elevation path passed a raw cross-VM address | **it copied text** (the narrower real gap was a `"` in a name) | 2026-09-22 | `fabric/FABRIC-3.7.md` (its own correction) |
| Kernel builds boot v3 (v4 only with `STARFORTH_V4=1`, then v3 not at all; board images v3 unless `system=v4`) | **every build carries both and boots v4** unless `system=v3` -- v3 is being retired | 2026-10-14 | `fabric/FABRIC-3.md` XLIII (revised) |
| `.claude/ARTEMIS.md`, `HERMES.md`, `TRIPOD.md`, `CONSOLE.md` describe the system | **frozen as record**, superseded by FABRIC-3.5/3.6 | 2026-09-22 | `.claude/CLAUDE.md` (top) |
**Resolved 2026-10-14:** the top-level `README.md` was titled "LithosAnanke v2.0.1" (the SER5
hardware line's version) while the kernel is 2.1.0; Captain Bob ruled it rewritten -- it now
describes the system as it is (Tripod Hera/Artemis/Hestia, kernel-Hermes, 1052-test POST, both
systems on every board image, v4 the default).
docs/DELETE-CANDIDATES.md
+23 -15
View File
@@ -1,20 +1,28 @@
# docs/DELETE-CANDIDATES.md
**Generated:** 2026-06-16 (docs reorg Phase 2)
**Status:** Awaiting Bob's explicit confirmation. Nothing here has been deleted.
**Listed:** 2026-10-14 (docs triage). **Status: deleted 2026-10-14 on Captain Bob's ruling
("delete").** The list is kept as the record of what was removed and why; nothing is awaiting a
ruling now. The formal tier's `%% SOURCE:` comments that named two of these were repointed at
the maintained copies.
These files were tagged `DELETE` during Phase 1 triage (see `docs/INDEX.md`).
Per the ground rules in `docs/CLAUDE.md`, they are listed here and left in place
until Bob confirms removal. They were relocated with their parent trees during
the Phase 2 reorganization but otherwise left unmodified (no provenance header
was inserted into them).
Every one is a duplicate: either byte-identical to another file in the same archive, or an older
copy of a document whose maintained copy is named in the reason. Deleting them loses nothing.
| Path (current) | Original path | Reason |
|----------------|---------------|--------|
| docs/working/archive/quality/validation/break-me-report.md | docs/04-quality/validation/break-me-report.md | Empty (0 bytes); never written despite `break_me_tests.c` existing. |
| docs/working/scratch/src/bug_report.adoc | docs/src/bug_report.adoc | Generic GitHub bug-report template (smartphone/browser/OS fields) auto-converted to AsciiDoc; irrelevant to a CLI FORTH VM. |
| docs/working/scratch/src/feature_request.adoc | docs/src/feature_request.adoc | Generic GitHub feature-request template, garbled by AsciiDoc conversion; no project-specific content. |
| docs/working/scratch/src/internal/SHARED_CLAUDE.adoc | docs/src/internal/SHARED_CLAUDE.adoc | Dated 2025-10-19 ad-hoc AI session notes/chat log; pure transient working notes. |
(The four candidates listed 2026-06-16 -- an empty break-me report, two GitHub issue templates and
an AI session note -- are no longer in the tree: they were removed at some point since.)
| Path | Why |
|---|---|
| `docs/lithosananke/hal/README.md` | Duplicate of docs/working/archive/dead/hal-target-contract/README.md, without that copy's 2026-10-09 "never adopted" flags. |
| `docs/lithosananke/hal/interfaces.md` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/interfaces.md. |
| `docs/lithosananke/hal/lithosananke-integration.md` | The same document as docs/working/archive/dead/hal-target-contract/starkernel-integration.md under the kernel's newer name, without its "obsolete" flag. |
| `docs/lithosananke/hal/migration-plan.md` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/migration-plan.md. |
| `docs/lithosananke/hal/overview.md` | Duplicate (older) of docs/working/archive/dead/hal-target-contract/overview.md. |
| `docs/lithosananke/hal/platform-implementations.md` | Duplicate (older, unflagged) of docs/working/archive/dead/hal-target-contract/platform-implementations.md. |
| `docs/working/architecture/03-architecture/word-acl/DESIGN.md` | Older copy (2026-06) of docs/reference/word-acl/DESIGN.md, which is the maintained one (status through Phase 7). |
| `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_CLAIMS_FOR_REVIEWERS.txt` | Byte-identical to ../../FORMAL_CLAIMS_FOR_REVIEWERS.txt in the same archive. |
| `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/QUICK_REFERENCE.txt` | Byte-identical to ../../QUICK_REFERENCE.txt in the same archive. |
| `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/experiment_summary.txt` | Byte-identical to ../../../full_90_run_comprehensive/experiment_summary.txt in the same archive. |
| `docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/run_logs/test_matrix.txt` | Byte-identical to the same file in ../../../full_90_run_comprehensive/run_logs/. |
| `docs/working/papers/ONTOLOGY.md` | Older copy (v1.0) of docs/reference/ONTOLOGY.md (v1.1, 2026-08-13). |
To approve deletion, tell Claude "delete the DELETE candidates" (or list specific
ones to keep).
docs/INDEX.md
+635 -331
View File
@@ -1,339 +1,643 @@
# docs/INDEX.md — Documentation Triage
# docs/INDEX.md — every document, and its status
> **⚠ STALE — dated snapshot (triage performed 2026-06-16; this banner added 2026-10-09).**
> This index is maintained by hand and has not been re-run since June 2026. Do not trust its
> status tags or file lists as current: use `.claude/CLAUDE.md` and the
> `docs/fabric/FABRIC-*.md` documents for authoritative status, and re-run the Phase 1 triage
> from `docs/CLAUDE.md` if a fresh inventory is needed. Paths shown here are pre-reorg
> (`docs/03-architecture/...`, `docs/02-experiments/...`) and may have moved to
> `docs/working/architecture/03-architecture/...` / `docs/working/experiments/02-experiments/...`.
Generated 2026-10-14 by the docs triage (docs/CLAUDE.md, Phase 1), from the tracked tree
after the reorganisation. Start at **[README.md](README.md)** for the map; abandoned ideas and
revised claims are in **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)**; files awaiting a delete
ruling are in **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)**. Logs (`logs/`) and DoE run
CSVs are not listed. Bulk data folders, and the formal LaTeX tree (governed by
`docs/formal/CLAUDE.md`), are listed one row per folder.
**Phase 1 triage:** 2026-06-16 · **Phase 2 reorg:** 2026-06-16 · **Phase 3 stubs:** 2026-06-16
**Total files inventoried:** 328
**Status tags:** CURRENT · WORKING · HISTORICAL · SUPERSEDED · OBSOLETE · DELETE
| Status | Meaning | Rows |
|---|---|---|
| CURRENT | Accurate; reflects the system as it is | 96 |
| WORKING | Living draft or record, still edited | 128 |
| HISTORICAL | Accurate for its time; kept as record | 90 |
| SUPERSEDED | Replaced -- its header says by what | 26 |
| DEAD | An idea or design that was abandoned or never adopted | 12 |
| DELETE | Proposed for deletion, awaiting a ruling | 0 |
| RECORD | Experiment data and results | 50 |
| FORMAL | The press-ready LaTeX tier | 19 |
| LEGAL HOLD | Patent-adjacent; not touched without Captain Bob | 57 |
---
## .claude
## Status Key
| Path | Title | Status | Notes |
|---|---|---|---|
| .claude/ARTEMIS.md | ARTEMIS.md — Artemis VM Architecture | SUPERSEDED | Frozen 2026-08-15 by ruling (archive as-is); see FABRIC-3.5/3.6. |
| .claude/CLAUDE.md | CLAUDE.md | CURRENT | Project instructions and status; authoritative. |
| .claude/CONSOLE.md | CONSOLE.md — Console VM Architecture (DRAFT) | SUPERSEDED | Frozen 2026-08-15; see FABRIC-3.5/3.6. |
| .claude/HERMES.md | HERMES.md — Hermes VM Architecture | SUPERSEDED | Frozen 2026-08-15; describes a VM that no longer exists. See FABRIC-3.5/3.6. |
| .claude/README.md | .claude/ | CURRENT | |
| .claude/TRIPOD.md | TRIPOD.md — Architectural Constraints for the Tripod VMs | SUPERSEDED | Frozen 2026-08-15; see FABRIC-3.5/3.6. |
| Tag | Meaning |
|-----|---------|
| CURRENT | Accurate and up-to-date; reflects present architecture |
| WORKING | Active draft or living document; still being edited |
| HISTORICAL | Accurate for its time; kept as a record |
| SUPERSEDED | Replaced by a specific newer document |
| OBSOLETE | Describes architecture or processes that no longer exist |
| DELETE | No value (empty, duplicate, pure noise) |
## (root)
---
| Path | Title | Status | Notes |
|---|---|---|---|
| CHANGELOG.md | Changelog | CURRENT | |
| CODE_OF_CONDUCT.md | Contributor Covenant Code of Conduct | CURRENT | |
| CONTRIBUTING.md | Contributing to StarForth | CURRENT | |
| NOTICE.md | NOTICE.md | CURRENT | |
| README.md | LithosAnanke v2.1.0 | CURRENT | |
## Full File Index
## boards
| Path | Topic | Status | Notes |
|------|-------|--------|-------|
| ./.claude/CLAUDE.md | Authoritative architecture/status reference | CURRENT | Self-declared authoritative reference; internally consistent (v3.0.3, LithosAnanke v1.0.8, ACL phases 1-6 done/7-8 pending); used as ground truth for this audit. |
| ./CODE_OF_CONDUCT.md | Community conduct standards | CURRENT | Standard Contributor Covenant boilerplate, not version/architecture-dependent. |
| ./CONTRIBUTING.md | Contribution guidelines, build/test workflow | WORKING | References "780+ tests" and points to `docs/CLAUDE.md` as project overview, while authoritative CLAUDE.md cites 936+ tests and itself (`.claude/CLAUDE.md`) as authoritative — minor staleness, but actively-useful living doc. |
| ./NOTICE.md | License attribution notice | CURRENT | Static legal/attribution text tied to Starship License 1.0, consistent with CLAUDE.md license section. |
| ./ONTOLOGY.md | Formal taxonomy/thermodynamic lexicon | CURRENT | Dated 2025-12-13; explicitly referenced as canonical lexicon by CLAUDE.md and README; conceptual framework, not version-dependent. |
| ./README.md | Project overview/quick start | SUPERSEDED | Cites release tag v1.5.0-RELEASE, "800+ test suite", "21 theory files" vs CLAUDE.md's current v3.0.3, 936+ tests, 24 theory files — predates several version bumps; superseded by `.claude/CLAUDE.md`. |
| ./ROADMAP.md | VM→Kernel→OS→FPGA phased roadmap | SUPERSEDED | Dated 2025-12-14, describes StarKernel/HAL as not yet begun, but CLAUDE.md shows LithosAnanke v1.0.8 with M0–M6 complete and M7 in progress — overtaken by progress; CLAUDE.md's embedded roadmap summary is now current. |
| docs/working/experiments/campaigns/doe_2x7/README.md | 2^7 factorial DoE methodology guide | CURRENT | Reusable how-to-run guide for the DoE experiment class, not tied to one run; matches current 7-loop architecture. |
| docs/working/experiments/campaigns/l8_attractor_map/SESSION_REPORT_2025-12-10.md | Narrative session report on L8 attractor debugging | HISTORICAL | Dated first-person account of one specific debugging/analysis session; accurate record of its time. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/TIDBITS.md | Informal findings notes from L8 attractor analysis | HISTORICAL | Informal commentary tied to one specific dataset/run (2025-12-09); a snapshot artifact. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/comprehensive_report.md | Statistical report on L8 heartbeat across 180 runs | HISTORICAL | Dated analysis report of one specific experiment run's results. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/comprehensive_report.md.pdf | Rendered PDF of comprehensive_report.md | HISTORICAL | Rendered artifact of the same dated run's report; same status as its .md source. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/heartbeat_analysis.md | Heartbeat statistical analysis (ANOVA, workload effects) | HISTORICAL | Dated 2025-12-09, tied to this specific 180-run dataset; a results record. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/mathematical_framework.md | Oscillator-inspired equations fit to heartbeat data | HISTORICAL | Speculative modeling derived from this one dataset's measured frequencies; dated analysis artifact. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/report/mathematical_framework.md.pdf | Rendered PDF of mathematical_framework.md | HISTORICAL | Rendered artifact of the same dated analysis. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/tables/NOTES.md | Notes accompanying generated data tables | HISTORICAL | Supporting notes for one run's generated tables; tied to that dated results directory. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/analysis_output/tables/anova_results.txt | Raw ANOVA output (tick count/duration vs workload) | HISTORICAL | Raw statistical output specific to the 2025-12-09 run. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/binary_2cycle_analysis_report.md | Binary 2-cycle clustering analysis of heartbeat phase space | HISTORICAL | Dated (2025-12-11) follow-on analysis of the same 180-run dataset. |
| docs/working/experiments/campaigns/l8_attractor_map/run_log.txt | Raw execution log of L8 attractor experiment run | HISTORICAL | Raw run transcript referencing a specific results directory; record of one execution session. |
| docs/working/experiments/campaigns/l8_validation/EXPERIMENT_SUMMARY.txt | L8 Jacquard validation experiment design summary | HISTORICAL | Fixed summary of one validation campaign ("IMPLEMENTED: 2025-11-26"), not a reusable guide (README fills that role). |
| docs/working/experiments/campaigns/l8_validation/README.md | L8 Jacquard validation methodology guide | CURRENT | Reusable how-to/experimental-design guide for re-running this class of experiment; matches current L8 Jacquard architecture. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_20251208_102205/conditions_randomized.txt | Randomized condition matrix for one validation run | HISTORICAL | Raw generated condition list timestamped 2025-12-08; specific run's input data. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_20251208_102205/conditions_raw.txt | Unrandomized condition matrix for one validation run | HISTORICAL | Companion raw matrix for the same dated run. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_30reps_20251126_135128/conditions_randomized.txt | Randomized condition matrix, 30-rep run | HISTORICAL | Dated 2025-11-26 run's input matrix; an earlier run in the same family. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_30reps_20251126_135128/conditions_raw.txt | Unrandomized condition matrix, 30-rep run | HISTORICAL | Companion raw matrix for the same 2025-11-26 run. |
| docs/working/experiments/campaigns/shape_validation/README.md | Workload shape validation methodology guide | CURRENT | Reusable quick-start guide for re-running the shape-validation experiment class; architecture-consistent with CLAUDE.md. |
| docs/working/experiments/campaigns/shape_validation/shape_RAJ_run_20251127_093208/conditions_randomized.txt | Randomized condition matrix for one shape-validation run | HISTORICAL | Specific dated (2025-11-27) run's randomized input data. |
| docs/working/experiments/campaigns/shape_validation/shape_RAJ_run_20251127_093208/conditions_raw.txt | Unrandomized condition matrix for one shape-validation run | HISTORICAL | Companion raw matrix for the same 2025-11-27 run. |
| docs/working/experiments/campaigns/shape_validation/shape_run_20251123_083147/conditions_randomized.txt | Randomized condition matrix, earlier shape-validation run | HISTORICAL | Dated 2025-11-23, earlier run in same family. |
| docs/working/experiments/campaigns/shape_validation/shape_run_20251123_083147/conditions_raw.txt | Unrandomized condition matrix, earlier shape-validation run | HISTORICAL | Companion raw matrix for the 2025-11-23 run. |
| docs/working/experiments/campaigns/window_scaling/QUICK_START.md | Window-scaling (James Law) experiment quick-start steps | CURRENT | Reusable step-by-step workflow for re-running the experiment; procedural, not tied to a single completed run. |
| docs/working/experiments/campaigns/window_scaling/README.md | Window-scaling experiment design / James Law hypothesis | CURRENT | Reusable experimental-design overview (hypothesis, expected outcomes) for the experiment class. |
| docs/working/papers/published/James_Steady-State_Convergence_Adaptive_Runtime.pdf | Published SSRN academic paper | CURRENT | Confirmed present; explicitly named as the published SSRN paper in CLAUDE.md; a citable finished artifact. |
| ./scripts/SCRIPT_REPAIR_LOG.md | Bug-fix log for run_ablation_study.sh | HISTORICAL | Documents specific fixes made 2025-11-20 to a script that still exists; valuable as a record but not living guidance. |
| docs/working/papers/ACADEMIC_WORDING_GUIDELINES.md | Academic language rules for physics-metaphor claims | CURRENT | Active style guide for SSRN paper and derivatives; referenced by authors/contributors. |
| docs/working/scratch/AGENTS.md | Repo structure and contribution rules for AI/human contributors | CURRENT | Accurate description of build, test, naming, and PR conventions; matches current codebase layout. |
| docs/working/scratch/AI_AGENT_MANDATORY_README.md | Mandatory AI-agent pre-read for physics runtime changes | CURRENT | Governance document; rules are evergreen; references live subsystem names. |
| docs/working/papers/ANTI_CLAIMS.md | Explicit boundary statements for SSRN/peer-review defensibility | CURRENT | Directly supports published SSRN paper; no code references that have drifted. |
| ./docs/CLAUDE.md | Docs-root instructions for Claude Code; two-tier doc model plan | WORKING | Describes a `docs/formal/` + `docs/working/` restructure not yet executed; active planning doc, not authoritative state ref (`.claude/CLAUDE.md` is). |
| docs/working/archive/COMPUTATIONAL_PHYSICS_FRAMEWORK.md | Expansive "physics of computation" claims framework | HISTORICAL | Contains strong over-claims ("This is not metaphor") that contradict `ANTI_CLAIMS.md` and `ACADEMIC_WORDING_GUIDELINES.md`; dates from earlier draft thinking (2025-12-10). |
| ./docs/DARPA_SSM_Proposal_James.docx | DARPA SSM grant proposal (Word format) | WORKING | Active proposal document; companion to the PDF version. |
| ./docs/DARPA_SSM_Proposal_James.pdf | DARPA SSM grant proposal (PDF) | WORKING | Active funding proposal; filename indicates a working/submission-ready draft. |
| docs/working/archive/DOCUMENTATION_AUDIT.md | Docs audit from 2025-12-14; gap/inconsistency findings | HISTORICAL | Audit from a past triage pass; most findings have since changed; useful historical record. |
| docs/working/papers/EXECUTIVE_SUMMARY.md | Plain-English summary of StarForth results for non-specialists | CURRENT | Accurate, well-calibrated summary with correct metaphor framing; audience: journalists, admins, reviewers. |
| docs/working/papers/FINAL_REPORT/appendix_glossary.adoc | AsciiDoc glossary appendix for multi-chapter report | CURRENT | Formal, math-precise definitions consistent with current ontology; intended for book/report compilation. |
| docs/working/papers/FORMAL_CLAIM_TABLE.md | Structured claim–evidence–reproducibility table for peer review | CURRENT | Core scientific accountability doc; tied to SSRN paper claims; still valid. |
| docs/working/archive/GAP_ANALYSIS.md | Gap analysis: StarForth → StarKernel → StarshipOS → FPGA | SUPERSEDED | Written when StarKernel had "zero implementation"; LithosAnanke v1.0.8 has M0-M6 complete — the kernel gaps section is stale. |
| docs/working/papers/NEGATIVE_RESULTS.md | Documented failure modes and limitations | CURRENT | Honest failure-mode catalog; still accurate and academically valuable. |
| docs/working/papers/NULL_HYPOTHESIS.md | Formal null hypothesis and falsification criteria | CURRENT | Rigorous statistical framing for SSRN claims; no stale references. |
| docs/working/papers/ONTOLOGY.md | Master ontology/taxonomy/lexicon for adaptive runtime concepts | CURRENT | Authoritative term definitions; referenced by root ONTOLOGY.md and docs/README.md; actively used. |
| docs/working/papers/ONTOLOGY_README.md | Index/guide to ontology file set (md, tex, adoc) | CURRENT | Accurate pointer document for ontology artifacts; still valid. |
| ./docs/README.md | Top-level docs directory README and navigation | WORKING | Navigation is broadly accurate but mentions HAL migration as "current active work" which is further along now. |
| docs/working/papers/REPLICATION_INVITE.md | Formal open invitation to independent replication | CURRENT | Evergreen scientific openness statement; expected output values still match claimed results. |
| docs/working/papers/REPRODUCIBILITY.md | One-command reproduction protocol with exact expected output | CURRENT | References valid build commands and `--doe` flag; expected output values consistent with published claims. |
| docs/working/papers/SCIENTIFIC_DEFENSE_CHECKLIST.md | Checklist of attack vectors and defenses for peer review | WORKING | Many "missing defenses" (GPG signing, Zenodo DOI, R/Python scripts) not yet addressed; still actively relevant. |
| docs/working/papers/SENSITIVITY_ANALYSIS.md | Parameter sweep design: robustness of 0% CV claim | CURRENT | Documents planned sensitivity experiments; scientifically sound framing; supports SSRN defensibility. |
| ./docs/SSM_DARPA_Complete_Proposal_James_FINAL.docx | DARPA SSM complete/final proposal (Word, FINAL) | WORKING | "FINAL" in name suggests submission-ready; likely supersedes `DARPA_SSM_Proposal_James.docx` but keep both until confirmed. |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.pdf | Compiled PDF of math companion to SSRN paper | CURRENT | Rendered output of the `.tex` source; companion to the published SSRN paper. |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex | LaTeX source for math companion document | CURRENT | Source of record for comprehensive math/engineering structures reference; cross-references implementation. |
| docs/working/papers/SSRN_companion/figures/fig1_snake_trajectory.pdf | Figure asset: snake/phase trajectory | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig2_K_vs_window.pdf | Figure asset: K vs window width | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig3_FFT_spectrum.pdf | Figure asset: FFT spectrum | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig4_golden_ratio_penalties.pdf | Figure asset: golden ratio penalties | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig5_bimodal_distributions.pdf | Figure asset: bimodal distributions | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig6_performance_vs_k.pdf | Figure asset: performance vs K | CURRENT | Figure asset for the SSRN math companion. |
| docs/working/papers/SSRN_companion/figures/fig7_performance_by_regime.pdf | Figure asset: performance by regime | CURRENT | Figure asset for the SSRN math companion. |
| ./docs/SYSTEM_NARRATIVE.pdf | Compiled PDF of system narrative | CURRENT | Rendered output of `SYSTEM_NARRATIVE.tex`; technical story for patent counsel and reviewers. |
| ./docs/SYSTEM_NARRATIVE.tex | LaTeX source: technical narrative for patent/research review | CURRENT | Well-framed, correctly calibrated narrative; accurate description of the adaptive runtime and 90-run experiment. |
| docs/working/scratch/TASK_LIST.md | AI/human task list with working rules and incremental tasks | WORKING | All tasks are unchecked; likely predates recent physics work; rules section is evergreen but specific tasks may be stale or partially done. |
| docs/working/archive/artifacts/kanban-workflow/MANIFEST.adoc | Artifact manifest for kanban workflow validation scripts | HISTORICAL | Tracks process-tooling artifacts from a past workflow setup session; no ongoing relevance to VM or kernel. |
| docs/working/scratch/assets/README.md | Binary assets holding area README | WORKING | Correctly flags `book-FIXED.docx` etc. as misplaced; the guidance (move to LFS/external) is still actionable. |
| docs/working/scratch/assets/book-FIXED.docx | Book/report Word document | WORKING | Binary asset misplaced in docs/assets; should move to LFS per assets/README.md guidance. |
| docs/working/architecture/heartbeat_csv_export.md | Heartbeat CSV export design: format, columns, TODO status | WORKING | Several columns marked `⚠️ TODO`; matches CLAUDE.md note that `heartbeat_export_csv()` is not yet implemented; active design/tracking doc. |
| ./docs/ontology.pdf | Compiled PDF of `ontology.tex` | CURRENT | Rendered output of `ontology.tex`; self-contained reference for academic inclusion. |
| ./docs/ontology.tex | LaTeX source for formal ontology | CURRENT | Source of record matching `ONTOLOGY.md` content; used for journal/conference paper inclusion. |
| docs/working/archive/prog-prove.pdf | Unknown — likely Isabelle/HOL or proof-assistant tutorial PDF | HISTORICAL | Filename suggests a proof-programming reference; not authored by this project; reference material only. |
| docs/working/architecture/getting-started/DEVELOPER.md | Dev environment setup, Isabelle install | CURRENT | Generic setup instructions still match current build system. |
| docs/working/architecture/getting-started/README.md | Getting-started index/TOC | CURRENT | Navigation page; links resolve to existing files. |
| docs/working/architecture/getting-started/quick-start/factorial-doe.md | Quick-start for 2^6 per-loop factorial DoE | OBSOLETE | Describes retired `ENABLE_LOOP_1..6` compile-time toggles; replaced by L8 Jacquard runtime mode selector. Hardcoded `/home/rajames/...` paths. |
| docs/working/architecture/getting-started/quick-start/heartbeat-doe.md | Quick-start for heartbeat DoE run | HISTORICAL | Dated 2025-11-20, references a specific completed run directory and hardcoded user paths. |
| docs/working/architecture/getting-started/quick-start/optimization-doe.md | Quick-start for 5-opportunity optimization DoE | HISTORICAL | References dated result dirs from a completed tuning campaign; superseded conceptually by L8's data-driven design. |
| docs/working/experiments/02-experiments/L8_WIRING_CODE_REVIEW_GUIDE.md | Code review guide for L8 wiring (L2/L3/L5/L6) | HISTORICAL | Dated 2025-12-05; matches current `physics_metadata.c` — completed, accurate review record. |
| docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md | Summary of L8 gating implementation | HISTORICAL | Dated 2025-12-05, marked complete; verified consistent with current source. |
| docs/working/experiments/02-experiments/L8_WIRING_PLAN.md | Plan for wiring loops to L8 mode selector | SUPERSEDED | Superseded by L8_WIRING_IMPLEMENTATION_SUMMARY.md and L8_WIRING_CODE_REVIEW_GUIDE.md (plan was executed and reviewed). |
| docs/working/experiments/02-experiments/README.md | Experiments directory index | CURRENT | Accurately lists existing subdirectories. |
| docs/working/experiments/02-experiments/factorial-doe/guide.md | Full 2^6 factorial DoE guide | OBSOLETE | Describes retired per-loop Makefile-toggle architecture, replaced by L8 Jacquard. |
| docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md | Handling incompatible factorial loop configs | OBSOLETE | Build-time incompatibility handling for the retired 2^6 toggle experiment. |
| docs/working/experiments/02-experiments/factorial-doe/index.md | Index for factorial DoE docs | OBSOLETE | Points to stale doc paths; describes retired architecture. |
| docs/working/experiments/02-experiments/factorial-doe/workflow.md | Factorial DoE data pipeline workflow | HISTORICAL | Documents completed 2025-11-19 factorial campaign that produced data behind current L8 design; toggle architecture retired. |
| docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md | Heartbeat DoE corrected metric design | SUPERSEDED | Superseded by phase2-corrected.md ("corrected and finalized" version). |
| docs/working/experiments/02-experiments/heartbeat-doe/design.md | Original Phase 2 heartbeat DoE design | SUPERSEDED | Pre-correction draft; superseded by corrected-design.md / phase2-corrected.md. |
| docs/working/experiments/02-experiments/heartbeat-doe/execution-guide.md | How to run Phase 2 heartbeat DoE | HISTORICAL | Dated 2025-11-20, hardcoded stale path; describes running the now-superseded design. |
| docs/working/experiments/02-experiments/heartbeat-doe/implementation-summary.md | Deliverables summary for heartbeat DoE | HISTORICAL | Point-in-time "complete" status snapshot dated 2025-11-20 for pre-correction design. |
| docs/working/experiments/02-experiments/heartbeat-doe/phase2-corrected.md | Final corrected heartbeat DoE design | WORKING | Latest version in the revision chain; still describes not-yet-fully-implemented work. |
| docs/working/experiments/02-experiments/james-law/protocol.md | SSM gravitational-collapse threshold hypothesis/protocol | WORKING | Forward-looking theoretical experiment protocol, no completion markers. |
| docs/working/experiments/02-experiments/physics-optimization/doe-guide.md | Guide for 5-opportunity progressive optimization DoE | CURRENT | Generic script-driven methodology still consistent with current physics engine. |
| docs/working/experiments/02-experiments/physics-optimization/execution-guide.md | Guide for 90-run comprehensive physics validation | CURRENT | Underlies the "0% variance across 90 runs" claim in CLAUDE.md. |
| docs/working/experiments/02-experiments/physics-optimization/hotwords-cache.md | Hot-words cache experiment results (1.78x speedup) | HISTORICAL | Completed-experiment results report with fixed numbers. |
| docs/working/experiments/02-experiments/physics-optimization/proposals.md | 9 proposed future optimization opportunities | WORKING | Living forward-looking proposal doc built on hotwords-cache result. |
| docs/working/experiments/02-experiments/physics-optimization/reproduce.md | Reproduction recipe for hotwords-cache result | CURRENT | Narrow, still-valid step-by-step reproduction guide. |
| docs/working/architecture/03-architecture/OVERVIEW.md | Top-level architecture overview (3-layer model, physics loops, boot sequence) | WORKING | Header says "Status: Complete, 2025-12-14" but roadmap still frames StarKernel as "PLANNED"/HAL migration "IN PROGRESS," lagging CLAUDE.md's actual M0-M6-done/M7-in-progress state; needs a refresh pass. |
| docs/working/architecture/03-architecture/README.md | Directory index/landing page for 03-architecture/ | WORKING | Shorter duplicate of OVERVIEW.md's roadmap; same staleness (treats StarKernel as not-yet-started); functions as nav index, content needs sync with CLAUDE.md. |
| docs/working/architecture/03-architecture/adaptive-systems/adaptive-window-and-decay.md | Root-cause investigation: rolling-window shrink + decay_slope placeholder bugs | HISTORICAL | Dated 2025-11-08, "Root Cause Analysis Complete." Diagnostic/incident report; trigger doc for window-inference-redesign.md. |
| docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md | Alternate Loop #5 proposal: prefetch-accuracy-driven binary-chop window tuning | SUPERSEDED | Superseded by window-inference-redesign.md. Undated draft ending in an open question to the user (never approved); the shipped Loop #5 uses Levene's test, not this mechanism. |
| docs/working/architecture/03-architecture/adaptive-systems/multivariate-dynamics.md | Phase 2 DoE experiment design: multivariate stability fingerprinting across 7 metrics | WORKING | Dated 2025-11-20, "Status: Design Phase." Forward-looking proposal tied to still-unimplemented heartbeat instrumentation. |
| docs/working/architecture/03-architecture/adaptive-systems/window-inference-redesign.md | Redesign of window-width inference using Levene's test on disjoint chunks | CURRENT | Dated 2025-11-19, "DESIGN (approved for implementation)." Matches the Loop #5/#6 mechanism CLAUDE.md/OVERVIEW.md describe as actually implemented (inference_engine.c). |
| docs/working/architecture/03-architecture/hal/README.md | Index/reading-order guide for HAL doc set | WORKING | Status table claims all 5 HAL docs "Complete, 2025-12-14," but describes target architecture per overview.md's own disclaimer, not built code; misleading without that caveat. |
| docs/working/architecture/03-architecture/hal/interfaces.md | hal_* C interface contract spec (time, interrupt, memory, console, cpu, panic) | WORKING | Normative target API design; current codebase uses sf_time_backend_t-style naming per overview.md — this HAL layer is not yet built as specified. |
| docs/working/architecture/03-architecture/hal/migration-plan.md | 7-phase plan to migrate codebase to hal_* interfaces | WORKING | Forward plan ("Phase 2 IN PROGRESS" per roadmap); CLAUDE.md's current source tree shows this migration not yet executed. |
| docs/working/architecture/03-architecture/hal/overview.md | HAL rationale/design-principles doc | WORKING | Contains the key disclaimer: "current codebase uses sf_time_backend_t... different naming" — explicitly flags the whole HAL doc family as target/aspirational, not current. |
| docs/working/architecture/03-architecture/hal/platform-implementations.md | Example hal_* implementations for Linux and kernel platforms | OBSOLETE | Assumes src/platform/<platform>/hal_*.c layout; actual built StarKernel tree (per CLAUDE.md) uses src/starkernel/{arch,boot,capsule,hal,memory,...} — a different, already-implemented structure. |
| docs/working/architecture/03-architecture/hal/starkernel-integration.md | Kernel HAL integration guide, src/platform/kernel/ layout, milestone roadmap to "ok" prompt | OBSOLETE | Describes Milestone 1 "Boot + Serial Output" as a starting point; LithosAnanke is actually at v1.0.8 with M0-M6 complete, M7 in progress, using a wholly different src/starkernel/ directory structure. |
| docs/working/architecture/03-architecture/heartbeat-system/architecture.md | Proposes vm_tick() dispatcher centralizing Loop #3/#5 heartbeat logic | HISTORICAL | No date; ends in an open question, never confirmed adopted. Foundational rationale doc; superseded in specifics by instrumentation-plan.md's HeartbeatTickSnapshot design. |
| docs/working/architecture/03-architecture/heartbeat-system/critical-insight.md | Discovery memo: heartbeat tick rate is variable, not fixed; Stage 1 DoE baseline was flawed | HISTORICAL | Dated 2025-11-20, "Game-changer for Phase 2 DoE." Point-in-time investigation memo that directly motivated implementation-plan.md. |
| docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md | Plan for HeartbeatRateSample logging to capture variable tick rate | SUPERSEDED | Superseded by instrumentation-plan.md. Same date (2025-11-20) and goal, but proposes an earlier/different struct (HeartbeatRateSample) than the HeartbeatTickSnapshot design CLAUDE.md cites as the live target. |
| docs/working/architecture/03-architecture/heartbeat-system/instrumentation-plan.md | Per-tick instrumentation plan: HeartbeatTickSnapshot, tick_buffer, heartbeat_export_csv() | WORKING | Explicitly the doc CLAUDE.md cites as current ("declared in include/vm.h, but heartbeat_export_csv() is not yet implemented"). Checklist entirely unchecked. |
| docs/working/architecture/03-architecture/heartbeat-system/segfault-analysis.md | Root-cause analysis of heartbeat-thread/main-thread race on RollingWindowOfTruth | HISTORICAL | Dated 2025-11-19, "Identified & Ready for Fix," includes a past-tense commit-message template implying the tuning_lock fix was applied. No current doc mentions this race as open. |
| docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md | Investigative bug-hunt audit of 6 feedback loops (precursor to the 7-loop model) | SUPERSEDED | Superseded by feedback-loops.md. Dated 2025-11-08, full of strikethrough "FIXED" headers; covers only 6 loops, unlike the polished current 7-loop reference. |
| docs/working/architecture/03-architecture/physics-engine/feedback-loops.md | Canonical reference: all 7 feedback loops, tuning knobs, related source files | CURRENT | Matches CLAUDE.md's explicit citation ("all 7 loops detailed") verbatim; clean finished reference table covering Loops #1-7 including #5/#6 inference. |
| docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md | Gap-analysis backlog of metrics not yet collected (stack depth, bucket histograms, etc.) | WORKING | Explicitly self-titled "GAPS ONLY"; prioritized TODO backlog, not a current-state description; some gaps may have since been filled. |
| docs/working/architecture/03-architecture/physics-engine/monitoring-principles.md | Doctrinal rules for non-perturbative monitoring instrumentation | CURRENT | Presents itself as binding/evergreen ("canonical rules for ALL AI assistants"); uses an older "four core loops (FL1-FL4)" framing that should be reconciled with the current 7-loop model, but the doctrine itself remains in force. |
| docs/working/architecture/03-architecture/physics-engine/ssm-equations.md | Exploratory mathematical modeling of SSM via physics analogies for patent/DARPA strategy | HISTORICAL | Dated 2025-11-29, self-labeled "Status: Research Analysis - Exploratory." Predates Jacquard naming; speculates generically about future "L8" without Jacquard/attractor-bucket/mode-name vocabulary. |
| docs/working/architecture/03-architecture/physics-engine/ssm-raw-data-analysis.md | Raw experimental data analysis from a specific Nov 22-27 2025 DoE campaign (51,840 runs) | HISTORICAL | Dated 2025-11-29; tied to specific named CSV files and a calendar-based "Next Steps" plan. Uses "L8" and 4 of 6 Jacquard mode names but never "Jacquard" — an early/transitional naming stage. |
| docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md | Formal theoretical definition of SSM as a computational model (attractor basins, axioms) | OBSOLETE | Zero mentions of "Jacquard," "L8," "attractor bucket," or the six named modes from CLAUDE.md; reads as a conceptual precursor never reconciled with the concrete ssm_jacquard.c system. |
| docs/working/architecture/03-architecture/pipelining/context-window-and-binary-chop.md | Context-window infrastructure (Knob #6) + planned binary-chop tuning for Loop #4 | WORKING | Dated 2025-11-06, "Phase 1 Extension Complete," but binary-chop decision logic explicitly a doubling-rule stub with "Phase 2 (Next session)" unchecked; corroborated as still-unutilized by wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/design.md | Master architectural design for pipelining/speculative execution (Loop #4) | HISTORICAL | No date/status stamp; entirely aspirational ("Goal:", "Hypothesis"); Phase 3+ (actual prefetching/speculation) roadmap items remain unchecked and appear unrealized per wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/phase-1-instrumentation.md | Completed-checkpoint record of Phase 1 transition-tracking instrumentation | HISTORICAL | Dated 2025-11-06, "Phase 1 Complete," 731 tests passing — accurate closed record of one sub-phase; its Phase 2-4 TODOs were never closed per wired-not-utilized.md. |
| docs/working/architecture/03-architecture/pipelining/wired-not-utilized.md | Critical-issue report: pipelining decision/speculation logic defined but never called | WORKING | No date/commit stamp; ends on an unactioned recommendation ("Option A: Disable") with no resolution language. Indicates Loop #4's prediction/speculation half may still be inactive in code. |
| docs/working/architecture/03-architecture/word-acl/DESIGN.md | Full design spec for word-level ACL system (C fields, ACL.4th, zuse.4th, two-console model) | CURRENT | Explicitly the doc CLAUDE.md designates authoritative; internal 8-phase punch list (Phases 1-6 done, 7-8 remaining) matches CLAUDE.md's summary exactly. |
| docs/working/archive/quality/README.md | Quality directory index | OBSOLETE | States "18 modules"; current is 22 categories/936+ tests per CLAUDE.md. |
| docs/working/archive/quality/audits/codebase-audit-report.md | Full codebase audit | HISTORICAL | Dated 2025-12-03; point-in-time snapshot, paired with corrective-actions.md. |
| docs/working/archive/quality/audits/corrective-actions.md | Resolution log for codebase audit | HISTORICAL | Dated 2025-12-03, v3.0.1, "COMPLETE" — 21/22 issues resolved; companion to codebase-audit-report.md. |
| docs/working/archive/quality/audits/implementation-audit.md | Adaptive tuning implementation audit | HISTORICAL | Dated 2025-11-19, references 787/840 tests (now 936+); overtaken by later OPP reports. |
| docs/working/archive/quality/audits/section-2-audit.md | Physics subsystem safety audit (full) | HISTORICAL | Dated 2025-11-20; paired with section-2-executive-summary.md. |
| docs/working/archive/quality/audits/section-2-executive-summary.md | Physics safety audit executive summary | HISTORICAL | Dated 2025-11-20, "complete - awaiting final approval"; summary counterpart to section-2-audit.md. |
| docs/working/archive/quality/phase-tracking/phase-2-implementation-checklist.md | Checklist for heartbeat instrumentation (tick_buffer/snapshot) | WORKING | CLAUDE.md confirms struct exists but heartbeat_export_csv() still not implemented — open, unrealized plan. |
| docs/working/archive/quality/phase-tracking/phase-2-issues-identified.md | Float/double violations root-cause list in physics code | HISTORICAL | Dated 2025-11-08, "in progress" at the time; precedes implementation-checklist. |
| docs/working/archive/quality/phase-tracking/phase-2a-session-summary.md | Session summary: WORD_FROZEN flag + linear decay | HISTORICAL | Dated 2025-11-07, "complete & validated"; distinct earlier "Phase 2a" thread. |
| docs/working/archive/quality/regression/detection-framework.md | Regression detection framework design (for OPP #2+) | HISTORICAL | Dated 2025-11-19, design doc later used in opp-02-report.md. |
| docs/working/archive/quality/regression/opp-02-report.md | OPP #2 window-width tuning experiment report | HISTORICAL | Dated 2025-11-19, "complete"; recommends a config for OPP #3 — completed dated report. |
| docs/working/archive/quality/validation/break-me-report.md | Adversarial/fuzz testing report (intended) | DELETE | File is empty (0 bytes); never written despite break_me_tests.c existing. |
| docs/working/archive/quality/validation/comprehensive-physics-validation.md | Triple-blind 90-run DoE physics validation protocol | HISTORICAL | Dated 2025-11-06; source protocol behind the "0% variance across 90 runs" figure cited in CLAUDE.md. |
| docs/working/archive/quality/validation/phase-1-protocol.md | GitHub governance/document-routing validation protocol | OBSOLETE | Dated 2025-11-03; describes a governance/vault repo system absent from current architecture, unrelated to physics DoE. |
| docs/working/archive/quality/validation/phase-2-executive-summary.md | DoE paradigm shift: factorial to multivariate dynamics (750-run plan) | HISTORICAL | Dated 2025-11-20, "design complete, ready for implementation." |
| docs/working/archive/operations/README.md | Ops directory index / build & CI overview | CURRENT | Build/test commands match current Makefile; honestly labels CI/CD section "(Future)". |
| docs/working/archive/operations/backlog-gatekeeper.md | Backlog governance (ECO/CAPA gatekeeper) | OBSOLETE | References a `.github/workflows/...` file that doesn't exist; no `.github/` directory in repo at all. |
| docs/working/archive/operations/jenkins-pipeline-guide.adoc | Jenkins CI pipeline architecture | OBSOLETE | No Jenkinsfile or CI config exists anywhere in the repo. |
| docs/working/archive/operations/qa-intake-workflow.adoc | QA defect intake / CAPA process | OBSOLETE | Cites stale version v2.0.2 (current v3.0.3); references nonexistent GitHub issue templates and Jenkins automation. |
| docs/working/archive/operations/refinement/annotations.adoc | C/Isabelle refinement annotation guide | WORKING | "Phase 1 in-progress" header; active methodology guide for ongoing refinement work. |
| docs/working/archive/operations/refinement/capa.adoc | C/Isabelle refinement defect tracking log | WORKING | All phases "not started," currently empty live tracking doc. |
| docs/working/archive/operations/refinement/roadmap.adoc | C/Isabelle refinement roadmap | WORKING | All key functions listed "OPEN"; active planning doc with 6-8 month estimate. |
| docs/working/archive/operations/workflow.md | CI/CD trunk-based branch workflow (devl/test/qual/prod) | OBSOLETE | Describes branches/Jenkins triggers that don't exist; repo only has master and feature branches. |
| docs/working/archive/research/README.md | Research directory index | SUPERSEDED | References a patent-filing placeholder/submission package now superseded by the published SSRN paper. |
| docs/working/archive/research/doe-metrics-schema.md | DoE CSV metrics schema (35 columns) | HISTORICAL | Dated 2025-11-19, predates the 2025-12-08 CSV-export suppression noted in CLAUDE.md. |
| docs/working/archive/research/literature-review.md | Literature positioning for the optimization paper | SUPERSEDED | Draft feeder material for the now-published SSRN paper. |
| docs/working/archive/research/research-outline.md | Paper outline draft ("working title" + alternatives) | SUPERSEDED | Pre-publication draft outline; paper has since been published. |
| docs/working/archive/research/results-for-publication.md | Draft abstract targeting PLDI/ASPLOS | SUPERSEDED | Draft abstracts for venues other than where it was ultimately published (SSRN). |
| docs/working/archive/session-logs/2025-11-20-recap.md | Dated session recap (DoE multivariate dynamics pivot) | HISTORICAL | Explicitly dated point-in-time design discussion record. |
| docs/working/archive/session-logs/2025-11-26-worklog.md | Dated work log (L8 Jacquard integration) | HISTORICAL | Explicitly dated; documents the l8-final-integration milestone. |
| docs/working/archive/session-logs/README.md | Session-logs directory index | CURRENT | Accurately describes folder purpose; explicitly warns logs may be outdated. |
| docs/working/archive/session-logs/experimental-addendum.md | Mislabeled: actually a "StarForth to StarshipOS Hybrid Kernel Transformation Plan" | OBSOLETE | Early kernel design plan superseded by the actually-implemented LithosAnanke v1.0.8 architecture (M0-M7). |
| docs/working/archive/session-logs/experimental-iteration-usage.md | Usage guide for run_doe.sh / run_experimental_iteration.sh | WORKING | Matching scripts still exist in scripts/; living usage guide, not a dated log. |
| docs/working/archive/session-logs/serialized-questing-pike.md | Informal narrative on physics-analogy overclaiming risk | HISTORICAL | Captured point-in-time exploratory discussion, not a guide. |
| ./docs/patent/CHANGES_SUMMARY.md | Patent revision log (title, James Law language, claim changes) dated 2025-12-10 | HISTORICAL | Records decisions made during v2 revisions; accurate for its time but describes edits already applied — not a live working document. |
| ./docs/patent/JARGON_CHANGES.md | Term-replacement log (e.g. "Execution Heat" → "Execution Frequency Counters") dated 2025-12-10 | HISTORICAL | Records terminology decisions already baked into _v2 section files; useful audit trail but not a living document. |
| ./docs/patent/Makefile | LaTeX build rules for `main.tex` | CURRENT | Minimal but functional; drives `pdflatex main.tex` double-pass build. |
| ./docs/patent/README_V3.md | Overview claiming `patent_v3_complete.tex` is the master document | OBSOLETE | Describes a master file (`patent_v3_complete.tex`) that does not exist; structure does not match the actual `main.tex`-based layout. |
| ./docs/patent/USPTO_COVER_LETTER.md | Draft USPTO provisional cover letter with placeholder contact fields | WORKING | Contact fields (`[Your email]`, `[Your phone]`) still blank; needs completion before filing. |
| ./docs/patent/main.tex | Master LaTeX patent document; inputs _v2 section files | CURRENT | This is the live build root; actual `\input` order confirmed. |
| ./docs/patent/sb0015a.pdf | USPTO form SB0015a (Provisional Application cover sheet) | CURRENT | Byte-identical to `final_provisional/sb0015a.pdf` (205016 bytes both); root copy is authoritative working copy. |
| ./docs/patent/sb0016.pdf | USPTO form SB0016 (fee transmittal or declaration) | WORKING | Differs from `final_provisional/sb0016.pdf` (557654 vs 577171 bytes); root copy is smaller — likely a prior draft; the larger `final_provisional/` copy appears to be the filed version. |
| ./docs/patent/ssm_RAJ_v1_patent_application.pdf | Compiled patent application PDF | CURRENT | Byte-identical to `final_provisional/ssm_RAJ_v1_patent_application.pdf` (1735085 bytes both); root copy is authoritative working copy. |
| ./docs/patent/ssm_provisional_patent.tex | Standalone monolithic provisional patent LaTeX document | SUPERSEDED | Self-contained single-file precursor; superseded by the modular `main.tex` + sections/ architecture. |
| ./docs/patent/sections/01_title_inventors.tex | Section file — title/inventors | OBSOLETE | Does not exist on disk; name never appears in any `\input` in main.tex. |
| ./docs/patent/sections/02_cross_reference.tex | Section file — cross-references | OBSOLETE | Does not exist on disk; the 02_* slot in main.tex is `02_field_v2`, not a cross-reference section. |
| ./docs/patent/sections/02_cross_reference_v2.tex | Section file — cross-references v2 | OBSOLETE | Does not exist on disk; main.tex uses `02_field_v2`, not a cross-reference section. |
| ./docs/patent/sections/03_background.tex | Background of the Invention — original draft | SUPERSEDED | Exists on disk; superseded by `03_background_v2.tex` which main.tex actually inputs. |
| ./docs/patent/sections/03_background_v2.tex | Background of the Invention — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/04_summary.tex | Summary of the Invention — original draft | SUPERSEDED | Exists on disk; superseded by `04_summary_v2.tex` which main.tex actually inputs. |
| ./docs/patent/sections/04_summary_v2.tex | Summary of the Invention — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/05_brief_description.tex | Brief Description of Drawings — original | OBSOLETE | Does not exist on disk; the 05_* slot in main.tex is `05_drawings`. |
| ./docs/patent/sections/05_brief_description_v2.tex | Brief Description of Drawings — v2 | OBSOLETE | Does not exist on disk; main.tex uses `05_drawings`, not this name. |
| ./docs/patent/sections/06_detailed_description.tex | Detailed Description — original draft | SUPERSEDED | Exists on disk; superseded by `06_detailed_description_v2.tex` which main.tex actually inputs. |
| ./docs/patent/sections/06_detailed_description_v2.tex | Detailed Description — revised | CURRENT | Inputted by main.tex. |
| ./docs/patent/sections/07_claims.tex | Claims section — original | OBSOLETE | Does not exist on disk; the 07_* slot in main.tex is `07_embodiments`, not claims. |
| ./docs/patent/sections/07_claims_v2.tex | Claims section — v2 | OBSOLETE | Does not exist on disk; main.tex uses `07_embodiments` and `08_claims_v2` for claims. |
| ./docs/patent/sections/08_abstract.tex | Abstract section | OBSOLETE | Does not exist on disk; main.tex uses `11_abstract_v2` for the abstract. |
| ./docs/patent/sections/RAJ_v1_01_title_inventors.tex | RAJ v1 title/inventors section | OBSOLETE | Does not exist on disk; entire RAJ_v1_* naming scheme not referenced in main.tex. |
| ./docs/patent/sections/RAJ_v1_02_cross_reference.tex | RAJ v1 cross-reference section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_03_background.tex | RAJ v1 background section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_04_summary.tex | RAJ v1 summary section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_05_brief_description.tex | RAJ v1 brief description section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/sections/RAJ_v1_06_detailed_description.tex | RAJ v1 detailed description section | OBSOLETE | Does not exist on disk. |
| ./docs/patent/final_provisional/README.md | README for the final_provisional/ subdirectory | OBSOLETE | Does not exist on disk. |
| ./docs/patent/final_provisional/sb0015a.pdf | USPTO form SB0015a — filed copy | SUPERSEDED | Byte-identical to root `sb0015a.pdf` (205016 bytes); root copy is the working canonical version. |
| ./docs/patent/final_provisional/sb0016.pdf | USPTO form SB0016 — filed copy | CURRENT | Differs from root `sb0016.pdf` (577171 vs 557654 bytes); this larger copy is the filed/submitted version and is the more complete document. |
| ./docs/patent/final_provisional/ssm_RAJ_v1_patent_application.pdf | Compiled patent application PDF — filed copy | SUPERSEDED | Byte-identical to root `ssm_RAJ_v1_patent_application.pdf` (1735085 bytes); root copy is the working canonical version. |
| docs/working/scratch/src/INTEGRATION_NOTES.adoc | StarForth↔StarshipOS sync scripts (integrator.sh) | HISTORICAL | Describes ad-hoc integrator.sh scripts and one-day debugging session; superseded by formal capsule/build pipeline in current CLAUDE.md. Worth keeping as record of integration approach. |
| docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc | L4Re integration checklist, hardcoded local paths | OBSOLETE | References absolute local dev paths (`/home/rajames/CLionProjects/...`) and a TODO checklist for copying platform files; current architecture has moved on. |
| docs/working/scratch/src-index.adoc | docs/src documentation index | WORKING | Active index/TOC for the docs/src tree, but contains multiple dead links (ABI.adoc, BLOCK_STORAGE_GUIDE.adoc, WORD_DEVELOPMENT.adoc, TESTING.adoc, BREAK_ME_REPORT.adoc, GAP_ANALYSIS.adoc) — needs pruning/repair. |
| docs/working/architecture/architecture-internals/INIT_SYSTEM.adoc | INIT system / conf/init.4th boot mechanism | CURRENT | Describes init.4th, INIT word, dictionary fence — matches current capsule/init architecture described in CLAUDE.md. |
| docs/working/architecture/architecture-internals/MESSAGING.adoc | Thermodynamic "Message Field" model for StarshipOS IPC | WORKING | Forward-looking design doc for a not-yet-implemented StarshipOS messaging subsystem; consistent with physics/thermodynamic metaphor language. |
| docs/working/scratch/src/bug_report.adoc | GitHub issue template (bug report) converted to AsciiDoc | DELETE | Generic GitHub bug-report template with smartphone/browser/OS fields irrelevant to a CLI FORTH VM; auto-converted from `.github/ISSUE_TEMPLATE`; no project-specific value. |
| docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc | Build-time flags/defines reference | CURRENT | Cross-checked flag names against Makefile; consistent catalog of build options, actively useful reference. |
| docs/working/architecture/build-and-tooling/DOCUMENTATION_README.adoc | How docs/API docs are generated (make docs, Doxygen→AsciiDoc) | CURRENT | Describes `docs/src/appendix/` generation via `scripts/generate-doxygen-appendix.sh`, directly wired into Makefile. |
| docs/working/architecture/build-and-tooling/INIT_TOOLS.adoc | tools/extract-init and init.4th↔disk image sync tooling | WORKING | Describes `tools/extract-init`; tool binary not confirmed in current `tools/` directory — may have been renamed; treat as living doc needing verification. |
| docs/working/hardware/PGO_GUIDE.adoc | Profile-Guided Optimization guide | WORKING | Content matches current Makefile `pgo`/`pgo-build`/`pgo-perf`/`pgo-valgrind` targets exactly, but the document's own title line literally reads "QUARANTiNE ME MOTHERFUCKER" — self-flagged for review before being trusted as polished. |
| docs/working/hardware/PLATFORM_BUILD_GUIDE.adoc | Cross-compilation / platform build matrix (POSIX, L4Re) | CURRENT | Matches Makefile `L4RE=1` flag and platform/time_posix.c, platform/time_l4re.c files in src/platform/. |
| docs/working/scratch/ci-cd/FMEA_BLOCKING_GATES.adoc | FMEA gating for CAPA/ECR/ECO governance workflow | CURRENT | Dated 2025-11-03, describes active GitHub Workflows + pending Jenkins governance gate; consistent with other governance docs. |
| docs/working/scratch/ci-cd/GITHUB_ISSUES_GOVERNANCE_FLOW.adoc | Relationship between GitHub Issues and governance in_basket | CURRENT | Same governance doc set, dated 2025-11-03, internally consistent. |
| docs/working/scratch/ci-cd/GOVERNANCE_INPUT_AUDIT.adoc | Audit/compliance checklist for governance input routing | CURRENT | Dated 2025-11-03, "COMPLIANT" audit result; part of active governance documentation set. |
| docs/working/scratch/ci-cd/JENKINS_GOVERNANCE_INTEGRATION.adoc | Jenkins pipeline → governance in_basket integration spec | CURRENT | Same active governance doc set, dated 2025-11-03. |
| docs/working/scratch/src/development/AGENTS.adoc | Repository guidelines / coding conventions | DELETE | Duplicate of docs/working/scratch/AGENTS.md (the live version); older AsciiDoc precursor with stale binary path (`./build/starforth`). Archived in docs/trash/duplicates-pass4.tar.gz. |
| docs/working/scratch/src/development/CONTRIBUTING.adoc | Generic contribution guide for "StarshipOS" | OBSOLETE | Boilerplate/templated contribution guide (placeholder `coc-contact@example.org`, generic Conventional Commits advice) not tailored to actual StarForth workflow or governance process; contradicts more specific and current ci-cd governance docs. |
| docs/working/architecture/doxygen/DOXYGEN_QUICK_REFERENCE.adoc | Doxygen comment cheat-sheet | CURRENT | Matches `make docs`/`make docs-html` targets and Doxygen pipeline; straightforward reference card still applicable. |
| docs/working/architecture/doxygen/DOXYGEN_STYLE_GUIDE.adoc | Doxygen documentation style guide | CURRENT | Companion to quick-reference; consistent with active Doxygen→AsciiDoc/HTML/PDF pipeline. |
| docs/working/scratch/src/feature_request.adoc | GitHub issue template (feature request) converted to AsciiDoc | DELETE | Generic GitHub feature-request template, garbled by adoc conversion; no project-specific content. |
| docs/working/architecture/getting-started/INSTALL.adoc | Installation guide (prerequisites, build/install) | WORKING | References `./build/starforth` run path rather than current `./build/amd64/<profile>/starforth` convention; otherwise generally accurate. |
| docs/working/architecture/getting-started/QUICKSTART.adoc | Quick-start build/run guide | WORKING | Same stale-path issue (`./build/starforth` instead of `./build/amd64/standard/starforth`); otherwise build command list matches current Makefile targets. |
| docs/working/scratch/governance/index.adoc | Pointer/redirect to external StarForth-Governance repo | CURRENT | Tiny stub file that redirects to the external governance repository README; still valid as a redirect. |
| docs/working/scratch/COMMUNICATION_GUIDE.adoc | "Analogy cheat sheet" for explaining physics-driven OS concept to various audiences | WORKING | Internal communications/marketing aid; not tied to specific code, ages well, still usable living document. |
| docs/working/scratch/GOVERNANCE_EXPORT_NOTES.adoc | Checklist of Phase 1 physics artifacts to mirror into governance repo | WORKING | Dated 2025-10-23; references HOLA_PROTOCOL.adoc and formal/Physics_*.thy files which still exist — consistent and current as an internal checklist. |
| docs/working/specifications/HOLA_PROTOCOL.adoc | HOLA shared-memory analytics protocol spec | CURRENT | Cross-checked against `include/physics_runtime.h`: HOLA_SHARED_MAGIC, HOLA_PROTOCOL_MAJOR/MINOR, and the analytics header struct all exist verbatim in current source — accurate technical reference. |
| docs/working/architecture/MAMA_FORTH_SUPERVISOR_ARCHITECTURE.adoc | Multi-VM supervisor architecture ("Mama Forth") | WORKING | Concept is alive in current code — `src/starkernel/capsule/mama_forth_words.c` exists and capsule birth protocol (MAMA_INIT capsule type) matches CLAUDE.md; this doc appears to be the design precursor to the now-partially-implemented capsule system. |
| docs/working/scratch/src/internal/PHASE_2A_COMPLETION_REPORT.adoc | Completion report: Freeze flag + linear decay (Phase 2a) | HISTORICAL | Accurate closed record dated 2025-11-07; feature is shipped and stable — downgraded from CURRENT as a completion record, not a living doc. |
| docs/working/scratch/src/internal/PHASE_2_IMPLEMENTATION_SUMMARY.adoc | Phase 2 action-item summary pointing to design + completion docs | HISTORICAL | Companion index to PHASE_2A_COMPLETION_REPORT; both docs describe a completed, closed phase — downgraded from CURRENT. |
| docs/working/scratch/src/internal/PHASE_2_PHYSICS_DECAY_AND_FREEZE.adoc | Design spec for decay/freeze mechanisms | HISTORICAL | Marked "Design Phase" as of 2025-11-07, but the corresponding PHASE_2A_COMPLETION_REPORT.adoc shows this has since been implemented and validated — spec is now historical record of the design rationale behind the now-shipped feature. |
| docs/working/architecture/PHYSICS_CONE_OF_INFLUENCE_DESIGN.adoc | Feedback-control architecture design ("cone of influence") | WORKING | Forward-looking architectural design note for scheduling/control; consistent with physics engine terminology still in active use. |
| docs/working/architecture/PHYSICS_CONTROL_SYSTEM_DESIGN.adoc | Physics observables → scheduling/memory management integration design | WORKING | Design-stage architecture note, not yet fully realized; scheduling/memory integration is still aspirational per current CLAUDE.md roadmap. |
| docs/working/scratch/src/internal/PHYSICS_HOTWORDS_CACHE_INTEGRATION.adoc | Hot-words cache integration implementation checklist | SUPERSEDED | Describes a step-by-step plan to add hot-words caching; this feature is now implemented and documented as "Loop #1 — Execution Heat" / `ENABLE_HOTWORDS_CACHE=1` / `dictionary_heat_optimization.c` in current CLAUDE.md. |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_OPTIONS.adoc | Three implementation-path options for physics engine | HISTORICAL | "Phase 1 complete" framing with options for next steps; physics engine has since progressed well past this decision point (7 loops, L8 Jacquard). |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_STATUS.adoc | POSIX vs L4Re porting strategy status for physics hooks | HISTORICAL | Describes early wiring state of `physics_metadata_touch()` calls; physics engine has since matured substantially — status snapshot now outdated. |
| docs/working/scratch/src/internal/PHYSICS_SCHEDULING_PLAN.adoc | Planning note for physics-inspired scheduling metadata | HISTORICAL | Describes `DictPhysics` struct fields as stub/unpopulated placeholders; current `DictPhysics` is now populated and actively used — doc predates that implementation. |
| docs/working/architecture/PHYSICS_SIGNAL_MAP.adoc | Telemetry signal inventory (L4Re KIP signals + VM-internal counters) | WORKING | Useful living reference of available L4Re kernel telemetry signals for future physics/scheduler work; L4Re remains a supported platform. |
| docs/working/scratch/src/internal/SHARED_CLAUDE.adoc | Cross-project Claude-instance shared notepad (StarForth↔StarshipOS) | DELETE | Dated 2025-10-19 ad-hoc session notes/chat log between AI instances about integrator script status; pure transient working notes with no lasting reference value. |
| docs/working/architecture/VM_FORMALIZATION_PLAN.adoc | Isabelle/HOL formalization roadmap for `docs/src/internal/formal/` theories | CURRENT | Directly describes the `docs/src/internal/formal/*.thy` files which exist on disk and are wired into the Makefile's Isabelle build targets. |
| docs/working/hardware/performance-profiling/ARM64_OPTIMIZATIONS.adoc | ARM64 assembly optimization summary | CURRENT | Referenced headers (`include/vm_asm_opt_arm64.h`, `vm_inner_interp_arm64.h`, `arch_detect.h`) all confirmed present in current `include/` tree. |
| docs/working/hardware/performance-profiling/ASM_OPTIMIZATIONS.adoc | x86_64 assembly optimization guide | CURRENT | Referenced headers (`vm_asm_opt.h`, `vm_inner_interp_asm.h`) confirmed present; consistent with `USE_ASM_OPT=1` build flag in current CLAUDE.md. |
| docs/working/hardware/performance-profiling/PROFILER.adoc | Built-in word-execution profiler guide | CURRENT | Describes profiler integrated with PGO pipeline; consistent with `make test PROFILE=1` and `profiler.c` present in current src tree. |
| docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc | Dictionary allocation strategy proposal for L4Re | WORKING | References `src/dictionary_management.c:228` (`vm_create_word()` malloc) and `defining_words.c:554` (`FORGET` free) — both locations exist; malloc/free dependency has likely not yet been replaced with L4Re-native allocator. |
| docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc | General L4Re integration guide (IPC, dataspaces, package structure) | WORKING | Broad integration guide; L4Re remains a supported platform per CLAUDE.md tech stack diagram. |
| docs/working/hardware/platform-integration/PLATFORM_ABSTRACTION.adoc | Platform abstraction layer (vtable pattern for POSIX/L4Re) | CURRENT | Matches actual `platform/linux/time.c` and `platform/l4re/time.c` files present in current src tree per CLAUDE.md source tree listing. |
| docs/working/hardware/platform-integration/RASPBERRY_PI_BUILD.adoc | Raspberry Pi 4 / ARM64 build guide | CURRENT | Matches `rpi4-cross` Makefile target and ARM64 architecture support (`ARCH=raspi`) listed in current CLAUDE.md build targets. |
| docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc | Block I/O L4Re porting endpoints (blkio vtable mapping) | CURRENT | Describes `blkio_open/close/read` vtable API; matches `blkio_*.c` backend files listed in current CLAUDE.md source tree. |
| docs/working/scratch/testing-quality/KANBAN-WORKFLOW-VALIDATION.adoc | Validation procedure for GitHub Projects Kanban automation (CAPA-032) | CURRENT | Dated 2025-11-02 with explicit source commit hash; references `.github/workflows/capa-kanban-sync.yml` which is a concrete CI artifact. |
| docs/working/archive/legacy/OPTIMIZATION_OPPORTUNITIES.md | Physics engine optimization opportunity ranking dated 2025-11-19 | SUPERSEDED | Superseded by docs/03-architecture/physics-engine/ and Loop #5/#6 implementations |
| docs/working/archive/legacy/README.md | Index and usage guide for the docs/archive directory | CURRENT | Self-referential; accurately describes the archive's purpose and sub-structure |
| docs/working/archive/legacy/START_HERE_HEARTBEAT_DOE.md | Phase 2 heartbeat DoE launch guide (250 runs, 5 elite configs) | SUPERSEDED | README notes this is superseded by docs/02-experiments/heartbeat-doe/ |
| docs/working/archive/legacy/phase-1/Reference/BACKLOG_INJECTION_ANALYSIS.md | Governance model analysis of GitHub issue injection points | HISTORICAL | Nov 2025 snapshot of CI/process governance state |
| docs/working/archive/legacy/phase-1/Reference/EXPERIMENT_QUICK_REFERENCE.txt | Quick-reference ops card for the 90-run A/B/C physics validation experiment | HISTORICAL | Raw ops card tied to a specific pre-publication experiment run |
| docs/working/archive/legacy/phase-1/Reference/IMPLEMENTATION_SUMMARY.md | Phase 1 CI/Kanban automation implementation summary | HISTORICAL | Records CI automation decisions made during project Phase 1 |
| docs/working/archive/legacy/phase-1/Reference/JENKINS_USER_GUIDE.md | Jenkins CI user guide | HISTORICAL | Jenkins may no longer be the active CI system; check .github/workflows/ |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-TESTING-GUIDE.md | Guide for testing GitHub Projects Kanban automation | HISTORICAL | Companion to CAPA-032 Kanban work; superseded by live workflow |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-WORKFLOW-TEST.md | Kanban workflow test procedures | HISTORICAL | Point-in-time test doc for Kanban automation validation |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_FINAL_STATUS.md | Final status report for project Phase 1 | HISTORICAL | Closed-loop status report; accurately captures Phase 1 completion state |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_IMPLEMENTATION_COMPLETE.md | Phase 1 implementation completion announcement | HISTORICAL | Records the Phase 1 done-condition at time of writing |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_TESTING_RESULTS.md | Phase 1 testing results summary | HISTORICAL | Test results from Phase 1 CI/governance work |
| docs/working/archive/legacy/phase-1/Reference/PHYSICS_EXPERIMENT_README.md | README for the 90-run physics validation experiment | HISTORICAL | Companion README to the experiment data in physics_experiment/ |
| docs/working/archive/legacy/phase-1/Reference/RULE_1_GATES_IMPLEMENTATION.md | Implementation notes for Rule 1 CI gating | HISTORICAL | CI gate design decisions from Phase 1 |
| docs/working/archive/legacy/phase-1/Reference/SECURITY.md | Security notes predating the ACL system | HISTORICAL | Pre-ACL security model; superseded by docs/03-architecture/word-acl/DESIGN.md |
| docs/working/archive/legacy/phase-1/Reference/SESSION_SUMMARY.md | Transient AI session summary | HISTORICAL | Session-level notes; limited long-term value |
| docs/working/archive/legacy/phase-1/Reference/TEST-CAPA-TEMPLATE.md | CAPA test case template | HISTORICAL | Template used during Phase 1 CAPA process |
| docs/working/archive/legacy/phase-1/Reference/codex_audit_report.md | Codex audit report of the codebase | HISTORICAL | Point-in-time static analysis or review; may be stale |
| docs/working/archive/legacy/phase-1/Reference/codex_capa_list.md | CAPA action items derived from Codex audit | HISTORICAL | Action items from Phase 1 audit cycle |
| docs/working/archive/legacy/phase-1/Reference/github_backlog_items.md | GitHub backlog items list | HISTORICAL | Snapshot of backlog at Phase 1; likely stale |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/DEVIATION_REPORT_CSV_FORMATTING.md | CSV formatting deviation report for experiment output | HISTORICAL | Experiment data-hygiene note for the 90-run run |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/FORMAL_CLAIMS_FOR_REVIEWERS.txt | Formal claims document prepared for peer reviewers | HISTORICAL | Pre-publication version; superseded by published SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/01_MAIN_PAPER/PAPER_KEY_CONTRIBUTIONS_SUMMARY.md | Key contributions summary for peer review submission | HISTORICAL | Pre-SSRN draft; superseded by papers/James_Steady-State_Convergence_Adaptive_Runtime.pdf |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/01_MAIN_PAPER/PEER_REVIEW_PAPER_DRAFT.md | Full paper draft submitted for peer review | HISTORICAL | Pre-SSRN draft; superseded by published SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_CLAIMS_FOR_REVIEWERS.txt | Formal claims for reviewers (supporting docs copy) | HISTORICAL | Duplicate of physics_experiment/FORMAL_CLAIMS_FOR_REVIEWERS.txt |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/FORMAL_VERIFICATION_INTERPRETATION.md | Interpretation guide for Isabelle/HOL proofs for reviewers | HISTORICAL | Pre-publication; proof/ directory is the live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/PEER_REVIEW_SUBMISSION_PACKAGE.md | Cover doc for the full peer review submission package | HISTORICAL | Submission metadata; superseded by SSRN publication |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/QUICK_REFERENCE.txt | Quick reference for reviewers | HISTORICAL | Reviewer-facing summary; superseded by published abstract |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/02_SUPPORTING_DOCS/VARIANCE_ANALYSIS_SUMMARY.md | Variance analysis summary for the 90-run experiment | HISTORICAL | Source data for SSRN paper; keep as experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/experiment_summary.txt | Comprehensive 90-run experiment summary | HISTORICAL | Primary experimental record; source data for SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/03_EXPERIMENTAL_DATA/full_90_run_comprehensive/run_logs/test_matrix.txt | Test matrix for full 90-run experiment | HISTORICAL | Experimental record; run configuration matrix |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/05_SUPPLEMENTARY/PEER_REVIEW_PAPER_OUTLINE.md | Outline used to structure the peer review paper | HISTORICAL | Pre-publication outline; superseded by final SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/05_SUPPLEMENTARY/WORK_COMPLETION_STATUS.md | Work completion checklist for peer review submission | HISTORICAL | Point-in-time submission checklist |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/00-abstract.adoc | AsciiDoc abstract section for peer review paper | HISTORICAL | Pre-publication AsciiDoc draft; superseded by SSRN PDF |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/01-introduction.adoc | AsciiDoc introduction section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/01-summary.adoc | AsciiDoc summary section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/02-formal-theorems.adoc | AsciiDoc formal theorems section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/02-related-work.adoc | AsciiDoc related-work section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/03-experimental-methodology.adoc | AsciiDoc experimental methodology section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/03-methodology.adoc | AsciiDoc methodology section (alternate) | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/04-results.adoc | AsciiDoc results section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/04-variance-analysis.adoc | AsciiDoc variance analysis section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/05-convergence-proof.adoc | AsciiDoc convergence proof section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/05-discussion.adoc | AsciiDoc discussion section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/06-stability-proof.adoc | AsciiDoc stability proof section | HISTORICAL | Pre-publication; proof/ directory is live source |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/07-predictability-bounds.adoc | AsciiDoc predictability bounds section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/08-peer-review-defense.adoc | AsciiDoc peer-review defense section | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/index.adoc | AsciiDoc index/master file for the peer review paper | HISTORICAL | Pre-publication AsciiDoc draft |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/06_ASCIIDOC/paper.adoc | AsciiDoc combined paper source | HISTORICAL | Pre-publication; superseded by SSRN PDF |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/PEER_REVIEW_SUBMISSION/README.md | README for the peer review submission package | HISTORICAL | Submission index; superseded by SSRN publication |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/QUICK_REFERENCE.txt | Quick reference for the 90-run experiment | HISTORICAL | Ops-level quick card; raw experiment record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/experiment_summary.txt | Top-level experiment summary | HISTORICAL | Primary experimental record; source data for SSRN paper |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/full_90_run_comprehensive/experiment_summary.txt | Full 90-run comprehensive experiment summary | HISTORICAL | Experimental record (duplicate path from submission tree) |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/full_90_run_comprehensive/run_logs/test_matrix.txt | Test matrix for full 90-run experiment | HISTORICAL | Run configuration matrix |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/run_logs/test_matrix.txt | Run logs test matrix (top-level) | HISTORICAL | Raw run log; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run/experiment_summary.txt | Test run experiment summary | HISTORICAL | Pre-full-run trial; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run/run_logs/test_matrix.txt | Test run matrix | HISTORICAL | Raw test matrix for trial run |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run2/experiment_summary.txt | Second test run experiment summary | HISTORICAL | Pre-full-run trial #2; experimental record |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/test_run2/run_logs/test_matrix.txt | Second test run matrix | HISTORICAL | Raw test matrix for trial run #2 |
| docs/working/archive/legacy/phase-1/Reference/toolchain/gcc.txt | GCC toolchain version/configuration notes | HISTORICAL | Point-in-time toolchain pinning record |
| docs/working/archive/legacy/phase-1/Reference/toolchain/make.txt | Make version/configuration notes | HISTORICAL | Point-in-time toolchain pinning record |
| Path | Title | Status | Notes |
|---|---|---|---|
| boards/BRINGUP.md | Board bring-up checklist | WORKING | Bare-metal bring-up checklist and blockers. |
| boards/README.md | boards/ | CURRENT | |
| boards/milkv/README.md | Milk-V Mars boot media | CURRENT | |
| boards/pc/README.md | PC boot media (generic x86-64, UEFI) | CURRENT | |
| boards/raspi/README.md | Raspberry Pi 5 native boot media | CURRENT | |
| boards/raspi/config.txt | LithosAnanke native (non-UEFI) boot config for Raspberry Pi 5 (BCM2712). | CURRENT | |
| boards/zynq7020/README.md | Xilinx Zynq-7020 boot media | CURRENT | |
## capsules
| Path | Title | Status | Notes |
|---|---|---|---|
| capsules/BLOCK_MAP.md | Capsule Block Manifest — Auto-generated | CURRENT | |
| capsules/MANIFEST.md | capsules/MANIFEST.md — Block Ownership Registry (justifications) | CURRENT | |
| capsules/MANIFEST_AUTO.md | Capsule Block Manifest — Auto-generated | CURRENT | |
| capsules/README.md | capsules/ | CURRENT | |
| capsules/contrib/README.md | capsules/contrib/ | CURRENT | |
| capsules/fonts/README.md | capsules/fonts/ | CURRENT | |
## configs
| Path | Title | Status | Notes |
|---|---|---|---|
| configs/README.md | configs/ | CURRENT | |
## disk
| Path | Title | Status | Notes |
|---|---|---|---|
| disk/README.md | disk/ | CURRENT | |
## docs
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/CLAUDE.md | CLAUDE.md — StarshipOS Documentation Root | CURRENT | Rules for documentation work. |
| docs/DEAD-AND-REVISED.md | Dead ideas and revised claims | CURRENT | Register of abandoned ideas and revised claims. |
| docs/DELETE-CANDIDATES.md | docs/DELETE-CANDIDATES.md | CURRENT | Record of the duplicates deleted 2026-10-14. |
| docs/INDEX.md | docs/INDEX.md — every document, and its status | CURRENT | This index. |
| docs/README.md | StarForth / LithosAnanke documentation — the map | CURRENT | The map: start here. |
| docs/SSM_DARPA_Summary_Slide.pptx | SSM_DARPA_Summary_Slide.pptx | CURRENT | |
## docs/book
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/book/README.md | docs/book/ | CURRENT | |
| docs/book/main.tex | LithosAnanke and StarForth | CURRENT | |
## docs/fabric
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/fabric/FABRIC-0.md | FABRIC-0.md — the Stadium | HISTORICAL | Closed design record (the Stadium). |
| docs/fabric/FABRIC-1.md | FABRIC-1.md — the Stadium, continued | HISTORICAL | Closed design record. |
| docs/fabric/FABRIC-2.md | FABRIC-2.md — the Stadium, continued again | HISTORICAL | Closed design record. |
| docs/fabric/FABRIC-3.5.md | FABRIC-3.5.md — the Tripod/kernel reshuffle | HISTORICAL | Closed at v2.1.0: the Tripod/kernel reshuffle, design. Authoritative for what it ruled. |
| docs/fabric/FABRIC-3.6.md | FABRIC-3.6.md — the Tripod/kernel reshuffle: execution log | HISTORICAL | Closed at v2.1.0: the reshuffle, execution. |
| docs/fabric/FABRIC-3.7.md | FABRIC-3.7.md — Phase 8 PKI: the elevation entrypoint | DEAD | Closed 2026-10-14: elevation ruled not needed and removed (FABRIC-3 XXXVII). |
| docs/fabric/FABRIC-3.md | FABRIC-3.md — bare metal boot | WORKING | The living record: bare metal boot and everything since. Authoritative. |
| docs/fabric/FABRIC-4.md | FABRIC-4.md — forward-looking design notes | WORKING | Ideas caught early, not yet scoped. |
## docs/formal
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/formal/CLAUDE.md | docs/formal/CLAUDE.md — Authoring Conventions for the Formal Documentation Tier | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/README.md | docs/formal/ | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/common/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/cookbook/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/dev-guide/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/experiments/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/patent/ | 1 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/proofs/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/ | 1 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/architecture/ | 49 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/archive/ | 81 files | SUPERSEDED | Flagged obsolete in its own header. |
| docs/formal/scraps/experiments/ | 31 files | HISTORICAL | Flagged in its own header. |
| docs/formal/scraps/hardware/ | 10 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/legal/ | 1 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/papers/ | 13 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/scraps/scratch/ | 23 files | HISTORICAL | Flagged in its own header. |
| docs/formal/scraps/specifications/ | 1 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/ssrn/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/user-guide/ | 2 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/vol1-vm-physics/ | 9 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/vol2-kernel/ | 8 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
| docs/formal/vol3-research/ | 11 files | FORMAL | Press tier; see docs/formal/CLAUDE.md. |
## docs/patent
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/patent/CHANGES_SUMMARY.md | Patent Application Review and Changes | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/JARGON_CHANGES.md | Jargon Removal and Precision Language Changes | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/README_V3.md | StarForth Patent Application Version 3.0 | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/USPTO_COVER_LETTER.md | USPTO PROVISIONAL PATENT APPLICATION | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/bibliography/bibliography.tex | bibliography.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig1_snake_trajectory.pdf | fig1_snake_trajectory.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig2_K_vs_window.pdf | fig2_K_vs_window.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig3_FFT_spectrum.pdf | fig3_FFT_spectrum.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig4_golden_ratio_penalties.pdf | fig4_golden_ratio_penalties.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig5_bimodal_distributions.pdf | fig5_bimodal_distributions.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig6_performance_vs_k.pdf | fig6_performance_vs_k.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/figures/fig7_performance_by_regime.pdf | fig7_performance_by_regime.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/final_provisional/cover_letter.txt | cover_letter.txt | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/final_provisional/sb0015a.pdf | sb0015a.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/final_provisional/sb0016.pdf | sb0016.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/final_provisional/ssm_RAJ_v1_patent_application.pdf | ssm_RAJ_v1_patent_application.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/macros/commands.tex | commands.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/main.pdf | main.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/main.tex | main.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sb0015a.pdf | sb0015a.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sb0016.pdf | sb0016.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/00_claims_validation_v3.tex | 00_claims_validation_v3.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/00_complete_patent_v3.tex | 00_complete_patent_v3.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/01_title.tex | 01_title.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/01_title_v2.tex | 01_title_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/02_field.tex | 02_field.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/02_field_v2.tex | 02_field_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/03_background.tex | 03_background.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/03_background_v2.tex | 03_background_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/04_summary.tex | 04_summary.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/04_summary_v2.tex | 04_summary_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/05_drawings.tex | 05_drawings.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/06_detailed_description.tex | 06_detailed_description.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/06_detailed_description_v2.tex | 06_detailed_description_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/07_embodiments.tex | 07_embodiments.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/08_claims.tex | 08_claims.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/08_claims_REAL.tex | 08_claims_REAL.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/08_claims_v2.tex | 08_claims_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/09_validation.tex | 09_validation.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/09_validation_v2.tex | 09_validation_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/10_implementation.tex | 10_implementation.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/11_abstract.tex | 11_abstract.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/11_abstract_REAL.tex | 11_abstract_REAL.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/11_abstract_v2.tex | 11_abstract_v2.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/11_appendix.tex | 11_appendix.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/12_appendix.tex | 12_appendix.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_01_background.tex | RAJ_v1_01_background.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_02_summary.tex | RAJ_v1_02_summary.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_03_drawings.tex | RAJ_v1_03_drawings.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_04_detailed_description.tex | RAJ_v1_04_detailed_description.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_05_claims.tex | RAJ_v1_05_claims.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/RAJ_v1_06_abstract.tex | RAJ_v1_06_abstract.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/sections/architecture_diagram_clean.tex | architecture_diagram_clean.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/ssm_RAJ_v1_patent_application.pdf | ssm_RAJ_v1_patent_application.pdf | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/ssm_RAJ_v1_patent_application.tex | ssm_RAJ_v1_patent_application.tex | LEGAL HOLD | Not touched without Captain Bob. |
| docs/patent/ssm_provisional_patent.tex | ssm_provisional_patent.tex | LEGAL HOLD | Not touched without Captain Bob. |
## docs/pptx
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/pptx/01-technical-elevator-pitch.pptx | 01-technical-elevator-pitch.pptx | CURRENT | |
| docs/pptx/02-nontechnical-elevator-pitch.pptx | 02-nontechnical-elevator-pitch.pptx | CURRENT | |
| docs/pptx/03-academic-overview.pptx | 03-academic-overview.pptx | CURRENT | |
| docs/pptx/04-phd-deep-dive.pptx | 04-phd-deep-dive.pptx | CURRENT | |
| docs/pptx/README.md | docs/pptx/ | CURRENT | |
## docs/reference
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/reference/DICTIONARY.md | LithosAnanke / StarForth — Word Dictionary Reference | CURRENT | |
| docs/reference/L8_ADAPTIVE_CONFIG_TABLE.md | L8 Jacquard: Adaptive 128-Config Heat-Ranked Selector | CURRENT | |
| docs/reference/M7.1.md | M7.1: Init Capsule Architecture | CURRENT | |
| docs/reference/ONTOLOGY.md | StarForth Ontology, Taxonomy, and Lexicon | CURRENT | |
| docs/reference/ROADMAP.md | LithosAnanke Roadmap | CURRENT | Roadmap and the ratified release-versioning policy. |
| docs/reference/STARFORTH_PRIMITIVES.md | StarForth Primitive Word Reference | CURRENT | |
| docs/reference/hosted-acceptance-test/README.md | Hosted StarForth — 3-Architecture Acceptance Test | CURRENT | |
| docs/reference/kernel-args/DESIGN.md | Kernel Command-Line Arguments (KernelArgs) | CURRENT | |
| docs/reference/kernel-args/README.md | docs/reference/kernel-args/ | CURRENT | |
| docs/reference/word-acl/DESIGN.md | Word-Level ACL System | CURRENT | |
| docs/reference/word-acl/README.md | docs/reference/word-acl/ | CURRENT | |
## docs/v4.0.0
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/v4.0.0/DECOMPOSITION.md | StarForth v4.0.0 — Primitive Decomposition | CURRENT | |
| docs/v4.0.0/ENGINE.md | StarForth v4.0.0 — The F18 engine in the VM's place | CURRENT | |
| docs/v4.0.0/JUSTIFICATION.md | StarForth v4.0.0 — Justification | CURRENT | |
| docs/v4.0.0/MESH.md | StarForth v4.0.0 — Talking nodes | CURRENT | |
| docs/v4.0.0/NUCLEUS.md | StarForth v4.0.0 — Nucleus, FORTH-79 Capsule and POST | CURRENT | |
| docs/v4.0.0/POST79.md | POST for the FORTH-79 Required Word Set: where it departs from v3 | CURRENT | |
| docs/v4.0.0/V3-PARITY.md | StarForth v4.0.0 — Parity with v3 up to the first prompt | CURRENT | |
| docs/v4.0.0/plans/2026-10-06-step6-storage.md | Step 6: Storage Implementation Plan (revised 2026-10-07) | HISTORICAL | An executed step plan. |
| docs/v4.0.0/plans/2026-10-07-step6b-post.md | Step 6b: POST Is the Kernel's — Implementation Plan | HISTORICAL | An executed step plan. |
| docs/v4.0.0/plans/2026-10-07-step6c-refusals-and-waits.md | Step 6c: Refusals and Waits — Implementation Plan | HISTORICAL | An executed step plan. |
| docs/v4.0.0/plans/2026-10-07-step6d-the-wait.md | Step 6d: The Wait — Implementation Plan | HISTORICAL | An executed step plan. |
| docs/v4.0.0/plans/2026-10-08-step6e-messages-on-the-wire.md | Step 6e: Messages on the Wire — Implementation Plan | HISTORICAL | An executed step plan. |
## docs/working
| Path | Title | Status | Notes |
|---|---|---|---|
| docs/working/README.md | docs/working/ — Living Documentation | WORKING | |
| docs/working/architecture/03-architecture/OVERVIEW.md | StarForth Architecture Overview | WORKING | |
| docs/working/architecture/03-architecture/README.md | Architecture | WORKING | |
| docs/working/architecture/03-architecture/adaptive-systems/adaptive-window-and-decay.md | Adaptive Window Shrinking & Decay Slope Investigation | WORKING | |
| docs/working/architecture/03-architecture/adaptive-systems/multivariate-dynamics.md | StarForth Multivariate Coupled Dynamics Experiment | WORKING | |
| docs/working/architecture/03-architecture/adaptive-systems/window-inference-redesign.md | Window Width Inference Redesign - Statistically Valid Approach | WORKING | |
| docs/working/architecture/03-architecture/heartbeat-system/architecture.md | VM Heartbeat Architecture: Centralized Time-Based Tuning | WORKING | |
| docs/working/architecture/03-architecture/heartbeat-system/critical-insight.md | CRITICAL INSIGHT: Heartbeat Rate is Variable, Not Fixed | WORKING | |
| docs/working/architecture/03-architecture/heartbeat-system/instrumentation-plan.md | Heartbeat Per-Tick Instrumentation Plan | WORKING | |
| docs/working/architecture/03-architecture/heartbeat-system/segfault-analysis.md | Heartbeat Segfault Root Cause Analysis & Repair | WORKING | |
| docs/working/architecture/03-architecture/physics-engine/feedback-loops.md | StarForth Physics Feedback Loops | WORKING | The seven feedback loops. |
| docs/working/architecture/03-architecture/physics-engine/monitoring-principles.md | StarForth Physics Runtime | WORKING | |
| docs/working/architecture/03-architecture/physics-engine/ssm-equations.md | Mathematical Analysis of the Steady-State Machine | WORKING | |
| docs/working/architecture/03-architecture/physics-engine/ssm-raw-data-analysis.md | Steady-State Machine (SSM): Raw Experimental Data Analysis | WORKING | |
| docs/working/architecture/03-architecture/pipelining/context-window-and-binary-chop.md | Phase 1 Extension: Context Window & Phase 2 Binary Chop Tuning | WORKING | |
| docs/working/architecture/03-architecture/pipelining/design.md | FORTH VM Pipelining & Speculative Execution Design | WORKING | |
| docs/working/architecture/03-architecture/pipelining/phase-1-instrumentation.md | Phase 1: Pipelining Instrumentation | WORKING | |
| docs/working/architecture/03-architecture/pipelining/wired-not-utilized.md | Pipelining Feedback Loop: WIRED BUT NOT UTILIZED (Critical Issue) | WORKING | |
| docs/working/architecture/ARTEMIS-BAM-ACCEPTANCE-20260703.md | Artemis BAM — Phase 1 Acceptance Report | WORKING | |
| docs/working/architecture/ARTEMIS-BLOCK-PHYSICS-DESIGN-20260708.md | Artemis Block Heat Physics — Design Doc | WORKING | |
| docs/working/architecture/ARTEMIS-FREEMAP-CAPSULE-RESERVATION-GAP-20260710.md | Artemis Free-Map Doesn't Reserve Capsule-Claimed Blocks | WORKING | |
| docs/working/architecture/CAPSULE-BLOCK-PERSISTENCE-BOUNDARY-FINDING-20260709.md | Capsule Loader — Missing Persistence Boundary Check | WORKING | |
| docs/working/architecture/CAPSULE-LOADER-DEFINITIONS-ONLY-DESIGN-20260709.md | Capsules Load Definitions Only — Design Doc | WORKING | |
| docs/working/architecture/DOE-LIBRARY-HOWTO-20260819.md | DoE Library HOWTO — `capsules/doe.4th` | CURRENT | HOWTO for capsules/doe.4th. |
| docs/working/architecture/K-PUSH-DICTIONARY-SHADOWING-BUG-20260704.md | K-PUSH Dictionary Shadowing Bug — Full Report | WORKING | |
| docs/working/architecture/MAMA_FORTH_SUPERVISOR_ARCHITECTURE.adoc | Mama Forth: Multi-VM Supervisor Architecture | WORKING | |
| docs/working/architecture/PHYSICS_CONE_OF_INFLUENCE_DESIGN.adoc | Physics Engine: Cone of Influence Design | WORKING | |
| docs/working/architecture/PHYSICS_CONTROL_SYSTEM_DESIGN.adoc | Physics Control System: Observables → Scheduling & Memory Management | WORKING | |
| docs/working/architecture/PHYSICS_SIGNAL_MAP.adoc | Physics Signal Inventory | WORKING | |
| docs/working/architecture/README.md | docs/working/architecture/ | WORKING | |
| docs/working/architecture/SDK-HOWTO-20260819.md | SDK HOWTO — `capsules/sdk.4th` | WORKING | |
| docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md | Turtle Graphics HOWTO — `capsules/turtle.4th` | WORKING | |
| docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md | VM Fleet Attractor Experiment — Design Doc | WORKING | Fleet physics; pre-reshuffle (names the Hermes VM) but still the source for the attractor design. |
| docs/working/architecture/VM-PHYSICS-DYNAMIC-FLEET-DESIGN-20260705.md | Dynamic VM Fleet Physics — Design Doc | WORKING | |
| docs/working/architecture/VM_FORMALIZATION_PLAN.adoc | VM Formalization Roadmap | WORKING | |
| docs/working/architecture/architecture-internals/INIT_SYSTEM.adoc | L4RE_TARGET | WORKING | |
| docs/working/architecture/architecture-internals/MESSAGING.adoc | SFM_THERMO_H | WORKING | |
| docs/working/architecture/build-and-tooling/BUILD_OPTIONS.adoc | defined(__x86_64__) // defined(_M_X64) // defined(__amd64__) | WORKING | |
| docs/working/architecture/build-and-tooling/DOCUMENTATION_README.adoc | Generate the AsciiDoc API documentation | WORKING | |
| docs/working/architecture/build-and-tooling/INIT_TOOLS.adoc | 1. Work in disk (using StarForth REPL) | WORKING | |
| docs/working/architecture/doxygen/DOXYGEN_QUICK_REFERENCE.adoc | MACRO_NAME value | WORKING | |
| docs/working/architecture/doxygen/DOXYGEN_STYLE_GUIDE.adoc | STACK_SIZE 1024 | WORKING | |
| docs/working/architecture/getting-started/DEVELOPER.md | StarForth Developer Guide | WORKING | |
| docs/working/architecture/getting-started/INSTALL.adoc | Build package | WORKING | |
| docs/working/architecture/getting-started/QUICKSTART.adoc | Build the fastest version for your platform | WORKING | |
| docs/working/architecture/getting-started/README.md | Getting Started with StarForth | WORKING | |
| docs/working/architecture/getting-started/quick-start/heartbeat-doe.md | StarForth Heartbeat DoE – Quick Start | WORKING | |
| docs/working/architecture/getting-started/quick-start/optimization-doe.md | Quick Start: Optimization DoE | WORKING | |
| docs/working/architecture/heartbeat_csv_export.md | Heartbeat CSV Export - Real-Time VM Metrics | WORKING | |
| docs/working/archive/COMPUTATIONAL_PHYSICS_FRAMEWORK.md | The Physics of Adaptive Computation | HISTORICAL | |
| docs/working/archive/DOCUMENTATION_AUDIT.md | StarForth Documentation Audit | HISTORICAL | |
| docs/working/archive/GAP_ANALYSIS.md | Gap Analysis: Missing Evolutionary Links | HISTORICAL | |
| docs/working/archive/README.md | docs/working/archive/ | HISTORICAL | |
| docs/working/archive/artifacts/kanban-workflow/MANIFEST.adoc | Kanban Workflow Artifacts Manifest | HISTORICAL | |
| docs/working/archive/dead/hal-target-contract/README.md | Hardware Abstraction Layer (HAL) Documentation | DEAD | See the file's own header. |
| docs/working/archive/dead/hal-target-contract/interfaces.md | HAL Interface Specifications | DEAD | See the file's own header. |
| docs/working/archive/dead/hal-target-contract/migration-plan.md | HAL Migration Plan | DEAD | See the file's own header. |
| docs/working/archive/dead/hal-target-contract/overview.md | Hardware Abstraction Layer (HAL) Architecture | DEAD | See the file's own header. |
| docs/working/archive/dead/hal-target-contract/platform-implementations.md | HAL Platform Implementation Guide | DEAD | See the file's own header. |
| docs/working/archive/dead/hal-target-contract/starkernel-integration.md | StarKernel HAL Integration Guide | DEAD | See the file's own header. |
| docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc | STARFORTH_VM_DICT_ALLOC | DEAD | See the file's own header. |
| docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc | Subdirectories to build | DEAD | See the file's own header. |
| docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc | Note: Do NOT copy time_posix.c - not needed in L4Re build | DEAD | See the file's own header. |
| docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc | l_4_re_blkio_endpoints.adoc | DEAD | See the file's own header. |
| docs/working/archive/dead/metrics-and-knobs.md | StarForth Metrics & Knobs: GAPS ONLY | DEAD | See the file's own header. |
| docs/working/archive/historical/2026-01-27-system-architecture-draft.md | LithosAnanke System Architecture | HISTORICAL | |
| docs/working/archive/historical/2026-06-03-test-gap-audit.md | StarForth Dictionary Test Coverage — Gap Audit | HISTORICAL | |
| docs/working/archive/historical/2026-06-10-next-session-plan.md | Next Session Plan | HISTORICAL | |
| docs/working/archive/historical/2026-06-30-break-me-report.md | 🔥 STARFORTH BREAK-ME DIAGNOSTIC REPORT 🔥 | HISTORICAL | |
| docs/working/archive/historical/2026-07-amd64-isr-fix/README.md | APIC Timer ISR Fix — amd64 | HISTORICAL | |
| docs/working/archive/historical/2026-07-birthing/PLAN.md | Birthing Plan: Child VMs Born of Hera | HISTORICAL | |
| docs/working/archive/historical/2026-07-birthing/README.md | docs/working/archive/historical/2026-07-birthing/ | HISTORICAL | |
| docs/working/archive/historical/2026-07-birthing/STATUS.md | Birthing — Work Status and Context | HISTORICAL | |
| docs/working/archive/historical/2026-07-birthing/acceptance-logs/README.md | docs/working/archive/historical/2026-07-birthing/acceptance-logs/ | HISTORICAL | |
| docs/working/archive/historical/2026-07-birthing/acceptance-logs/SUMMARY.md | Birthing — Kernel QEMU Acceptance Test Summary | HISTORICAL | |
| docs/working/archive/historical/2026-08-riscv64-stack-fix/README.md | Kernel Stack Trampoline Fix — riscv64 | HISTORICAL | |
| docs/working/archive/historical/2026-10-lithosananke-orientation.md | LithosAnanke — StarForth Kernel Branch | HISTORICAL | |
| docs/working/archive/legacy/OPTIMIZATION_OPPORTUNITIES.md | StarForth Optimization Opportunities | HISTORICAL | |
| docs/working/archive/legacy/README.md | Archived Documentation | HISTORICAL | |
| docs/working/archive/legacy/START_HERE_HEARTBEAT_DOE.md | START HERE – Heartbeat DoE Phase 2 | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/BACKLOG_INJECTION_ANALYSIS.md | Backlog Injection Points Analysis | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/EXPERIMENT_QUICK_REFERENCE.txt | Watch CSV grow in real-time | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/IMPLEMENTATION_SUMMARY.md | Physics Engine Comprehensive Validation - Complete Implementation Summary | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/JENKINS_USER_GUIDE.md | Jenkins User Guide | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-TESTING-GUIDE.md | Kanban Workflow Testing Guide | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/KANBAN-WORKFLOW-TEST.md | Kanban Workflow Test Guide (Phase 3) | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_FINAL_STATUS.md | Phase 1 Final Status & Completion Report | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_IMPLEMENTATION_COMPLETE.md | Phase 1 Implementation Complete ✅ | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/PHASE_1_TESTING_RESULTS.md | Phase 1 Testing Results | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/PHYSICS_EXPERIMENT_README.md | StarForth Physics Engine Validation Experiment | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/RULE_1_GATES_IMPLEMENTATION.md | Rule 1: Governance-First Backlog Injection Gates Implementation | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/SECURITY.md | Security Policy | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/SESSION_SUMMARY.md | Session Summary: Governance Workflow Implementation Complete ✅ | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/StarForth_Complete_Presentation.pptx | StarForth_Complete_Presentation.pptx | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/TEST-CAPA-TEMPLATE.md | Test CAPA Issue Template | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/codex_audit_report.md | StarForth Governance – Fresh Audit Report | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/codex_capa_list.md | StarForth Governance – CAPA Register (Fresh Audit) | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/github_backlog_items.md | GitHub Project Backlog Prep | HISTORICAL | |
| docs/working/archive/legacy/phase-1/Reference/physics_experiment/ | 35 files | HISTORICAL | Grouped: bulk data or a self-governed tree. |
| docs/working/archive/legacy/phase-1/Reference/toolchain/ | 2 files | HISTORICAL | Grouped: bulk data or a self-governed tree. |
| docs/working/archive/operations/README.md | Operations | HISTORICAL | |
| docs/working/archive/operations/backlog-gatekeeper.md | Backlog Gatekeeper Procedures | HISTORICAL | |
| docs/working/archive/operations/jenkins-pipeline-guide.adoc | StarForth Jenkins Pipeline Guide | HISTORICAL | |
| docs/working/archive/operations/qa-intake-workflow.adoc | QA Intake & CAPA Backlog Population Workflow | HISTORICAL | |
| docs/working/archive/operations/refinement/annotations.adoc | StarForth Refinement Code Annotation Guide | HISTORICAL | |
| docs/working/archive/operations/refinement/capa.adoc | StarForth C↔Isabelle Refinement Defect Tracking | HISTORICAL | |
| docs/working/archive/operations/refinement/roadmap.adoc | StarForth C↔Isabelle Refinement Implementation Roadmap | HISTORICAL | |
| docs/working/archive/operations/workflow.md | StarForth CI/CD Workflow | HISTORICAL | |
| docs/working/archive/prog-prove.pdf | prog-prove.pdf | HISTORICAL | |
| docs/working/archive/quality/README.md | Quality Assurance | HISTORICAL | |
| docs/working/archive/quality/audits/codebase-audit-report.md | StarForth Codebase Audit Report | HISTORICAL | |
| docs/working/archive/quality/audits/corrective-actions.md | StarForth Codebase Audit: Corrective Actions Report | HISTORICAL | |
| docs/working/archive/quality/audits/implementation-audit.md | StarForth Adaptive Tuning: Implementation Audit | HISTORICAL | |
| docs/working/archive/quality/audits/section-2-audit.md | SECTION 2 AUDIT REPORT | HISTORICAL | |
| docs/working/archive/quality/audits/section-2-executive-summary.md | SECTION 2 EXECUTIVE SUMMARY | HISTORICAL | |
| docs/working/archive/quality/phase-tracking/phase-2-implementation-checklist.md | Phase 2 Implementation Checklist | HISTORICAL | |
| docs/working/archive/quality/phase-tracking/phase-2-issues-identified.md | Phase 2 Issues: Shrink/Grow, Decay Slope, Fixed-Point Violations | HISTORICAL | |
| docs/working/archive/quality/phase-tracking/phase-2a-session-summary.md | Phase 2a Session Summary: Linear Decay & Freeze Flag Implementation | HISTORICAL | |
| docs/working/archive/quality/regression/detection-framework.md | Optimization Regression Detection Framework | HISTORICAL | |
| docs/working/archive/quality/regression/opp-02-report.md | OPP #2: VARIANCE-BASED WINDOW WIDTH TUNING | HISTORICAL | |
| docs/working/archive/quality/validation/comprehensive-physics-validation.md | Comprehensive Physics Engine Validation Protocol | HISTORICAL | |
| docs/working/archive/quality/validation/phase-1-protocol.md | Phase 1 Governance Validation Protocol | HISTORICAL | |
| docs/working/archive/quality/validation/phase-2-executive-summary.md | Phase 2 Experiment: Executive Summary | HISTORICAL | |
| docs/working/archive/research/README.md | Research | HISTORICAL | |
| docs/working/archive/research/doe-metrics-schema.md | StarForth Design of Experiments (DoE) Metrics Schema | HISTORICAL | |
| docs/working/archive/research/literature-review.md | Literature Review: Physics-Driven VM Optimization | HISTORICAL | |
| docs/working/archive/research/research-outline.md | Research Paper Outline: Physics-Driven VM Optimization | HISTORICAL | |
| docs/working/archive/research/results-for-publication.md | Results for Publication: Physics-Driven VM Optimization | HISTORICAL | |
| docs/working/archive/session-logs/2025-11-20-recap.md | Session Recap: 2025-11-20 | HISTORICAL | |
| docs/working/archive/session-logs/2025-11-26-worklog.md | Work Log: November 26, 2025 | HISTORICAL | |
| docs/working/archive/session-logs/2026-07-05-worklog.md | Work Log: July 5, 2026 | HISTORICAL | |
| docs/working/archive/session-logs/2026-07-24-punch-list.md | Punch List: Gaps from 2026-07-24 Session | HISTORICAL | |
| docs/working/archive/session-logs/README.md | Session Logs | HISTORICAL | |
| docs/working/archive/session-logs/experimental-addendum.md | Window Scaling Experiment — Validation of the James Law of Computational Dynamic | HISTORICAL | |
| docs/working/archive/session-logs/experimental-iteration-usage.md | Experimental Iteration Runner - Usage Guide | HISTORICAL | |
| docs/working/archive/session-logs/serialized-questing-pike.md | StarForth → StarshipOS Hybrid Kernel Transformation Plan | HISTORICAL | |
| docs/working/archive/superseded/2025-12-14-starforth-roadmap.md | StarForth Roadmap: VM → Kernel → OS → FPGA | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-07-08-hermes-message-block-storage-design.md | Hermes Message/Channel Block-Backed Storage — Design Doc | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-07-08-hermes-message-channel-physics-design.md | Hermes Message/Channel Heat Physics — Design Doc | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-02-artemis-hermes-compudynamics-plan.md | Artemis (and Hermes) Compudynamics — Implementation Plan | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md | docs/03-architecture/ | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-tripod/ARTEMIS.md | ARTEMIS.md — Artemis VM Architecture | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-tripod/HERMES.md | HERMES.md — Hermes VM Architecture | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-tripod/README.md | docs/working/archive/superseded/2026-08-tripod/ | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/2026-08-tripod/TRIPOD.md | TRIPOD.md — Architectural Constraints for the Tripod VMs | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/L8_WIRING_PLAN.md | L8 Control Wiring Implementation Plan | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/factorial-doe/guide.md | StarForth Complete 2^6 Factorial Design of Experiments | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/factorial-doe/incompatible-configs.md | Handling Incompatible Configurations in Factorial DoE | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/factorial-doe/index.md | StarForth Complete 2^6 Factorial DoE - Documentation Index | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/factorial-doe/quick-start.md | Quick Start: Complete 2^6 Factorial DoE | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/factorial-doe/workflow.md | Factorial DoE Analysis Workflow | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/feedback-loops-analysis.md | StarForth Feedback Loops & Self-Optimization Analysis | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/heartbeat-doe-corrected-design.md | StarForth Heartbeat DoE – CORRECTED Design (Heartrate Focus) | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/heartbeat-doe-design.md | StarForth Factorial DoE with Heartbeat Integration | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/heartbeat-rate-logging-plan.md | Implementation Plan: Heartbeat Rate Logging | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/loop-5-sketch.md | Loop #5: Context-Aware Window Tuning - Design Sketch | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/archive/superseded/steady-state-machine.md | 1. Introduction | SUPERSEDED | See the file's own header for what replaces it. |
| docs/working/experiments/02-experiments/L8_WIRING_CODE_REVIEW_GUIDE.md | L8 Wiring Code Review Guide | WORKING | |
| docs/working/experiments/02-experiments/L8_WIRING_IMPLEMENTATION_SUMMARY.md | L8 Control Wiring Implementation Summary | WORKING | |
| docs/working/experiments/02-experiments/README.md | Experiments | WORKING | |
| docs/working/experiments/02-experiments/heartbeat-doe/execution-guide.md | StarForth Heartbeat DoE Experiment – Execution Guide | WORKING | |
| docs/working/experiments/02-experiments/heartbeat-doe/implementation-summary.md | StarForth Heartbeat DoE – Implementation Summary | WORKING | |
| docs/working/experiments/02-experiments/heartbeat-doe/phase2-corrected.md | StarForth Phase 2 Heartbeat DoE – CORRECTED AND FINALIZED | WORKING | |
| docs/working/experiments/02-experiments/james-law/protocol.md | Critical Window Scaling Experiment | WORKING | |
| docs/working/experiments/02-experiments/physics-optimization/doe-guide.md | StarForth Optimization DoE Guide | WORKING | |
| docs/working/experiments/02-experiments/physics-optimization/execution-guide.md | StarForth Physics Engine - Comprehensive Validation Experiment | WORKING | |
| docs/working/experiments/02-experiments/physics-optimization/hotwords-cache.md | Physics Engine Experiment: Hot-Words Cache Performance Analysis | WORKING | |
| docs/working/experiments/02-experiments/physics-optimization/proposals.md | Physics-Driven Optimization Proposals for StarForth | WORKING | |
| docs/working/experiments/02-experiments/physics-optimization/reproduce.md | Reproducing the Physics Engine Hot-Words Cache Experiment | WORKING | |
| docs/working/experiments/README.md | docs/working/experiments/ | WORKING | |
| docs/working/experiments/campaigns/doe_2x7/README.md | 2^7 Factorial Design of Experiments (DoE) | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_attractor_map/SESSION_REPORT_2025-12-10.md | L8 Attractor Map: From Crashes to Computational Physics | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_attractor_map/results_20251209_145907/ | 9 files | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_attractor_map/run_log.txt | run_log.txt | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_validation/EXPERIMENT_SUMMARY.txt | Quick test (10 reps, ~8 min) | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_validation/README.md | L8 Jacquard Mode Selector Validation Experiment | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_20251208_102205/ | 2 files | RECORD | Campaign data. |
| docs/working/experiments/campaigns/l8_validation/l8_validation_30reps_20251126_135128/ | 2 files | RECORD | Campaign data. |
| docs/working/experiments/campaigns/shape_validation/README.md | Workload Shape Validation Experiment | RECORD | Campaign data. |
| docs/working/experiments/campaigns/shape_validation/shape_RAJ_run_20251127_093208/ | 2 files | RECORD | Campaign data. |
| docs/working/experiments/campaigns/shape_validation/shape_run_20251123_083147/ | 2 files | RECORD | Campaign data. |
| docs/working/experiments/campaigns/window_scaling/QUICK_START.md | Window Scaling Experiment - Quick Start Guide | RECORD | Campaign data. |
| docs/working/experiments/campaigns/window_scaling/README.md | Window Scaling Experiment — James Law Validation | RECORD | Campaign data. |
| docs/working/hardware/PGO_GUIDE.adoc | Interactive TUI | WORKING | |
| docs/working/hardware/PLATFORM_BUILD_GUIDE.adoc | POSIX Build (Linux/macOS/BSD) - DEFAULT | WORKING | |
| docs/working/hardware/README.md | docs/working/hardware/ | HISTORICAL | Flagged in its own header. |
| docs/working/hardware/performance-profiling/ARM64_OPTIMIZATIONS.adoc | Detect architecture | WORKING | |
| docs/working/hardware/performance-profiling/ASM_OPTIMIZATIONS.adoc | Add to CFLAGS | WORKING | |
| docs/working/hardware/performance-profiling/PROFILER.adoc | Run your typical Forth program with profiling | WORKING | |
| docs/working/hardware/platform-integration/PLATFORM_ABSTRACTION.adoc | POSIX build (default - Linux/macOS/BSD) | WORKING | |
| docs/working/hardware/platform-integration/RASPBERRY_PI_BUILD.adoc | Install dependencies | WORKING | |
| docs/working/legal/README.md | docs/working/legal/ — Patent-Adjacent Material (HOLD) | LEGAL HOLD | Not touched without Captain Bob. |
| docs/working/papers/ACADEMIC_WORDING_GUIDELINES.md | Academic Wording Guidelines for StarForth | WORKING | |
| docs/working/papers/ANTI_CLAIMS.md | Anti-Claims: What This Work Does NOT Claim | WORKING | |
| docs/working/papers/EXECUTIVE_SUMMARY.md | Executive Summary: StarForth in Plain English | WORKING | |
| docs/working/papers/FINAL_REPORT/appendix_glossary.adoc | appendix_glossary.adoc | WORKING | |
| docs/working/papers/FORMAL_CLAIM_TABLE.md | Formal Claim Table: StarForth Adaptive Runtime | WORKING | |
| docs/working/papers/NEGATIVE_RESULTS.md | Negative Results: Where StarForth Fails | WORKING | |
| docs/working/papers/NULL_HYPOTHESIS.md | Null Hypothesis and Falsification Criteria | WORKING | |
| docs/working/papers/ONTOLOGY_README.md | StarForth Ontology Documentation | WORKING | |
| docs/working/papers/README.md | docs/working/papers/ | WORKING | |
| docs/working/papers/REPLICATION_INVITE.md | Invitation to Independent Replication | WORKING | |
| docs/working/papers/REPRODUCIBILITY.md | Reproducibility: One-Command Experiment Reproduction | WORKING | |
| docs/working/papers/SCIENTIFIC_DEFENSE_CHECKLIST.md | Scientific Defense Checklist | WORKING | |
| docs/working/papers/SENSITIVITY_ANALYSIS.md | Sensitivity Analysis: Parameter Robustness | WORKING | |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.pdf | Math_Companion_SSRN.pdf | WORKING | |
| docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex | | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig1_snake_trajectory.pdf | fig1_snake_trajectory.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig2_K_vs_window.pdf | fig2_K_vs_window.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig3_FFT_spectrum.pdf | fig3_FFT_spectrum.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig4_golden_ratio_penalties.pdf | fig4_golden_ratio_penalties.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig5_bimodal_distributions.pdf | fig5_bimodal_distributions.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig6_performance_vs_k.pdf | fig6_performance_vs_k.pdf | WORKING | |
| docs/working/papers/SSRN_companion/figures/fig7_performance_by_regime.pdf | fig7_performance_by_regime.pdf | WORKING | |
| docs/working/papers/SYSTEM_NARRATIVE.pdf | SYSTEM_NARRATIVE.pdf | WORKING | |
| docs/working/papers/SYSTEM_NARRATIVE.tex | StarForth System Narrative}\\ | WORKING | |
| docs/working/papers/ontology.pdf | ontology.pdf | WORKING | |
| docs/working/papers/ontology.tex | StarForth Ontology: Formal Conceptual Framework for\\ | WORKING | |
| docs/working/papers/proposals/DARPA_SSM_Proposal_James.docx | DARPA_SSM_Proposal_James.docx | WORKING | |
| docs/working/papers/proposals/DARPA_SSM_Proposal_James.pdf | DARPA_SSM_Proposal_James.pdf | WORKING | |
| docs/working/papers/proposals/SSM_DARPA_Complete_Proposal_James_FINAL.docx | SSM_DARPA_Complete_Proposal_James_FINAL.docx | WORKING | |
| docs/working/papers/published/James_ACL_Security_Invariant_TTL_Mitigation.tex | % | WORKING | |
| docs/working/papers/published/James_Steady-State_Convergence_Adaptive_Runtime.pdf | James_Steady-State_Convergence_Adaptive_Runtime.pdf | WORKING | |
| docs/working/scratch/AGENTS.md | Repository Guidelines | WORKING | |
| docs/working/scratch/AI_AGENT_MANDATORY_README.md | AI_AGENT_MANDATORY_README.md | WORKING | |
| docs/working/scratch/COMMUNICATION_GUIDE.adoc | StarshipOS Analogy Cheat Sheet | WORKING | |
| docs/working/scratch/GOVERNANCE_EXPORT_NOTES.adoc | Governance Export Notes (Physics Phase 1) | WORKING | |
| docs/working/scratch/README.md | docs/working/scratch/ | WORKING | |
| docs/working/scratch/TASK_LIST.md | StarForth Physics Runtime — TASK_LIST.md | WORKING | |
| docs/working/scratch/assets/README.md | Binary Assets | WORKING | |
| docs/working/scratch/assets/book-FIXED.docx | book-FIXED.docx | WORKING | |
| docs/working/scratch/ci-cd/FMEA_BLOCKING_GATES.adoc | FMEA Blocking Gates Implementation | WORKING | |
| docs/working/scratch/ci-cd/GITHUB_ISSUES_GOVERNANCE_FLOW.adoc | GitHub Issues & Governance Integration | WORKING | |
| docs/working/scratch/ci-cd/GOVERNANCE_INPUT_AUDIT.adoc | Governance Input Audit & Compliance Checklist | WORKING | |
| docs/working/scratch/ci-cd/JENKINS_GOVERNANCE_INTEGRATION.adoc | Jenkins Governance Integration Guide | WORKING | |
| docs/working/scratch/governance/index.adoc | Governance | WORKING | |
| docs/working/scratch/src-index.adoc | StarForth Documentation Index | WORKING | |
| docs/working/scratch/src/INTEGRATION_NOTES.adoc | This blocks EVERYTHING because of empty line: | WORKING | |
| docs/working/scratch/src/development/CONTRIBUTING.adoc | 1) Fork and clone | WORKING | |
| docs/working/scratch/src/internal/PHASE_2A_COMPLETION_REPORT.adoc | Phase 2a Completion Report: Freeze Flag & Linear Decay | WORKING | |
| docs/working/scratch/src/internal/PHASE_2_IMPLEMENTATION_SUMMARY.adoc | Phase 2 Implementation Summary & Action Items | WORKING | |
| docs/working/scratch/src/internal/PHASE_2_PHYSICS_DECAY_AND_FREEZE.adoc | Phase 2: Physics Model Extensions — Decay & Freeze Mechanisms | WORKING | |
| docs/working/scratch/src/internal/PHYSICS_HOTWORDS_CACHE_INTEGRATION.adoc | Hot-Words Cache Integration Guide | WORKING | |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_OPTIONS.adoc | Physics Engine Implementation Options: Three Paths Forward | WORKING | |
| docs/working/scratch/src/internal/PHYSICS_IMPLEMENTATION_STATUS.adoc | Physics Engine Implementation Status: POSIX vs L4Re Porting Strategy | WORKING | |
| docs/working/scratch/src/internal/PHYSICS_SCHEDULING_PLAN.adoc | Physics-Driven Scheduling Metadata Plan | WORKING | |
| docs/working/scratch/testing-quality/KANBAN-WORKFLOW-VALIDATION.adoc | Kanban Workflow Validation Procedure | WORKING | |
| docs/working/specifications/HOLA_PROTOCOL.adoc | HOLA Shared Memory Protocol (Phase 1) | WORKING | |
| docs/working/specifications/README.md | docs/working/specifications/ | WORKING | |
## experiments
| Path | Title | Status | Notes |
|---|---|---|---|
| experiments/README.md | experiments/ | RECORD | Experiment design, data or result. |
## experiments/artemis_stress
| Path | Title | Status | Notes |
|---|---|---|---|
| experiments/artemis_stress/analysis/ | 6 files | RECORD | Experiment design, data or result. |
## experiments/bare_metal
| Path | Title | Status | Notes |
|---|---|---|---|
| experiments/bare_metal/README.md | Bare-Metal DoE Experiment | RECORD | Experiment design, data or result. |
| experiments/bare_metal/analysis/ | 130 files | RECORD | Experiment design, data or result. |
## experiments/std79-doe
| Path | Title | Status | Notes |
|---|---|---|---|
| experiments/std79-doe/README.md | std79 DoE — 3(architecture) × 9(identity) × 3(replicate) randomized full-factori | RECORD | Experiment design, data or result. |
| experiments/std79-doe/analysis-20260912/ | 2 files | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/README.md | std79-doe LaTeX report: the fleet conservation invariant K | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/actual_window_size_dark.pdf | actual_window_size_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/actual_window_size_light.pdf | actual_window_size_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/apic_delta_dark.pdf | apic_delta_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/apic_delta_light.pdf | apic_delta_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/artemis_heat_dark.pdf | artemis_heat_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/artemis_heat_light.pdf | artemis_heat_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/avg_word_heat_dark.pdf | avg_word_heat_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/avg_word_heat_light.pdf | avg_word_heat_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/fleet_k_dark.pdf | fleet_k_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/fleet_k_light.pdf | fleet_k_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hera_heat_dark.pdf | hera_heat_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hera_heat_light.pdf | hera_heat_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hermes_heat_dark.pdf | hermes_heat_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hermes_heat_light.pdf | hermes_heat_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hot_word_count_dark.pdf | hot_word_count_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/hot_word_count_light.pdf | hot_word_count_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/jitter_ns_dark.pdf | jitter_ns_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/jitter_ns_light.pdf | jitter_ns_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/time_trust_dark.pdf | time_trust_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/time_trust_light.pdf | time_trust_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/variance_dark.pdf | variance_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/variance_light.pdf | variance_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/vm_call_depth_max_dark.pdf | vm_call_depth_max_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/vm_call_depth_max_light.pdf | vm_call_depth_max_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/window_width_dark.pdf | window_width_dark.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/figures/window_width_light.pdf | window_width_light.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/std79_doe_report.pdf | std79_doe_report.pdf | RECORD | Experiment design, data or result. |
| experiments/std79-doe/report-20260912/report/std79_doe_report.tex | % | RECORD | Experiment design, data or result. |
## experiments/std79-exerciser
| Path | Title | Status | Notes |
|---|---|---|---|
| experiments/std79-exerciser/README.md | FORTH-79 Standard-Dictionary Cross-ISA Exerciser | RECORD | Experiment design, data or result. |
| experiments/std79-exerciser/results-20260910/ | 27 files | RECORD | Experiment design, data or result. |
## img
| Path | Title | Status | Notes |
|---|---|---|---|
| img/README.md | img/ | CURRENT | |
## kernel
| Path | Title | Status | Notes |
|---|---|---|---|
| kernel/include/starkernel/README.md | include/starkernel/ | CURRENT | |
| kernel/include/starkernel/freestanding/README.md | include/starkernel/freestanding/ | CURRENT | |
| kernel/include/starkernel/freestanding/sys/README.md | include/starkernel/freestanding/sys/ | CURRENT | |
| kernel/include/starkernel/hal/README.md | include/starkernel/hal/ | CURRENT | |
| kernel/include/starkernel/vm/README.md | include/starkernel/vm/ | CURRENT | |
| kernel/include/starkernel/vm/bootstrap/README.md | include/starkernel/vm/bootstrap/ | CURRENT | |
| kernel/linker/README.md | linker/ | CURRENT | |
| kernel/src/README.md | src/starkernel/ | CURRENT | |
| kernel/src/arch/aarch64/README.md | src/starkernel/arch/aarch64/ | CURRENT | |
| kernel/src/arch/amd64/README.md | src/starkernel/arch/amd64/ | CURRENT | |
| kernel/src/arch/riscv64/README.md | src/starkernel/arch/riscv64/ | CURRENT | |
| kernel/src/boot/README.md | src/starkernel/boot/ | CURRENT | |
| kernel/src/capsule/README.md | src/starkernel/capsule/ | CURRENT | |
| kernel/src/hal/README.md | src/starkernel/hal/ | CURRENT | |
| kernel/src/hash/README.md | src/starkernel/hash/ | CURRENT | |
| kernel/src/math/README.md | src/starkernel/math/ | CURRENT | |
| kernel/src/memory/README.md | src/starkernel/memory/ | CURRENT | |
| kernel/src/pci/README.md | src/starkernel/pci/ | CURRENT | |
| kernel/src/virtio/README.md | src/starkernel/virtio/ | CURRENT | |
| kernel/src/vm/README.md | src/starkernel/vm/ | CURRENT | |
| kernel/src/vm/bootstrap/README.md | src/starkernel/vm/bootstrap/ | CURRENT | |
| kernel/src/vm/host/README.md | src/starkernel/vm/host/ | CURRENT | |
## lfs
| Path | Title | Status | Notes |
|---|---|---|---|
| lfs/README.md | lfs/ | CURRENT | |
## mk
| Path | Title | Status | Notes |
|---|---|---|---|
| mk/README.md | mk/ | CURRENT | |
## proof
| Path | Title | Status | Notes |
|---|---|---|---|
| proof/COVERAGE.md | Isabelle/HOL Proof Suite — Coverage & Purpose | CURRENT | |
| proof/FINDINGS.md | Isabelle/HOL Word-Source Sweep — Aggregated Architectural Findings | CURRENT | |
| proof/README.md | proof/ | CURRENT | |
## scripts
| Path | Title | Status | Notes |
|---|---|---|---|
| scripts/README.md | scripts/ | CURRENT | |
| scripts/SCRIPT_REPAIR_LOG.md | Ablation Study Script Repair Log | CURRENT | |
## tools
| Path | Title | Status | Notes |
|---|---|---|---|
| tools/README.md | tools/ | CURRENT | |
| tools/capsule-reserved.txt | capsule-reserved.txt — human-authored, git-tracked block ranges NOT | CURRENT | |
| tools/kconfig/README.md | tools/kconfig — vendored Linux kernel Kconfig tooling | CURRENT | |
## v3
| Path | Title | Status | Notes |
|---|---|---|---|
| v3/include/README.md | include/ | CURRENT | |
| v3/src/README.md | src/ | CURRENT | |
| v3/src/platform/README.md | src/platform/ | CURRENT | |
| v3/src/platform/l4re/README.md | src/platform/l4re/ | HISTORICAL | Flagged in its own header. |
| v3/src/platform/linux/README.md | src/platform/linux/ | CURRENT | |
| v3/src/test_runner/README.md | src/test_runner/ | CURRENT | |
| v3/src/test_runner/include/README.md | src/test_runner/include/ | CURRENT | |
| v3/src/test_runner/modules/README.md | src/test_runner/modules/ | CURRENT | |
| v3/src/word_source/README.md | src/word_source/ | CURRENT | |
| v3/src/word_source/include/README.md | src/word_source/include/ | CURRENT | |
## v4
| Path | Title | Status | Notes |
|---|---|---|---|
| v4/README.md | v4/ | CURRENT | |
docs/README.md
+65 -53
View File
@@ -1,59 +1,71 @@
# StarForth / LithosAnanke Documentation
# StarForth / LithosAnanke documentation — the map
This is the `lithosananke` branch: the bare-metal StarKernel side of the project
(contrast `master`, which is the hosted-VM-only side). Documentation follows the
two-tier model described in `docs/CLAUDE.md`: **`formal/`** is the polished,
citable LaTeX tier; **`working/`** is living design notes and drafts that feed it.
Everything else in this directory is branch- or subsystem-specific material that
doesn't fit either tier.
Start here. This page says where each kind of document lives and which one to believe.
Reorganised 2026-10-14 (the docs triage): one place for current reference, one archive for
everything kept as record, and every superseded or abandoned document labelled as such in
its own header.
- **[INDEX.md](INDEX.md)** — every document in the repository, with its status.
- **[DEAD-AND-REVISED.md](DEAD-AND-REVISED.md)** — the ideas that were abandoned, and the claims
that were revised, each with the date and where the decision is recorded.
- **[DELETE-CANDIDATES.md](DELETE-CANDIDATES.md)** — what was deleted as duplicate, and why
(2026-10-14).
## What to believe
| For | Authoritative | Where |
|---|---|---|
| How to work in this repo, and current status | `.claude/CLAUDE.md` | repo root |
| What was decided, and why; work as it happened | the FABRIC record | [fabric/](fabric/) — `FABRIC-3.md` is the living one |
| StarForth v4 (the F18-derived engine) | the v4 design | [v4.0.0/](v4.0.0/) and `../v4/README.md` |
| Roadmap and release-versioning policy | `ROADMAP.md` | [reference/](reference/) |
| Getting onto the boards | the bring-up checklist | `../boards/BRINGUP.md` |
| A word, a primitive, a term | the dictionaries and the ontology | [reference/](reference/) |
| What the code does | the code, and its folder's `README.md` | `../kernel/`, `../v3/`, `../v4/` |
Where two documents disagree, the one higher in this table wins, and code wins over all.
## Layout
- **[formal/](formal/)** — Three-volume LaTeX documentation set (research volumes,
practitioner books, standalone reports) plus the `scraps/` fragment library it's
assembled from. Audience: patent counsel, SSRN reviewers, licensees, hobbyists
with hardware in hand. See `formal/CLAUDE.md` for authoring conventions.
- **[working/](working/)** — Living documents: architecture design notes, DoE
experiment logs, hardware/platform notes, draft specs, academic-paper source
material, and an archive of superseded docs. Source material for `formal/`.
- **[03-architecture/](03-architecture/)** — Tripod VM architecture constraints and the
word-level ACL system design. (Note: the fleet is now **Hera/Artemis/Hestia** post-
reshuffle; the old Hera/Hermes/Artemis framing in older docs is historical. The older,
triaged copy of this tree is `working/architecture/03-architecture/`.)
- **[lithosananke/](lithosananke/)** — LithosAnanke kernel branch documentation:
milestone roadmap, system architecture, HAL reference, kernel command-line argument
design, and the amd64 APIC-timer ISR postmortem.
- **[birthing/](birthing/)** — VM birthing plan and status for the Hera-spawns-
Hermes/Artemis constellation, plus three-architecture QEMU acceptance logs.
- **[patent/](patent/)** — Provisional patent application source. **Legal hold —
ask Bob before touching anything in this directory.**
- **[api/](api/)** — Generated Doxygen tag file and warnings log (gitignored;
not part of the tracked doc tree).
- **[pptx/](pptx/)** — Elevator-pitch and deep-dive slide decks for different
audiences (technical, non-technical, academic, PhD-level).
- **[fabric/](fabric/)** — the design and work record, numbered in order. `FABRIC-3.md`
(bare-metal boot and everything since) is open; the others are closed:
- FABRIC-0, -1 and -2 are history;
- FABRIC-3.5 and -3.6 are the Tripod/kernel reshuffle, still authoritative for what they ruled;
- FABRIC-3.7 (elevation) is closed as not needed;
- FABRIC-4 holds ideas caught early, not yet scoped.
- **[v4.0.0/](v4.0.0/)** — StarForth v4: justification, engine, decomposition, nucleus, mesh,
parity with v3. `plans/` holds the step plans, all executed.
- **[reference/](reference/)** — current reference material:
- `ROADMAP.md` (roadmap and the ratified versioning policy);
- `M7.1.md` (init capsules and birth);
- `word-acl/` (the word-level ACL design);
- `kernel-args/` (the boot command line);
- `hosted-acceptance-test/`;
- `DICTIONARY.md` and `STARFORTH_PRIMITIVES.md` (the words);
- `ONTOLOGY.md` (the lexicon);
- `L8_ADAPTIVE_CONFIG_TABLE.md`.
- **[working/](working/)** — living material and the source for `formal/`:
- `architecture/` (design notes and HOWTOs);
- `experiments/` (DoE designs and campaign data);
- `papers/` (academic sources, the system narrative, proposals);
- `hardware/`, `specifications/` and `scratch/`;
- **`archive/`**, which has four parts:
- `historical/`: finished work, kept as record;
- `superseded/`: replaced, and each file's header names what replaced it;
- `dead/`: abandoned or never adopted;
- the older `legacy/`, `quality/`, `operations/`, `research/` and `session-logs/`.
- **[formal/](formal/)** — the press-ready LaTeX tier (three volumes, books, standalone
reports). Governed by `formal/CLAUDE.md`.
- **[book/](book/)** — the LithosAnanke and StarForth book build.
- **[pptx/](pptx/)** — slide decks for different audiences.
- **[patent/](patent/)** — provisional patent material. **Legal hold: ask Captain Bob before
touching anything here** (also `formal/patent/`, `formal/scraps/legal/`, `working/legal/`).
## Current Active Work
## Adding a document
> **⚠ `INDEX.md` is a dated triage snapshot (2026-06-16) and is stale.** The authoritative
> current status lives in `.claude/CLAUDE.md` and `docs/fabric/FABRIC-2.md` /
> `FABRIC-3.md` / `FABRIC-3.5.md` / `FABRIC-3.6.md` — not in the status tags in `INDEX.md`.
- **LithosAnanke M7.1 — live** — init capsules, the Tripod fleet, Stadium physics-economy,
and word-level ACL (Phases 1–7 complete; Phase 8 Ed25519 PKI pending). See
`lithosananke/ROADMAP.md` and the FABRIC documents above.
- **Tripod VMs (post-reshuffle)** — Hera (governor), Artemis (memory/block storage),
Hestia; the Hermes VM was removed and messaging moved into the kernel as kernel-Hermes.
See `.claude/CLAUDE.md`.
- **StarForth v4** — the F18-derived 32-opcode engine with the node/mesh design. See
`v4.0.0/` and `../v4/README.md`.
- **Word-level ACL system** — see `03-architecture/word-acl/` and `lithosananke/ROADMAP.md`.
## Contributing
- Place new material in `working/` first; promote to `formal/` only when it's
ready to be cited (see `formal/CLAUDE.md` for promotion criteria).
- Never touch `patent/`, `formal/patent/`, `formal/scraps/legal/`, or
`working/legal/` without Bob's explicit instruction.
- Add a `README.md` to any new category-level subdirectory, following the
format used throughout this tree: orientation paragraph + bullet list of
real files with one-line descriptions.
- Draft in `working/`; promote to `formal/` when it is ready to be cited (`formal/CLAUDE.md`).
Reference material that describes the system as it is goes in `reference/`.
- When a document is overtaken, do not delete it: `git mv` it into `working/archive/superseded/`
or `dead/` with a header saying why and what replaces it, and add a line to
`DEAD-AND-REVISED.md`.
- Rules for documentation work: [CLAUDE.md](CLAUDE.md).
docs/book/Makefile
+2 -2
View File
@@ -30,8 +30,8 @@ PANDOC_FLAGS := -f gfm -t latex --top-level-division=chapter --wrap=preserve \
# fragment name : Markdown source. The order of \input lines is main.tex's.
CHAPTERS := \
ontology:docs/ONTOLOGY.md \
roadmap:docs/ROADMAP.md \
ontology:docs/reference/ONTOLOGY.md \
roadmap:docs/working/archive/superseded/2025-12-14-starforth-roadmap.md \
boards:boards/README.md \
justification:docs/v4.0.0/JUSTIFICATION.md \
decomposition:docs/v4.0.0/DECOMPOSITION.md \
docs/book/main.tex
+2 -2
View File
@@ -122,8 +122,8 @@ are reproduced as written, including their struck-through corrections.
Chapter & Source \\
\midrule
\endhead
Ontology & \texttt{docs/ONTOLOGY.md} \\
Roadmap & \texttt{docs/ROADMAP.md} \\
Ontology & \texttt{docs/reference/ONTOLOGY.md} \\
Roadmap & \texttt{docs/working/archive/superseded/2025-12-14-starforth-roadmap.md} \\
Boot targets & \texttt{boards/README.md} \\
v4 justification & \texttt{docs/v4.0.0/JUSTIFICATION.md} \\
v4 decomposition & \texttt{docs/v4.0.0/DECOMPOSITION.md} \\
docs/fabric/FABRIC-0.md
+6 -6
View File
@@ -34,7 +34,7 @@ an unrelated structure. The document has been swept; "arena" now survives only i
quotes that reproduce an earlier section verbatim, and in §12's preserved question list,
which several sections quote.
**On `docs/lithosananke/ROADMAP.md`.** As of 2026-08-11, Captain Bob stated this document
**On `docs/reference/ROADMAP.md`.** As of 2026-08-11, Captain Bob stated this document
superseded ROADMAP.md entirely. That still holds, transitively, through `FABRIC-1.md` now.
---
@@ -4425,7 +4425,7 @@ document and committing that amendment as its own item.*
> `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not
> decided here.
>
> **Now scoped, 2026-08-11 — resolved in `docs/lithosananke/ROADMAP.md`'s M8 section,
> **Now scoped, 2026-08-11 — resolved in `docs/reference/ROADMAP.md`'s M8 section,
> not here.** M8 is "tracked outside Stadium" per §27.5, and its console-facing pieces
> don't change this document's own scope, so the resolution lives there rather than as
> new 4.3.x items. Short answer to the open question above: `io_words.c` under
@@ -4999,7 +4999,7 @@ document and committing that amendment as its own item.*
> decision #4 -- both text paths coexist. Per this item's own posture (matching 4.3.6g),
> stopping here before scoping REPL wiring (M8).
>
> **M8 scoped 2026-08-11 in `docs/lithosananke/ROADMAP.md`, not here** -- per §27.5, M8 is
> **M8 scoped 2026-08-11 in `docs/reference/ROADMAP.md`, not here** -- per §27.5, M8 is
> tracked outside Stadium, so its design decisions live in that roadmap's own M8 section
> rather than as new 4.3.x items. Key finding from that scoping pass, worth recording in
> this document too since it bears on §27.6's CANVAS/REPL-strip framing: the REPL's
@@ -5939,7 +5939,7 @@ document and committing that amendment as its own item.*
exactly that — no scancode-to-ASCII translation table exists, and no code path connects the
keyboard ring buffer to the REPL's line-read loop. The hardware/interrupt layer is done; the
bridge from that layer into text the REPL can act on is not. This is the same conclusion
`docs/lithosananke/ROADMAP.md`'s M8 section and this document's own 4.3.5-series entries
`docs/reference/ROADMAP.md`'s M8 section and this document's own 4.3.5-series entries
already recorded ("no keyboard path into the VM on any architecture, confirmed by reading
the code") — restated here specifically so 4.4u's TAB-toggle has an accurate prerequisite,
not because the earlier conclusion was in doubt.
@@ -5957,7 +5957,7 @@ document and committing that amendment as its own item.*
keyboard event injected via QEMU's own input-send-event monitor command (not socat/serial),
screendump showing the typed text landed in the REPL strip; three-arch QEMU boot + logs per
CLAUDE.md.
*Refs:* §27.8, 4.3.5 series, 4.4r, 4.4u, `docs/lithosananke/ROADMAP.md` M8 section.
*Refs:* §27.8, 4.3.5 series, 4.4r, 4.4u, `docs/reference/ROADMAP.md` M8 section.
> **DONE 2026-08-12.** Reused item 4.3.5f's `KEY-EVENT` convergence work rather than building
> two per-arch tables from scratch (`kbw_key_event`'s FORTH-word logic was refactored into a
@@ -7549,7 +7549,7 @@ direct-arena reference — 4.3.7b's own call) behind that lookup.
### 27.8 REPL: prompt, text path, CANVAS geometry (4.4–4.4s)
Scoped 2026-08-11, in conversation with Captain Bob, replacing `docs/lithosananke/ROADMAP.md`'s
Scoped 2026-08-11, in conversation with Captain Bob, replacing `docs/reference/ROADMAP.md`'s
M8 section entirely (marked OBSOLETE there, kept for history only). Original visual reference:
[`repl-mockup.png`](repl-mockup.png).
docs/fabric/FABRIC-1.md
+2 -2
View File
@@ -1425,14 +1425,14 @@ evidence nothing regressed.
`docs/CLAUDE.md`'s own correction, made in the same pass, for the doc-toolchain findings —
`doxygen` installed, `docs/Makefile` pointer corrected — and this section's own proof-count
reconciliation above for the Isabelle/HOL findings):
- [ ] `docs/lithosananke/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such
- [ ] `docs/reference/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such
branch exists post-split), `M7.1.md`'s "Status: Design Complete" (shipped and live, not
just designed), `ROADMAP.md`'s self-contradiction (M8 marked OBSOLETE in one place,
still a live success criterion in another), and its stale "AHCI driver" claim for M9
(real implementation is `virtio_blk.c`) — not fixed this pass, flagged.
- [ ] Top-level `ROADMAP.md` (StarForth-era, "Phase 0 Complete... Phase 1 Starting," dated
2025-12-14) — badly stale, no historical/superseded banner to warn a reader. Not fixed.
- [ ] `docs/03-architecture/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity)
- [ ] `docs/reference/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity)
is still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states
Phase 7 is independently verified complete. Not fixed.
- [ ] `VM-FLEET-ATTRACTOR-DESIGN-20260705.md` claims `doe-campaign.4th` is "broken and being
docs/fabric/FABRIC-2.md
+4 -4
View File
@@ -102,7 +102,7 @@ decisions get added here, not to `FABRIC-1.md`. Follow the same discipline `FABR
### From FABRIC-1.md §J — Maintainability sweep (2026-08-18)
- [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.**
`docs/lithosananke/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such
`docs/reference/ROADMAP.md` and `M7.1.md` — stale `Branch: lithosananke` (no such
branch exists post-split), `M7.1.md`'s "Status: Design Complete" (shipped and live, not
just designed), `ROADMAP.md`'s self-contradiction (M8 marked OBSOLETE in one place, still
a live success criterion in another), and its stale "AHCI driver" claim for M9 (real
@@ -112,10 +112,10 @@ decisions get added here, not to `FABRIC-1.md`. Follow the same discipline `FABR
- [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.** Top-level
`ROADMAP.md` (StarForth-era, "Phase 0 Complete... Phase 1 Starting," dated
2025-12-14) — marked OBSOLETE by `cbe7b49` (Captain Bob's call: more than stale), pointing
to `docs/lithosananke/ROADMAP.md` and `FABRIC*.md` for current status.
to `docs/reference/ROADMAP.md` and `FABRIC*.md` for current status.
- [x] **Fixed 2026-08-26 (commit `cbe7b49`), stale carry-forward closed 2026-08-28.**
`docs/03-architecture/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity)
`docs/reference/word-acl/DESIGN.md` says ACL Phase 7 (LithosAnanke kernel parity)
is still "remaining" — direct contradiction with `.claude/CLAUDE.md`, which states Phase 7
is independently verified complete. Phase 7 restated as independently-verified complete and
the stale lithosananke-branch-parity framing removed by `cbe7b49`.
@@ -3434,7 +3434,7 @@ hardware), the **release-gate recommendation**, and the **punch lists to complet
each.
**The versioning split, decided 2026-08-28 — now standing policy, see
`docs/lithosananke/ROADMAP.md` "Release Versioning Policy" for the authoritative form.**
`docs/reference/ROADMAP.md` "Release Versioning Policy" for the authoritative form.**
v2.0.0 is the **QEMU release** — the point
where the QEMU-only story is complete and defensible on its own terms. v2.5.0 is the
**real-hardware release** — the point where the same story transfers to bare metal on a real
docs/fabric/FABRIC-3.5.md
+6 -6
View File
@@ -2489,13 +2489,13 @@ describe are stripped** (§XXII.5), so the manifest never describes a file that
**Superseded subsystem docs** — `.claude/TRIPOD.md`, `HERMES.md`, `ARTEMIS.md`, `CONSOLE.md`
already carry superseded headers, but after this reshuffle they describe a fleet that no longer
exists. Same for `docs/03-architecture/tripod/{TRIPOD,HERMES,ARTEMIS,README}.md`, which
exists. Same for `docs/working/archive/superseded/2026-08-tripod/{TRIPOD,HERMES,ARTEMIS,README}.md`, which
`.claude/CLAUDE.md` still lists as current for Tripod. **Decide deliberately: update, or mark
archival and point at `FABRIC-3.5.md`.** Not a silent edit either way.
**Also in scope:** `capsules/README.md` (lists `hermes/init.4th` as a live personality),
`ROADMAP.md` / `docs/lithosananke/ROADMAP.md`, `CHANGELOG.md`, `README.md`,
`docs/lithosananke/SYSTEM_ARCHITECTURE.md` and `M7.1.md`, and `proof/COVERAGE.md` (after the
`ROADMAP.md` / `docs/reference/ROADMAP.md`, `CHANGELOG.md`, `README.md`,
`docs/working/archive/historical/2026-01-27-system-architecture-draft.md` and `M7.1.md`, and `proof/COVERAGE.md` (after the
§XXV pass — and per §XXV.3 its *boundary* statement matters more than its file count).
`capsules/BLOCK_MAP.md` is a generated artifact; regenerate, don't hand-edit.
@@ -2705,7 +2705,7 @@ the version number (§XXVI.3).** No code is authorized.
table in `Makefile.starkernel` itself (lines ~74–82), which is more specific:
```
# Roadmap (per docs/lithosananke/ROADMAP.md "Release Versioning Policy" and
# Roadmap (per docs/reference/ROADMAP.md "Release Versioning Policy" and
# FABRIC-2.md §G — X.0.0 = QEMU release, X.5.0 = hardware bare-metal release):
# v1.0.x — serial-only production (released)
# v1.5.x — framebuffer VT100 terminal/console milestone (released)
@@ -2736,7 +2736,7 @@ will step 2.0.1 → 2.2.0 with a released `v2.1.0` tag sitting in a gap the tabl
mention. **Add the line wherever the table lives:**
1. `Makefile.starkernel` (the copy above, beside the `LITHOS_VERSION` edit itself).
2. `docs/lithosananke/ROADMAP.md`, "Release Versioning Policy" — the comment names it as the
2. `docs/reference/ROADMAP.md`, "Release Versioning Policy" — the comment names it as the
upstream source.
3. `FABRIC-2.md` §G is the origin of the scheme but is **CLOSED/ARCHIVAL** — **cite it, do not
edit it.** Amending a closed document to match a later decision is exactly what this series'
@@ -3011,7 +3011,7 @@ removed 2026-08-15 as non-functional and must not be resurrected.
- ✅ **Versioning policy — CLOSED** (§XXX). All three §XXIX.3 conflicts resolved; LTS criteria
ratified; engine `VERSION` closed as a rule.
- ✅ **This release is `2.1.0`** (§XXVIII), even major, working line.
- ⬜ **Carry §XXX.1–XXX.6 into `Makefile.starkernel` and `docs/lithosananke/ROADMAP.md`**
- ⬜ **Carry §XXX.1–XXX.6 into `Makefile.starkernel` and `docs/reference/ROADMAP.md`**
(§XXVIII.2), replacing the old roadmap table. `FABRIC-2.md` §G is cited, never edited.
- ⬜ Engine `VERSION` applied at tag time per §XXX.6's rule.
docs/fabric/FABRIC-3.6.md
+1 -1
View File
@@ -1484,7 +1484,7 @@ opposite of what per-task commits are for. Tasks 5.5–5.7 return to one-commit-
`PLOT`/`FB-*` relocated to Hestia; no FORTH-79 word semantics changed). The stale
version-comment block in `Makefile.starkernel` (which still said "even major = LTS" —
backwards relative to the ratified §XXX.1 odd/even rule — and had no `v2.1.0` entry)
replaced with the real ladder. `docs/lithosananke/ROADMAP.md`'s own "Release Versioning
replaced with the real ladder. `docs/reference/ROADMAP.md`'s own "Release Versioning
Policy" section (the second of the two live places) was still the full retired
2026-08-28 policy, not just a stale table — replaced with the ratified §XXX policy text,
the old text kept struck-through in a `<details>` block for traceability, and the
docs/fabric/FABRIC-3.7.md
+13 -1
View File
@@ -1,6 +1,18 @@
# FABRIC-3.7.md — Phase 8 PKI: the elevation entrypoint
**Status: OPEN — design only, no code written or authorized.**
**Status: CLOSED 2026-10-14 — not needed; elevation removed, not built.** Captain Bob, asked
"is it even a necessary capability?": privilege comes from the drive (Zuse's drive, or the
personality an identity is minted with), so a runtime request-and-grant channel only adds attack
surface — and the old one was a live hole: `KH-ELEVATE-SEND` let any identity have arbitrary
FORTH run as Zuse. `ELEVATE-GRANT` granted automatically on eligibility-list membership (no
human approves), into Hera's own dictionary (never the requester's), and could never reach a
FORTH-79-locked identity's words (pinned, and pins are one-way). Removed: `KH-ELEVATE-SEND`,
message type 8, `zuse-eligibility.4th`, `ZUSE-ELIGIBLE?`/`ZUSE-ELIGIBILITY-ADD`/
`ELEVATE-PUBKEY-UNPACK`, the eligibility list itself and Part B's gate in `zuse.4th`;
`devblock_from_top` 1–63 on Artemis's disk stay reserved, unused (his ruling). See
`FABRIC-3.md` §XXXVII. Everything below is kept as the record of the design.
**Former status: OPEN — design only, no code written or authorized.**
**CORRECTION (2026-09-22, before any code was written against this document): §2's central
claim — that the old `SEND-ELEVATE-REQUEST` passed a raw cross-VM address into `ELEVATE-GRANT`'s
docs/fabric/FABRIC-3.md
+414 -5
View File
@@ -2461,6 +2461,29 @@ the existing xHCI multi-device history (§VII, and the 2026-09-05/06/07 fixes re
-- possibly a recurrence or a related gap in the same per-slot attach-pending scan, given the
similar shape ("several ports become pending at once, only some get serviced").
**No longer reproduces, 2026-10-14 -- checked on all three ISAs, closed.** Both reproductions
above were rerun against a freshly minted, matched set: a scratch `artemis.img` and Zuse drive,
and five identity drives (`00`-`04`) minted at a live `zuse@Hera` prompt by `MINT`, one hot-plug
at a time (`logs/20261014-082526`). Not against the committed images: every image under
`disk/thumbdrives/`, and `disk/artemis.img`, is all zeros since `e56974e0` bleached them ahead of
§XXXV.6's re-mint, which has not been done. A blank drive is correctly passed over in silence
(its home-blocks check reads BLANK, logged at debug level only), so a first attempt today with
copies of the committed images (`logs/20261014-062249`) showed no WIREBIND lines and proved
nothing either way.
| ISA | five drives present at power-on | five drives hot-plugged ~1 s apart over QMP |
|---|---|---|
| amd64 | 5/5 attached (`logs/20261014-082755`) | 5/5 attached (`logs/20261014-083236`) |
| aarch64 | 5/5 attached (`logs/20261014-083415`) | 5/5 attached (`logs/20261014-083917`) |
| riscv64 | 5/5 attached (`logs/20261014-084134`) | 5/5 attached (`logs/20261014-084624`) |
Zuse's own drive was confirmed in every boot as well. No code changed for this. What closed the
gap is most likely the xHCI driver's per-port connect queue (`kernel/src/usb/xhci.c`,
`dev->pending_events[]`: a connect event that arrives while a command is in flight is held and
handled once the command ring is idle, not dropped); when that landed cannot be traced past the
source-tree reorganisation (`a8b70e88`), so this is inference, not proven. The one-at-a-time
attach rule of §XV and §XXXI is no longer needed.
## XV. 3(architecture) × 9(identity) × 3(replicate) randomized full-factorial DoE — self-contained
FORTH capsule, replacing the ad hoc exerciser-feeding process (2026-09-11)
@@ -3969,7 +3992,7 @@ are attached reliably in the first place, including under the "already plugged i
case §XIV's own second reproduction showed failing.
**Bug 2 -- the MSG-TICK/Stage-3-switch dual-ownership rough edge (§XXVIII's own admission,
never revisited).** Both MSG-TICK's idle-pump dispatch and the Stage 3 timer-driven switcher can
never revisited).** *Closed 2026-10-14: one delivery path, built -- §XXXVI.* Both MSG-TICK's idle-pump dispatch and the Stage 3 timer-driven switcher can
independently move control between the same VMs; not reconciled, not observed to interact badly
so far, but never proven safe under all interleavings either. Directly relevant to Stage 4 for
the same reason as Bug 1: WIREBIND VMs bring a second population of dynamically-birthed contexts
@@ -4579,7 +4602,7 @@ call sites (`repl.c` has 18); most are direct interactive replies already correc
this rule -- reclassifying the specific sites that aren't is Stage D's job (the same files Stage
C's triage already walks), not repeated here.
**Decision on the two §XXVII gaps: fix eviction now, defer `LOG-FLUSH` again.**
**Decision on the two §XXVII gaps: fix eviction now, defer `LOG-FLUSH` again.** *`LOG-FLUSH` built 2026-10-14 -- §XXXVIII.*
`LOG-FLUSH` needs real new machinery first -- the per-VM log buffer its own doc comment already
presumes (`vm_log_buffer.h`) does not exist anywhere in the tree, confirmed by grep; building it
means designing that buffer format and the flush word together, genuine feature work deserving
@@ -5197,6 +5220,19 @@ sequence at all until/unless this is fixed at the source -- the interactive two-
(typed live over the serial socket) sidesteps the bug, it does not fix it. Flagged here as a
real, reproducible defect worth its own fix later, out of scope for this section.
**Fixed 2026-10-14.** The mechanism, traced: `vm_interpret()` (`kernel/src/vm/vm_core.c`, and
the hosted `v3/src/vm.c`) copies each text it runs into the VM's one `input_buffer` and resets
`input_pos`. `LOAD` runs its block by calling it, so the block took the place of the line `LOAD`
was on, and when the block was done the outer loop found nothing left to read. The same held
for every word that runs text from inside a line: `-->`, a capsule's `EXEC`, a message
kernel-Hermes delivers. `vm_interpret()` now keeps what the outer text had not yet read when it
is called from inside another, and puts it back afterwards, as FORTH-79's `LOAD` keeps the
input stream it interrupts. Two POST cases, `LOAD.rest_of_line` (`1 LOAD 0 0 /`) and
`THRU.rest_of_line` (`1 2 THRU 0 0 /`), fail without the fix (`logs/20261014-061222`) and pass
with it; three-ISA acceptance `logs/20261014-061508` (amd64), `-061624` (aarch64), `-061837`
(riscv64): 1052 tests, none failed, hash `0x08873e0f44b7cb2a` unchanged. So a `THRU`-then-call
line now works as one `SK_CMD`; that use itself was not re-run.
### XXXIV.2 -- A cross-session QEMU collision killed the first real relaunch at 0 trials
Once running for real (via the two-line workaround), the campaign was silently killed a fourth
@@ -5463,7 +5499,7 @@ device it was minted on.
- Build a **new, blank 1 GiB `disk/artemis.img`** from scratch -- not a resize of the current
file. No migration code written or needed.
- **Zuse re-minted fresh** on the new image (genesis marker, root CA placement, per
`docs/03-architecture/word-acl/DESIGN.md`'s Phase 8 design and
`docs/reference/word-acl/DESIGN.md`'s Phase 8 design and
`project_phase8_milestone6_complete.md`'s already-verified entropy/signing/block-fence chain --
same mechanism, new device, not new code).
- **All 8 thumbdrive identities re-minted** (`project_thumbdrive_identities_minted_20260906.md`:
@@ -5476,8 +5512,8 @@ device it was minted on.
### XXXV.7 -- Genuinely open, not decided here
- **Exact v2 decimation factor**, if/when v2 is built at all (§XXXV.4).
- Whether `THRU`'s own line-swallowing defect (§XXXIV.1, still un-root-caused at the C level) gets
fixed before or after this work -- it blocks true single-command `SK_STARTUP_FORTH` autolaunch
- ~~Whether `THRU`'s own line-swallowing defect (§XXXIV.1, still un-root-caused at the C level) gets
fixed before or after this work~~ Fixed 2026-10-14, before it (§XXXIV.1) -- it blocks true single-command `SK_STARTUP_FORTH` autolaunch
of the campaign regardless of persistence format; the two-line interactive workaround still
applies either way.
- Disposal of the two stale partial amd64 runs' data (§XXXIV.5's own still-open item) is unrelated
@@ -5488,3 +5524,376 @@ device it was minted on.
design/decision only, no capsule/C code, no new disk image, and no re-mint actually performed
or committed for the drive resize, the persistence region, or the N=2 campaign shape.
## XXXVI. One delivery path: a VM takes its own messages, on its own turn -- built (2026-10-14)
Closes the MSG-TICK/Stage-3 dual-ownership item (§XXVIII, §XXIX bug 2, §XXXI), as ruled in
`FABRIC-3.5.md` §XXXII ("one mover"); Captain Bob, 2026-10-14: collapse it before the bare-metal
builds. **The state before:** the MSG-TICK pump was gone (FABRIC-3.6 Stage E), but two paths
still ran a VM's kernel-Hermes messages -- the VM's own outermost colon-word checkpoint, and
Hera's idle beat, which walked every live VM and ran each one's messages *for* it, on Hera's
stack. The second was the only path for a VM nothing else drives (a WIREBIND identity's `~user`
VM, FABRIC-3.6 task 3.9). It was guarded (parked VMs are not LIVE and were skipped) but it was
two paths.
**What changed.**
- `sk_hermes_send_one()` marks the receiver as having work for the switch signal.
- What a VM runs on its own native stack (`sk_vm_switch_entry()`, until now a placeholder that
only yielded) now takes its own messages, then yields. Not while its interpreter is mid-line on
some other, parked, stack (new per-VM `interpret_depth`, counted in `vm_interpret()`): then
they wait and it asks for another turn.
- Hera's idle beat no longer runs anyone's messages but her own; it makes the switch the switch
signal has pending (`sk_vm_switch_service_pending()`, shared with the colon-word checkpoint),
so a message still arrives while she sits at her prompt.
- Every VM is registered with the switch signal at its birth (idempotent; the Tripod and
WIREBIND registrations stay) and unregistered when killed or reaped.
- `sk_hermes_drain_checkpoint()` refuses, with "Kernel-Hermes: message held -- its VM is not the
one running", any call not in the VM's own context: its interpreter running at the outermost
text, or it is the VM switched in and not mid-line elsewhere. This is the test: it failed
first, holding every relayed line (`logs/20261014-092558`), and never fires now.
- A VM yielding from the top of its own loop stays LIVE; only a VM switched out mid-line is
SWITCHED_OUT. Found by the test: with every yield SWITCHED_OUT, the console stopped relaying
to an identity after its first message (it relays only to a LIVE one) and KILL would have
refused every VM that had ever taken a message (`logs/20261014-095904`).
**A real defect found on the way, amd64 only:** `sk_vm_switch_prime()` (`arch/amd64/switch.S`)
built a first-entry frame that left `rsp` a multiple of 16 at `sk_vm_switch_entry()`'s entry; the
SysV ABI wants `rsp + 8` to be. Harmless while that function only switched back; a #GP (an
aligned SSE store to the stack) the first time it ran the interpreter there
(`logs/20261014-093823`). The frame is now 64 bytes with a null return address above the entry
address. aarch64 (160) and riscv64 (208) frames were already 16-aligned. This may also be what
stopped the 2026-09-14 attempt (`vm_interpret(self, "MSG-TICK")` in the same function, reverted
after a stall never root-caused) -- not proven.
**`FABRIC-3.5.md` §XXXII.5's three build questions, as answered here:** (1) the payload waits in
the receiver's kernel-Hermes queue and is run by the receiver on its own stack on its turn; (2)
Hera's special case stays only in this sense -- her messages run at her own idle beat, which is
her own context; (3) `g_mama_interpreting` and `g_idle_pump_active` stay, still guarding Hera's
own drain.
**Verified.** A WIREBIND identity (`S" 00" USE`, then four plain lines: `1 2 + .`, an unknown
word, `5 6 * .`, `7 8 + .`) receives and runs all four on its own stack -- `3`, the unknown-word
error, `30`, `15` -- with nothing held and no fault, on amd64 (`logs/20261014-101933`), aarch64
(`logs/20261014-102701`) and riscv64 (`logs/20261014-100948`). Five identity drives hot-plugged a
second apart at the prompt all attach (their attach acknowledgements are messages to Hera)
(`logs/20261014-102525`). Standard acceptance, committed disks: all three ISAs to `zuse@Hera`,
POST 1052 tests passed, `PARITY:M7.1a ... hash=0x08873e0f44b7cb2a` unchanged, no unknown word
(`logs/20261014-103248`, `-103409`, `-103616`). Superseded attempts, kept: `-092406` (wrong `USE`
syntax), `-094908` (before the LIVE-on-yield fix, one line only).
## XXXVII. Any identity could run FORTH as Zuse; a message could run twice; elevation removed (2026-10-14)
Found while building FABRIC-3.7's elevation entrypoint, proven live, fixed test first.
**1. Two words let any VM have Hera run any text, in her own dictionary -- Zuse's.**
`KH-ELEVATE-SEND ( paddr plen -- ok? )` and `KH-BLK-ATTACH-SEND ( paddr plen -- ok? )`
(`repl.c`) are registered in every VM (`word_registry.c`), and each sent whatever text it was
handed to Hera as a kernel-Hermes message, which Hera interprets. From a WIREBIND identity's
console: `S" 777 ." KH-ELEVATE-SEND .` and `S" 778 ." KH-BLK-ATTACH-SEND .` -- Hera printed
`777` and `778` (`logs/20261014-105930`, `-110937`). A line holding `"` is run on the identity's
console VM instead of relayed (`repl.c`'s own v1 limitation), which is what reached them.
**2. One message could run twice.** `sk_hermes_drain_checkpoint()` popped a message only after
running it; a payload that runs a colon word reaches the checkpoint in `execute_colon_word()`,
which drains the same VM again -- and found the same message at the head. A relayed `T3`
(`: T3 333 . ;`) printed `333 333`; `778` above printed twice (`logs/20261014-110937`).
**3. Elevation itself: not needed (Captain Bob, 2026-10-14).** Asked whether it was even a
necessary capability, given (1): privilege comes from the drive -- Zuse's, or the personality an
identity is minted with -- and a runtime request-and-grant channel only adds attack surface.
`ELEVATE-GRANT` granted on eligibility-list membership alone (no human approves), into Hera's own
dictionary (never the requester's), and could never reach a FORTH-79-locked identity's words (all
pinned; pins are one-way). Its only caller had been gone since 2026-09-22 and nothing missed it.
`FABRIC-3.7.md` is closed as not needed.
**Fixes.**
- Removed: `KH-ELEVATE-SEND`; message type 8 (retired, not reused); `capsules/zuse-eligibility.4th`
(`ELEVATE-GRANT`, blocks 4021-4022) and its `EXEC` in `init.4th`; the C words `ZUSE-ELIGIBLE?`,
`ZUSE-ELIGIBILITY-ADD`, `ELEVATE-PUBKEY-UNPACK`; the eligibility list (`zuse_eligibility.c`,
`zuse_eligibility.h`, `zuse_eligibility_list.h`); FABRIC-3.7 Part B's gate on
`ZUSE-ELIGIBILITY-ADD` in `zuse.4th`. `devblock_from_top` 1-63 on Artemis's disk stay reserved,
unused (his ruling). `NAME>XT` stays: general-purpose.
- `KH-BLK-ATTACH-SEND` is now `( dev-addr ok? -- sent? )`, refused unless Artemis calls it; the
kernel writes `<dev-addr> <0|1> BLK-ATTACH-ACK` itself. Artemis's `HERA-BLK-ATTACH-REQ` is now
`DUP BLK-ATTACH KH-BLK-ATTACH-SEND DROP` (its text builder is gone, and with it Artemis's one
"Unterminated comment" warning, a nested-paren comment).
- `BLK-ATTACH-ACK` is refused unless Hera runs it.
- The drain pops a message before running it; the message, and so its payload, is still held
until released after.
**Verified.** The same session after the fix (`logs/20261014-112514`): `333` once,
`KH-BLK-ATTACH-SEND: refused -- only Artemis replies to a storage attach`, `UNKNOWN WORD:
'KH-ELEVATE-SEND'`, identity `00` attaches. Five identities hot-plugged at the prompt all attach
(`logs/20261014-113615`). Standard acceptance, all three ISAs: `zuse@Hera`, POST 1052 passed, no
unknown word, **`PARITY:M7.1a word_count=523 ... hash=0xb73b58052d591638` -- a deliberate new
baseline** (was 530 / `0x08873e0f44b7cb2a`: the four C words and `zuse-eligibility.4th`'s
definitions are gone from Hera's dictionary) (`logs/20261014-113112`, `-113232`, `-113450`). A first attempt (`-111859`) broke
attach two ways, both mine: nested parens in the new capsule comment, and `%lld`, which the
kernel's freestanding `snprintf` does not do.
**Found, not fixed (pre-existing, unrelated):** Hera prints two and Hestia three `( Unterminated
comment` warnings at every boot, in logs from before this work too.
## XXXVIII. `LOG-FLUSH` built: a VM's log records reach Artemis's log ring (2026-10-14)
Deferred in §XXXII.4 as its own initiative; Captain Bob, 2026-10-14: build it before the
bare-metal builds. His rulings: **everything the VM logs** goes in its buffer (at or above the
log level -- the one, global `LOG-LEVEL!` setting, the same filter `log_message()` applies);
it goes to disk **on `LOG-FLUSH`, when the buffer fills, and at once on an ERROR record**.
**Built.**
- Each VM has a buffer of its own (`VM.log_buf`, 900 bytes, packed records: level, timestamp,
length, text; `vm_log_buffer.c`/`.h`). `log_message()` (`shim.c`) adds every record it prints
to the buffer of the VM it is attributed to (`vm_log_attributed_vm()`); a record made outside
any VM's text -- the kernel's own -- belongs to none and is not kept.
- A flush is one kernel-Hermes message to Artemis, type `SK_HERMES_MSG_TYPE_LOG_BATCH` (10), the
one message type that is not FORTH text: `sk_hermes_drain_checkpoint()` hands it to
`vm_log_batch_deliver()`, which writes each record with `log_region_append()` -- in Artemis's
own context, on her turn (§XXXVI). The record's source is the sender the kernel stamped on the
message, never a name the sender gives: a VM cannot write under another's name.
- Nothing is lost silently: records that cannot go (Artemis not yet live -- all of Hera's POST --
or the send refused) are counted, and the next flush that can be sent leads with "N log
records not sent: Artemis not ready" (175 at a normal boot).
- `LOG-FLUSH ( -- )`, every VM. `LOG-SHOW ( n -- )`, Hera only: the newest n records, oldest of
them first, as source, level, text -- added because the ring had no reader at all, so nothing
written there could be read or checked (`log_region_read_recent()`). Hera only because it shows
every VM's records, and Hera's console is Zuse's.
**A real defect in the ring, found by the first test that filled it:** growth
(`log_region_append()`) claimed to be "safe regardless of wrap state" and was not. The ring is
full when it grows, so head == tail; nothing moved and tail stayed put, so the next write
overwrote the oldest record and the new, blank slots read back as records inside the live
range. 30 records written to a fresh ring read back as 28 of them and 12 blank
(`logs/20261014-115648`; also `-115434` on a ring already damaged by an earlier test). Fixed:
the records from head on move up by the slots added, and the next write goes into the gap (with
head at 0 -- the only case growth meets, since nothing is evicted before the ring is at its full
size -- simply at the old end). §XXXII.4 had flagged eviction as never live-exercised.
**Verified.** Test first: `LOG-FLUSH` and `LOG-SHOW` unknown (`logs/20261014-114028`). Then:
Hera's WARN probe and her boot warnings, under source `Hera`, after `LOG-FLUSH`; identity `00`'s
ERROR probe, sent by itself at once, under source `00` (`-114847`); the lost-records notice
(`-115434`); 30 records through a growth, in order, no blank, on amd64 (`-115841`), aarch64
(`-120526`) and riscv64 (`-120746`). Standard acceptance, all three ISAs: `zuse@Hera`, POST 1052
passed, no unknown word, **new baseline `word_count=526 ... hash=0x82f4ae7cb2e2d424`**
(deliberate: Hera's new words) (`logs/20261014-120027`, `-120148`, `-120356`).
## XXXIX. The Pi 5's native path: MMU and caches on before any C, bounded mailbox, framebuffer address from the devicetree -- and a rehearsal on QEMU that found three more (2026-10-14)
Captain Bob, 2026-10-14: "fix the pi 5 problems" -- the three from the Friday review (`boards/BRINGUP.md`
R2, R3).
**1. MMU and caches off (R2).** The firmware enters at EL2 with the MMU off: every access is
Device memory, where an unaligned access or an exclusive faults and nothing is cached. The
aarch64 kernel had never needed to turn the MMU on -- under UEFI it runs on the firmware's map
(`arch_mmu_init()` is a stub; `vmm.c` builds x86-shaped tables it never loads on aarch64).
`native_rpi5_entry.S` now: cleans and invalidates the data cache over the whole image first
(so nothing the firmware left there lands on top of what follows); builds an identity map, the
image's GiB Normal write-back in 2 MiB blocks, every other GiB Device-nGnRE and never executable;
sets MAIR, TCR and TTBR0 and turns on M, C and I at whichever EL it was entered at (EL2 on the
Pi 5, EL1 handled too), with WXN and alignment checking off. In C, `rpi5_mmu.c` then makes every
further GiB the devicetree's `/memory` covers entirely Normal, and makes the framebuffer Normal
non-cacheable (the display reads it straight from RAM), each change break-before-make.
**2. Unbounded mailbox waits (R3).** Every wait now gives up after one second by the
architectural counter (`-5`); before any console exists a silent VideoCore must cost a missing
framebuffer, not a hang. With the caches on, the request buffer is cleaned to RAM before it is
sent and invalidated before the answer is read: the VideoCore does not see the ARM's caches.
**3. The framebuffer address (R3).** `& 0x3FFFFFFF` was the Pi 4's rule. The address the firmware
returns is now carried through the devicetree's `dma-ranges` from the firmware node up: on the
Pi 5 (the real `bcm2712-rpi-5-b.dtb`) the firmware node's is empty and `/soc` has none, so it is
already physical; on a Pi 4 `/soc` maps bus `0xC0000000` onto 0, and that is handled too. An
address no entry holds is refused (`-6`). Still unverified: the allocate tag's size field.
**The rehearsal.** There is no QEMU model of the Pi 5, but QEMU's virt machine with
`virtualization=on` enters a raw image exactly as the Pi 5's firmware does: at EL2, MMU off,
devicetree in x0. New `make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000
rpi5-rehearsal` links the same native image at virt's address (the linker script's base is now
`RPI5_NATIVE_BASE`, 0x80000 by default) and boots it, Cortex-A76, one QEMU, foreground. It found
three more, each of which would have stopped the Pi 5:
- **The PL011's register shift**, mine (`c9519173`): `fdt_uart.c` gave a devicetree PL011 a shift
of 0, but `console.c` numbers its registers by word -- the flag register was read at +6, not
+0x18: an alignment fault on Device memory at the first character. The UEFI path never met it
(it uses a built-in default with the right shift), and the host test asserted the wrong value.
Shift 2 now; the test expects it.
- **The GIC's address**: `apic.c` read the GIC's `reg` as two 64-bit cells with no translation --
right only where the GIC is a child of the root. On the Pi 5 it is on `/soc` (one cell,
`0x7fff9000`), `0x107fff9000` to the CPU. New `fdt_reg_address()` (`fdt.c`) reads a node's `reg`
entry in its parent's cells and carries it up through every bus's `ranges`; the GIC lookup uses
it, and accepts virt's `arm,cortex-a15-gic` too. Checked against the real Pi 5 devicetree:
`tools/fdt_uart_test.c <dtb> pl011 0x107d001000 2 4 arm,gic-400 0x107fff9000 0x107fffa000`.
- **No timer interrupt at EL2**: with `HCR_EL2.IMO/FMO/AMO` clear an IRQ targets EL1 and is never
taken while the CPU runs at EL2 -- "Heartbeat: 0 ticks". The entry stub sets them at EL2. The
UEFI path runs at EL1 and never met it.
**Verified.** Rehearsal, final: POST 1052 passed, `PARITY:M7.1a word_count=526 ...
hash=0x82f4ae7cb2e2d424` -- the same as the UEFI build -- the Tripod born, the heartbeat ticking,
no exception (`logs/20261014-124530/aarch64-rpi5/`). Earlier rehearsal and the hand-run QEMU
sessions that found the three are not logged (`-d int` to a scratch file); `logs/20261014-123129`
is the first, silent, run. Not rehearsed: the mailbox and framebuffer (virt has neither), the Pi
5's own UART and GIC addresses (the host test checks them against its devicetree), PCI (virt's
needs ACPI; the Pi 5's is R4). The board image (`make boot_image TARGET=RASPI`) links at 0x80000
and ends at 0x834000. Standard acceptance, all three ISAs: POST 1052 passed, same hash
(`logs/20261014-125305`, `-125427`, `-125635`).
## XL. The USB controller found as real hardware has it (`boards/BRINGUP.md` A1, 2026-10-14)
Captain Bob, 2026-10-14: "start on A1". The xHCI driver matched QEMU's own controller only --
vendor and device `1B36:000D`, on PCI bus 0, function 0 -- so no real board's controller was ever
found, and with it no thumbdrive, no login, no keyboard to come.
**What a real controller needs, done:**
- **Found by class**, `0x0C/0x03/0x30`, from any vendor: new `pci_find_class()` (`pci.c`) reads
every bus, slot and function the configuration space reaches (port I/O on amd64, all 256 buses;
through ECAM, the MCFG entry's bus range, now recorded). Real controllers sit behind bridges.
- **Mapped at its real size**: new `pci_bar_size()` (the standard all-ones probe, decoding off
meanwhile); never less than the old fixed 64 KiB.
- **Taken from the firmware** (xHCI 1.2 section 4.22.1): through the USB Legacy Support extended
capability, OS-owned set and BIOS-owned waited out for a second (taken regardless after, as
Linux does), every SMI enable off and SMI status cleared. QEMU's controller has no such
capability; a PC's BIOS, driving USB for its own setup screen, does.
- **64-byte contexts** (`HCCPARAMS1.CSZ=1`) laid out, not refused: every context is 32 or 64 bytes
apart (`xhci_ctx_bytes()`); a 64-byte context holds the same fields in its first 32 bytes, so the
existing structs stand.
- `XHCI_QEMU_ARGS` (`kernel/Makefile`) replaces the QEMU controller, to rehearse one placed as real
hardware places it.
**Verified.** Test first: QEMU's NEC controller (`nec-usb-xhci`, vendor 1033) behind a PCIe root
port on bus 1, Zuse's drive on it -- before, nothing attached and no `zuse@Hera` prompt
(`logs/20261014-131238`); after, the drive attaches and Zuse is minted, on amd64 (`-131934`),
aarch64 (`-132056`) and riscv64 (`-132257`). Standard acceptance with the usual controller, all
three: POST 1052 passed, hash `0x82f4ae7cb2e2d424` unchanged (`-132431`, `-132548`, `-132746`);
five identities hot-plugged, all attached (`-132912`).
**Not rehearsable, so unproven until the SER5:** the firmware handoff and 64-byte contexts --
QEMU's controller has neither. **Still open:** one controller only -- the first found. A PC with
several (the SER5 has more than one) drives that one's ports alone; the stick and keyboard must be
in them until the driver runs several (`xhci_get_dev()` is a single controller throughout).
## XLI. A USB keyboard, a full one (`boards/BRINGUP.md` A3) -- and a hang on any PC without PS/2 (S3) (2026-10-14)
Captain Bob, 2026-10-14: "start on A3", then, mid-way: "use this keyboard as a target. for example
include caps lock, numlock, keypad and arrow ... Note for `later`, let's build keyboard VM's"
(recorded as a concept, nothing built).
**Built.**
- **The device** (`xhci.c`): a configuration whose interface is HID / boot / keyboard (3/1/1) is
taken as a keyboard, not refused as "not a drive": its first interrupt IN endpoint is configured
(`xhci_cmd_configure_hid_endpoint()` -- interval converted from bInterval for full/low and high
speed), `SET_CONFIGURATION`, then `SET_PROTOCOL(boot)` (a keyboard starts in report protocol),
then one Normal TRB at a time on its ring; each report is read and the next queued, deferred like
every doorbell in this driver. Unplugging forgets it. "USB keyboard ready" on the console.
- **The keys** (`usb_kbd.c`): a boot report says which keys are held; the difference from the one
before is the presses and releases, modifiers included, ErrorRollOver ignored. HID usage IDs
become Linux keycodes -- the namespace the PS/2 and virtio keyboards already use -- for a full
keyboard: the main block, F1-F12, Print Screen/Scroll Lock/Pause, the navigation block, arrows,
Num Lock and the whole keypad. `sk_key_event_poll()` (`keyboard_words.c`) reads them first, on
every ISA.
- **What a key means** (`repl.c`, every keyboard alike): Caps Lock and Num Lock are toggles (Num
Lock on at start); Caps Lock acts on letters, Shift reverses it; the keypad types `/ * - +` and
Enter always, digits and `.` with Num Lock on, nothing with it off (navigation -- this REPL's
line editor appends and backspaces only, so arrows and Home/End type nothing either); the 102nd
key types `\` `|`. The lock state goes to a USB keyboard's lights by `SET_REPORT` on its next
report.
- **Speed**: one report at a time, serviced only on the once-a-second idle beat, lost keys -- the
keyboard's own queue overflowed at typing speed (found by the test: of a typed line, only `1`
arrived). While a USB keyboard runs, the console now services the event ring on every timer
tick as it waits for a key.
**S3, found on the way -- a hang.** To have the USB keyboard be QEMU's only keyboard on amd64 the
test turned the PS/2 controller off (`-machine i8042=off`), and the kernel hung at boot just after
the I/O APIC: with no controller port 0x64 reads 0xFF, "output full" for ever, and `i8042_init()`'s
drain never ended (nor would `i8042_drain_stale()`'s). A legacy-free PC -- quite possibly the SER5 --
would have stopped there. Now: 0xFF means no controller, "i8042: no PS/2 controller -- keyboard by
USB only", nothing more done to it; every drain bounded. With a controller, unchanged.
**Verified.** amd64 with the USB keyboard the only keyboard, typed over QMP (`logs/20261014-135243`):
`1 2 + .` on the main keys and again on the keypad with keypad Enter -- `3` both times; Caps Lock,
then `s" ab" type` typed in lower case -- the line reads `S" AB" TYPE` and prints `AB`; Num Lock
off, keypad 7, Enter -- nothing typed. aarch64 and riscv64 (`-135420`, `-135629`): "USB keyboard
ready" and the same three results -- there QEMU also has a virtio keyboard, so those runs show the
USB keyboard configured, not which keyboard each key came through. The hang and its fix:
`-134410` (stops after the I/O APIC), `-135022` (boots). Standard acceptance, all three ISAs: POST
1052 passed, hash unchanged, PS/2 initialised as before on amd64 (`-135808`, `-135918`, `-140123`);
five identities hot-plugged, all attached (`-140240`). Test first? No: this time the test was
written after the code, its "before" being no keyboard support at all (`-134213`, where QMP could
not reach the device, records the enumeration working).
**Limits, not hidden:** the first xHCI controller only (§XL); a keyboard whose first interface is
not its keyboard is not used; no key repeat (a boot keyboard does not repeat, and nothing here
does it for it); the lights are sent on the next report after a lock key, not at once.
## XLII. Every USB controller, not the first (`boards/BRINGUP.md` A1, the rest) (2026-10-14)
Captain Bob, 2026-10-14: "do multiple controllers" -- §XL's open item. A PC has several xHCI
controllers, each with its own ports; only the first found was driven, so a stick or keyboard in
another's ports was never seen.
**What assumed one controller, and now does not:**
- `xhci.c`: one latched `g_xhci_dev` → a table of up to `XHCI_MAX_CONTROLLERS` (8);
`xhci_poll_events()` services each in turn; `xhci_get_dev()` → `xhci_dev_count()` /
`xhci_dev_at(i)`; `xhci_find_and_map(dev, index)` finds the index-th controller (1 when there is
none). Everything per device was already per controller (`msc_slots`, the rings, the connect
state machine, the BOT state).
- `kernel_main.c`: brings up controller 0, 1, ... until there is none; one that fails is skipped.
- `repl.c` and `blkio_usb.c`: their per-slot arrays were indexed by slot ID alone -- but a slot ID is
a controller's own, so slot 1 on two controllers would have been one entry. Now one set per
controller (`g_usb_ctrl[]`; `blkio_usb.c` finds its set by the controller's pointer); the attach
acknowledgement looks the device up across all of them.
- `usb_kbd.c`: one "previous report" and one "lights sent" for every keyboard would have diffed two
keyboards against each other. Both are each keyboard's own now (in its slot); a keyboard that
goes releases whatever it still held (no Shift stuck down after unplugging).
**Verified.** Test first: amd64, no PS/2, Zuse's drive on the usual controller, a second (NEC,
behind a root port) with the USB keyboard and identity `00` -- before, only Zuse attached
(`logs/20261014-140826`); after, the keyboard types (`3`, `3`, `AB`), `00` attaches, Zuse is confirmed
(`-141442`) -- both controllers with a device in slot 1, the collision case. Four identities
hot-plugged onto the second controller all attach, and unplugging one detaches that one
(`-141621`). aarch64 and riscv64, the same two-controller boot: all the same results (`-141756`,
`-141953`). Standard acceptance, all three: POST 1052, hash unchanged (`-142120`, `-142237`,
`-142449`); five identities hot-plugged on the first controller, all attached (`-142606`).
## XLIII. Both systems on every board image, chosen at boot (`boards/BRINGUP.md` A6) (2026-10-14)
Captain Bob, 2026-10-13, ruled the boards carry "both, switchable"; asked 2026-10-14 where the
switch is: **at boot, one image** -- a word in the boot configuration, v3 as built.
**Built.**
- `STARFORTH_V4=1` already compiled the v4 engine in; `kernel_main` then ran v4 unconditionally.
Now it runs v4 only if the boot arguments say `system=v4`, or say nothing and the build's
default is v4 (`SK_V4_DEFAULT`, from `kernel/Makefile`'s `V4_DEFAULT`: 1 for a plain
`STARFORTH_V4=1` build, as before, so every v4 QEMU boot and test is unchanged). Otherwise v3,
which is compiled in alongside, runs. A kernel without v4 asked for it says so and runs v3. The
boot prints the choice and why: "System: StarForth v4 (system=v4)", "... (this build's
default)", ...
- `cmdline.c`: `system=v3` / `system=v4` (also `--system=`), a later one winning; anything else is
ignored, as every unknown argument is.
- `make boot_image`: `STARFORTH_V4=1 V4_DEFAULT=0` -- both systems, v3 unless asked -- and the
boot arguments file always written, `system=v3` first: `starforth.cfg` on the ESP (SER5, Mars),
`cmdline.txt` on the Pi 5's card (the firmware hands it over as the devicetree's `bootargs`).
- `make boot_image` also cleans its ISA's kernel objects first: they are shared with `make qemu`
and make does not see changed compile flags. Found doing it: the clean was handed the root's
`TARGET=SER5` and removed `build/amd64/SER5`, nothing -- the first SER5 image carried the v4
engine but a `kernel_main` compiled without it. Now `TARGET=kernel`; all three images checked to
carry both.
**Verified.** Board-style build (both, v3 default), each ISA: no argument -- v3, POST 1052, hash
unchanged; `system=v4` -- v4, `PARITY:V4_POST tests=538 pass=538`, `dict_hash=0xe5a57f3eb72ff94a`
(amd64 `logs/20261014-144027`, `-144141`; aarch64 `-144411`, `-144604`; riscv64 `-144934`,
`-145108`). A plain `STARFORTH_V4=1` build still boots v4 by default (`-145331`); a v3-only kernel
asked for v4 says so and runs v3 (`-145550`). The SER5 image itself, booted from its own disk under
OVMF (`logs/20261014-ser5-image/`): v3 as built; after changing the one word in `starforth.cfg` on
it, v4. The Pi 5 and Mars images: built, their `cmdline.txt` / `starforth.cfg` read back from the
image, both systems found in their kernels; not booted (no QEMU model for either). Standard
acceptance, all three ISAs: unchanged (`-150651`, `-150801`, `-151007`).
**XLIII, revised the same day -- v4 is the default build.** Captain Bob, 2026-10-14: "v4 is the
default build", then "no, qemu to v4 too ... we are effectively trying to retire v3". Every kernel
build now carries v4 and v3 and boots **v4**: `STARFORTH_V4` defaults on (Kconfig `default y`),
`V4_DEFAULT=1` everywhere, and the board images write `system=v4` into `starforth.cfg` /
`cmdline.txt`. `system=v3` is the one word that boots v3; `STARFORTH_V4=0` builds v3 alone. The
acceptance rule (`.claude/CLAUDE.md`) became: the three ISAs as built (v4), and the 32-bit build,
`make -C v4 test-32` ("the 32 bit build needs to go into the acceptance test too"). v3 is not part
of it ("i don't care about v3"); it stays in the tree, `system=v3` still boots it. Verified: the three images rebuilt with `system=v4` in their boot files; the
SER5 image under OVMF as built boots v4, and after changing the word, v3 (`logs/20261014-ser5-image/`).
docs/fabric/FABRIC-4.md
+63
View File
@@ -104,3 +104,66 @@ addressable VM other patrons talk to, rather than a bare C primitive anyone can
- How this interacts with §IV.1's own still-open native-boot-flow work — a GPIO VM needs GPIO
register addresses from the DTB the same way the rest of that bring-up does, so this idea
isn't independent of that work, just downstream of it.
## 3. Information state over information moment (2026-10-16)
Raised in conversation with Captain Bob during MESH step 7 (`docs/v4.0.0/MESH.md` §9a) --
theory stage, no code, no scope, deliberately not punch-listed yet.
**The idea, in his words:** "I actually have a theory about what information actually is; the
temporal existence and not a moment." And: "What we have is a 'information state' over
information moment. The question I will answer is that is there any advantage to this over a
conventional OS." Said after "simple is the object."
**Where it came from.** Step 7 first handed a believed GONE on from inside the node that believed
it, at that instant, on the stacks of whatever text it was in -- information as a moment. The final
review found it could be lost at depth, and a node between texts could lose its values to a fault.
The fix that was ruled (2026-10-16) makes the GONE a state: the kernel puts it on each node's
wire, where it waits until the node takes it. The moment version needed depth sweeps and stack
constants; the state version needs neither. The same shape runs through the design already:
messages that wait on wires, not in nodes (7d); patrons that arrive and depart over time (the
Stadium, `FABRIC-0.md`); K conserved, not sampled.
**The question he will answer:** is there any advantage to this over a conventional OS?
**As a null hypothesis** (phrased at his request, 2026-10-16; a starting form, to be sharpened
before any experiment):
> **H0:** Delivering information to a computing element as *state* -- a fact that persists where
> the element will take it, when it has the means to -- confers **no advantage** over delivering
> it as a *moment* -- an event the element must act on at the instant it arrives, with whatever
> resources it has then -- as a conventional OS does with signals and interrupts.
>
> **H1:** Delivery as state gives a measurable advantage on at least one of the measures below,
> at a cost in the others that does not outweigh it.
Measures that would decide it, each the same for both forms on the same workload:
1. **Loss:** events delivered that never took effect (believed but not acted on, coalesced,
dropped).
2. **Corruption under pressure:** faults, and state lost to them, when the receiver is short of the
resources the event needs (here: stack depth; in general memory, time).
3. **Variance:** the coefficient of variation of outcomes over repeated runs, and agreement of
state hashes across machines.
4. **Cost:** latency from delivery to effect, and the memory held by facts waiting.
H0 is rejected if state is better on 1, 2 or 3 beyond the measurement floor, with 4 within a bound
fixed before the run. It stands if not. Either result is a result.
**Contrasts noted in the conversation, as starting points, not conclusions:**
- A conventional OS delivers much information as moments: Unix signals run a handler at whatever
instant they land, on the interrupted code's stack, may call only async-signal-safe functions,
and plain signals arriving together coalesce -- the failure step 7's hand-on had. Interrupts,
preemption points and callbacks share the shape.
- What state may buy: no reentrancy class of bug (nothing runs on borrowed stack); nothing silently
lost to timing (a fact persists until taken, or is refused at once and its sender told, 7d.1);
reproducibility (state can be hashed and compared across machines, as `dict_hash` and K are);
verifiability (state is what Isabelle reasons about; interleavings of moments are what make
conventional kernels hard to prove).
- What it costs: latency (a fact waits until it is taken), memory for the queues, and a policy for
a full wire (today: refusal, or for the kernel's GONE, not told).
- How it could be answered with evidence: the DoE apparatus -- the same workload with facts
delivered as state and as interrupt-style moments, measuring lost events, variance (CV), and
behaviour under pressure.
**Explicitly not decided:** what "information" means formally in this theory; whether it bears on
the patent work; any experiment design. Captain Bob's question to answer, not yet scoped.
docs/formal/cookbook/main.tex
+1 -1
View File
@@ -100,7 +100,7 @@
\part{Security and ACL Recipes}
\chapter{Word-Level ACL Basics}
%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
%% SOURCE: docs/reference/word-acl/DESIGN.md
%% TODO(bob): promote ACL recipe: loading ACL.4th, granting/revoking modes,
%% TTL-based expiry. Do NOT draft independent claim language.
\input{../scraps/architecture/03-architecture/word-acl/DESIGN}
docs/formal/experiments/main.tex
+4 -4
View File
@@ -48,7 +48,7 @@
\part{$2^7$ Factorial Campaign}
\chapter{Campaign Design}
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/guide.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/guide.md
%% docs/working/experiments/campaigns/doe_2x7/README.md
\input{../scraps/experiments/02-experiments/factorial-doe/guide}
\input{../scraps/experiments/02-experiments/factorial-doe/workflow}
@@ -57,7 +57,7 @@
\input{../scraps/experiments/campaigns/shape_validation/README}
\chapter{Incompatible Configurations}
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/incompatible-configs.md
\input{../scraps/experiments/02-experiments/factorial-doe/incompatible-configs}
\chapter{Campaign Results — 90 Runs}
@@ -146,8 +146,8 @@
\part{Supplementary Campaigns}
\chapter{Heartbeat DoE}
%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/design.md
%% docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md
%% SOURCE: docs/working/archive/superseded/heartbeat-doe-design.md
%% docs/working/archive/superseded/heartbeat-doe-corrected-design.md
\input{../scraps/experiments/02-experiments/heartbeat-doe/design}
\input{../scraps/experiments/02-experiments/heartbeat-doe/corrected-design}
\input{../scraps/experiments/02-experiments/heartbeat-doe/implementation-summary}
docs/formal/scraps/architecture/03-architecture/adaptive-systems/loop-5-sketch.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/adaptive-systems/loop-5-sketch
%% SOURCE: docs/working/architecture/03-architecture/adaptive-systems/loop-5-sketch.md
%% SOURCE: docs/working/archive/superseded/loop-5-sketch.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/README.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/README
%% SOURCE: docs/working/architecture/03-architecture/hal/README.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/README.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/interfaces.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/interfaces
%% SOURCE: docs/working/architecture/03-architecture/hal/interfaces.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/interfaces.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/migration-plan.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/migration-plan
%% SOURCE: docs/working/architecture/03-architecture/hal/migration-plan.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/migration-plan.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/overview.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/overview
%% SOURCE: docs/working/architecture/03-architecture/hal/overview.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/overview.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/platform-implementations.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/platform-implementations
%% SOURCE: docs/working/architecture/03-architecture/hal/platform-implementations.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/platform-implementations.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/hal/starkernel-integration.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/hal/starkernel-integration
%% SOURCE: docs/working/architecture/03-architecture/hal/starkernel-integration.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/starkernel-integration.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-platform
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/heartbeat-system/implementation-plan.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/heartbeat-system/implementation-plan
%% SOURCE: docs/working/architecture/03-architecture/heartbeat-system/implementation-plan.md
%% SOURCE: docs/working/archive/superseded/heartbeat-rate-logging-plan.md
%% STATUS: HISTORICAL
%% FITS: dev-guide/ch-heartbeat
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/feedback-loops-analysis.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/feedback-loops-analysis
%% SOURCE: docs/working/architecture/03-architecture/physics-engine/feedback-loops-analysis.md
%% SOURCE: docs/working/archive/superseded/feedback-loops-analysis.md
%% STATUS: HISTORICAL
%% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/metrics-and-knobs.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/metrics-and-knobs
%% SOURCE: docs/working/architecture/03-architecture/physics-engine/metrics-and-knobs.md
%% SOURCE: docs/working/archive/dead/metrics-and-knobs.md
%% STATUS: WORKING
%% FITS: dev-guide/ch-physics, cookbook/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/physics-engine/steady-state-machine.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/physics-engine/steady-state-machine
%% SOURCE: docs/working/architecture/03-architecture/physics-engine/steady-state-machine.md
%% SOURCE: docs/working/archive/superseded/steady-state-machine.md
%% STATUS: CURRENT
%% FITS: dev-guide/ch-physics
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/03-architecture/word-acl/DESIGN.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/03-architecture/word-acl/DESIGN
%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
%% SOURCE: docs/reference/word-acl/DESIGN.md
%% STATUS: CURRENT
%% FITS: dev-guide/ch-acl, cookbook/ch-acl
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/architecture/getting-started/quick-start/factorial-doe.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: architecture/getting-started/quick-start/factorial-doe
%% SOURCE: docs/working/architecture/getting-started/quick-start/factorial-doe.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/quick-start.md
%% STATUS: CURRENT
%% FITS: cookbook/ch-doe
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/archive/DOCUMENTATION_AUDIT.tex
+1 -1
View File
@@ -36,7 +36,7 @@ The audit assigned priority as follows.
\begin{itemize}
\item Add missing \texttt{README} files to all numbered directories.
\item Update \texttt{CLAUDE.md} to reflect HAL and StarKernel vision.
\item Create \texttt{docs/03-architecture/README.md} as a system overview.
\item Create \texttt{docs/working/archive/superseded/2026-08-tripod/03-architecture-README.md} as a system overview.
\end{itemize}
\textbf{Medium priority:}
docs/formal/scraps/experiments/02-experiments/L8_WIRING_PLAN.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/L8_WIRING_PLAN
%% SOURCE: docs/working/experiments/02-experiments/L8_WIRING_PLAN.md
%% SOURCE: docs/working/archive/superseded/L8_WIRING_PLAN.md
%% STATUS: HISTORICAL
%% FITS: experiments/ch-l8
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/guide.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/guide
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/guide.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/guide.md
%% STATUS: CURRENT
%% FITS: experiments/ch-factorial, cookbook/ch-doe
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/incompatible-configs.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/incompatible-configs
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/incompatible-configs.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/incompatible-configs.md
%% STATUS: CURRENT
%% FITS: experiments/ch-factorial
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/index.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/index
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/index.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/index.md
%% STATUS: CURRENT
%% FITS: experiments/ch-factorial
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/factorial-doe/workflow.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/factorial-doe/workflow
%% SOURCE: docs/working/experiments/02-experiments/factorial-doe/workflow.md
%% SOURCE: docs/working/archive/superseded/factorial-doe/workflow.md
%% STATUS: CURRENT
%% FITS: experiments/ch-factorial, cookbook/ch-doe
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/heartbeat-doe/corrected-design.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/heartbeat-doe/corrected-design
%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/corrected-design.md
%% SOURCE: docs/working/archive/superseded/heartbeat-doe-corrected-design.md
%% STATUS: WORKING
%% FITS: experiments/ch-heartbeat
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/experiments/02-experiments/heartbeat-doe/design.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: experiments/02-experiments/heartbeat-doe/design
%% SOURCE: docs/working/experiments/02-experiments/heartbeat-doe/design.md
%% SOURCE: docs/working/archive/superseded/heartbeat-doe-design.md
%% STATUS: WORKING
%% FITS: experiments/ch-heartbeat
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION
%% SOURCE: docs/working/hardware/platform-integration/L4RE_DICTIONARY_ALLOCATION.adoc
%% SOURCE: docs/working/archive/dead/l4re/L4RE_DICTIONARY_ALLOCATION.adoc
%% STATUS: WORKING
%% FITS: dev-guide/ch-l4re
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/hardware/platform-integration/L4RE_INTEGRATION.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: hardware/platform-integration/L4RE_INTEGRATION
%% SOURCE: docs/working/hardware/platform-integration/L4RE_INTEGRATION.adoc
%% SOURCE: docs/working/archive/dead/l4re/L4RE_INTEGRATION.adoc
%% STATUS: WORKING
%% FITS: dev-guide/ch-l4re
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/hardware/platform-integration/l_4_re_blkio_endpoints.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: hardware/platform-integration/l_4_re_blkio_endpoints
%% SOURCE: docs/working/hardware/platform-integration/l_4_re_blkio_endpoints.adoc
%% SOURCE: docs/working/archive/dead/l4re/l_4_re_blkio_endpoints.adoc
%% STATUS: WORKING
%% FITS: dev-guide/ch-l4re
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/scraps/legal/README.tex
+1 -1
View File
@@ -40,7 +40,7 @@ They are deferred to a later, build-verified pass.
\toprule
Path & Description \\
\midrule
\texttt{docs/ontology.tex} / \texttt{.pdf} & Formal ontology source and compiled PDF; candidate for \texttt{formal/}. \\
\texttt{docs/working/papers/ontology.tex} / \texttt{.pdf} & Formal ontology source and compiled PDF; candidate for \texttt{formal/}. \\
\texttt{docs/ontology\_diagrams.dot} & Graphviz source for ontology diagrams. \\
\texttt{docs/fig\_*.png} / \texttt{.svg} & Shared figure assets referenced by ontology and system narrative LaTeX. \\
\bottomrule
docs/formal/scraps/papers/ONTOLOGY.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: papers/ONTOLOGY
%% SOURCE: docs/working/papers/ONTOLOGY.md
%% SOURCE: docs/reference/ONTOLOGY.md
%% STATUS: CURRENT
%% FITS: ssrn/ch-ontology, vol3-research/ch-ontology
%% EDITORIAL: lifted — prose rewritten to press voice; thermodynamic-as-metaphor framing preserved throughout
docs/formal/scraps/scratch/src/L4RE_INTEGRATION_TODO.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% SCRAP: scratch/src/L4RE_INTEGRATION_TODO
%% SOURCE: docs/working/scratch/src/L4RE_INTEGRATION_TODO.adoc
%% SOURCE: docs/working/archive/dead/l4re/L4RE_INTEGRATION_TODO.adoc
%% STATUS: HISTORICAL
%% FITS: dev-guide/ch-l4re
%% EDITORIAL: lifted — prose rewritten to press voice
docs/formal/ssrn/main.tex
+2 -2
View File
@@ -2,7 +2,7 @@
%% SOURCE: docs/working/papers/published/James_Steady-State_Convergence_Adaptive_Runtime.pdf
%% docs/working/papers/SSRN_companion/Math_Companion_SSRN.tex
%% docs/working/papers/FORMAL_CLAIM_TABLE.md
%% docs/working/papers/ONTOLOGY.md
%% docs/reference/ONTOLOGY.md
%% NOTE: The SSRN paper itself is a published PDF — it is NOT re-typeset here.
%% This volume collects the companion material: Math Companion (full LaTeX),
%% formal claim tables, ontology, and academic wording guidelines.
@@ -84,7 +84,7 @@ The canonical paper PDF is at:
\part{Ontology of Terms}
\chapter{Thermodynamic Metaphor Ontology}
%% SOURCE: docs/working/papers/ONTOLOGY.md
%% SOURCE: docs/reference/ONTOLOGY.md
%% NOTE: Thermodynamic terms are modeling tools, not physics claims.
%% Always introduce with domain qualifier: "using X as a proxy for Y, …"
\input{../scraps/papers/ONTOLOGY}
docs/formal/vol2-kernel/README.md
+1 -1
View File
@@ -22,7 +22,7 @@ Built via `make -C docs/formal vol2`; output lands at
## See also
- [`docs/lithosananke/README.md`](../../lithosananke/README.md) — the
- [`docs/working/archive/historical/2026-10-lithosananke-orientation.md`](../../lithosananke/README.md) — the
living kernel-branch documentation this volume draws from.
- [`docs/formal/README.md`](../README.md) — the three research volumes
this belongs to (with `vol1-vm-physics/` and `vol3-research/`).
docs/formal/vol2-kernel/ch03-acl-security.tex
+2 -2
View File
@@ -1,5 +1,5 @@
%% Vol II, Chapter 3 — ACL and Security Model
%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
%% SOURCE: docs/reference/word-acl/DESIGN.md
%% .claude/CLAUDE.md (Word-Level ACL System section)
%% capsules/ACL.4th, capsules/zuse.4th
@@ -19,7 +19,7 @@
\section{Two-Console Model}
\label{vol2:sec:acl:consoles}
%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
%% SOURCE: docs/reference/word-acl/DESIGN.md
%% TODO(bob): describe the two permanent console layers:
%% - emergency console (ok>) — fault handler active
%% - zuse console (zuse)ok>) — superuser authenticated
docs/formal/vol2-kernel/ch04-platform-support.tex
+2 -2
View File
@@ -1,6 +1,6 @@
%% Vol II, Chapter 4 — Platform Support
%% SOURCE: docs/working/scratch/src/platform-integration/ (multiple .adoc files)
%% docs/working/architecture/03-architecture/hal/ (HAL design — aspirational)
%% docs/working/archive/dead/hal-target-contract/ (HAL design — aspirational)
%% .claude/CLAUDE.md (Platform abstraction, build targets)
\chapter{Platform Support}
@@ -43,7 +43,7 @@
\section{Platform Abstraction Layer (HAL Target)}
\label{vol2:sec:platforms:hal}
%% SOURCE: docs/working/architecture/03-architecture/hal/overview.md
%% SOURCE: docs/working/archive/dead/hal-target-contract/overview.md
%% IMPORTANT: the hal_* API described in the hal/ doc family is the TARGET
%% design, not the current codebase. Current code uses sf_time_backend_t-style
%% naming. This section describes the planned migration.
docs/formal/vol3-research/ch06-ontology.tex
+1 -1
View File
@@ -1,5 +1,5 @@
%% Vol III, Chapter 6 — Ontology of Thermodynamic Terms
%% SOURCE: docs/working/papers/ONTOLOGY.md
%% SOURCE: docs/reference/ONTOLOGY.md
%% docs/working/papers/ONTOLOGY_README.md
\chapter{Ontology of Thermodynamic Terms}
docs/lithosananke/hal/README.md
-84
View File
@@ -1,84 +0,0 @@
# LithosAnanke Hardware Abstraction Layer (HAL)
This directory contains HAL documentation for the LithosAnanke kernel branch.
> **HISTORICAL — L4Re/Fiasco.OC**: L4Re references throughout this directory's docs describe a target that was a supported platform through mid-2026. L4Re support has since been removed as an active target — `src/platform/l4re/time.c` and related `#ifdef __l4__` code are retained for reference but no longer wired into any build.
---
## Document Overview
| Document | Purpose |
|----------|---------|
| [overview.md](overview.md) | HAL architecture and design principles |
| [interfaces.md](interfaces.md) | HAL function specifications and contracts |
| [lithosananke-integration.md](lithosananke-integration.md) | Kernel-specific HAL implementation |
| [platform-implementations.md](platform-implementations.md) | How to implement HAL for a platform |
| [migration-plan.md](migration-plan.md) | Migration from hosted to kernel |
---
## Reading Order
1. **overview.md** — Understand why HAL exists
2. **interfaces.md** — Learn the contracts
3. **lithosananke-integration.md** — See kernel implementation
4. **platform-implementations.md** — Reference implementations
---
## HAL Subsystems
```
hal_time.h — Monotonic time, timers
hal_interrupt.h — IRQ management, ISR registration
hal_memory.h — Allocation, page mapping
hal_console.h — Character I/O (UART, framebuffer)
hal_cpu.h — CPU ID, relax/halt, SMP
hal_panic.h — Fatal error handling
```
---
## Current State (lithosananke branch)
The HAL is **partially implemented** in LithosAnanke:
| Subsystem | Status | Location |
|-----------|--------|----------|
| Time | Implemented | `src/starkernel/arch/amd64/timer.c` |
| Interrupts | Implemented | `src/starkernel/arch/amd64/interrupts.c` |
| Memory | Implemented | `src/starkernel/memory/` |
| Console | Implemented | `src/starkernel/hal/console.c` |
| CPU | Partial | `src/starkernel/arch/amd64/apic.c` |
| Panic | Implemented | `src/starkernel/hal/hal.c` |
---
## Relationship to Hosted StarForth
The HAL enables the same VM code to run on:
- **Linux** (hosted, POSIX)
- **LithosAnanke** (freestanding, bare metal)
- **L4Re** (microkernel, optional)
```
┌─────────────────────────────────────┐
│ StarForth VM + Physics Subsystems │
│ (platform-agnostic) │
├─────────────────────────────────────┤
│ HAL Layer │
├──────────┬──────────┬───────────────┤
│ Linux │ L4Re │ LithosAnanke │
│ (POSIX) │ (micro) │ (kernel) │
└──────────┴──────────┴───────────────┘
```
---
## See Also
- [../README.md](../README.md) — LithosAnanke overview
- [../ROADMAP.md](../ROADMAP.md) — Milestone roadmap
- [../M7.1.md](../M7.1.md) — Init Capsule Architecture
docs/lithosananke/hal/interfaces.md
-703
View File
@@ -1,703 +0,0 @@
# HAL Interface Specifications
## Overview
This document defines the **contract** for each HAL subsystem. These interfaces are platform-agnostic and must be implemented identically (semantically) on all platforms.
> **HISTORICAL — L4Re/Fiasco.OC**: L4Re references below describe a target that was a supported platform through mid-2026. L4Re support has since been removed as an active target — `src/platform/l4re/time.c` and related `#ifdef __l4__` code are retained for reference but no longer wired into any build.
**Critical:** These are not optional "convenience wrappers"—they are the **only** way VM and physics code access platform resources.
---
## 1. Time & Timers (`include/hal/hal_time.h`)
### Purpose
Provide monotonic time, periodic/oneshot timers, and calibration for physics subsystems.
### Interface
```c
#ifndef HAL_TIME_H
#define HAL_TIME_H
#include <stdint.h>
/**
* Initialize time subsystem.
* Must be called before any other hal_time_* functions.
*
* Responsibilities:
* - Calibrate high-resolution timer (TSC, HPET, etc.)
* - Validate monotonicity
* - Set up timer interrupt sources (if needed)
*
* Error handling:
* - hal_panic() if no suitable time source available
* - hal_panic() if calibration fails
*/
void hal_time_init(void);
/**
* Get current monotonic time in nanoseconds.
*
* Guarantees:
* - MUST be monotonic (never goes backward)
* - SHOULD have sub-microsecond resolution
* - MUST be callable from interrupt context (ISR-safe)
* - MUST be callable concurrently (thread-safe)
*
* Performance:
* - Target: < 50 cycles on x86_64
* - Acceptable: < 200 cycles
*
* Returns:
* - Nanoseconds since arbitrary epoch (typically boot time)
*/
uint64_t hal_time_now_ns(void);
/**
* Busy-wait delay for specified nanoseconds.
* Used for calibration and short delays.
*
* Guarantees:
* - MUST delay for at least `ns` nanoseconds
* - MAY delay longer (but not by more than 10%)
* - MUST be callable from interrupt context
*
* Parameters:
* - ns: Nanoseconds to delay (0 = no delay)
*
* Notes:
* - This is a busy-wait, not a sleep
* - For delays > 1ms, prefer hal_timer_oneshot()
*/
void hal_time_delay_ns(uint64_t ns);
/**
* Timer callback function type.
*
* Parameters:
* - ctx: User-provided context pointer
*
* Context:
* - MAY be called from interrupt context (ISR)
* - MUST NOT block or sleep
* - MUST complete quickly (< 10µs target)
*/
typedef void (*hal_timer_callback_t)(void *ctx);
/**
* Schedule a oneshot timer to fire after specified nanoseconds.
*
* Guarantees:
* - Callback will fire at least `ns` nanoseconds in the future
* - MAY fire up to 10% late (jitter allowed)
* - Callback runs in interrupt context (ISR)
*
* Parameters:
* - ns: Nanoseconds until callback fires (0 = ASAP)
* - callback: Function to call when timer fires
* - ctx: User context passed to callback
*
* Error handling:
* - Returns 0 on success
* - Returns -1 if timer resources exhausted
*
* Concurrency:
* - Thread-safe (can be called from multiple threads)
* - NOT reentrant from same timer callback
*/
int hal_timer_oneshot(uint64_t ns, hal_timer_callback_t callback, void *ctx);
/**
* Schedule a periodic timer to fire every `period_ns` nanoseconds.
*
* Guarantees:
* - Callback will fire repeatedly at ~period_ns intervals
* - Jitter: < 10% of period (target: < 1%)
* - Callback runs in interrupt context (ISR)
* - Timer continues until hal_timer_cancel() called
*
* Parameters:
* - period_ns: Period in nanoseconds (minimum: 1000ns = 1µs)
* - callback: Function to call on each period
* - ctx: User context passed to callback
*
* Returns:
* - Timer ID (> 0) on success
* - -1 if timer resources exhausted
* - -2 if period_ns < minimum
*
* Notes:
* - This is the PRIMARY mechanism for heartbeat ISR
* - Platform MUST minimize jitter for experimental validity
*/
int hal_timer_periodic(uint64_t period_ns, hal_timer_callback_t callback, void *ctx);
/**
* Cancel a periodic timer.
*
* Parameters:
* - timer_id: ID returned from hal_timer_periodic()
*
* Guarantees:
* - Callback will not fire after this call returns
* - Safe to call even if timer already fired or was cancelled
*
* Returns:
* - 0 on success
* - -1 if timer_id invalid
*/
int hal_timer_cancel(int timer_id);
/**
* Get timer frequency in Hz.
* Used for diagnostics and experiment metadata.
*
* Returns:
* - Frequency of underlying time source (e.g., TSC frequency)
* - 0 if frequency is variable or unknown
*/
uint64_t hal_time_frequency_hz(void);
#endif /* HAL_TIME_H */
```
### Platform Implementation Notes
**Linux (`platform/linux/hal_time.c`):**
- `hal_time_now_ns()` → `clock_gettime(CLOCK_MONOTONIC)`
- `hal_timer_periodic()` → `timer_create()` with `SIGRTMIN` + signal handler
- Challenge: Signal-based timers have ~1-10µs latency jitter
**L4Re (`platform/l4re/hal_time.c`):**
- `hal_time_now_ns()` → `l4re_kip_clock()`
- `hal_timer_periodic()` → L4Re IPC-based timer + IRQ object
- Challenge: IPC overhead, but lower jitter than Linux
**Kernel (`platform/kernel/hal_time.c`):**
- `hal_time_now_ns()` → `rdtsc()` calibrated against HPET
- `hal_timer_periodic()` → APIC timer interrupt
- Challenge: TSC drift on old hardware, calibration complexity
---
## 2. Interrupts (`include/hal/hal_interrupt.h`)
### Purpose
Enable/disable interrupts, register ISRs, query interrupt context.
### Interface
```c
#ifndef HAL_INTERRUPT_H
#define HAL_INTERRUPT_H
#include <stdint.h>
/**
* Initialize interrupt subsystem.
* Must be called before any other hal_interrupt_* functions.
*
* Responsibilities:
* - Set up interrupt controller (PIC/APIC on x86_64)
* - Initialize IDT (on kernel platforms)
* - Prepare for ISR registration
*
* Error handling:
* - hal_panic() if interrupt controller unavailable
*/
void hal_interrupt_init(void);
/**
* Enable interrupts globally.
*
* Guarantees:
* - Interrupts will be delivered after this call
* - Safe to call multiple times (idempotent)
* - NOT callable from interrupt context
*
* Notes:
* - On x86_64 kernel: sti
* - On Linux: no-op (interrupts always enabled)
*/
void hal_irq_enable(void);
/**
* Disable interrupts globally.
*
* Guarantees:
* - Interrupts will NOT be delivered after this call
* - Safe to call multiple times (idempotent)
* - Callable from interrupt context
*
* Returns:
* - Previous interrupt state (for hal_irq_restore)
*
* Notes:
* - On x86_64 kernel: cli
* - On Linux: no-op (interrupts always enabled)
*/
unsigned long hal_irq_disable(void);
/**
* Restore previous interrupt state.
*
* Parameters:
* - state: Value returned from hal_irq_disable()
*
* Use case:
* unsigned long flags = hal_irq_disable();
* // critical section
* hal_irq_restore(flags);
*/
void hal_irq_restore(unsigned long state);
/**
* Interrupt service routine function type.
*
* Parameters:
* - irq: IRQ number that triggered
* - ctx: User-provided context pointer
*
* Context:
* - ALWAYS called from interrupt context
* - MUST NOT block or sleep
* - MUST complete quickly (< 10µs target, < 100µs acceptable)
* - MUST NOT call non-ISR-safe HAL functions
*/
typedef void (*hal_isr_t)(unsigned int irq, void *ctx);
/**
* Register an interrupt service routine.
*
* Parameters:
* - irq: IRQ number to register (platform-specific numbering)
* - isr: Function to call when IRQ fires
* - ctx: User context passed to ISR
*
* Guarantees:
* - ISR will be called when IRQ fires
* - Only one ISR per IRQ (replaces previous if registered)
* - ISR runs with interrupts disabled (not reentrant)
*
* Returns:
* - 0 on success
* - -1 if IRQ number invalid
* - -2 if ISR registration failed
*
* Notes:
* - Used by hal_timer_periodic() internally
* - Used by device drivers for hardware IRQs
*/
int hal_irq_register(unsigned int irq, hal_isr_t isr, void *ctx);
/**
* Unregister an interrupt service routine.
*
* Parameters:
* - irq: IRQ number to unregister
*
* Returns:
* - 0 on success
* - -1 if IRQ was not registered
*/
int hal_irq_unregister(unsigned int irq);
/**
* Check if currently executing in interrupt context.
*
* Returns:
* - 1 if in interrupt context (ISR)
* - 0 if in normal execution context
*
* Use case:
* - Validate ISR-only functions (e.g., heartbeat sampling)
* - Conditional behavior (ISR vs. normal path)
*
* Performance:
* - MUST be fast (< 10 cycles)
* - Often implemented as checking a per-CPU flag
*/
int hal_in_interrupt_context(void);
#endif /* HAL_INTERRUPT_H */
```
### Platform Implementation Notes
**Linux:**
- `hal_irq_enable/disable()` → no-op (can't disable signals)
- `hal_irq_register()` → `sigaction()` + signal handler
- `hal_in_interrupt_context()` → thread-local flag set by signal handler
**Kernel:**
- `hal_irq_enable/disable()` → `sti`/`cli` (x86_64)
- `hal_irq_register()` → IDT entry + APIC configuration
- `hal_in_interrupt_context()` → check per-CPU interrupt nesting count
---
## 3. Memory (`include/hal/hal_memory.h`)
### Purpose
Allocate/free memory, map pages, manage heap.
### Interface
```c
#ifndef HAL_MEMORY_H
#define HAL_MEMORY_H
#include <stddef.h>
#include <stdint.h>
/**
* Initialize memory subsystem.
* Must be called before any other hal_mem_* functions.
*
* Responsibilities:
* - Set up heap allocator
* - Initialize page tables (kernel platforms)
* - Parse memory map (kernel platforms)
*
* Error handling:
* - hal_panic() if insufficient memory
*/
void hal_mem_init(void);
/**
* Allocate memory from heap.
*
* Parameters:
* - size: Bytes to allocate (0 = returns NULL)
*
* Guarantees:
* - Returns aligned pointer (at least 8-byte aligned)
* - Memory is zero-initialized
* - Thread-safe (can be called concurrently)
* - NOT callable from interrupt context
*
* Returns:
* - Pointer to allocated memory
* - NULL if allocation failed
*
* Notes:
* - On Linux: wrapper around malloc()
* - On kernel: custom heap allocator (kmalloc)
*/
void *hal_mem_alloc(size_t size);
/**
* Free memory allocated by hal_mem_alloc().
*
* Parameters:
* - ptr: Pointer returned from hal_mem_alloc() (NULL = no-op)
*
* Guarantees:
* - Thread-safe
* - NOT callable from interrupt context
* - Safe to call with NULL
*/
void hal_mem_free(void *ptr);
/**
* Allocate contiguous physical pages.
* Used for DMA buffers, page tables, large allocations.
*
* Parameters:
* - count: Number of pages to allocate (page size is platform-specific)
*
* Returns:
* - Physical address of first page
* - 0 if allocation failed
*
* Notes:
* - Pages are NOT mapped into virtual address space
* - Caller must call hal_mem_map() to access
* - On Linux: may use mmap() with MAP_ANONYMOUS
* - On kernel: physical memory manager (PMM)
*/
uint64_t hal_mem_alloc_pages(size_t count);
/**
* Free physical pages allocated by hal_mem_alloc_pages().
*
* Parameters:
* - paddr: Physical address returned from hal_mem_alloc_pages()
* - count: Number of pages to free
*/
void hal_mem_free_pages(uint64_t paddr, size_t count);
/**
* Map physical memory into virtual address space.
*
* Parameters:
* - vaddr: Virtual address to map (must be page-aligned)
* - paddr: Physical address to map (must be page-aligned)
* - size: Size in bytes (must be page-multiple)
* - flags: Mapping flags (HAL_MEM_*)
*
* Returns:
* - 0 on success
* - -1 if mapping failed
*
* Flags:
* - HAL_MEM_READ: Readable
* - HAL_MEM_WRITE: Writable
* - HAL_MEM_EXEC: Executable
* - HAL_MEM_NOCACHE: Uncached (for MMIO)
*
* Notes:
* - On Linux: no-op (identity mapping assumed)
* - On kernel: update page tables, flush TLB
*/
int hal_mem_map(uint64_t vaddr, uint64_t paddr, size_t size, unsigned int flags);
/* Mapping flags */
#define HAL_MEM_READ (1 << 0)
#define HAL_MEM_WRITE (1 << 1)
#define HAL_MEM_EXEC (1 << 2)
#define HAL_MEM_NOCACHE (1 << 3)
/**
* Get page size in bytes.
*
* Returns:
* - Page size (typically 4096 on x86_64)
*/
size_t hal_mem_page_size(void);
#endif /* HAL_MEMORY_H */
```
---
## 4. Console (`include/hal/hal_console.h`)
### Purpose
Character I/O for REPL and diagnostics.
### Interface
```c
#ifndef HAL_CONSOLE_H
#define HAL_CONSOLE_H
/**
* Initialize console subsystem.
* Must be called before any other hal_console_* functions.
*
* Responsibilities:
* - Initialize UART (kernel platforms)
* - Set up framebuffer (if available)
* - Configure terminal settings (Linux)
*
* Error handling:
* - hal_panic() if no console available
*/
void hal_console_init(void);
/**
* Write a single character to console.
*
* Parameters:
* - c: Character to write
*
* Guarantees:
* - Character will be visible on console
* - Blocking (waits if output buffer full)
* - Callable from interrupt context (for panic messages)
*
* Performance:
* - May be slow (UART is ~1µs per char)
* - Buffering recommended for bulk output
*/
void hal_console_putc(char c);
/**
* Write a null-terminated string to console.
*
* Parameters:
* - s: String to write (NULL = no-op)
*
* Notes:
* - Convenience wrapper around hal_console_putc()
*/
void hal_console_puts(const char *s);
/**
* Read a single character from console.
*
* Guarantees:
* - Blocking (waits until character available)
* - NOT callable from interrupt context
*
* Returns:
* - Character read (0-255)
* - -1 on error or EOF
*/
int hal_console_getc(void);
/**
* Check if input is available (non-blocking).
*
* Returns:
* - 1 if character available (hal_console_getc() will not block)
* - 0 if no character available
*/
int hal_console_has_input(void);
#endif /* HAL_CONSOLE_H */
```
---
## 5. CPU (`include/hal/hal_cpu.h`)
### Purpose
CPU identification, relax/halt, SMP coordination.
### Interface
```c
#ifndef HAL_CPU_H
#define HAL_CPU_H
#include <stdint.h>
/**
* Initialize CPU subsystem.
* Must be called before any other hal_cpu_* functions.
*
* Responsibilities:
* - Detect CPU features (SSE, AVX, etc.)
* - Set up per-CPU storage
* - Bring up secondary CPUs (SMP)
*
* Error handling:
* - hal_panic() if CPU unsupported
*/
void hal_cpu_init(void);
/**
* Get current CPU ID.
*
* Returns:
* - CPU ID (0 = boot processor, 1+ = application processors)
*
* Guarantees:
* - Callable from interrupt context
* - Fast (< 10 cycles)
*
* Notes:
* - On x86_64 kernel: APIC ID
* - On Linux: thread ID (not true CPU ID)
*/
unsigned int hal_cpu_id(void);
/**
* Hint to CPU to relax (pause in spin-wait loop).
*
* Guarantees:
* - Callable from interrupt context
* - No functional effect (pure performance hint)
*
* Notes:
* - On x86_64: pause instruction
* - On ARM: yield instruction
* - On Linux: sched_yield()
*/
void hal_cpu_relax(void);
/**
* Halt CPU until next interrupt.
*
* Guarantees:
* - CPU enters low-power state
* - Wakes on next interrupt
* - NOT callable from interrupt context
*
* Notes:
* - On x86_64 kernel: hlt instruction
* - On Linux: select() or nanosleep()
*/
void hal_cpu_halt(void);
/**
* Get number of CPUs in system.
*
* Returns:
* - Number of CPUs (1 = single-core, 2+ = multi-core)
*/
unsigned int hal_cpu_count(void);
#endif /* HAL_CPU_H */
```
---
## 6. Panic/Error Handling (`include/hal/hal_panic.h`)
### Purpose
Fatal error handling (system halt or abort).
### Interface
```c
#ifndef HAL_PANIC_H
#define HAL_PANIC_H
/**
* Fatal error: print message and halt system.
*
* Parameters:
* - msg: Error message (NULL = "panic")
*
* Guarantees:
* - NEVER returns
* - Message printed to console (if available)
* - System halted (kernel) or abort() (hosted)
* - Callable from interrupt context
*
* Notes:
* - Use for unrecoverable errors only
* - On kernel: disable interrupts + hlt loop
* - On Linux: fprintf(stderr) + abort()
*/
void hal_panic(const char *msg) __attribute__((noreturn));
#endif /* HAL_PANIC_H */
```
---
## Interface Summary
| Subsystem | Key Functions | ISR-Safe | Thread-Safe |
|-----------|---------------|----------|-------------|
| **Time** | `hal_time_now_ns()` | ✅ | ✅ |
| | `hal_timer_periodic()` | ❌ | ✅ |
| **Interrupt** | `hal_in_interrupt_context()` | ✅ | ✅ |
| | `hal_irq_disable()` | ✅ | ✅ |
| **Memory** | `hal_mem_alloc()` | ❌ | ✅ |
| | `hal_mem_map()` | ❌ | ⚠️ |
| **Console** | `hal_console_putc()` | ✅ | ⚠️ |
| | `hal_console_getc()` | ❌ | ❌ |
| **CPU** | `hal_cpu_id()` | ✅ | ✅ |
| | `hal_cpu_relax()` | ✅ | ✅ |
**Legend:**
- ✅ = Safe
- ❌ = Unsafe
- ⚠️ = Platform-dependent
---
## Next Steps
See companion documentation:
- `platform-implementations.md` - How to implement HAL for a platform
- `migration-plan.md` - Refactoring existing code to use HAL
- `lithosananke-integration.md` - LithosAnanke-specific HAL implementation

Some files were not shown because too many files have changed in this diff Show More