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

161 lines
10 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).
## 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.
- **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?
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.