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

11 KiB
Raw Blame History

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).

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 DEFERred 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: 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?
  5. How callers reach a replacement:
    • (a) the old entry's code is overwritten by a jump to the new: one cell, every caller follows, and the old code is unreachable but for that cell;
    • (b) the kernel's call hook redirects calls to the old address, from a table;
    • (c) callers are re-patched from records kept at placement.
  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.