Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
197 lines
13 KiB
Markdown
197 lines
13 KiB
Markdown
# The F18 ABI -- draft contract, for ruling
|
||
|
||
Written 2026-11-19. Step 1 of `ADR-2026-11-19-F18-ARTIFACTS.md` §7: "Define and document the minimal ABI
|
||
contract". It builds on the rulings in `plans/2026-11-19-f18-artifacts.md`:
|
||
1. compiled artifacts are allowed beside the ROM;
|
||
2. Hermes is the messaging role;
|
||
3. Artemis owns persistent memory;
|
||
4. a word's identity is its capsule plus its name.
|
||
|
||
**Nothing here is built.** The choices left open are numbered in §9, and each will be put to Captain Bob on
|
||
its own.
|
||
|
||
## 1. Terms
|
||
|
||
| 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: 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). |
|
||
|
||
## 2. The hardware contract (unchanged; kept apart, ADR §3.2)
|
||
|
||
The engine's contract is what it is today, and the ABI does not change it:
|
||
- **Instruction words** of six slots (`v4/include/v4/iword.h`). A branch (`jump`, `call`, `next`, `if`,
|
||
`-if`) carries its target in the bits to the right of its slot, page-relative, with a reach of 27, 22, 17
|
||
or 12 bits.
|
||
- **The return stack and the data stack** are rings, with their depths set by the build (`V4_DATA_RING`,
|
||
`V4_RET_RING`). A call pushes its return address.
|
||
- **Ports and messages** between nodes, as MESH.md has them. The ABI adds nothing between nodes: "inter-core
|
||
communication shall continue to use the established message architecture" (ADR §3.2).
|
||
- **The call hook** (2026-11-19, `exec.h`) may redirect a call. The ACL uses it now; §6 may use it.
|
||
|
||
**What this means for artifacts:** compiled code holds addresses in its branch fields. An artifact placed
|
||
anywhere but where it was compiled needs those fields fixed (§5).
|
||
|
||
## 3. The word contract
|
||
|
||
**The entry** is as `dict.f18` has it today:
|
||
|
||
| Cell | Holds |
|
||
|---|---|
|
||
| `xt - 4` | the word ID, local |
|
||
| `xt - 3` | the flags: 1 immediate, 2 hidden, 4 data, 8 in-line, 16 compile-only, 128 deferred, plus the ACL fields (bit 5 denied, bit 6 pinned, bits 8–15 the mode, bits 16–31 the TTL) |
|
||
| `xt - 2` | the name |
|
||
| `xt - 1` | the link |
|
||
| `xt` | the code |
|
||
|
||
**What the ABI adds is recorded, not run.** Each exported word has:
|
||
- **its stack effect:** how many cells it takes and leaves on each stack. This is the "stack effects" of
|
||
ADR §3.2. It is derived by the host tool from the compiled code (choice 2), checked when the artifact is
|
||
placed and in the proofs, never at run time.
|
||
- **its capabilities:** the kernel requests it may make (`KERNEL-WORD` numbers) and whether it touches ports.
|
||
- **its ACL defaults:** pinned or not, and its mode. They are applied at placement, through the same fields.
|
||
|
||
**The calling convention:** a call with a return address on the return stack, as now. A word returns with
|
||
`;`. Arguments and results travel on the data stack only, in the declared counts. There is nothing else.
|
||
|
||
## 4. The artifact
|
||
|
||
All of it is in cells, so an F18 node can read it.
|
||
|
||
| Record | Holds |
|
||
|---|---|
|
||
| **Header** | a magic number; the ABI version; the cell width (32 or 64); the record counts |
|
||
| **Provenance** (ADR §3.1) | the source capsule's hash; the compiler's identity (the host tool's hash, choice 1); the build configuration's hash (the knobs, `V4_NODE_WORDS`, the rings); the target |
|
||
| **Exports** | for each word: its name, its entry's offset in the code, its flags, its declared stack effect, its capabilities |
|
||
| **Imports** | for each word used from another capsule: (that capsule's hash, the name), and the stack effect it is expected to have |
|
||
| **Relocations** | every cell of the code whose branch field holds an address, with how to fix it: internal (add the base), or import *k* |
|
||
| **Code** | the compiled cells, as if placed at address 0 |
|
||
| **Verification** | the identity of the proof that covers this exact artifact, and the assumptions it holds under (ADR §5), or none |
|
||
|
||
**Integrity and authorship** are the capsule's: its content hash and its Ed25519 signature, as now. The
|
||
artifact repeats neither, and, as ADR §5 says, a hash is not correctness.
|
||
|
||
## 5. Placement: resolution without a linker
|
||
|
||
A loader places an artifact in one pass, in order:
|
||
1. **Check:**
|
||
- the header is one this ABI version and cell width take;
|
||
- the capsule's hash and signature check, as `CAPSULE-OPEN` already does;
|
||
- every import's capsule is present in this node, and the imported word is exported by it with the
|
||
stack effect expected. **Fail closed:** if any check fails, nothing is placed.
|
||
2. **Place:** the code cells are copied to the node's dictionary space at its `HERE`, the base.
|
||
3. **Fix:** each relocation's branch field is patched, adding the base, or putting in the import's
|
||
resolved address. A field whose patched address does not fit its slot's reach is refused (fail
|
||
closed). Patching happens at placement only, once, with no lazy binding and no later resolution.
|
||
4. **Enter:** an entry is made for each export, as `(HEADER)` makes one, and the kernel is told
|
||
(`(WORD-DEFINED)`). The word accounts, the ACL fields and the defaults of §3 apply from here.
|
||
|
||
This is the work FORTH's compiler already does when it compiles a reference to a word. It is done here
|
||
from records, not from source. It is not dynamic linking in the ADR's sense: there are no shared libraries,
|
||
no lazy binding, no global address space and no linker running beside the program.
|
||
|
||
## 6. Activation and retirement (ADR §4)
|
||
|
||
**A replacement** is a newer capsule exporting a word of the same name. Its identity differs, because its
|
||
capsule hash differs. Activation must make the code that calls the old word reach the new one. The call
|
||
sites compiled into other definitions hold the old address (§2). Choice 5 is how they reach it.
|
||
|
||
**A safe boundary** is a heartbeat at which no node is inside the old word: no return address into it is
|
||
on any return stack, and no message for it is waiting. Choice 6 is how that is known.
|
||
|
||
**Retirement:** the old code is freed only when nothing can reach it. Until then both versions coexist
|
||
(ADR §4).
|
||
|
||
**Rollback** is activating the old one again, as long as it is not retired. Artemis keeps the staged and
|
||
recovery copies (ruling 3).
|
||
|
||
## 7. Compatibility
|
||
|
||
**A replacement is compatible** when, for every word the old artifact exported:
|
||
- the new one exports a word of the same name;
|
||
- with the same stack effect;
|
||
- needing no capability the old did not.
|
||
|
||
Anything else is incompatible, and activation is refused. A verified artifact is not compatible because it
|
||
is verified (ADR §5); compatibility is checked against the old artifact's records.
|
||
|
||
## 8. What stays as it is
|
||
|
||
- POST, the protocol, and CI's gates (ADR §7).
|
||
- Source capsules and the boot as it is: the ROM still assembles the system at boot (ruling 1).
|
||
- 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).
|
||
|
||
**The rail yard: the SDK and CI's model** (Captain Bob, 2026-11-19, recorded as given; nothing built):
|
||
> "When we build the SDK, we can naturally think of a railroad yard for staging outgoing artifact capsule
|
||
> 'trains' from first order preexisting 'cars' prior to writing new ones.. That would be the model and on
|
||
> the CI side we can use messaging as semaphores in our staging yard with inbound and outbound trains and
|
||
> the artifacts are the persistent part. Signed, sealed and versioned."
|
||
|
||
Read here as:
|
||
- **The yard stages trains.** An outgoing train is made up first from cars that already exist, which are
|
||
first-order and already built. New cars are written only for what is missing.
|
||
- **In CI, messages are the semaphores.** They signal inbound and outbound trains through the yard: what
|
||
may move, and when.
|
||
- **What persists is the artifacts:** signed, sealed and versioned. The yard's moves are transient.
|
||
|
||
It ties in `(-`, the build marker that asks CI to clear a block for the next image (`plans/2026-11-18-
|
||
capsule-blocks.md` §5), and Artemis keeping what is kept (ruling 3).
|
||
|
||
## 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
|
||
`.f18` to artifacts on the build machine. It is a second assembler beside the ROM's, so the two must
|
||
agree: the tool's output is checked against what the ROM assembles from the same source, cell for cell,
|
||
in the build and in CI. The compiler's identity in the provenance record is the tool's own hash.
|
||
2. ~~The stack-effect declaration~~ **Ruled 2026-11-19: "Derived by the tool".**
|
||
- A first answer, "the ( -- ) comment, strict", was withdrawn the same day. Captain Bob: "I think I may
|
||
have made a bad assumption. I had the idea of that after (- was aliased to ( is for SDK special. We're
|
||
working on something more fundamental."
|
||
- **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.
|
||
- **2c, ruled 2026-11-19: "Refused as an export".** A word whose effect depends on its data (a loop
|
||
leaving a count of values, branches that leave different depths, `EXECUTE`, a `DEFER`red word) has no
|
||
fixed count. It cannot be exported by an engine: it stays internal to its train, or is restructured.
|
||
Every export has a fixed effect, which the tool derives and the build fails without.
|
||
3. ~~What a capsule carries~~ **Ruled 2026-11-19: "No, by reference".** A train's engine carries only the
|
||
hash of the `.f18` source it was assembled from, in its provenance record. The source stays in the
|
||
repository and in its own capsule. To check an engine against its source, the source is fetched by
|
||
that hash.
|
||
4. ~~Imports by capsule hash~~ **Ruled 2026-11-19: "Exact hash".** An import names the exact build of
|
||
the train it imports from: (its capsule hash, the word's name). If that train is rebuilt or updated,
|
||
its hash changes, so its importers are rebuilt too, and a live update replaces the whole dependent set
|
||
of trains together. Placement refuses an import whose hash is not present.
|
||
5. ~~How callers reach a replacement~~ **Ruled 2026-11-19: "Jump at the old entry".** At activation, each
|
||
replaced word's first code cell, at its xt, is overwritten with a `jump` to the new word: one cell per
|
||
word, and every caller, compiled at run time or not, follows at once. The old code stays in place,
|
||
unreachable but for that cell, until it is retired. The new word must be within the jump's reach from
|
||
the old entry (27 bits in slot 0, which covers a node's memory), or activation is refused.
|
||
6. ~~The safe boundary~~ **Ruled 2026-11-19: "Scan at a heartbeat".** At a heartbeat tick the kernel
|
||
scans every node's P and return stack for an address inside the old words' code. When none is there, it
|
||
writes all of a set's jumps in that one tick. While some are there, it tries again on later ticks. A
|
||
message waiting for an old word is not code on a stack and does not hold the set back: the word it
|
||
reaches is the new one.
|
||
7. ~~Proofs first~~ **Ruled 2026-11-19: "Safe activation first".** The first Isabelle/HOL property:
|
||
- the jump at each old entry is written only at a tick when no node's P or return stack holds an address
|
||
inside the old code (choice 6);
|
||
- after it, every call to an old word, from any caller, reaches the new word.
|
||
|
||
Placement's checks, compatibility and the soundness of the derived stack effects come after.
|
||
|
||
## 10. Status
|
||
|
||
All seven choices are ruled, plus 2c (no fixed effect means no export). This draft is the minimal ABI
|
||
contract, the ADR's step 1, as ruled.
|
||
|
||
The next step is the ADR's step 2, the artifact representation in detail: the exact cell layout of §4's
|
||
records, a design for ruling before any code. |