@sanning/proof 0.18.0 → 0.19.1

package/src/declaration.ts

@@ -131,6 +131,7 @@
 // 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 type { ChainLink } from "./chain.js";
 import { hexToBytes, utf8 } from "./crypto.js";
 import { jcs, jcsParse } from "./verifier.js";
 import { isConformantHandoffRecord, isHandoffNamespace, type HandoffRecord } from "./handoff.js";
@@ -151,8 +152,23 @@ export const DECLARATION_VERSION = "sanning.declaration/v1";
  */
 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] as const;
+export const DECLARATION_VERSIONS = [
+  DECLARATION_VERSION,
+  DECLARATION_VERSION_V2,
+  DECLARATION_VERSION_V3,
+] as const;
+
+/** The versions whose every `records[]` entry carries a signed `role`. */
+const ROLE_VERSIONS: readonly string[] = [DECLARATION_VERSION_V2, DECLARATION_VERSION_V3];
 
 /**
  * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
@@ -205,6 +221,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",
 ] as const;
 export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 
@@ -300,6 +328,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",
 ] as const;
 export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
@@ -320,6 +356,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`. */
@@ -339,6 +377,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 {
@@ -377,6 +417,12 @@ export interface DeclarationCheck {
    * Empty for v1, and for anything this reader could not read.
    */
   roles?: { 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[];
 }
 
 // ---- Reading the pack --------------------------------------------------------
@@ -385,7 +431,7 @@ interface DeclarationBundleLike {
   body?: {
     declaration?: unknown;
     events?: {
-      envelope?: { event_id?: unknown; public_key?: unknown };
+      envelope?: { event_id?: unknown; public_key?: unknown; payload_hash?: unknown };
       content?: unknown;
       event_bytes?: unknown;
     }[];
@@ -504,6 +550,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;
 }
 
 /**
@@ -545,6 +604,8 @@ export function packRecords(
       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 : "",
     };
   });
 }
@@ -568,6 +629,7 @@ interface ReadDeclaration {
   records: { eventId: string; withheld: boolean }[];
   pairs: { sent: string | null; received: string | null }[];
   roles: { eventId: string; role: DeclarationRole }[];
+  chains: string[];
 }
 
 /**
@@ -587,7 +649,7 @@ function readDeclaration(
   // 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: { eventId: string; role: DeclarationRole }[] = [];
-  const v2 = version === DECLARATION_VERSION_V2;
+  const v2 = ROLE_VERSIONS.includes(version);
   const note = (r: string) => reasons.push(r);
 
   if (!isId(declaration["case_id"])) note("case_id is not a non-empty string");
@@ -665,7 +727,31 @@ function readDeclaration(
     }
   }
 
-  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: string[] = [];
+  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"] as string;
+        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 ---------------------------------------------------------------
@@ -680,6 +766,7 @@ const noDeclaration = (): DeclarationCheck => ({
   declaredWithheld: [],
   version: null,
   roles: [],
+  chains: [],
 });
 
 /**
@@ -690,7 +777,9 @@ const noDeclaration = (): DeclarationCheck => ({
 function knownVersion(declaration: unknown): string | null {
   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 as readonly string[]).includes(version)
+    ? version
+    : null;
 }
 
 /**
@@ -752,16 +841,19 @@ function hasExactKeys(value: unknown, keys: string[]): value is Record<string, u
 function isDeclarationShape(obj: unknown): boolean {
   if (!isObject(obj)) return false;
   const version = obj["declaration_version"];
-  if (version !== DECLARATION_VERSION && version !== DECLARATION_VERSION_V2) return false;
-  if (!hasExactKeys(obj, DECLARATION_KEYS)) return false;
+  if (typeof version !== "string" || !(DECLARATION_VERSIONS as readonly string[]).includes(version))
+    return false;
+  const v3 = version === DECLARATION_VERSION_V3;
+  if (!hasExactKeys(obj, v3 ? [...DECLARATION_KEYS, "chains"] : DECLARATION_KEYS)) return false;
   if (!isId(obj["case_id"])) return false;
   const agents = obj["agents"];
   if (!Array.isArray(agents) || !agents.every((a) => typeof a === "string")) return false;
   const period = obj["period"];
   if (!hasExactKeys(period, ["start", "end"])) 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;
   for (const r of records) {
@@ -769,7 +861,13 @@ function isDeclarationShape(obj: unknown): boolean {
   }
   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")
+  );
 }
 
 /**
@@ -871,6 +969,14 @@ function otherDeclarationNotes(
  * 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.
@@ -878,6 +984,7 @@ function otherDeclarationNotes(
 export function checkDeclaration(
   bundle: unknown,
   content?: SideContentMap | null,
+  links?: readonly ChainLink[] | null,
 ): DeclarationCheck {
   // `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
@@ -922,10 +1029,12 @@ export function checkDeclaration(
       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);
@@ -1080,6 +1189,19 @@ export function checkDeclaration(
     }
   }
 
+  // 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
@@ -1093,7 +1215,11 @@ export function checkDeclaration(
   // only unsigned bytes could settle, which is UNDETERMINED: `partial` is
   // 3's word for that, and it adds none.
   const verdict: DeclarationVerdict =
-    deviations.length > 0 ? "failed" : contentFindings.length > 0 ? "partial" : "verified";
+    deviations.length > 0
+      ? "failed"
+      : contentFindings.length > 0 || unread
+        ? "partial"
+        : "verified";
 
   return {
     verdict,
@@ -1105,9 +1231,75 @@ export function checkDeclaration(
     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: string[],
+  links: readonly ChainLink[],
+  pack: { publicKey: string; bindingUndetermined: boolean; payloadHash: string }[],
+): { deviations: DeclarationDeviation[]; notes: DeclarationNote[] } {
+  const deviations: DeclarationDeviation[] = [];
+  const notes: DeclarationNote[] = [];
+  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<string, Set<string>>();
+    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<string>();
+    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 };
+}
+
 // ---- Presentation (optional) -------------------------------------------------
 
 /**
@@ -1257,6 +1449,15 @@ export function renderDeclarationSummary(check: DeclarationCheck): string {
       "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, " +
@@ -1303,6 +1504,13 @@ export function renderNote(note: DeclarationNote): string {
         "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"
+      );
   }
 }
 
@@ -1380,5 +1588,27 @@ export function renderDeviation(deviation: DeclarationDeviation): string {
         `${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/src/environment.ts

@@ -0,0 +1,145 @@
+// 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,
+  type EvidenceBundleResult,
+  SIMULATED_WITNESS_KIND,
+  STAMP_EVIDENCE_BODY_TYPE,
+} 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 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: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function own(o: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(o, key) ? o[key] : undefined;
+}
+
+function entryEnvelopes(list: unknown, out: Record<string, unknown>[]): void {
+  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: unknown): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  if (isObject(bundle) && isAgentProofSpec(own(bundle, "spec_version"))) {
+    const env = own(bundle, "checkpoint_envelope");
+    if (isObject(env)) out.push(env);
+    return out;
+  }
+  let cur: unknown = 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: readonly unknown[]): EnvironmentMarker | null {
+  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: EvidenceBundleResult): boolean {
+  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: EvidenceBundleResult, gateways: readonly string[]): boolean {
+  if (gateways.length === 0 || result.onChainChecked) return false;
+  return [...result.checkpoints, ...(result.stamps ?? [])].some(
+    (w) => w.anchorRef?.kind === SIMULATED_WITNESS_KIND,
+  );
+}

package/src/evidence.ts

@@ -1662,6 +1662,10 @@ async function verifyAnchorTrace(
   let gatewayUnavailable = false;
   let uncheckedKind = false;
   let uncheckedId = false;
+  // Simulated witnesses against witnesses of any other kind, counted over the
+  // checkpoints that name one, as `refetchStamps` counts stamps.
+  let simulated = 0;
+  let onChainKinds = 0;
   if (onChainChecked) {
     if (typeof fetchImpl !== "function") {
       gatewayUnavailable = true;
@@ -1701,6 +1705,8 @@ async function verifyAnchorTrace(
           cpr.errors.push("checkpoint has no anchor_ref -- not yet witnessed, nothing to re-fetch");
           continue;
         }
+        if (cpr.anchorRef.kind === SIMULATED_WITNESS_KIND) simulated++;
+        else onChainKinds++;
         const outcome = await refetchCheckpoint(cp, cpr.anchorRef, gateways, fetchImpl);
         cpr.onChain = outcome.onChain;
         cpr.onChainOk = outcome.onChain?.onChainOk ?? null;
@@ -1764,7 +1770,10 @@ async function verifyAnchorTrace(
     bodyHashOk: true,
     signatureOk: true,
     bodyType,
-    onChainChecked,
+    // A run whose only witnessed checkpoints are simulated looked nothing up
+    // on a chain, so it is not counted as checked on one (the stamp rule in
+    // `refetchStamps`). The checkpoints stay not checked and the run partial.
+    onChainChecked: onChainChecked && !(simulated > 0 && onChainKinds === 0),
     checkpoints: checkpointResults,
     events: eventResults,
     assertedStatus,
@@ -2679,12 +2688,16 @@ async function refetchStamps(
   let gatewayUnavailable = false;
   let uncheckedKind = false;
   let uncheckedId = false;
+  let simulated = 0;
+  let onChainKinds = 0;
   for (let i = 0; i < stamps.length; i++) {
     const st = stamps[i]!;
     const witnessedHex = witnessed[i];
     // No witness named, or bytes we could not read: nothing to re-fetch, and
     // nothing a gateway could confirm or deny. Left as `onChain: null`.
     if (st.anchorRef === null || witnessedHex === undefined) continue;
+    if (st.anchorRef.kind === SIMULATED_WITNESS_KIND) simulated++;
+    else onChainKinds++;
 
     const outcome = await refetchStamp(witnessedHex, st.anchorRef, gateways, fetchImpl);
     st.onChain = outcome.onChain;
@@ -2704,9 +2717,24 @@ async function refetchStamps(
     // unreachable note would fail a stamp for a gateway being down.
     st.ok = st.ok && st.onChainOk !== false;
   }
+  // A simulated witness is a sandbox plane's stand-in for a chain: there is no
+  // chain to look it up on, so it is never counted as checked on one.
+  // It stays not checked like any kind this verifier has no adapter for, and
+  // the run stays undetermined; what changes is that a run whose only
+  // witnesses are simulated no longer says it checked anything on a chain.
+  if (simulated > 0 && onChainKinds === 0) {
+    return { onChainChecked: false, gatewayUnavailable, uncheckedKind, uncheckedId };
+  }
   return { onChainChecked, gatewayUnavailable, uncheckedKind, uncheckedId };
 }
 
+/**
+ * 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 const SIMULATED_WITNESS_KIND = "simulated";
+
 interface StampRefetchSummary {
   onChainChecked: boolean;
   gatewayUnavailable: boolean;