From 2957be86e593dee871fd5e0c106b3a1bd837ba0b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 14:49:40 +0000 Subject: [PATCH] ABI: one train per capsule -- an engine of assembled .f18, its named blobs as rolling stock (Captain Bob) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/v4.0.0/ABI.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/v4.0.0/ABI.md b/docs/v4.0.0/ABI.md index 45cecfe0..bf78f43a 100644 --- a/docs/v4.0.0/ABI.md +++ b/docs/v4.0.0/ABI.md @@ -15,8 +15,9 @@ its own. | Term | Meaning | |---|---| | **Word** | The unit of interface and access control (ADR §1). It has a name, an entry point, a stack effect and its ACL fields. | -| **Capsule** | The unit of packaging, distribution and deployment (ADR §1). It is content-addressed, so its ID is its hash, and it is signed, as now (`kernel/include/starkernel/capsule.h`). It carries source (`.4th`, `.f18`), an artifact, or both. | -| **Artifact** | A compiled F18 unit: code cells, and the records of §4 that make them placeable and checkable. It travels inside a capsule. | +| **Capsule: a train** | The unit of packaging, distribution and deployment (ADR §1). It is content-addressed, so its ID is its hash, and it is signed, as now (`kernel/include/starkernel/capsule.h`). **Ruled 2026-11-19, "One train per capsule":** each capsule is a train. Its *engine* is its `.f18` code, assembled by the host tool into one artifact. Its *rolling stock* is the named blobs coupled behind the engine: `.4th` source, data, and whatever else it carries, each with its own identity and provenance. A system is many trains; the nucleus is one of them. | +| **Artifact: the engine** | A train's compiled F18 unit: code cells, and the records of §4 that make them placeable and checkable. It is assembled from all of that capsule's `.f18` files. | +| **Rolling stock** | The named blobs behind an engine (MACHINE.md §1's trailer). The engine's code is what acts on them: the ROM's types, `.f18` assembled and `.4th` handed a line at a time, now carried by each train. | | **Identity** | Ruling 4: a word's identity is (the hash of the capsule that defines it, the word's name). Addresses, word IDs and places are local resolution only. | | **Loader** | Whoever places an artifact in a node. As today, that is the node itself, through words like `CAPSULE-INCLUDE`, or the kernel at boot. No central linker (ADR §6). | @@ -125,6 +126,10 @@ is verified (ADR §5); compatibility is checked against the old artifact's recor - The ACL's check at call, and the word accounts: an artifact's words are words like any other. - Messages between nodes. +**Captain Bob's image, 2026-11-19:** "the .f18 assembler assembles all .f18 files it finds. Now here's a +thought. That 'assembled' code can be the 'engine' for a train of named blobs as metaphorically rolling +stock." Ruled "One train per capsule" (§1). + ## 9. Open, for ruling one at a time 1. ~~Where artifacts come from~~ **Ruled 2026-11-19: "A host tool".** A C tool beside `mkcapsule` compiles @@ -138,8 +143,9 @@ is verified (ADR §5); compatibility is checked against the old artifact's recor - **There is no declaration in the source.** The host tool computes each exported word's stack effect from its compiled code, by static analysis of the F18 opcodes, and records it in the artifact. The proofs check it. Comments stay comments. - - **Open within it:** a word whose effect depends on its data (a loop, a branch that leaves different - depths, `EXECUTE`) has no fixed count. What the tool records for such a word is a question of its own. + - **Open within it (2c):** a word whose effect depends on its data (a loop, a branch that leaves + different depths, `EXECUTE`) has no fixed count. What the tool records for such a word is a question + of its own, asked again now that each capsule is a train. 3. **What a capsule carries:** an artifact alone, or the artifact and its source (provenance, ADR §3.1)? 4. **Imports by capsule hash:** a hash pins one exact build. Is an import of an older build of the same capsule a mismatch, or is the name of the capsule enough with the stack effect checked?