@sanning/proof 0.18.0 → 0.19.1

package/dist/cli.js

@@ -17,6 +17,8 @@
 //      could not be reached reads `partial`; a pack whose records nobody hashed
 //      reads `incomplete` (see below)
 //   4  mixed
+//   5  sandbox: a record is signed environment dev; would be 0, or only a
+//      simulated witness is unchecked (`sandboxExit`)
 // `sanningd verify-status` in sanning-io/agent mirrored the 0.12 table, which
 // exited 0 on `partial`; it moves with this one.
 //
@@ -47,13 +49,15 @@ import { createHash, randomBytes } from "node:crypto";
 import { basename, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
-import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
+import { CHAIN_READING_SCOPE, readChainLinks, readChains, renderChainFinding } from "./chain.js";
 import { VERDICT_DISPLAY_TITLES, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
 import { CASE_FILE_INDEX_NAME, caseFileListedPaths, jsonDepthExceeds, readCaseFileIndex, renderCaseFileFinding, unreadableCaseFileIndex, } from "./case-file.js";
 import { MAX_ZIP_ARCHIVE_BYTES, MAX_ZIP_BYTES, ZipReadError, readZip } from "./zip-reader.js";
 import { composeExport } from "./compose.js";
 import { isHexField, sha256Hex, utf8 } from "./crypto.js";
 import { verifyEvidenceBundle } from "./evidence.js";
+import { readRuns, renderAccountLine, renderEnclaveLines } from "./run.js";
+import { loadInstalledAdapters } from "./run-adapters.js";
 import { DuplicateKeyError, parseRefusingDuplicates } from "./verifier.js";
 import { fileMatchToJson, matchCaseFiles, matchFiles, notAccountedFor, renderFileMatch, } from "./file-match.js";
 import { WITNESS_CACHE_NAME, readWitnessCache, } from "./witness-cache.js";
@@ -65,7 +69,8 @@ import { WITNESS_CACHE_NAME, readWitnessCache, } from "./witness-cache.js";
 import { onChainHalf, witnessLine } from "./witness-lookup.js";
 import { checkDeclaration, renderDeclarationSummary, renderNote } from "./declaration.js";
 import { completenessNotes, gradePack, renderCause } from "./grading.js";
-import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
+import { EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_SANDBOX, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, sandboxExit, } from "./exit-codes.js";
+import { environmentMarker, onlySimulatedUnsettled, simulatedOnlyRun, SANDBOX_HEADLINE, SANDBOX_LINE, SANDBOX_TITLE, } from "./environment.js";
 // ── What a person reads is escaped at one choke point ──
 //
 // Every human-readable line this command prints passes through `guard`, which
@@ -326,7 +331,7 @@ async function runVerify(rest, io, sink) {
             gateways,
             ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
         });
-        return reportAgentProof(result, bundlePath, gateways, io, sink);
+        return reportAgentProof(result, bundlePath, gateways, io, sink, parsed);
     }
     // Default: treat anything else as an evidence bundle. verifyEvidenceBundle
     // rejects an unknown major as "malformed" so a genuinely unknown shape still
@@ -338,8 +343,11 @@ async function runVerify(rest, io, sink) {
     });
     // Read the chains from the SAME parsed bundle the verifier saw. Findings are
     // evidence about the records in front of us, not a verdict: they are printed
-    // and they never move `exit`, because a chain is not a completeness proof and
-    // an exit code is exactly the kind of thing people read as one.
+    // and they move `exit` only through the pack's own declaration, where a v3
+    // declaration claims a chain complete and in order and a finding under that
+    // claim contradicts it (rule 11). Without a claim a chain is not a
+    // completeness proof, and an exit code is exactly the kind of thing people
+    // read as one.
     //
     // A READING THAT COULD NOT BE PRODUCED SAYS SO. This was an unguarded call:
     // a throw out of `readChains` would have escaped the command entirely and
@@ -355,7 +363,17 @@ async function runVerify(rest, io, sink) {
     catch (e) {
         chains = { unreadable: errMsg(e) };
     }
-    const exit = reportEvidence(result, bundlePath, gateways, io, chains, parsed, logs, sink);
+    // The links rule 11 holds a claimed chain to (evidence-bundle.md 5.4.2), from
+    // the same parsed bundle. Links that cannot be read are none, which reads a
+    // claim UNKNOWN and never clean.
+    let links;
+    try {
+        links = "unreadable" in chains ? null : await readChainLinks(parsed);
+    }
+    catch {
+        links = null;
+    }
+    const exit = reportEvidence(result, bundlePath, gateways, io, chains, links, parsed, logs, sink);
     // Files handed in beside the pack (evidence-bundle.md 5.7, A29): findings
     // beside the verdict, never inside it, so `exit` is untouched.
     if (offered !== undefined) {
@@ -1234,7 +1252,7 @@ function cliDisclosureAccount(result, logs) {
         extra: (logs?.suppliedIds ?? []).filter((id) => !known.has(id)),
     };
 }
-function reportEvidence(result, path, gateways, io, chains, parsed, logs, sink) {
+function reportEvidence(result, path, gateways, io, chains, links, parsed, logs, sink) {
     if (result.status === "malformed") {
         if (sink)
             sink.data = verifyJson(result, null, null, null);
@@ -1324,10 +1342,24 @@ function reportEvidence(result, path, gateways, io, chains, parsed, logs, sink)
     // their verdicts rather than a new check. A pack that DOES
     // carry a declaration this reader cannot read is a different case and exits
     // 3: the holder chose that field, so UNKNOWN is the honest answer.
-    const declaration = checkDeclaration(parsed, logs?.content);
+    //
+    // A v3 declaration that claims a chain is checked against this command's
+    // own chain links (rule 11, evidence-bundle.md 5.4.2 v1.36, A45). Links
+    // that could not be read are passed as none, which reads the claim UNKNOWN
+    // and never clean.
+    const declaration = checkDeclaration(parsed, logs?.content, links);
     const grade = gradePack(result, cliDisclosureAccount(result, logs), completenessNotes(parsed), declaration);
+    // Sandbox evidence: read from the signed envelopes the pack holds.
+    const marker = environmentMarker([parsed]);
+    // A pack whose records are all signed `dev`, undetermined only because a
+    // simulated witness cannot be looked up, would grade `verified` with that
+    // witness accepted: it is sandbox evidence, exit 5, never 3.
+    const simulatedOnly = grade.verdict === "partial" &&
+        onlySimulatedUnsettled(result) &&
+        gradePack({ ...result, status: "verified" }, cliDisclosureAccount(result, logs), completenessNotes(parsed), declaration).verdict === "verified";
+    const exit = sandboxExit(mapGradeToExit(grade), marker, simulatedOnly);
     io.out("");
-    printRollup(grade.verdict, result.status, result.assertedStatus, gateways, result.onChainChecked, io);
+    printRollup(grade.verdict, result.status, result.assertedStatus, gateways, result.onChainChecked, io, marker, exit === EXIT_SANDBOX, simulatedOnlyRun(result, gateways));
     io.out(paint(`  declaration: ${renderDeclarationSummary(declaration)}`, declaration.verdict === "failed" ? R : declaration.verdict === "verified" ? DIM : Y));
     for (const n of declaration.notes)
         io.out(paint(`  note: ${renderNote(n)}`, Y));
@@ -1346,15 +1378,15 @@ function reportEvidence(result, path, gateways, io, chains, parsed, logs, sink)
         io.out(paint(`  logs: ${grade.recordsVerified}/${result.events.length} record(s) content-verified`, DIM));
     }
     if (sink)
-        sink.data = verifyJson(result, grade, declaration, chains);
-    return mapGradeToExit(grade);
+        sink.data = verifyJson(result, grade, declaration, chains, marker);
+    return exit;
 }
 /**
  * What `verify --json` prints for an evidence bundle, the same keys and the
  * same words as `_verify_json` in the Python twin. `grade`, `declaration` and
  * `chains` are null for a bundle no verdict could be rendered over.
  */
-function verifyJson(result, grade, declaration, chains) {
+function verifyJson(result, grade, declaration, chains, marker = null) {
     let chainBlock = null;
     if (chains !== null) {
         chainBlock =
@@ -1380,6 +1412,9 @@ function verifyJson(result, grade, declaration, chains) {
             ? { presented: result.events.length, content_verified: grade.recordsVerified }
             : null,
         chains: chainBlock,
+        // Present only where the pack holds an envelope signed `dev`
+        // (envelope-spec §2 MAY), so a production pack's JSON is unchanged.
+        ...(marker !== null ? { environment_marker: marker } : {}),
     };
 }
 /**
@@ -1440,7 +1475,8 @@ function reportExport(exp, io) {
         }
     }
 }
-function reportAgentProof(result, path, gateways, io, sink) {
+function reportAgentProof(result, path, gateways, io, sink, parsed) {
+    const marker = result.status === "malformed" ? null : environmentMarker([parsed]);
     if (sink) {
         sink.data = {
             verdict: result.status,
@@ -1448,6 +1484,7 @@ function reportAgentProof(result, path, gateways, io, sink) {
             spec_version: "sanning.agent.proof/v1",
             on_chain_checked: result.onChainChecked,
             notes: [...result.errors],
+            ...(marker !== null ? { environment_marker: marker } : {}),
         };
     }
     if (result.status === "malformed") {
@@ -1464,17 +1501,30 @@ function reportAgentProof(result, path, gateways, io, sink) {
     io.out("");
     // An agent inclusion proof carries no records and no disclosed bytes, so
     // there is no pack to grade: the bundle status IS the headline here.
-    printRollup(result.status, result.status, null, gateways, result.onChainChecked, io);
+    const exit = sandboxExit(exitCodeFor(result.status), marker);
+    printRollup(result.status, result.status, null, gateways, result.onChainChecked, io, marker, exit === EXIT_SANDBOX);
     for (const e of result.errors)
         io.out(paint(`  note: ${e}`, DIM));
-    return exitCodeFor(result.status);
+    return exit;
 }
-function printRollup(headline, bundleStatus, asserted, gateways, onChainChecked, io) {
+function printRollup(headline, bundleStatus, asserted, gateways, onChainChecked, io, marker = null, sandbox = false, simulatedOnly = false) {
+    // Three scopes, not two. A run with gateways whose only witnesses are
+    // simulated looked nothing up (`simulatedOnlyRun`): saying "on-chain" there
+    // claims a check that never happened, and saying "no gateway re-fetch
+    // requested" denies the flag the reader passed. Every other run that is not
+    // counted as checked on a chain, a run that stopped early among them, keeps
+    // the second scope as before.
     const scope = onChainChecked
         ? `verified offline + on-chain against ${gateways.length} gateway(s)`
-        : "verified offline (no gateway re-fetch requested)";
+        : simulatedOnly
+            ? "verified offline; a simulated witness is not on a chain, so nothing was looked up"
+            : "verified offline (no gateway re-fetch requested)";
     let head;
-    switch (headline) {
+    switch (sandbox ? "sandbox" : headline) {
+        // Sandbox evidence (exit 5) never prints VERIFIED.
+        case "sandbox":
+            head = paint(SANDBOX_HEADLINE, Y);
+            break;
         case "verified":
             head = paint("VERIFIED", G);
             break;
@@ -1492,6 +1542,8 @@ function printRollup(headline, bundleStatus, asserted, gateways, onChainChecked,
             head = paint(headline.toUpperCase(), R);
     }
     io.out(`${head}  ${paint(scope, DIM)}`);
+    if (marker !== null)
+        io.out(paint(`  ${SANDBOX_LINE}`, Y));
     // Both verdicts, whenever they differ, because they answer different
     // questions: §3 grades the signed bundle, the pack verdict grades the bundle
     // plus whatever bytes travelled beside it. A pack can be incomplete while the
@@ -2072,7 +2124,7 @@ async function unzip(arg, prefix, tree, seen) {
 // 5.5.4 v1.16, A17), so it reads `failed` and exits 1.
 export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict over one pack or many, offline
 
-  sanning-proof case <folder or case file>... [--gateways <url,url>] [--files <path>...] [--json]
+  sanning-proof case <folder or case file>... [--gateways <url,url>] [--files <path>...] [--enclave-policy <file>] [--enclave-rpc <url>] [--json]
 
   <folder>    a pack folder (bundle.json plus logs/), a folder that holds
               several packs, or an unzipped case file. Packs are found by the
@@ -2110,6 +2162,17 @@ export const CASE_USAGE = `sanning-proof case -- a case reading: one verdict ove
               contribution, the packs, each with its index, the files outside
               them, the case file index comparison, the witness line and the
               on-chain half.
+  --enclave-policy
+              a sanning.enclave-policy/v1 file: what this reader accepts of
+              an enclave attestation. Where the packs hold a runner's run, an
+              enclave attestation line and a run-account line print beside
+              the witness line (DRAFT); neither moves the verdict or the exit
+              code. Without a policy, or without an adapter for the provider
+              installed, the line reads not_checked.
+  --enclave-rpc
+              a chain JSON-RPC endpoint: a flare-fcc run also gets the online
+              line, read from the contracts the policy names. It moves
+              nothing either.
 
 Files outside every pack are matched too, always, so
 sanning-proof case audit-file.zip checks a whole download in one command: each
@@ -2184,12 +2247,21 @@ const titleOf = (word) => Object.prototype.hasOwnProperty.call(VERDICT_DISPLAY_T
  * scope sentence and the witness line are printed with it every time.
  */
 function caseReport(data) {
-    const lines = [
-        data.title,
-        `  ${data.summary}`,
-        `  ${data.witness.rendered}`,
-        `  ${data.reliance}`,
-    ];
+    const lines = [data.title];
+    // Sandbox evidence: printed with every headline the marker is on.
+    if (data.environment_marker !== undefined)
+        lines.push(`  ${SANDBOX_LINE}`);
+    lines.push(`  ${data.summary}`, `  ${data.witness.rendered}`);
+    // Where the packs hold a runner's run: its enclave attestation line and its
+    // run-account line, beside the witness line.
+    const enclave = data.enclave_attestation ?? [];
+    const account = data.run_account ?? [];
+    for (let i = 0; i < Math.min(enclave.length, account.length); i++) {
+        for (const line of enclave[i].rendered)
+            lines.push(`  ${line}`);
+        lines.push(`  ${account[i].rendered}`);
+    }
+    lines.push(`  ${data.reliance}`);
     for (const e of data.exceptions)
         lines.push(`  - ${e.rendered}`);
     for (const n of data.notes)
@@ -2197,7 +2269,11 @@ function caseReport(data) {
     lines.push(`packs         ${data.packs.length}`);
     for (const p of data.packs) {
         const key = p.signing_key !== null ? p.signing_key : "a key this reader cannot read";
-        const grade = p.grade !== null ? titleOf(p.grade) : "not graded";
+        const grade = p.grade === null
+            ? "not graded"
+            : p.grade === "verified" && p.environment_marker !== undefined
+                ? SANDBOX_TITLE
+                : titleOf(p.grade);
         // Each record's status, counted per pack (A43): the JSON lists every one.
         const mine = data.records.filter((r) => r.pack_index === p.index);
         const count = (status) => mine.filter((r) => r.status === status).length;
@@ -2235,13 +2311,23 @@ function caseReport(data) {
     }
     const oc = data.on_chain;
     if (oc.checked) {
-        lines.push(`on-chain      looked up against ${oc.gateways.length} gateway(s), ` +
-            "pack by pack; the reading above is offline and this does not " +
-            "change it");
+        // A drop whose only witnesses are simulated had nothing looked up on a
+        // chain, and the header says so rather than "looked up against".
+        const simulated = oc.packs.reduce((n, r) => n + (r.simulated ?? 0), 0);
+        const onlySimulated = simulated > 0 &&
+            oc.packs.every((r) => (r.simulated ?? 0) === r.witnesses && (r.witness_times ?? []).length === 0);
+        lines.push(onlySimulated
+            ? "on-chain      nothing looked up: every witness here is simulated, " +
+                "which is not on a chain; the reading above is offline and this " +
+                "does not change it"
+            : `on-chain      looked up against ${oc.gateways.length} gateway(s), ` +
+                "pack by pack; the reading above is offline and this does not " +
+                "change it");
         for (const r of oc.packs) {
+            const sim = r.simulated ? `, ${r.simulated} of them simulated (not on a chain)` : "";
             lines.push(`  ${r.ref}  ${r.witnesses} witness(es): ${r.confirmed} ` +
                 `confirmed, ${r.mismatched} mismatched, ${r.unreachable} ` +
-                `unreachable, ${r.not_checked} not checked`);
+                `unreachable, ${r.not_checked} not checked${sim}`);
         }
     }
     return lines;
@@ -2333,6 +2419,12 @@ export async function caseFileReadings(tree, whole, cap = MAX_FOLDER_BYTES) {
     }
     return out;
 }
+// One pack's environment marker, as the key its JSON row carries only where
+// the pack holds an envelope signed `dev`.
+function packMarker(bundle) {
+    const m = environmentMarker([bundle]);
+    return m !== null ? { environment_marker: m } : {};
+}
 function caseError(e, asJson, io) {
     if (asJson)
         outJson(io, jsonText({ error: e.message, exit_code: EXIT_MALFORMED, hint: e.hint }));
@@ -2417,11 +2509,69 @@ export async function looseFiles(tree, split, cap = MAX_FOLDER_BYTES) {
     }
     return { offered, skipped };
 }
+// A policy file that is not JSON: read, and unreadable (`policy_unreadable`).
+const POLICY_NOT_JSON = Symbol("policy not JSON");
+async function readEnclavePolicy(path) {
+    if (path === null)
+        return null;
+    let raw;
+    try {
+        if (!(await stat(path)).isFile())
+            throw new CaseInputError(`--enclave-policy ${path} is not a readable file`);
+        raw = new Uint8Array(await readFile(path));
+    }
+    catch (e) {
+        if (e instanceof CaseInputError)
+            throw e;
+        throw new CaseInputError(`--enclave-policy ${path} is not a readable file`);
+    }
+    try {
+        return parseRefusingDuplicates(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw));
+    }
+    catch {
+        return POLICY_NOT_JSON;
+    }
+}
+/** The two line members of `--json`: one entry per run, with the lines it prints. */
+function runLines(runs) {
+    const enclave = runs.map((r) => ({
+        pack_ref: r.packRef,
+        pack_index: r.packIndex,
+        event_id: r.eventId,
+        runner_public_key: r.runnerPublicKey,
+        agent_public_key: r.agentPublicKey,
+        state: r.enclave.state,
+        kinds: r.enclave.kinds,
+        notes: r.enclave.notes,
+        reason: r.enclave.reason,
+        provider: r.enclave.provider,
+        evaluation: r.enclave.evaluation,
+        evaluated_at: r.enclave.evaluatedAt,
+        token_checked: r.enclave.tokenChecked,
+        online: r.online !== null ? { state: r.online.state, kinds: r.online.kinds } : null,
+        rendered: renderEnclaveLines(r).map(escapeControl),
+    }));
+    const account = runs.map((r) => ({
+        pack_ref: r.packRef,
+        pack_index: r.packIndex,
+        event_id: r.eventId,
+        runner_public_key: r.runnerPublicKey,
+        state: r.account.state,
+        findings: r.account.findings.map((f) => ({ kind: f.kind, event_id: f.eventId })),
+        notes: r.account.notes.map((n) => ({ kind: n.kind, event_id: n.eventId })),
+        closing_event_id: r.account.closingEventId,
+        reason: r.account.reason,
+        rendered: escapeControl(renderAccountLine(r)),
+    }));
+    return [enclave, account];
+}
 async function caseCommand(argv, io) {
     let asJson = false;
     let gateways = [];
     const paths = [];
     let filePaths;
+    let enclavePolicy = null;
+    let enclaveRpc = null;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ((arg === "--help" || arg === "-h" || arg === "help") && paths.length === 0) {
@@ -2454,6 +2604,19 @@ async function caseCommand(argv, io) {
             filePaths = [...(filePaths ?? []), ...taken];
             i += taken.length;
         }
+        else if (arg === "--enclave-policy" || arg === "--enclave-rpc") {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                io.err(arg === "--enclave-policy" ? "case: --enclave-policy requires a policy file" : "case: --enclave-rpc requires a URL");
+                outBlock(io, CASE_USAGE);
+                return EXIT_MALFORMED;
+            }
+            if (arg === "--enclave-policy")
+                enclavePolicy = next;
+            else
+                enclaveRpc = next;
+            i++;
+        }
         else if (arg.startsWith("--")) {
             io.err(`case: unknown option ${arg}`);
             outBlock(io, CASE_USAGE);
@@ -2477,6 +2640,15 @@ async function caseCommand(argv, io) {
         offered = read.offered;
         skipped = read.skipped;
     }
+    let policy;
+    try {
+        policy = await readEnclavePolicy(enclavePolicy);
+    }
+    catch (e) {
+        if (e instanceof CaseInputError)
+            return caseError(e, asJson, io);
+        throw e;
+    }
     const whole = { n: MAX_FOLDER_BYTES };
     let split;
     let tree;
@@ -2506,14 +2678,25 @@ async function caseCommand(argv, io) {
     for (const [p, bundle] of bundles) {
         caches.push(readWitnessCache(bundle, await witnessCacheBytes(tree, split, p, whole, cacheRefused)));
     }
-    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, { ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) });
+    const confirmedStamps = [];
+    const onChain = await onChainHalf(bundles.map(([p, bundle], i) => [p.ref, bundle, caches[i]]), gateways, { ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}) }, confirmedStamps);
     const witness = witnessLine(onChain, caches.flat());
-    const code = caseExitCode(reading.verdict, onChain.verdict);
+    // Sandbox evidence: over every envelope every pack holds, and per
+    // pack for its row. Only a case that would otherwise exit 0 exits 5.
+    const marker = environmentMarker(bundles.map(([, b]) => b));
+    // Undetermined only because a simulated witness cannot be looked up: every
+    // other witness confirmed, none unreachable or mismatched, every pack names
+    // one. With every record signed `dev` that is sandbox evidence, exit 5.
+    const simulatedOnly = reading.verdict === "verified" &&
+        onChain.verdict === "undetermined" &&
+        onChain.packs.some((r) => (r.simulated ?? 0) > 0) &&
+        onChain.packs.every((r) => r.witnesses > 0 && r.unreachable === 0 && r.mismatched === 0 && r.not_checked === (r.simulated ?? 0));
+    const code = sandboxExit(caseExitCode(reading.verdict, onChain.verdict), marker, simulatedOnly);
     const nil = (v) => (v === undefined ? null : v);
     const data = {
         verdict: reading.verdict,
-        title: titleOf(reading.verdict),
-        reliance: caseReliance(reading.verdict, reading.handoffRecords),
+        title: reading.verdict === "verified" && marker !== null ? SANDBOX_TITLE : titleOf(reading.verdict),
+        reliance: caseReliance(reading.verdict, reading.handoffRecords, marker),
         exit_code: code,
         summary: renderCaseSummary(reading),
         witness: {
@@ -2572,13 +2755,23 @@ async function caseCommand(argv, io) {
             grade: reading.packs[i].grade,
             records_withheld: reading.packs[i].recordsWithheld,
             declaration_version: reading.packs[i].declarationVersion,
+            ...packMarker(bundles[i][1]),
         })),
         outside: split.outside,
         not_regular: split.notRegular,
         case_file: caseFile,
         on_chain: onChain,
         ...(cacheRefused.length > 0 ? { witness_cache_not_read: cacheRefused } : {}),
+        ...(marker !== null ? { environment_marker: marker } : {}),
     };
+    // The runs in the drop (DRAFT, specs/enclave-attestation.md and
+    // run-records.md): an enclave attestation line and a run-account line per
+    // run, beside the witness line. Neither moves `code`, and a drop that holds
+    // no run prints and writes exactly what it did before.
+    const runs = (await readRuns(bundles.map(([p, bundle]) => ({ ref: p.ref, bundle, content: p.content })), { policy, adapters: await loadInstalledAdapters(), rpc: enclaveRpc, witnessed: confirmedStamps })).runs;
+    const withRuns = data;
+    if (runs.length > 0)
+        [withRuns.enclave_attestation, withRuns.run_account] = runLines(runs);
     // The files outside every pack (evidence-bundle.md 5.7, A29, A41), always,
     // then the files after --files. A pack's logs/ is its side content and is
     // never an offered file; only the paths after --files are. Both are matched

package/dist/declaration.d.ts

@@ -1,3 +1,4 @@
+import type { ChainLink } from "./chain.js";
 import { type HandoffRecord } from "./handoff.js";
 import { type SideContentMap } from "./side-content.js";
 /** The first declaration schema, which every earlier reader knows. */
@@ -8,8 +9,15 @@ export declare const DECLARATION_VERSION = "sanning.declaration/v1";
  * it cannot read, which is the safe direction.
  */
 export declare const DECLARATION_VERSION_V2 = "sanning.declaration/v2";
+/**
+ * v2 plus a signed `chains[]`: the `chain_key`s the holder claims are complete
+ * and in order (evidence-bundle.md 5.4.1 v1.36, A45). A reader that knows only
+ * v1 and v2 reads a v3 declaration as one it cannot read, which is the safe
+ * direction.
+ */
+export declare const DECLARATION_VERSION_V3 = "sanning.declaration/v3";
 /** Every declaration schema this reader knows, in the order they were added. */
-export declare const DECLARATION_VERSIONS: readonly ["sanning.declaration/v1", "sanning.declaration/v2"];
+export declare const DECLARATION_VERSIONS: readonly ["sanning.declaration/v1", "sanning.declaration/v2", "sanning.declaration/v3"];
 /**
  * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
  * record 4.1 governs that the pack claims as a side in `handoffs[]`, or
@@ -20,7 +28,7 @@ export type DeclarationRole = (typeof DECLARATION_ROLES)[number];
 /** The three states a declaration check can reach, from the §3 vocabulary. */
 export declare const DECLARATION_VERDICTS: readonly ["verified", "failed", "partial"];
 export type DeclarationVerdict = (typeof DECLARATION_VERDICTS)[number];
-export declare const DECLARATION_DEVIATION_KINDS: readonly ["declaration_malformed", "declared_absent", "undeclared_present", "withheld_but_disclosed", "duplicate_event_id", "pair_record_undeclared", "pair_record_not_a_handoff", "role_handoff_unclaimed", "role_step_claimed", "role_step_governed", "role_step_unreadable"];
+export declare const DECLARATION_DEVIATION_KINDS: readonly ["declaration_malformed", "declared_absent", "undeclared_present", "withheld_but_disclosed", "duplicate_event_id", "pair_record_undeclared", "pair_record_not_a_handoff", "role_handoff_unclaimed", "role_step_claimed", "role_step_governed", "role_step_unreadable", "chain_second_root", "chain_fork", "chain_link_dangling", "chain_claimed_absent"];
 export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 /**
  * Every way a pack and the UNSIGNED content handed in beside it fail to line
@@ -60,7 +68,7 @@ export interface DeclarationContentFinding {
     eventId?: string;
 }
 /** Everything this check reports that is NOT a deviation, as a closed set. */
-export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld"];
+export declare const DECLARATION_NOTE_KINDS: readonly ["disclosure_did_not_travel", "pair_record_withheld", "role_step_withheld", "other_declaration_held", "other_declaration_withheld", "chain_claim_withheld"];
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 /**
  * One named non-deviation finding, as data.
@@ -79,6 +87,8 @@ export interface DeclarationNote {
     side?: "sent" | "received";
     /** Which claimed hand-off, by position, for `pair_record_withheld`. */
     pairIndex?: number;
+    /** The claimed chain, for `chain_claim_withheld`. */
+    chainKey?: string;
 }
 /** One deviation, as data. A surface renders its own prose or calls `renderDeviation`. */
 export interface DeclarationDeviation {
@@ -97,6 +107,8 @@ export interface DeclarationDeviation {
      * the first one this reader learned.
      */
     version?: string;
+    /** The claimed chain, for the four rule 11 `chain_` deviations. */
+    chainKey?: string;
 }
 export interface DeclarationCheck {
     verdict: DeclarationVerdict;
@@ -137,6 +149,12 @@ export interface DeclarationCheck {
         eventId: string;
         role: DeclarationRole;
     }[];
+    /**
+     * Every `chain_key` a v3 declaration claims is complete and in order, in
+     * declaration order. Empty for v1 and v2, and for anything this reader could
+     * not read.
+     */
+    chains?: string[];
 }
 /**
  * One of the pack's own records: the id, and whether the pack supplied its
@@ -172,6 +190,19 @@ export interface PackRecord {
      * two different readings and never one.
      */
     bytesSupplied: boolean;
+    /**
+     * Whether this record's payload binding is UNDETERMINED: no `event_bytes`
+     * string and no inline envelope `payload`, the two things the envelope
+     * verifier binds `payload_hash` against. Rule 11 excuses a dangling link
+     * only for such a record's producing key.
+     */
+    bindingUndetermined: boolean;
+    /**
+     * The envelope's signed `payload_hash` as written, or `""`. For a record
+     * whose binding is undetermined it is the identity a successor's pointer
+     * names: rule 11 excuses a dangling link only where the pointer equals it.
+     */
+    payloadHash: string;
 }
 /**
  * The pack's own records, in bundle order. Exported so the CASE layer
@@ -189,11 +220,19 @@ export declare function packRecords(bundle: unknown, content: SideContentMap | n
  * and a pack that discloses them beside itself passes the map a consumer
  * already built.
  *
+ * `chains` is `readChains` over the SAME bundle. Only a v3 declaration that
+ * claims a chain reads it (rule 11). It is an argument rather than computed
+ * here because `readChains` is asynchronous and this check is not, and Python's
+ * `check_declaration` takes it the same way so the two kernels share one
+ * contract. A v3 declaration that claims a chain, checked without it, reads as
+ * a reader that does not know v3 reads it: `partial`, nothing named, and the
+ * pack `incomplete`. Leaving it out can never read `verified`.
+ *
  * The verdict is this check's own. It does not restate the bundle verdict and
  * it does not read it: a declaration can match perfectly over a pack whose
  * signatures are forged, and saying so is `gradePack`'s job, which takes both.
  */
-export declare function checkDeclaration(bundle: unknown, content?: SideContentMap | null): DeclarationCheck;
+export declare function checkDeclaration(bundle: unknown, content?: SideContentMap | null, links?: readonly ChainLink[] | null): DeclarationCheck;
 /**
  * The house wording for one deviation.
  *