@sanning/proof 0.17.0 → 0.19.0

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.
  *

package/dist/declaration.js

@@ -127,9 +127,6 @@
 //   a deviation, and the cheapest escape from that was to stop claiming pairs
 //   at all. A withheld side now gets its OWN reading, distinct from both
 //   conformant and non-conformant, and is a NAMED NOTE.
-// The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
-// byte-order mark, no non-finite literal. `jcs_loads` in
-// `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
 import { hexToBytes, utf8 } from "./crypto.js";
 import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
@@ -142,8 +139,21 @@ export const DECLARATION_VERSION = "sanning.declaration/v1";
  * it cannot read, which is the safe direction.
  */
 export 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 const DECLARATION_VERSION_V3 = "sanning.declaration/v3";
 /** Every declaration schema this reader knows, in the order they were added. */
-export const DECLARATION_VERSIONS = [DECLARATION_VERSION, DECLARATION_VERSION_V2];
+export const DECLARATION_VERSIONS = [
+    DECLARATION_VERSION,
+    DECLARATION_VERSION_V2,
+    DECLARATION_VERSION_V3,
+];
+/** The versions whose every `records[]` entry carries a signed `role`. */
+const ROLE_VERSIONS = [DECLARATION_VERSION_V2, DECLARATION_VERSION_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
@@ -191,6 +201,18 @@ export const DECLARATION_DEVIATION_KINDS = [
      * read under rule 7's parser rule.
      */
     "role_step_unreadable",
+    /**
+     * Rule 11 (v1.36, A45), `sanning.declaration/v3` only. The holder signed
+     * that a chain is complete and in order, and a second record under that key,
+     * under any producing key, begins it.
+     */
+    "chain_second_root",
+    /** A record of a claimed chain is the second successor of one predecessor. */
+    "chain_fork",
+    /** A record of a claimed chain points at a predecessor its chain does not present in the pack. */
+    "chain_link_dangling",
+    /** A claimed chain of which the pack presents no record at all. */
+    "chain_claimed_absent",
 ];
 /**
  * Every way a pack and the UNSIGNED content handed in beside it fail to line
@@ -272,6 +294,14 @@ export const DECLARATION_NOTE_KINDS = [
      * declaration other than this pack's own is UNKNOWN.
      */
     "other_declaration_withheld",
+    /**
+     * Rule 11 (v1.36, A45). A claimed chain has a dangling link, and a record
+     * signed by the same producing key has an undetermined payload binding. That
+     * record takes no part in a chain, so whether the missing link is it is
+     * UNKNOWN. Moves nothing: the undetermined binding holds the pack at
+     * `incomplete`.
+     */
+    "chain_claim_withheld",
 ];
 /**
  * The record committed inside one `events[]` entry, or `null`.
@@ -367,6 +397,8 @@ export function packRecords(bundle, content) {
             publicKey: typeof key === "string" ? key : "",
             record: committedRecord(rawBytes),
             bytesSupplied: typeof rawBytes === "string" && rawBytes.length > 0,
+            bindingUndetermined: typeof rawBytes !== "string" && !(isObject(ev?.envelope) && "payload" in ev.envelope),
+            payloadHash: typeof ev?.envelope?.payload_hash === "string" ? ev.envelope.payload_hash : "",
         };
     });
 }
@@ -393,7 +425,7 @@ function readDeclaration(declaration, version = DECLARATION_VERSION) {
     // or `step` (5.4.1 v1.20, A21); under v1 the member is not read at all, so a
     // v1 declaration carrying `role` reads exactly as the same object without it.
     const roles = [];
-    const v2 = version === DECLARATION_VERSION_V2;
+    const v2 = ROLE_VERSIONS.includes(version);
     const note = (r) => reasons.push(r);
     if (!isId(declaration["case_id"]))
         note("case_id is not a non-empty string");
@@ -472,7 +504,31 @@ function readDeclaration(declaration, version = DECLARATION_VERSION) {
             pairs.push({ sent: sent, received: received });
         }
     }
-    return reasons.length > 0 ? { ok: false, reasons } : { ok: true, read: { records, pairs, roles } };
+    // v3 is v2 plus a required `chains[]` (5.4.1 v1.36, A45); v1 and v2 do not
+    // read the member.
+    const chains = [];
+    if (version === DECLARATION_VERSION_V3) {
+        const rawChains = declaration["chains"];
+        if (!Array.isArray(rawChains))
+            note("chains is not an array");
+        else {
+            for (const [i, c] of rawChains.entries()) {
+                if (!isObject(c) || !isId(c["chain_key"])) {
+                    note(`chains[${i}] carries no chain_key`);
+                    continue;
+                }
+                const chainKey = c["chain_key"];
+                if (chains.includes(chainKey)) {
+                    note(`chains[${i}] claims ${chainKey} a second time`);
+                    continue;
+                }
+                chains.push(chainKey);
+            }
+        }
+    }
+    return reasons.length > 0
+        ? { ok: false, reasons }
+        : { ok: true, read: { records, pairs, roles, chains } };
 }
 // ---- The check ---------------------------------------------------------------
 const noDeclaration = () => ({
@@ -485,6 +541,7 @@ const noDeclaration = () => ({
     declaredWithheld: [],
     version: null,
     roles: [],
+    chains: [],
 });
 /**
  * The `declaration_version` of an object this reader knows, or `null`: a
@@ -495,7 +552,9 @@ function knownVersion(declaration) {
     if (!isObject(declaration))
         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;
 }
 /**
  * Rule 9 over one record the pack holds: the deviation or note it earns, or
@@ -548,9 +607,10 @@ function isDeclarationShape(obj) {
     if (!isObject(obj))
         return false;
     const version = obj["declaration_version"];
-    if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2)
+    if (typeof version !== "string" || !DECLARATION_VERSIONS.includes(version))
         return false;
-    if (!hasExactKeys(obj, DECLARATION_KEYS))
+    const v3 = version === DECLARATION_VERSION_V3;
+    if (!hasExactKeys(obj, v3 ? [...DECLARATION_KEYS, "chains"] : DECLARATION_KEYS))
         return false;
     if (!isId(obj["case_id"]))
         return false;
@@ -562,7 +622,9 @@ function isDeclarationShape(obj) {
         return false;
     if (typeof period["start"] !== "string" || typeof period["end"] !== "string")
         return false;
-    const recordKeys = version === DECLARATION_VERSION_V2 ? ["event_id", "disclosure", "role"] : ["event_id", "disclosure"];
+    const recordKeys = ROLE_VERSIONS.includes(version)
+        ? ["event_id", "disclosure", "role"]
+        : ["event_id", "disclosure"];
     const records = obj["records"];
     if (!Array.isArray(records))
         return false;
@@ -573,7 +635,13 @@ function isDeclarationShape(obj) {
     const handoffs = obj["handoffs"];
     if (!Array.isArray(handoffs))
         return false;
-    return handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"]));
+    if (!handoffs.every((h) => hasExactKeys(h, ["sent_event_id", "received_event_id"])))
+        return false;
+    if (!v3)
+        return true;
+    const chains = obj["chains"];
+    return (Array.isArray(chains) &&
+        chains.every((c) => hasExactKeys(c, ["chain_key"]) && typeof c["chain_key"] === "string"));
 }
 /**
  * The content bytes disclosed for one record, or `null` where none are usable:
@@ -674,11 +742,19 @@ function otherDeclarationNotes(bundle, pack, declaration, content) {
  * 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 function checkDeclaration(bundle, content) {
+export function checkDeclaration(bundle, content, links) {
     // `body.declaration` as WRITTEN, not as hoped. The key being absent and the
     // key holding a string, an array or `null` are graded differently and must
     // not collapse into one another: a body with no `declaration` key claimed
@@ -721,9 +797,10 @@ export function checkDeclaration(bundle, content) {
             declaredWithheld: [],
             version,
             roles: [],
+            chains: [],
         };
     }
-    const { records, pairs, roles } = read.read;
+    const { records, pairs, roles, chains: claimedChains } = read.read;
     const declared = records.map((r) => r.eventId);
     const declaredSet = new Set(declared);
     const pack = packRecords(bundle, content);
@@ -885,6 +962,18 @@ export function checkDeclaration(bundle, content) {
                 deviations.push({ kind, eventId });
         }
     }
+    // Rule 11 (5.4.2 v1.36, A45), `sanning.declaration/v3` only: a chain the
+    // holder signed as complete and in order, against the chain reading of the
+    // same pack. Its deviations follow rule 9's, and its notes follow rule 9's
+    // and precede rule 10's, both in `chains[]` order.
+    // A caller that passed no links leaves the claim UNREAD: rules 1 to 10 still
+    // run, and the verdict below is never `verified`.
+    const unread = claimedChains.length > 0 && (links === undefined || links === null);
+    if (claimedChains.length > 0 && links !== undefined && links !== null) {
+        const found = chainClaimFindings(claimedChains, links, pack);
+        deviations.push(...found.deviations);
+        notes.push(...found.notes);
+    }
     // Rule 10 (5.4.2 v1.29, A36): content handed in for a record signed
     // `declaration` that is a declaration other than this pack's own. Notes only, in bundle order, after every other note, and
     // never a deviation: the pack holds what its own declaration says whatever
@@ -896,7 +985,11 @@ export function checkDeclaration(bundle, content) {
     // its claim everywhere a signature reaches and does not line up somewhere
     // only unsigned bytes could settle, which is UNDETERMINED: `partial` is
     // 3's word for that, and it adds none.
-    const verdict = deviations.length > 0 ? "failed" : contentFindings.length > 0 ? "partial" : "verified";
+    const verdict = deviations.length > 0
+        ? "failed"
+        : contentFindings.length > 0 || unread
+            ? "partial"
+            : "verified";
     return {
         verdict,
         deviations,
@@ -907,8 +1000,73 @@ export function checkDeclaration(bundle, content) {
         declaredWithheld: records.filter((r) => r.withheld).map((r) => r.eventId),
         version,
         roles,
+        chains: claimedChains,
     };
 }
+/**
+ * Rule 11 over every claimed `chain_key`, in `chains[]` order. The twin of
+ * Python's `_chain_claim_findings`, which states the rule in full.
+ *
+ * A claim covers every record whose OWN signed linkage names the key
+ * (`source === "record"`), under every producing key; an adapter's metadata
+ * linkage is never read for a claim. Under a claim, in bundle order: every
+ * record after the first that begins the chain is a `chain_second_root`; a
+ * record whose predecessor already has an earlier successor in its chain is a
+ * `chain_fork`; a record whose pointer resolves to no record of its own chain
+ * (one producing key, one `chain_key`) is a `chain_link_dangling`, with no
+ * window allowance; a claimed key with no such record is
+ * `chain_claimed_absent`. Links are read from the record each envelope binds,
+ * `event_bytes` or an inline `payload`. A dangling link is the note
+ * `chain_claim_withheld` instead, once per key, only where its pointer equals
+ * the signed `payload_hash` of a same-key record whose binding is
+ * undetermined: exactly the missing link. Nothing else is excused.
+ */
+function chainClaimFindings(claimed, links, pack) {
+    const deviations = [];
+    const notes = [];
+    const withheldLinks = new Set(pack
+        .filter((p) => p.bindingUndetermined && p.publicKey !== "" && p.payloadHash !== "")
+        .map((p) => JSON.stringify([p.publicKey, p.payloadHash])));
+    for (const chainKey of claimed) {
+        const members = links
+            .filter((l) => l.source === "record" && l.chainKey === chainKey)
+            .sort((a, b) => a.order - b.order);
+        if (members.length === 0) {
+            deviations.push({ kind: "chain_claimed_absent", chainKey });
+            continue;
+        }
+        const idsByKey = new Map();
+        for (const m of members) {
+            if (!idsByKey.has(m.publicKey))
+                idsByKey.set(m.publicKey, new Set());
+            idsByKey.get(m.publicKey).add(m.selfId);
+        }
+        let roots = 0;
+        const successors = new Set();
+        let excused = false;
+        for (const m of members) {
+            if (m.prev === null) {
+                roots++;
+                if (roots > 1)
+                    deviations.push({ kind: "chain_second_root", eventId: m.eventId, chainKey });
+                continue;
+            }
+            const edge = JSON.stringify([m.publicKey, m.prev]);
+            if (successors.has(edge))
+                deviations.push({ kind: "chain_fork", eventId: m.eventId, chainKey });
+            successors.add(edge);
+            if (!idsByKey.get(m.publicKey).has(m.prev)) {
+                if (withheldLinks.has(JSON.stringify([m.publicKey, m.prev])))
+                    excused = true;
+                else
+                    deviations.push({ kind: "chain_link_dangling", eventId: m.eventId, chainKey });
+            }
+        }
+        if (excused)
+            notes.push({ kind: "chain_claim_withheld", chainKey });
+    }
+    return { deviations, notes };
+}
 /**
  * Read the claim a pack's declaration makes, without grading the pack.
  *
@@ -986,6 +1144,13 @@ export function renderDeclarationSummary(check) {
             `and in ${check.contentFindings.length} way(s) it does not line up with the ` +
             "unsigned content handed in beside it, which anyone could have supplied");
     }
+    if (check.verdict === "partial" && (check.chains ?? []).length > 0) {
+        // Read before the branch below: the declaration WAS read, and its chain
+        // claim was not checked because the caller gave no reading.
+        return ("this pack holds what it declares, and says its chains are complete " +
+            "and in order, which this verifier did not check, so whether they " +
+            "are is UNKNOWN");
+    }
     if (check.verdict === "partial") {
         return ("this pack says what it holds in a declaration this verifier cannot read, " +
             "so whether it is complete is UNKNOWN");
@@ -1017,6 +1182,11 @@ export function renderNote(note) {
             return (`${note.eventId} is signed as a declaration and no content for it ` +
                 "reached this verifier, so whether it is a declaration other than " +
                 "this pack's own is UNKNOWN");
+        case "chain_claim_withheld":
+            return (`this pack declares chain ${note.chainKey} complete and in order, ` +
+                "and a link in it points at a record its producer signed and this " +
+                "pack withholds: the pointer equals that record's signed " +
+                "payload_hash, and the record's bytes are not here to read");
     }
 }
 /**
@@ -1072,5 +1242,19 @@ export function renderDeviation(deviation) {
         case "role_step_unreadable":
             return (`${deviation.eventId} is signed as a step and this pack carries ` +
                 "record bytes for it that this verifier cannot read");
+        case "chain_second_root":
+            return (`${deviation.eventId} begins chain ${deviation.chainKey} a second ` +
+                "time, and the declaration says that chain is complete and in order");
+        case "chain_fork":
+            return (`${deviation.eventId} in chain ${deviation.chainKey} points at a ` +
+                "record another record of that chain already points at, and the " +
+                "declaration says that chain is complete and in order");
+        case "chain_link_dangling":
+            return (`${deviation.eventId} in chain ${deviation.chainKey} points at a ` +
+                "record of that chain this pack does not present, and the " +
+                "declaration says that chain is complete and in order");
+        case "chain_claimed_absent":
+            return (`the declaration says chain ${deviation.chainKey} is complete and ` +
+                "in order, and this pack presents no record of it");
     }
 }

package/dist/environment.d.ts

@@ -0,0 +1,42 @@
+import { type EvidenceBundleResult } from "./evidence.js";
+/** `"dev"` when every envelope is signed `dev`, `"mixed"` when only some are. */
+export type EnvironmentMarker = "dev" | "mixed";
+/** The headline `verify` prints for sandbox evidence in place of `VERIFIED`. */
+export declare const SANDBOX_HEADLINE = "SANDBOX";
+/** The title `case` prints for sandbox evidence in place of `Verified` (case titles are title case). */
+export declare const SANDBOX_TITLE = "Sandbox";
+/** The one line printed with it, and with any other headline, wherever the marker is present. */
+export declare const SANDBOX_LINE = "Sandbox evidence (environment dev): not production evidence";
+/**
+ * The signed envelopes a pack holds: every checkpoint and event envelope of an
+ * anchor-trace body, every event envelope of a stamp-evidence body, the same
+ * inside an export's inline source bundle, and an agent proof's checkpoint
+ * envelope. A stamp-trace body holds none. A value that is not an object is
+ * not an envelope and is not counted.
+ */
+export declare function packEnvelopes(bundle: unknown): Record<string, unknown>[];
+/**
+ * The environment marker over one or more packs: `"dev"` where every envelope
+ * they hold is signed `environment: "dev"`, `"mixed"` where some are and some
+ * are not (`production`, or no `environment` at all), and `null` where none
+ * is, which is every production pack and every pack that holds no envelope.
+ */
+export declare function environmentMarker(bundles: readonly unknown[]): EnvironmentMarker | null;
+/**
+ * Whether a body's only unsettled witnesses are simulated: the body has events
+ * and witnesses (checkpoints, stamps or both), every witness is named, at
+ * least one is simulated, and every other one a gateway confirmed. Then the
+ * one thing that keeps the bundle from `verified` is a simulated witness
+ * nobody can look up: no mismatch, no unreachable gateway, no witness of
+ * another kind, no checkpoint or stamp witnessed by nobody.
+ */
+export declare function onlySimulatedUnsettled(result: EvidenceBundleResult): boolean;
+/**
+ * Whether a run with gateways counted only simulated witnesses, so nothing
+ * was looked up on a chain: gateways were passed, the run is not counted as
+ * checked on a chain, and it holds a simulated witness. A run that stopped
+ * before its witnesses were read (a bad wrapper signature or `body_hash`, an
+ * unknown `body_type`, an export whose source is not inline) holds none, so it
+ * is not one, and prints what it printed before simulated witnesses existed.
+ */
+export declare function simulatedOnlyRun(result: EvidenceBundleResult, gateways: readonly string[]): boolean;

package/dist/environment.js

@@ -0,0 +1,136 @@
+// The environment marker: is this sandbox evidence?
+//
+// `environment` is an OPTIONAL skeleton field inside every envelope's signed
+// scope, `"dev"` or `"production"` (envelope-spec §2, A1 and A9). The spec
+// says a verifier MAY surface the value as `environment_marker` in its result
+// and a profile MAY refuse to count dev-marked envelopes toward production
+// evidence. Both commands now do the first, and print a pack or case that
+// holds a `dev` envelope as sandbox evidence rather than as `VERIFIED`.
+//
+// The marker is read from the signed envelopes the pack holds, never from a
+// wrapper field, a pack name or anything else the holder could write without a
+// key. It never moves the verdict word: a sandbox pack that verifies is still
+// `verified`, and the commands map that to the headline `SANDBOX` and exit 5
+// (`sandboxExit` in `./exit-codes.ts`). The Python twin is
+// `src/sanning_proof/environment.py`.
+import { isAgentProofSpec } from "./agent-proof.js";
+import { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, SIMULATED_WITNESS_KIND, STAMP_EVIDENCE_BODY_TYPE, } from "./evidence.js";
+/** The headline `verify` prints for sandbox evidence in place of `VERIFIED`. */
+export const SANDBOX_HEADLINE = "SANDBOX";
+/** The title `case` prints for sandbox evidence in place of `Verified` (case titles are title case). */
+export const SANDBOX_TITLE = "Sandbox";
+/** The one line printed with it, and with any other headline, wherever the marker is present. */
+export const SANDBOX_LINE = "Sandbox evidence (environment dev): not production evidence";
+// The same bound `resolveTraceEvents` puts on unwrapping export wrappers.
+const MAX_EXPORT_UNWRAP = 4;
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function own(o, key) {
+    return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+function entryEnvelopes(list, out) {
+    if (!Array.isArray(list))
+        return;
+    for (const entry of list) {
+        if (!isObject(entry))
+            continue;
+        const env = own(entry, "envelope");
+        if (isObject(env))
+            out.push(env);
+    }
+}
+/**
+ * The signed envelopes a pack holds: every checkpoint and event envelope of an
+ * anchor-trace body, every event envelope of a stamp-evidence body, the same
+ * inside an export's inline source bundle, and an agent proof's checkpoint
+ * envelope. A stamp-trace body holds none. A value that is not an object is
+ * not an envelope and is not counted.
+ */
+export function packEnvelopes(bundle) {
+    const out = [];
+    if (isObject(bundle) && isAgentProofSpec(own(bundle, "spec_version"))) {
+        const env = own(bundle, "checkpoint_envelope");
+        if (isObject(env))
+            out.push(env);
+        return out;
+    }
+    let cur = bundle;
+    for (let depth = 0; depth < MAX_EXPORT_UNWRAP; depth++) {
+        if (!isObject(cur))
+            return out;
+        const bodyType = own(cur, "body_type");
+        const body = own(cur, "body");
+        if (!isObject(body))
+            return out;
+        if (bodyType === ANCHOR_TRACE_BODY_TYPE) {
+            entryEnvelopes(own(body, "checkpoints"), out);
+            entryEnvelopes(own(body, "events"), out);
+            return out;
+        }
+        if (bodyType === STAMP_EVIDENCE_BODY_TYPE) {
+            entryEnvelopes(own(body, "events"), out);
+            return out;
+        }
+        if (bodyType !== EXPORT_BODY_TYPE)
+            return out;
+        cur = own(body, "source_bundle");
+    }
+    return out;
+}
+/**
+ * The environment marker over one or more packs: `"dev"` where every envelope
+ * they hold is signed `environment: "dev"`, `"mixed"` where some are and some
+ * are not (`production`, or no `environment` at all), and `null` where none
+ * is, which is every production pack and every pack that holds no envelope.
+ */
+export function environmentMarker(bundles) {
+    let total = 0;
+    let dev = 0;
+    for (const bundle of bundles) {
+        for (const env of packEnvelopes(bundle)) {
+            total++;
+            if (own(env, "environment") === "dev")
+                dev++;
+        }
+    }
+    if (dev === 0)
+        return null;
+    return dev === total ? "dev" : "mixed";
+}
+/**
+ * Whether a body's only unsettled witnesses are simulated: the body has events
+ * and witnesses (checkpoints, stamps or both), every witness is named, at
+ * least one is simulated, and every other one a gateway confirmed. Then the
+ * one thing that keeps the bundle from `verified` is a simulated witness
+ * nobody can look up: no mismatch, no unreachable gateway, no witness of
+ * another kind, no checkpoint or stamp witnessed by nobody.
+ */
+export function onlySimulatedUnsettled(result) {
+    const witnesses = [...result.checkpoints, ...(result.stamps ?? [])];
+    if (witnesses.length === 0 || result.events.length === 0)
+        return false;
+    let simulated = 0;
+    for (const w of witnesses) {
+        if (w.anchorRef === null)
+            return false;
+        if (w.anchorRef.kind === SIMULATED_WITNESS_KIND)
+            simulated++;
+        else if (w.onChain?.rollup !== "confirm")
+            return false;
+    }
+    return simulated > 0;
+}
+/**
+ * Whether a run with gateways counted only simulated witnesses, so nothing
+ * was looked up on a chain: gateways were passed, the run is not counted as
+ * checked on a chain, and it holds a simulated witness. A run that stopped
+ * before its witnesses were read (a bad wrapper signature or `body_hash`, an
+ * unknown `body_type`, an export whose source is not inline) holds none, so it
+ * is not one, and prints what it printed before simulated witnesses existed.
+ */
+export function simulatedOnlyRun(result, gateways) {
+    if (gateways.length === 0 || result.onChainChecked)
+        return false;
+    return [...result.checkpoints, ...(result.stamps ?? [])].some((w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND);
+}

package/dist/evidence.d.ts

@@ -464,6 +464,12 @@ export declare function coSignaturesPresent(b: unknown): boolean;
 /** evidence-bundle §2 (A31). Byte-identical to the Python kernel's. */
 export declare const GENERATED_AT_MALFORMED = "malformed generated_at: not an RFC 3339 UTC date-time with Z naming a real date and time (evidence-bundle \u00A72)";
 export declare function verifyEvidenceBundle(bundle: unknown, options?: VerifyEvidenceOptions): Promise<EvidenceBundleResult>;
+/**
+ * The `anchor_ref.kind` a sandbox plane writes for a witness it simulated
+ * (chain id `sanning-sandbox`). Never looked up and never counted as checked
+ * on a chain.
+ */
+export declare const SIMULATED_WITNESS_KIND = "simulated";
 export type DisclosureStatus = "verified" | "not_disclosed" | "undetermined" | "failed";
 export interface DisclosedEventContent {
     eventId: string;