From d052af6d5387278f236a38fd692a6cf011449a38 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 16:16:20 +0000 Subject: [PATCH] ARTIFACT.md: choice 2 ruled, SHA-512 for provenance and proofs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- docs/v4.0.0/ARTIFACT.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/v4.0.0/ARTIFACT.md b/docs/v4.0.0/ARTIFACT.md index 7b00f5f2..02527c2a 100644 --- a/docs/v4.0.0/ARTIFACT.md +++ b/docs/v4.0.0/ARTIFACT.md @@ -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