ARTIFACT.md: choice 2 ruled, SHA-512 for provenance and proofs

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 16:16:20 +00:00
parent c4b922d496
commit d052af6d53
+21 -16
View File
@@ -18,7 +18,9 @@ ruled:
the same at either cell width.
- **The code is cells of the build's width.** A 32-bit engine and a 64-bit engine are two artifacts: the
header says which, and placement refuses the wrong one.
- **A 64-bit value**, such as a hash, is two units, low unit first.
- **A 64-bit value**, such as a capsule's hash, is two units, low unit first.
- **A SHA-512 hash** (choice 2) is 16 units: its 64 bytes in their order, packed four to a unit, low byte
first.
- **A name** is a counted string, its length byte then its characters, packed four to a unit, low byte
first, as the dictionary packs names (`dict.f18`). It sits in the string pool and is referred to by its
unit offset.
@@ -27,11 +29,11 @@ ruled:
```
header 16 units
provenance 12 units
provenance 64 units
exports E x 8 units
imports I x 6 units
relocations R x 2 units
verification 4 units
verification 18 units
string pool S units
code C cells
```
@@ -54,15 +56,16 @@ engine of a train: the capsule's payload. The capsule's content hash and Ed25519
| 9 | the unit offset of the exports (the others follow, in §2's order) |
| 10–15 | reserved, 0 |
## 4. Provenance (12 units, ADR §3.1)
## 4. Provenance (64 units, ADR §3.1)
Each hash is SHA-512 (choice 2).
| Units | Field |
|---|---|
| 0–1 | the hash of the `.f18` source the engine was assembled from (choice 3: by reference) |
| 2–3 | the host tool's hash, the compiler's identity (choice 1) |
| 4–5 | the build configuration's hash: the knobs that change code, the cell width, `V4_NODE_WORDS`, the rings |
| 6–7 | the ROM's hash it must agree with: the tool's output is checked against the ROM's assembly |
| 8–11 | reserved, 0 |
| 0–15 | the hash of the `.f18` source the engine was assembled from (ABI choice 3: by reference) |
| 16–31 | the host tool's hash, the compiler's identity (ABI choice 1) |
| 32–47 | the build configuration's hash: the knobs that change code, the cell width, `V4_NODE_WORDS`, the rings |
| 48–63 | the ROM's hash it must agree with: the tool's output is checked against the ROM's assembly |
## 5. Exports, imports, relocations
@@ -98,13 +101,13 @@ engine of a train: the capsule's payload. The capsule's content hash and Ed25519
Placement (`ABI.md` §5) patches each relocation's branch field. It refuses a patched address beyond that
slot's reach: 27, 22, 17 or 12 bits (`iword.h`).
## 6. Verification (4 units, ADR §5)
## 6. Verification (18 units, ADR §5)
| Units | Field |
|---|---|
| 0–1 | the hash of the proof that covers this exact artifact: its theory and its build; 0 means none |
| 2 | the assumptions it holds under, as a string pool offset, or 0 |
| 3 | reserved, 0 |
| 0–15 | the SHA-512 hash of the proof that covers this exact artifact: its theory and its build; all 0 means none |
| 16 | the assumptions it holds under, as a string pool offset, or 0 |
| 17 | reserved, 0 |
## 7. What makes a valid artifact
@@ -122,9 +125,11 @@ about the format:
1. ~~The unit~~ **Ruled 2026-11-19: "32-bit units".** Every record is in 32-bit units, low byte first,
as v4's blocks are, so the records read the same at either cell width (§1). Only the code is in the
build's cells.
2. **The hashes:** XXHash64, as capsule identities are today, for every hash in the artifact, or a
cryptographic hash (SHA-512, already in the tree for Ed25519) for provenance and proofs? Signing stays
Ed25519 either way.
2. ~~The hashes~~ **Ruled 2026-11-19: "SHA-512 for provenance".** The provenance hashes (source, tool,
configuration, ROM) and the proof's hash are SHA-512, the one already in the tree for Ed25519, 16
units each (§4, §6). An import's capsule hash stays the capsule's ID, XXHash64, 2 units (§5), and
signing stays Ed25519. The provenance record grows from 12 units to 64, with no reserved units, and
verification from 4 to 18.
3. **The return-stack effect:** recorded and checked (§5, unit 4), or the data stack only?
4. **Capabilities:** the port bit plus a list of kernel request numbers (§5, unit 5), or something else?
5. **Endianness for the code cells:** as the golden model stores them (host order), or fixed low-first like