@sanning/proof 0.18.0 → 0.19.1

package/README.md

@@ -63,7 +63,7 @@ npx @sanning/proof verify trace-bundle.json
 npx @sanning/proof verify trace-bundle.json --gateways https://arweave.net,https://permagate.io
 ```
 
-It prints a per-event verdict, then the PACK verdict, and exits by the one table every verb uses: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` usage or malformed · `3` undetermined (`partial`, `pending`, `incomplete` or `not_found`: a gateway that could not be reached, a stamp no witness published, or a pack the grading rule calls `incomplete`) · `4` mixed. Since 0.13.0 `partial` exits `3` whatever caused it; it exited `0` unless a gateway was unreachable. The headline is the pack verdict, the same one `gradePack` gives the browser verify page: a record nobody hashed leaves the pack incomplete even when the signed bundle itself is `verified`, and both verdicts are printed when they differ. Only `arweave` witnesses are re-fetched: a checkpoint or stamp whose `anchor_ref.kind` is anything else is not checked, and with gateways passed the run answers `partial`, exit `3`. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
+It prints a per-event verdict, then the PACK verdict, and exits by the one table every verb uses: `0` verified · `1` a real failure (bad signature / tamper / broken inclusion) · `2` usage or malformed · `3` undetermined (`partial`, `pending`, `incomplete` or `not_found`: a gateway that could not be reached, a stamp no witness published, or a pack the grading rule calls `incomplete`) · `4` mixed · `5` sandbox: every check passed, and a record is signed `environment: "dev"`. Since 0.13.0 `partial` exits `3` whatever caused it; it exited `0` unless a gateway was unreachable. A pack holding a record signed `dev` never prints `VERIFIED`: the headline is `SANDBOX`, the line `Sandbox evidence (environment dev): not production evidence` follows it, `--json` carries `environment_marker` (`dev` or `mixed`), and a run that would exit `0` exits `5`. So does a pack whose records are all `dev` whose only unchecked witness, with `--gateways`, is `simulated`; a failure is still `1`, and a production or mixed pack with a simulated witness is still `3`. A production pack prints what it did before. The headline is the pack verdict, the same one `gradePack` gives the browser verify page: a record nobody hashed leaves the pack incomplete even when the signed bundle itself is `verified`, and both verdicts are printed when they differ. Only `arweave` witnesses are re-fetched: a checkpoint or stamp whose `anchor_ref.kind` is anything else is not checked, and with gateways passed the run answers `partial`, exit `3`. A sandbox plane's `simulated` witness is never fetched and never counted as checked on a chain: where it is the only witness, the verdict line says nothing was looked up and `--json` writes `"on_chain_checked": false`. The producer's asserted `verdict` is shown but **never trusted**, the displayed verdict is always recomputed from the body. The same CLI also verifies the agent's `sanning.agent.proof/v1` inclusion bundle (it sniffs `spec_version`), so one command covers anchor + agent.
 
 > The `verify` CLI is live in `@sanning/proof` ≥ 0.2.2, `npx @sanning/proof verify <bundle> [--gateways <url,url>]` (the gateway list was a second positional argument until 0.13.0). `verifyEvidenceBundle` is the programmatic API.
 
@@ -226,7 +226,7 @@ The walk is bounded and follows no link. A symbolic link is never followed: it i
 
 Known differences from the verify page: the page opens a dropped `.zip`; the page drops a leading byte-order mark from `bundle.json`, which `verify`'s reader refuses; the page reads whatever the browser hands it for a link, a bad name or a very deep tree; and the page loses a record named `__proto__`, which this command keeps.
 
-The first line is the case verdict, then the kernel's summary and every exception through `renderException`, then the packs, the files outside them, and the on-chain half. Exit codes: `0` verified · `1` failed · `2` malformed, usage, an input that cannot be read as a case, or an unexpected error in the command · `3` incomplete or partial · `4` mixed (more than one outcome: read the exceptions). This is the one table every verb uses (`EXIT_CODES`, exported from the package root), and `verify` exits `3` on `partial` since 0.13.0.
+The first line is the case verdict, then the kernel's summary and every exception through `renderException`, then the packs, the files outside them, and the on-chain half. Exit codes: `0` verified · `1` failed · `2` malformed, usage, an input that cannot be read as a case, or an unexpected error in the command · `3` incomplete or partial · `4` mixed (more than one outcome: read the exceptions) · `5` sandbox (it would be `0`, and a pack holds a record signed `environment: "dev"`, or every record is `dev` and only simulated witnesses are unchecked; the title is then `Sandbox`, never `Verified`). This is the one table every verb uses (`EXIT_CODES`, exported from the package root), and `verify` exits `3` on `partial` since 0.13.0.
 
 A case reading establishes that every pack verified offline, that every record every pack supplied was read in one pile under envelope-spec §4.1's hand-off rules, and that a hand-off record with no counterpart is always named. It does **not** establish that the case is complete, that a party which presented no pack under the named key recorded nothing, that two organizations are independent, or that any witness was re-fetched on chain: the output says `on-chain NOT CHECKED` unless you pass `--gateways <url,url>`. With gateways, each pack's witnesses are re-fetched pack by pack and reported beside the reading, which they never change; a witness that does not match exits `1`, and an on-chain half that could not be settled turns `0` into `3`.
 

package/dist/case-file.js

@@ -82,7 +82,8 @@ export function howToVerifyText(name) {
         `  sanning-proof case ${name}\n` +
         "\n" +
         "Exit codes: 0 verified, 1 failed, 2 not readable or a usage error,\n" +
-        "3 could not be settled (partial, pending, incomplete, not found), 4 mixed.\n" +
+        "3 could not be settled (partial, pending, incomplete, not found), 4 mixed,\n" +
+        "5 sandbox (records signed environment dev, not production evidence).\n" +
         "\n" +
         "To also look each witness up on the public record, add --gateways <url,url>.\n" +
         "The lookup is reported on its own line and never changes the verdict word.\n" +

package/dist/case.d.ts

@@ -243,6 +243,7 @@
  */
 import { type DeclarationRole } from "./declaration.js";
 import { type PackGradeCauseKind, type PackVerdict } from "./grading.js";
+import type { EnvironmentMarker } from "./environment.js";
 import type { SideContentMap } from "./side-content.js";
 /**
  * The verdicts a case can reach. Every one is already in use in
@@ -991,15 +992,30 @@ export declare const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>>;
  */
 export declare const CASE_RELIANCE_HANDOFF_CLAUSE = "Every hand-off with both sides in this drop is intact.";
 /**
- * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
- * for byte the text `case_reliance`'s Python sibling returns.
+ * The sentence a case reading's reliance line gains where its packs hold an
+ * envelope signed `environment: "dev"` (5.5.6, A48), keyed by the environment
+ * marker (`environmentMarker`): `dev` where every envelope is signed dev,
+ * `mixed` where only some are. Inserted after the line's first sentence, for
+ * every verdict word. A drop with no `dev` envelope has no marker and gains
+ * nothing.
+ */
+export declare const CASE_RELIANCE_SANDBOX: Readonly<Record<EnvironmentMarker, string>>;
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.38, A35 and A48),
+ * byte for byte the text `case_reliance`'s Python sibling returns.
  *
- * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * For every word but `verified` the base is `CASE_RELIANCE` unchanged. For
  * `verified`, the hand-off clause is inserted after the first sentence
  * where `handoffRecords` is not zero, and left out where it is zero: the
  * base sentence never claims a hand-off the drop does not hold.
+ *
+ * Where `environmentMarker` is `dev` or `mixed`, the `CASE_RELIANCE_SANDBOX`
+ * sentence for it is inserted after the first sentence, for every word, so
+ * it directly follows the claim it qualifies (and precedes the hand-off
+ * clause). Where it is null or absent, the text is exactly what it was
+ * before A48.
  */
-export declare function caseReliance(verdict: CaseVerdict, handoffRecords: number): string;
+export declare function caseReliance(verdict: CaseVerdict, handoffRecords: number, environmentMarker?: EnvironmentMarker | null): string;
 /** The three witness states, and how each is printed (5.5.6, D7). No other. */
 export declare const WITNESS_STATES: {
     readonly confirmed: "Confirmed on the public record";

package/dist/case.js

@@ -241,7 +241,8 @@
  * sequence. Narrowing any of it here with `handoffs[]` is precisely the move
  * that would reopen proof#137's door.
  */
-import { DECLARATION_VERSION, DECLARATION_VERSION_V2, checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
+import { DECLARATION_VERSION, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
+import { readChainLinks } from "./chain.js";
 import { NOT_A_HANDOFF_FINDING, normalizedSigningKey, readHandoffs, recordIsMalformed, } from "./handoff.js";
 import { coSignaturesPresent, resolveTraceEvents, verifyEvidenceBundle } from "./evidence.js";
 import { accountDisclosure, completenessNotes, gradePack, } from "./grading.js";
@@ -1152,10 +1153,14 @@ export async function readCase(packs) {
             grade = signed.status === "verified" ? "malformed" : signed.status;
         }
         else {
-            check = checkDeclaration(pack.bundle, pack.content);
+            // Rule 11 reads the chain links of the same pack, and the reader reads
+            // only the signed body, so the bare check below takes the same reading
+            // (evidence-bundle.md 5.4.2 v1.36, A45).
+            const chainLinks = await readChainLinks(pack.bundle);
+            check = checkDeclaration(pack.bundle, pack.content, chainLinks);
             const completeness = completenessNotes(pack.bundle);
             full = gradePack(verified, accountDisclosure(pack.bundle, pack.content ?? {}), completeness, check);
-            const bareGrade = gradePack(signed, accountDisclosure(pack.bundle, {}), completeness, checkDeclaration(pack.bundle, null));
+            const bareGrade = gradePack(signed, accountDisclosure(pack.bundle, {}), completeness, checkDeclaration(pack.bundle, null, chainLinks));
             // NO `failed` HERE RESTS ON BYTES NOBODY SIGNED. The signed grade decides
             // where it is `failed` or `malformed`; a failure only the side map
             // produced is `incomplete`; otherwise the full grade.
@@ -1619,7 +1624,9 @@ function declarationVersionOf(bundle) {
         return null;
     }
     const version = declaration["declaration_version"];
-    return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+    return typeof version === "string" && DECLARATION_VERSIONS.includes(version)
+        ? version
+        : null;
 }
 // ---- Presentation (optional) ------------------------------------------------
 /**
@@ -1847,23 +1854,58 @@ export const CASE_RELIANCE = {
  */
 export const CASE_RELIANCE_HANDOFF_CLAUSE = "Every hand-off with both sides in this drop is intact.";
 /**
- * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
- * for byte the text `case_reliance`'s Python sibling returns.
+ * The sentence a case reading's reliance line gains where its packs hold an
+ * envelope signed `environment: "dev"` (5.5.6, A48), keyed by the environment
+ * marker (`environmentMarker`): `dev` where every envelope is signed dev,
+ * `mixed` where only some are. Inserted after the line's first sentence, for
+ * every verdict word. A drop with no `dev` envelope has no marker and gains
+ * nothing.
+ */
+export const CASE_RELIANCE_SANDBOX = {
+    dev: "The records in this drop are sandbox records, signed environment " +
+        "dev: they are not production evidence.",
+    mixed: "Some records in this drop are sandbox records, signed environment " +
+        "dev: those are not production evidence.",
+};
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.38, A35 and A48),
+ * byte for byte the text `case_reliance`'s Python sibling returns.
  *
- * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * For every word but `verified` the base is `CASE_RELIANCE` unchanged. For
  * `verified`, the hand-off clause is inserted after the first sentence
  * where `handoffRecords` is not zero, and left out where it is zero: the
  * base sentence never claims a hand-off the drop does not hold.
+ *
+ * Where `environmentMarker` is `dev` or `mixed`, the `CASE_RELIANCE_SANDBOX`
+ * sentence for it is inserted after the first sentence, for every word, so
+ * it directly follows the claim it qualifies (and precedes the hand-off
+ * clause). Where it is null or absent, the text is exactly what it was
+ * before A48.
  */
-export function caseReliance(verdict, handoffRecords) {
+export function caseReliance(verdict, handoffRecords, environmentMarker = null) {
+    let first;
+    let rest;
     if (verdict === "verified" && handoffRecords > 0) {
-        return ("Every pack in this drop is genuine, unaltered, and matches its own " +
-            "signed declaration. Every hand-off with both sides in this drop is " +
-            "intact. Every record in it was signed by its holder's key. This " +
-            "was read offline, on this device. It does not say this drop holds " +
-            "everything that was recorded.");
+        first = "Every pack in this drop is genuine, unaltered, and matches its own signed declaration.";
+        rest =
+            "Every hand-off with both sides in this drop is intact. Every record " +
+                "in it was signed by its holder's key. This was read offline, on this " +
+                "device. It does not say this drop holds everything that was recorded.";
+    }
+    else {
+        const base = CASE_RELIANCE[verdict];
+        const cut = base.indexOf(". ");
+        first = base.slice(0, cut + 1);
+        rest = base.slice(cut + 2);
     }
-    return CASE_RELIANCE[verdict];
+    // Only `dev` and `mixed` add the sentence. Any other value, which the type
+    // forbids but an untyped caller can pass, reads as no marker.
+    const sandbox = environmentMarker === "dev" || environmentMarker === "mixed"
+        ? CASE_RELIANCE_SANDBOX[environmentMarker]
+        : null;
+    if (sandbox === null)
+        return `${first} ${rest}`;
+    return `${first} ${sandbox} ${rest}`;
 }
 /** The three witness states, and how each is printed (5.5.6, D7). No other. */
 export const WITNESS_STATES = {

package/dist/chain.d.ts

@@ -79,6 +79,34 @@ export interface ChainReading {
     chains: ChainSummary[];
     findings: ChainFinding[];
 }
+/**
+ * One record's place in a chain, as the reader grouped it, for a check that
+ * needs the links themselves rather than the findings: rule 11 of
+ * evidence-bundle.md 5.4.2, which holds a claimed chain to every link. The
+ * twin of Python's `ChainLink`.
+ */
+export interface ChainLink {
+    eventId: string;
+    publicKey: string;
+    chainKey: string;
+    source: ChainSource;
+    namespace?: string;
+    /** The SHA-256 of the record's committed bytes, or its event id for an adapter chain. */
+    selfId: string;
+    /** The pointer the record carries, or `null` where it begins a chain. */
+    prev: string | null;
+    seq: number | null;
+    /** Position in `body.events`. */
+    order: number;
+}
+/**
+ * Every record the chain reader places in a chain, in bundle order, with the
+ * identity and pointer it read: the grouping `readChains` reads, over every
+ * record an envelope binds, `event_bytes` or the inline `payload` where no
+ * `event_bytes` travel, with the identity the SHA-256 of those bytes, exactly
+ * as the envelope verifier binds `payload_hash`.
+ */
+export declare function readChainLinks(bundle: unknown): Promise<ChainLink[]>;
 /**
  * Follow every chain the bundle's records describe, and report the links that
  * do not resolve within it.

package/dist/chain.js

@@ -49,12 +49,13 @@
 //
 // (2) is a transitional accommodation, not the design. `metadata` is
 // caller-owned and the profile says a verifier MUST NOT read it for
-// verification — which is exactly why nothing here feeds a verdict. The fix is
+// verification — which is exactly why nothing read through it feeds a
+// verdict, a claimed chain included (rule 11 reads linkage (1) only). The fix is
 // for every adapter to set the record's own `previous_hash` (filed separately
 // against `anchor`); when it lands, the namespace table below stops mattering
 // and can go.
 import { hexToBytes, sha256Hex } from "./crypto.js";
-import { jcsParse } from "./verifier.js";
+import { inlinePayloadBytes, jcsParse } from "./verifier.js";
 import { resolveTraceEvents } from "./evidence.js";
 /**
  * The one sentence a surface should print beside these findings, so the reader
@@ -186,7 +187,33 @@ function adapterLinkage(record) {
  * nothing and means a relabelled record DANGLES instead of quietly resolving.
  * That is why this function is async.
  */
-async function groupChains(bundle) {
+/**
+ * The record an envelope binds, for rule 11's links: `event_bytes` where the
+ * entry carries them, else the inline `payload` read through
+ * `inlinePayloadBytes`, the bytes `payload_hash` binds. Its identity is the
+ * SHA-256 of whichever bytes it is read from. Python's `_bound_record`.
+ */
+function boundRecord(entry) {
+    const eventBytes = entry?.event_bytes;
+    if (typeof eventBytes === "string" && eventBytes.length > 0)
+        return decodeRecord(eventBytes);
+    const envelope = entry?.envelope;
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope))
+        return null;
+    if (!("payload" in envelope))
+        return null;
+    try {
+        const bytes = inlinePayloadBytes(envelope);
+        const record = jcsParse(bytes);
+        if (record === null || typeof record !== "object" || Array.isArray(record))
+            return null;
+        return { record, bytes };
+    }
+    catch {
+        return null;
+    }
+}
+async function groupChains(bundle, inline = false) {
     const groups = new Map();
     const events = eventsOf(bundle);
     for (let order = 0; order < events.length; order++) {
@@ -197,7 +224,11 @@ async function groupChains(bundle) {
         // event id an adapter pointer has nothing to resolve against.
         if (eventId === null || publicKey === null)
             continue;
-        const decoded = decodeRecord(entry?.event_bytes);
+        // `inline` (rule 11's links only): a record carried as the envelope's
+        // inline `payload` with no `event_bytes` is read too. The chain reading
+        // itself keeps reading `event_bytes` alone, so its findings and its rule
+        // table do not move.
+        const decoded = inline ? boundRecord(entry) : decodeRecord(entry?.event_bytes);
         if (decoded === null)
             continue;
         const { record, bytes } = decoded;
@@ -346,6 +377,32 @@ function findingsFor(group) {
     }
     return findings;
 }
+/**
+ * Every record the chain reader places in a chain, in bundle order, with the
+ * identity and pointer it read: the grouping `readChains` reads, over every
+ * record an envelope binds, `event_bytes` or the inline `payload` where no
+ * `event_bytes` travel, with the identity the SHA-256 of those bytes, exactly
+ * as the envelope verifier binds `payload_hash`.
+ */
+export async function readChainLinks(bundle) {
+    const links = [];
+    for (const g of await groupChains(bundle, true)) {
+        for (const m of g.members) {
+            links.push({
+                eventId: m.eventId,
+                publicKey: g.publicKey,
+                chainKey: g.chainKey,
+                source: g.source,
+                ...(g.namespace !== undefined ? { namespace: g.namespace } : {}),
+                selfId: m.selfId,
+                prev: m.prev,
+                seq: m.seq,
+                order: m.order,
+            });
+        }
+    }
+    return links.sort((a, b) => a.order - b.order);
+}
 /**
  * Follow every chain the bundle's records describe, and report the links that
  * do not resolve within it.