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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
Claude
2026-11-19 14:49:40 +00:00
parent d46ca3d174
commit 2957be86e5
+10 -4
View File
@@ -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?