Files
LithosAnanke/docs/v4.0.0/ABI.md
T

183 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:** how the system knows no node is inside the old word. It could scan return stacks
at a heartbeat for return addresses in its range, or wait until the node is idle at its prompt.
7. **Proofs:** which of ADR §5's properties come first in Isabelle/HOL. Placement's fail-closed checks and
compatibility (§7) are the smallest.