@sanning/proof 0.18.0 → 0.19.1

package/src/run.ts

@@ -0,0 +1,1598 @@
+// The run reading: the enclave attestation line and the run-account line.
+//
+// DRAFT. `specs/enclave-attestation.md` and `specs/run-records.md` define both
+// lines; this module is their provider-neutral half, the twin of
+// `src/sanning_proof/run.py`. It changes no verdict, no exception and no exit
+// code: a drop without an opening record reads exactly as it did before, and a
+// drop with one gets two lines beside the verdict.
+//
+// No new cryptography. The kernel has already verified every envelope and every
+// stamp; this module reads the records it verified and adds SHA-256 and
+// comparisons. The token, the certificate chain and the result signature are an
+// ADAPTER's, a separate package. `readRuns` imports nothing: a caller passes the
+// adapters it loaded (see `run-adapters.ts`, Node-only), and without one every
+// opening record reads `not_checked` with `no_adapter`.
+
+import { bytesToHex, hexToBytes, sha256Hex, utf8 } from "./crypto.js";
+import { verifyEvidenceBundle } from "./evidence.js";
+import { sideContentEntry, sideContentKeys, type SideContentMap } from "./side-content.js";
+import {
+  DuplicateKeyError,
+  exceedsTextDepth,
+  jcs,
+  jcsParse,
+  jcsParseWithinLimits,
+  MAX_READ_DEPTH,
+  renderKey,
+} from "./verifier.js";
+
+export const ATTESTATION_VERSION = "sanning.enclave-attestation/v1";
+export const BINDING_VERSION = "sanning.run-binding/v1";
+export const POLICY_VERSION = "sanning.enclave-policy/v1";
+export const MANIFEST_VERSION = "sanning.run-manifest/v1";
+export const RUN_OPENED = "runner.run_opened";
+export const RUN_CLOSED = "runner.run_closed";
+const RUNNER_PREFIX = "runner.";
+export const PROVIDER_GCP = "gcp-confidential-space";
+export const PROVIDER_FLARE = "flare-fcc";
+
+/**
+ * The fixed table: provider id to the package that answers for it. A provider
+ * id read from a pack is looked up HERE and nowhere else, so a pack naming `os`
+ * or `../x` loads nothing.
+ */
+export const ADAPTER_MODULES: Readonly<Record<string, string>> = Object.freeze({
+  [PROVIDER_GCP]: "@sanning/enclave-gcp",
+  [PROVIDER_FLARE]: "@sanning/enclave-flare",
+});
+
+/** Printed after an enclave line whose token was checked. Never a state. */
+export const REVOCATION_SENTENCE =
+  "enclave attestation: revocation not checked " +
+  "(the pack carries no certificate revocation lists)";
+
+export const ENCLAVE_STATES = ["confirmed", "differs", "not_checked"] as const;
+export const RUN_ACCOUNT_STATES = ["closed", "differs", "not_closed"] as const;
+
+/** Why an enclave line reads `not_checked`. */
+export const ENCLAVE_NOT_CHECKED_KINDS = [
+  "no_adapter",
+  "no_attestation",
+  "unknown_version",
+  "no_policy",
+  "policy_unreadable",
+  "adapter_failed",
+  "no_opening_record",
+] as const;
+/** The provider-neutral checks that make a line `differs`, in line order. */
+export const ENCLAVE_DIFFERS_KINDS = [
+  "attestation_malformed",
+  "subject_key_not_signer",
+  "manifest_not_content",
+  "binding_other_run",
+  "binding_other_manifest",
+  "binding_other_keys",
+  "signed_at_outside_tolerance",
+  "manifest_content_mismatch",
+  "manifest_unreadable",
+  "case_hash_differs",
+  "agent_record_under_runner_key",
+] as const;
+/** The kinds an adapter may answer with; any other reads `adapter_failed`. */
+export const ENCLAVE_NOTE_KINDS = ["no_issue_time", "manifest_withheld", "stamp_unwitnessed"] as const;
+/**
+ * Every kind and note the kernel itself names. An adapter declares its own
+ * failure kinds (its `kinds`, section 9); none of them may be one of these, so
+ * an adapter can never speak for a neutral check.
+ */
+export const NEUTRAL_KINDS: ReadonlySet<string> = new Set<string>([
+  ...ENCLAVE_NOT_CHECKED_KINDS,
+  ...ENCLAVE_DIFFERS_KINDS,
+  ...ENCLAVE_NOTE_KINDS,
+]);
+/** The form of a kind an adapter declares: snake_case, one word on the line. */
+const KIND_FORM = /^[a-z][a-z0-9_]{0,63}$/;
+export const ACCOUNT_FINDING_KINDS = [
+  "record_not_listed",
+  "listed_record_absent",
+  "more_than_one_closing_record",
+  "closing_malformed",
+] as const;
+/**
+ * Why the online line (`flare-fcc` only, section 8) reads `not_checked`:
+ * nothing was decided. `adapter_failed` is the kernel's.
+ */
+export const ONLINE_NOT_CHECKED_KINDS = [
+  "adapter_failed",
+  "evidence_not_confirmed",
+  "no_contracts",
+  "manifest_withheld",
+  "manifest_unreadable",
+  "chain_unavailable",
+  "not_final",
+] as const;
+/** Why the online line reads `differs`: the chain answered, and it does not match. */
+export const ONLINE_DIFFERS_KINDS = [
+  "instruction_count",
+  "instruction_other_extension",
+  "instruction_other_machine",
+  "instruction_other_operation",
+  "instruction_other_message",
+  "transaction_failed",
+  "log_malformed",
+  "run_opened_differs",
+  "run_opened_count",
+  "machine_not_production",
+  "machine_other_extension",
+  "code_not_supported",
+  "call_reverted",
+] as const;
+export const ACCOUNT_NOTE_KINDS = [
+  "agent_key_unknown",
+  "runner_record_under_agent_key",
+  "runner_record_bytes_withheld",
+  "payload_hashes_absent",
+  "unacknowledged_record_absent",
+] as const;
+
+const SAFE = Number.MAX_SAFE_INTEGER;
+const U32 = 2 ** 32 - 1;
+const U8 = 255;
+
+const LOWER_HEX64 = /^[0-9a-f]{64}$/;
+const HEX_0X = /^0x(?:[0-9a-fA-F]{2})*$/;
+const LOWER_0X = /^0x(?:[0-9a-f]{2})*$/;
+const B64URL_32 = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * A plane's origin (section 4): http or https, a lowercase host (a DNS name, an
+ * IPv4 address, or an IPv6 address in brackets), and an optional port from 1
+ * to 65535 with no leading zero, never the scheme's default (443, 80). Nothing
+ * after it: no path, no trailing slash.
+ */
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const ORIGIN = new RegExp(
+  `^https?://(?:${LABEL}(?:\\.${LABEL})*|\\[([0-9a-f:.]+)\\])` +
+    "(?::(?:6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?$",
+);
+
+/** A plane origin in its one form (section 4): `isOrigin` in Python. */
+function isOrigin(value: string): boolean {
+  const m = ORIGIN.exec(value);
+  if (m === null) return false;
+  if (m[1] !== undefined && !isIpv6Text(m[1])) return false;
+  return !value.endsWith(value.startsWith("https://") ? ":443" : ":80");
+}
+
+const isHex = (c: string): boolean => c !== "" && "0123456789abcdef".includes(c);
+const isDigit = (c: string): boolean => c !== "" && c >= "0" && c <= "9";
+
+/**
+ * Whether `s`, the text between a host's brackets, is an IPv6 address as the
+ * WHATWG URL Standard's IPv6 parser accepts one (RFC 4291 text form), in
+ * lowercase. A step for step port of the parser, the twin of Python's
+ * `is_ipv6_text` and the runner's `run.IsPlaneOrigin`.
+ */
+export function isIpv6Text(s: string): boolean {
+  const n = s.length;
+  const at = (k: number): string => (k < n ? s[k]! : "");
+  let i = 0;
+  let piece = 0;
+  let compress: number | null = null;
+  if (at(i) === ":") {
+    if (at(i + 1) !== ":") return false;
+    i += 2;
+    piece += 1;
+    compress = piece;
+  }
+  while (i < n) {
+    if (piece === 8) return false;
+    if (s[i] === ":") {
+      if (compress !== null) return false;
+      i += 1;
+      piece += 1;
+      compress = piece;
+      continue;
+    }
+    let length = 0;
+    while (length < 4 && isHex(at(i))) {
+      i += 1;
+      length += 1;
+    }
+    if (at(i) === ".") {
+      if (length === 0) return false;
+      i -= length;
+      if (piece > 6) return false;
+      let seen = 0;
+      while (i < n) {
+        if (seen > 0) {
+          if (s[i] === "." && seen < 4) i += 1;
+          else return false;
+        }
+        if (!isDigit(at(i))) return false;
+        let part: number | null = null;
+        while (isDigit(at(i))) {
+          const d = Number(s[i]);
+          if (part === null) part = d;
+          else if (part === 0) return false;
+          else part = part * 10 + d;
+          if (part > 255) return false;
+          i += 1;
+        }
+        seen += 1;
+        if (seen === 2 || seen === 4) piece += 1;
+      }
+      if (seen !== 4) return false;
+      break;
+    }
+    if (at(i) === ":") {
+      i += 1;
+      if (i === n) return false;
+    } else if (i < n) {
+      return false;
+    }
+    piece += 1;
+  }
+  return compress !== null || piece === 8;
+}
+
+const INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?Z$/;
+
+// ---- The strict reader ------------------------------------------------------
+
+/** The object does not read under the one spelling. The message is the reason. */
+export class AttestationRefused extends Error {}
+
+/** `attestation_version` is a string this reader does not know. */
+export class UnknownAttestationVersion extends AttestationRefused {}
+
+type Node =
+  | { kind: "obj"; members: readonly (readonly [string, Node])[] }
+  | { kind: "any" }
+  | { kind: "str" | "nstr" | "lhex64" | "hex" | "origin" }
+  | { kind: "const"; value: string }
+  | { kind: "hexn" | "lhexn"; bytes: number }
+  | { kind: "int"; max: number };
+
+const obj = (members: readonly (readonly [string, Node])[]): Node => ({ kind: "obj", members });
+const STR: Node = { kind: "str" };
+const NSTR: Node = { kind: "nstr" };
+const LHEX64: Node = { kind: "lhex64" };
+const HEX: Node = { kind: "hex" };
+const ORIGIN_NODE: Node = { kind: "origin" };
+const hexn = (bytes: number): Node => ({ kind: "hexn", bytes });
+const lhexn = (bytes: number): Node => ({ kind: "lhexn", bytes });
+const int = (max: number): Node => ({ kind: "int", max });
+const konst = (value: string): Node => ({ kind: "const", value });
+
+const SUBJECT = [
+  ["runner_public_key", LHEX64],
+  ["agent_public_key", LHEX64],
+  ["manifest_hash", LHEX64],
+  ["run_id", NSTR],
+] as const;
+
+const ATTESTATION = [
+  ["attestation_version", konst(ATTESTATION_VERSION)],
+  ["subject", obj(SUBJECT)],
+  ["provider", NSTR],
+  ["evidence", { kind: "any" } as Node],
+] as const;
+
+function bindingSchema(request: readonly (readonly [string, Node])[]): (readonly [string, Node])[] {
+  return [
+    ["binding_version", konst(BINDING_VERSION)],
+    ["run_id", NSTR],
+    ["manifest_hash", LHEX64],
+    ["runner_public_key", LHEX64],
+    ["agent_public_key", LHEX64],
+    ["credential_public_key", LHEX64],
+    ["case_hash", LHEX64],
+    ["plane", ORIGIN_NODE],
+    ["request", obj(request)],
+  ];
+}
+
+const GCP_BINDING = bindingSchema([["provider", konst(PROVIDER_GCP)]]);
+const FLARE_BINDING = bindingSchema([
+  ["provider", konst(PROVIDER_FLARE)],
+  ["chain_id", int(SAFE)],
+  ["instruction_id", lhexn(32)],
+  ["tee_id", lhexn(20)],
+  ["opener", lhexn(20)],
+]);
+const GCP_EVIDENCE = [
+  ["binding", obj(GCP_BINDING)],
+  ["token", NSTR],
+] as const;
+const PUBLIC_KEY = [
+  ["x", hexn(32)],
+  ["y", hexn(32)],
+] as const;
+const TEE_INFO = [
+  ["challenge", hexn(32)],
+  ["publicKey", obj(PUBLIC_KEY)],
+  ["initialSigningPolicyId", int(U32)],
+  ["initialSigningPolicyHash", hexn(32)],
+  ["lastSigningPolicyId", int(U32)],
+  ["lastSigningPolicyHash", hexn(32)],
+  ["chainId", int(SAFE)],
+  [
+    "state",
+    obj([
+      ["systemState", HEX],
+      ["systemStateVersion", hexn(32)],
+      ["state", HEX],
+      ["stateVersion", hexn(32)],
+    ]),
+  ],
+  ["teeTimestamp", int(SAFE)],
+  ["machinePathListNonce", int(SAFE)],
+  ["machinePathListHash", hexn(32)],
+] as const;
+const MACHINE_DATA = [
+  ["extensionId", hexn(32)],
+  ["initialOwner", hexn(20)],
+  ["codeHash", hexn(32)],
+  ["platform", hexn(32)],
+  ["publicKey", obj(PUBLIC_KEY)],
+  ["governanceHash", hexn(32)],
+] as const;
+const INFO = [
+  ["teeInfo", obj(TEE_INFO)],
+  ["machineData", obj(MACHINE_DATA)],
+  ["dataSignature", HEX],
+  ["attestation", STR],
+] as const;
+const RESULT = [
+  ["id", hexn(32)],
+  ["submissionTag", STR],
+  ["status", int(U8)],
+  ["log", STR],
+  ["opType", hexn(32)],
+  ["opCommand", hexn(32)],
+  ["additionalResultStatus", HEX],
+  ["version", STR],
+  ["data", HEX],
+] as const;
+const FLARE_EVIDENCE = [
+  ["result", obj(RESULT)],
+  ["signature", HEX],
+  ["info", obj(INFO)],
+] as const;
+
+const EVIDENCE: Readonly<Record<string, readonly (readonly [string, Node])[]>> = {
+  [PROVIDER_GCP]: GCP_EVIDENCE,
+  [PROVIDER_FLARE]: FLARE_EVIDENCE,
+};
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function has(o: Record<string, unknown>, k: string): boolean {
+  return Object.prototype.hasOwnProperty.call(o, k);
+}
+
+/** A JSON number whose value is a whole number within 2^53 - 1. */
+function wholeNumber(v: unknown): number | null {
+  return typeof v === "number" && Number.isSafeInteger(v) ? v + 0 : null;
+}
+
+function walk(value: unknown, node: Node, path: string): void {
+  switch (node.kind) {
+    case "any":
+      if (!isPlainObject(value)) throw new AttestationRefused(`${path} must be an object`);
+      return;
+    case "obj": {
+      if (!isPlainObject(value)) throw new AttestationRefused(`${path} must be an object`);
+      const allowed = new Set(node.members.map(([name]) => name));
+      const unknown = Object.keys(value)
+        .filter((k) => !allowed.has(k))
+        .sort();
+      if (unknown.length > 0) {
+        throw new AttestationRefused(`${path}: unknown member ${renderKey(unknown[0]!)}`);
+      }
+      for (const [name, sub] of node.members) {
+        if (!has(value, name)) throw new AttestationRefused(`${path}.${name} is required`);
+        walk(value[name], sub, `${path}.${name}`);
+      }
+      return;
+    }
+    case "int": {
+      const n = wholeNumber(value);
+      if (n === null) throw new AttestationRefused(`${path} must be a whole number`);
+      if (n < 0 || n > node.max) throw new AttestationRefused(`${path} is out of range`);
+      return;
+    }
+  }
+  if (typeof value !== "string") throw new AttestationRefused(`${path} must be a string`);
+  switch (node.kind) {
+    case "str":
+      return;
+    case "nstr":
+      if (value === "") throw new AttestationRefused(`${path} must be a non-empty string`);
+      return;
+    case "const":
+      if (value !== node.value) throw new AttestationRefused(`${path} must be ${renderKey(node.value)}`);
+      return;
+    case "lhex64":
+      if (!LOWER_HEX64.test(value)) {
+        throw new AttestationRefused(`${path} must be 64 lowercase hex characters`);
+      }
+      return;
+    case "hex":
+    case "hexn":
+      if (!HEX_0X.test(value)) throw new AttestationRefused(`${path} must be 0x-prefixed hex`);
+      if (node.kind === "hexn" && value.length !== 2 + 2 * node.bytes) {
+        throw new AttestationRefused(`${path} must be ${node.bytes} bytes`);
+      }
+      return;
+    case "origin":
+      if (!isOrigin(value)) {
+        throw new AttestationRefused(`${path} must be an origin (scheme://host[:port])`);
+      }
+      return;
+    case "lhexn":
+      if (!LOWER_0X.test(value) || value.length !== 2 + 2 * node.bytes) {
+        throw new AttestationRefused(
+          `${path} must be lowercase 0x-prefixed hex of ${node.bytes} bytes`,
+        );
+      }
+      return;
+  }
+}
+
+/** Whether a parsed value holds a number past 2^53 - 1 (or not finite). Iterative. */
+function hasUnsafeInteger(value: unknown): boolean {
+  const stack: unknown[] = [value];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (typeof node === "number") {
+      if (!Number.isFinite(node)) return true;
+      if (Number.isInteger(node) && !Number.isSafeInteger(node)) return true;
+    } else if (Array.isArray(node)) {
+      stack.push(...node);
+    } else if (typeof node === "object" && node !== null) {
+      stack.push(...Object.values(node));
+    }
+  }
+  return false;
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Read bytes that must be `JCS(value)`: strict UTF-8, valid JSON, no repeated
+ * name, no integer beyond 2^53 - 1, and canonical. Bytes nested deeper than
+ * every kernel canonicalizes cannot be shown to be JCS, decided on the bytes
+ * before any parser runs (section 2.1).
+ */
+function oneSpelling(raw: Uint8Array, what: string): unknown {
+  if (exceedsTextDepth(raw, MAX_READ_DEPTH)) throw new AttestationRefused(`${what} is not JCS`);
+  let value: unknown;
+  try {
+    value = jcsParse(raw);
+  } catch (err) {
+    const reason = err instanceof DuplicateKeyError ? err.message : "not JSON";
+    throw new AttestationRefused(`${what}: ${reason}`);
+  }
+  if (hasUnsafeInteger(value)) {
+    throw new AttestationRefused(`${what} holds an integer beyond 2^53 - 1`);
+  }
+  let canonical: Uint8Array | null = null;
+  try {
+    canonical = utf8(jcs(value));
+  } catch {
+    canonical = null;
+  }
+  if (canonical === null || !bytesEqual(canonical, raw)) {
+    throw new AttestationRefused(`${what} is not JCS`);
+  }
+  return value;
+}
+
+/** `sanning.run-binding/v1`, read strictly from the evidence. */
+export interface Binding {
+  runId: string;
+  manifestHash: string;
+  runnerPublicKey: string;
+  agentPublicKey: string;
+  credentialPublicKey: string;
+  caseHash: string;
+  /**
+   * The plane's origin the runner claimed the run from (section 4). Carried,
+   * not compared: the plane refuses a claim whose binding names another plane.
+   */
+  plane: string;
+  request: Readonly<Record<string, unknown>>;
+}
+
+/** `sanning.enclave-attestation/v1`, read strictly. */
+export interface Attestation {
+  runnerPublicKey: string;
+  agentPublicKey: string;
+  manifestHash: string;
+  runId: string;
+  provider: string;
+  evidence: Readonly<Record<string, unknown>>;
+  /** The binding the evidence carries, for a registered provider; else null. */
+  binding: Binding | null;
+}
+
+function readBinding(value: unknown, schema: (readonly [string, Node])[], path: string): Binding {
+  walk(value, obj(schema), path);
+  const v = value as Record<string, unknown>;
+  return {
+    runId: v.run_id as string,
+    manifestHash: v.manifest_hash as string,
+    runnerPublicKey: v.runner_public_key as string,
+    agentPublicKey: v.agent_public_key as string,
+    credentialPublicKey: v.credential_public_key as string,
+    caseHash: v.case_hash as string,
+    plane: v.plane as string,
+    request: v.request as Record<string, unknown>,
+  };
+}
+
+/** A binding as JCS text, so two bindings compare as the bytes they stand for. */
+function bindingText(b: Binding): string {
+  return jcs({
+    run_id: b.runId,
+    manifest_hash: b.manifestHash,
+    runner_public_key: b.runnerPublicKey,
+    agent_public_key: b.agentPublicKey,
+    credential_public_key: b.credentialPublicKey,
+    case_hash: b.caseHash,
+    plane: b.plane,
+    request: b.request,
+  });
+}
+
+function isBinding(v: unknown): v is Binding {
+  if (!isPlainObject(v)) return false;
+  for (const k of ["runId", "manifestHash", "runnerPublicKey", "agentPublicKey", "credentialPublicKey", "caseHash", "plane"]) {
+    if (typeof v[k] !== "string") return false;
+  }
+  return isPlainObject(v.request);
+}
+
+/**
+ * Read the `enclave_attestation` member of an opening record strictly. Throws
+ * `UnknownAttestationVersion` for a version string this reader does not know,
+ * and `AttestationRefused` for anything else that is not the one spelling.
+ */
+export function readAttestation(value: unknown): Attestation {
+  const path = "enclave_attestation";
+  if (!isPlainObject(value)) throw new AttestationRefused(`${path} must be an object`);
+  if (!has(value, "attestation_version")) {
+    throw new AttestationRefused(`${path}.attestation_version is required`);
+  }
+  const version = value.attestation_version;
+  if (typeof version !== "string") {
+    throw new AttestationRefused(`${path}.attestation_version must be a string`);
+  }
+  if (version !== ATTESTATION_VERSION) {
+    throw new UnknownAttestationVersion(
+      `${path}.attestation_version is not a version this reader knows`,
+    );
+  }
+  walk(value, obj(ATTESTATION), path);
+  const provider = value.provider as string;
+  const evidence = value.evidence as Record<string, unknown>;
+  const subject = value.subject as Record<string, string>;
+  let binding: Binding | null = null;
+  const schema = has(EVIDENCE, provider) ? EVIDENCE[provider] : undefined;
+  if (schema !== undefined) {
+    const evPath = `${path}.evidence`;
+    walk(evidence, obj(schema), evPath);
+    if (provider === PROVIDER_GCP) {
+      binding = readBinding(evidence.binding, GCP_BINDING, `${evPath}.binding`);
+    } else {
+      const dataPath = `${evPath}.result.data`;
+      const data = ((evidence.result as Record<string, unknown>).data as string).slice(2);
+      binding = readBinding(oneSpelling(hexToBytes(data), dataPath), FLARE_BINDING, dataPath);
+    }
+  }
+  return {
+    runnerPublicKey: subject.runner_public_key!,
+    agentPublicKey: subject.agent_public_key!,
+    manifestHash: subject.manifest_hash!,
+    runId: subject.run_id!,
+    provider,
+    evidence,
+    binding,
+  };
+}
+
+/** `readAttestation` over bytes that must be `JCS(object)`. */
+export function readAttestationJson(raw: Uint8Array): Attestation {
+  return readAttestation(oneSpelling(raw, "enclave_attestation"));
+}
+
+// ---- Adapters -------------------------------------------------------------------
+
+/**
+ * What an adapter answers (checks 2 to 6 and 8). `binding` is the binding the
+ * adapter verified its evidence commits to: `confirmed` without one is outside
+ * the contract and reads `adapter_failed`, because the kernel runs checks 7
+ * and 11 on that binding. Each kind is one the adapter declares in `kinds`.
+ */
+export interface AdapterResult {
+  state: (typeof ENCLAVE_STATES)[number];
+  kinds?: readonly string[];
+  /** The verified token's issue time, seconds since the epoch, or null. */
+  issuedAt?: number | null;
+  imageId?: string | null;
+  hwModel?: string | null;
+  tokenChecked?: boolean;
+  binding?: Binding | null;
+}
+
+/**
+ * An adapter: the provider it answers for, the failure kinds it declares, its
+ * check, and optionally the online line.
+ */
+export interface EnclaveAdapter {
+  provider: string;
+  kinds: readonly string[];
+  check(
+    attestation: Attestation,
+    options: { policy: Readonly<Record<string, unknown>>; at: string | null },
+  ): AdapterResult | Promise<AdapterResult>;
+  online?(
+    attestation: Attestation,
+    options: {
+      policy: Readonly<Record<string, unknown>>;
+      at: string | null;
+      manifest: Uint8Array | null;
+      rpc: string;
+    },
+  ): OnlineLine | Promise<OnlineLine>;
+}
+
+/**
+ * The online line (section 8): what the chain says of a `flare-fcc` opening,
+ * read by the adapter at the offline line's evaluation time. `confirmed`
+ * carries no kind; `not_checked` and `differs` carry one. It moves nothing.
+ */
+export interface OnlineLine {
+  state: (typeof ENCLAVE_STATES)[number];
+  kinds: string[];
+}
+
+// ---- The reading ----------------------------------------------------------------
+
+export interface EnclaveLine {
+  state: (typeof ENCLAVE_STATES)[number];
+  kinds: string[];
+  notes: string[];
+  reason: string | null;
+  provider: string | null;
+  evaluatedAt: string | null;
+  evaluation: "stamp" | "token_issue_time" | null;
+  tokenChecked: boolean;
+}
+
+export interface AccountEntry {
+  kind: string;
+  eventId: string | null;
+}
+
+export interface RunAccountLine {
+  state: (typeof RUN_ACCOUNT_STATES)[number];
+  findings: AccountEntry[];
+  notes: AccountEntry[];
+  closingEventId: string | null;
+  reason: string | null;
+}
+
+export interface RunReading {
+  /** The pack by the reader's name for it; two packs can share one (A43). */
+  packRef: string;
+  /** The pack's position among the packs read, as the case reading's `pack_index`. */
+  packIndex: number;
+  eventId: string;
+  runnerPublicKey: string;
+  agentPublicKey: string | null;
+  enclave: EnclaveLine;
+  account: RunAccountLine;
+  /** The online line, where the reader asked for one and the adapter reads the chain; else null. */
+  online: OnlineLine | null;
+}
+
+export interface RunsReading {
+  runs: RunReading[];
+}
+
+/** One pack, as `readCase` takes it. */
+export interface RunPack {
+  ref: string;
+  bundle: unknown;
+  content?: SideContentMap | null;
+}
+
+interface Held {
+  packRef: string;
+  packIndex: number;
+  eventId: string;
+  /** The envelope's key in its one lowercase form: two spellings, one key. */
+  publicKey: string;
+  payloadHash: string | null;
+  signedAt: unknown;
+  verified: boolean;
+  bytesSupplied: boolean;
+  raw: Uint8Array | null;
+  record: Record<string, unknown> | null;
+  content: Uint8Array | null;
+  /**
+   * The interval end of a stamp the kernel verified as including this record,
+   * and whether the reader's lookup confirmed that stamp's witness on the
+   * public record. Only a confirmed witness makes the interval end more than
+   * the word of whoever sealed the pack.
+   */
+  stampEnd: string | null;
+  stampWitnessed: boolean;
+}
+
+const KEY_HEX = /^[0-9a-fA-F]{64}$/;
+
+/** A key as a key: 64 hex digits of either case in their lowercase form; else as it is. */
+function asKey(value: unknown): string {
+  if (typeof value !== "string") return "";
+  return KEY_HEX.test(value) ? value.toLowerCase() : value;
+}
+
+function line(
+  state: EnclaveLine["state"],
+  kinds: string[],
+  extra: Partial<EnclaveLine> = {},
+): EnclaveLine {
+  return {
+    state,
+    kinds,
+    notes: [],
+    reason: null,
+    provider: null,
+    evaluatedAt: null,
+    evaluation: null,
+    tokenChecked: false,
+    ...extra,
+  };
+}
+
+function eventType(h: Held): string | null {
+  const t = h.record?.event_type;
+  return typeof t === "string" ? t : null;
+}
+
+// The disclosed bytes the kernel bound to this record's content_hash, by its
+// own precedence: in the body first, then beside it. Called only for a record
+// whose content the kernel bound, so the hex reads.
+function disclosed(
+  ev: Record<string, unknown>,
+  eventId: string,
+  content: SideContentMap | null | undefined,
+): Uint8Array | null {
+  if (typeof ev.content === "string") return hexToBytes(ev.content);
+  const entry = sideContentEntry(content, eventId);
+  if (!entry.offered) return null;
+  if (entry.value instanceof Uint8Array) return entry.value;
+  return hexToBytes(entry.value as string);
+}
+
+async function heldRecords(
+  pack: RunPack,
+  packIndex: number,
+  witnessedRefs: ReadonlySet<string>,
+): Promise<Held[]> {
+  const result = await verifyEvidenceBundle(pack.bundle, {
+    content: (pack.content ?? undefined) as
+      | Record<string, Uint8Array | string>
+      | ReadonlyMap<string, Uint8Array | string>
+      | undefined,
+  });
+  const bundle = pack.bundle;
+  const body = isPlainObject(bundle) ? bundle.body : undefined;
+  const events = isPlainObject(body) ? body.events : undefined;
+  // One result per body event, in order; a pack whose wrapper does not hold
+  // has none, so none of its records is read.
+  if (!Array.isArray(events) || events.length !== result.events.length) return [];
+  const stamps = new Map<string, NonNullable<typeof result.stamps>[number]>();
+  for (const s of result.stamps ?? []) if (s.ok && s.stampRef) stamps.set(s.stampRef, s);
+  const out: Held[] = [];
+  for (let i = 0; i < events.length; i++) {
+    const ev = events[i];
+    const er = result.events[i]!;
+    if (!isPlainObject(ev)) continue;
+    const envelope = ev.envelope;
+    if (!isPlainObject(envelope)) continue;
+    // Only a verified record is ever read, and its event_id is a UUID.
+    const eventId = typeof envelope.event_id === "string" ? envelope.event_id : "";
+    const rawHex = ev.event_bytes;
+    const bytesSupplied = typeof rawHex === "string" && rawHex.length > 0;
+    // A verified envelope whose record bytes are present is one whose bytes
+    // bound to its payload_hash: the kernel fails it otherwise.
+    const verified = er.envelopeOk;
+    let raw: Uint8Array | null = null;
+    let record: Record<string, unknown> | null = null;
+    if (verified) {
+      try {
+        raw = hexToBytes(rawHex as string);
+        const parsed = jcsParse(raw);
+        record = isPlainObject(parsed) ? parsed : null;
+      } catch {
+        raw = null;
+        record = null;
+      }
+    }
+    let stampEnd: string | null = null;
+    let witnessed = false;
+    const incl = ev.inclusion;
+    // The stamp the kernel verified as INCLUDING this record: its inclusion,
+    // and nothing else about the event. Bytes handed in beside the pack can
+    // fail an event; they must not move the time.
+    if (er.inclusionOk && isPlainObject(incl) && typeof incl.stamp_ref === "string") {
+      const st = stamps.get(incl.stamp_ref);
+      if (st !== undefined) {
+        stampEnd = st.intervalEnd;
+        // Witnessed means looked up and confirmed, by the caller, on the
+        // public record. A stamp that merely names a witness is signed by
+        // nobody but the pack's wrapper key, which whoever sealed the pack
+        // holds, so its interval end is theirs to choose.
+        witnessed = witnessedRefs.has(st.stampRef);
+      }
+    }
+    const payloadHash = envelope.payload_hash;
+    out.push({
+      packRef: pack.ref,
+      packIndex,
+      eventId,
+      publicKey: asKey(envelope.public_key),
+      payloadHash: typeof payloadHash === "string" ? payloadHash : null,
+      signedAt: envelope.signed_at,
+      verified,
+      bytesSupplied,
+      raw,
+      record,
+      content: er.contentOk === true ? disclosed(ev, eventId, pack.content) : null,
+      stampEnd,
+      stampWitnessed: witnessed,
+    });
+  }
+  return out;
+}
+
+// ---- Times ----------------------------------------------------------------------
+
+function daysFromCivil(y: number, m: number, d: number): number {
+  y -= m <= 2 ? 1 : 0;
+  const era = Math.floor((y >= 0 ? y : y - 399) / 400);
+  const yoe = y - era * 400;
+  const doy = Math.floor((153 * (m + (m > 2 ? -3 : 9)) + 2) / 5) + d - 1;
+  const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+  return era * 146097 + doe - 719468;
+}
+
+function instant(value: unknown): [number, boolean] | null {
+  if (typeof value !== "string") return null;
+  const m = INSTANT.exec(value);
+  if (m === null) return null;
+  const [y, mo, d, h, mi, s] = [1, 2, 3, 4, 5, 6].map((i) => Number(m[i]));
+  const seconds = daysFromCivil(y!, mo!, d!) * 86400 + h! * 3600 + mi! * 60 + s!;
+  const frac = m[7];
+  return [seconds, frac !== undefined && /[1-9]/.test(frac)];
+}
+
+/** Check 9: `|signed_at - issued_at| <= tolerance`, exactly. */
+function within(signedAt: unknown, issuedAt: number, tolerance: number): boolean {
+  const t = instant(signedAt);
+  if (t === null) return false;
+  const [seconds, fraction] = t;
+  const hi = issuedAt + tolerance;
+  return seconds >= issuedAt - tolerance && (seconds < hi || (seconds === hi && !fraction));
+}
+
+function rfc3339(seconds: number): string {
+  const days = Math.floor(seconds / 86400);
+  let rem = seconds - days * 86400;
+  const z = days + 719468;
+  const era = Math.floor((z >= 0 ? z : z - 146096) / 146097);
+  const doe = z - era * 146097;
+  const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365);
+  let y = yoe + era * 400;
+  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+  const mp = Math.floor((5 * doy + 2) / 153);
+  const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+  const m = mp + (mp < 10 ? 3 : -9);
+  y += m <= 2 ? 1 : 0;
+  const h = Math.floor(rem / 3600);
+  rem -= h * 3600;
+  const mi = Math.floor(rem / 60);
+  const s = rem - mi * 60;
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `${p(y, 4)}-${p(m)}-${p(d)}T${p(h)}:${p(mi)}:${p(s)}Z`;
+}
+
+// ---- The policy -----------------------------------------------------------------
+
+function providerPolicy(
+  policy: unknown,
+  provider: string,
+): ["ok", Record<string, unknown>] | ["none" | "unreadable", null] {
+  if (policy === null || policy === undefined) return ["none", null];
+  if (
+    !isPlainObject(policy) ||
+    policy.policy_version !== POLICY_VERSION ||
+    !isPlainObject(policy.providers)
+  ) {
+    return ["unreadable", null];
+  }
+  // No entry is no_policy; an entry that is there and not an object, null
+  // included, is one this reader cannot read.
+  if (!has(policy.providers, provider)) return ["none", null];
+  const entry = policy.providers[provider];
+  if (!isPlainObject(entry)) return ["unreadable", null];
+  const tol = wholeNumber(entry.signed_at_tolerance_seconds);
+  if (tol === null || tol < 0) return ["unreadable", null];
+  return ["ok", entry];
+}
+
+// ---- The enclave line ------------------------------------------------------------
+
+function base64UrlStrict32(s: string): Uint8Array | null {
+  if (!B64URL_32.test(s)) return null;
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=";
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  let back = btoa(String.fromCharCode(...out));
+  back = back.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return back === s && out.length === 32 ? out : null;
+}
+
+async function manifestCaseHash(content: Uint8Array): Promise<string | null> {
+  let m: unknown;
+  try {
+    m = jcsParseWithinLimits(content);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(m) || m.manifest_version !== MANIFEST_VERSION) return null;
+  const caseId = m.case_id;
+  const salt = m.case_salt;
+  if (typeof caseId !== "string" || caseId === "" || typeof salt !== "string") return null;
+  const saltBytes = base64UrlStrict32(salt);
+  if (saltBytes === null) return null;
+  const id = utf8(caseId);
+  const joined = new Uint8Array(saltBytes.length + id.length);
+  joined.set(saltBytes, 0);
+  joined.set(id, saltBytes.length);
+  return sha256Hex(joined);
+}
+
+/**
+ * The time the token is evaluated at (7): the interval end of a stamp that
+ * holds the opening record and whose witness the reader's lookup confirmed;
+ * otherwise null, the token's own issue time.
+ */
+/**
+ * @internal For the kernel's own tests: the enclave line of one opening record,
+ * verified as the caller says, under a provider table the caller names. It is
+ * how a test reaches a provider outside `ADAPTER_MODULES`; `readRuns` always
+ * reads under `ADAPTER_MODULES`.
+ */
+export async function enclaveLineForTest(
+  record: Record<string, unknown>,
+  publicKey: string,
+  content: Uint8Array | null,
+  policy: unknown,
+  adapters: ReadonlyMap<string, EnclaveAdapter>,
+  table: Readonly<Record<string, string>>,
+): Promise<EnclaveLine> {
+  const opening: Held = {
+    packRef: "p",
+    packIndex: 0,
+    eventId: "e",
+    publicKey,
+    payloadHash: null,
+    signedAt: "2026-10-13T00:00:00Z",
+    verified: true,
+    bytesSupplied: true,
+    raw: utf8(jcs(record)),
+    record,
+    content,
+    stampEnd: null,
+    stampWitnessed: false,
+  };
+  const [l] = await enclaveLine(opening, [opening], policy, adapters, table);
+  return l;
+}
+
+function evaluationTime(opening: Held): string | null {
+  return opening.stampWitnessed ? opening.stampEnd : null;
+}
+
+function tryRead(opening: Held): Attestation | null {
+  if (opening.record === null) return null;
+  const metadata = opening.record.metadata;
+  if (!isPlainObject(metadata) || !has(metadata, "enclave_attestation")) return null;
+  try {
+    oneSpelling(opening.raw ?? new Uint8Array(), "the opening record");
+    return readAttestation(metadata.enclave_attestation);
+  } catch (err) {
+    if (err instanceof AttestationRefused) return null;
+    throw err;
+  }
+}
+
+/**
+ * The failure kinds an adapter declares as its `kinds`: an array of snake_case
+ * strings, at least one, none of them a kind or note the kernel names
+ * (`NEUTRAL_KINDS`). `null` where the declaration is not of that form, an
+ * empty one included, and then the adapter is not loaded.
+ */
+export function declaredKinds(adapter: unknown): ReadonlySet<string> | null {
+  const kinds = isPlainObjectLike(adapter) ? (adapter as { kinds?: unknown }).kinds : undefined;
+  if (!Array.isArray(kinds) || kinds.length === 0) return null;
+  for (const k of kinds) {
+    if (typeof k !== "string" || !KIND_FORM.test(k) || NEUTRAL_KINDS.has(k)) return null;
+  }
+  return new Set(kinds as string[]);
+}
+
+function isPlainObjectLike(v: unknown): boolean {
+  return (typeof v === "object" || typeof v === "function") && v !== null;
+}
+
+async function enclaveLine(
+  opening: Held,
+  held: Held[],
+  policy: unknown,
+  adapters: ReadonlyMap<string, EnclaveAdapter>,
+  table: Readonly<Record<string, string>> = ADAPTER_MODULES,
+): Promise<[EnclaveLine, Attestation | null]> {
+  if (adapters.size === 0) return [line("not_checked", ["no_adapter"]), tryRead(opening)];
+  const record = opening.record!;
+  const metadata = record.metadata;
+  if (!isPlainObject(metadata) || !has(metadata, "enclave_attestation")) {
+    return [line("not_checked", ["no_attestation"]), null];
+  }
+  let att: Attestation;
+  try {
+    oneSpelling(opening.raw ?? new Uint8Array(), "the opening record");
+    att = readAttestation(metadata.enclave_attestation);
+  } catch (err) {
+    if (err instanceof UnknownAttestationVersion) {
+      return [line("not_checked", ["unknown_version"], { reason: err.message }), null];
+    }
+    if (err instanceof AttestationRefused) {
+      return [line("differs", ["attestation_malformed"], { reason: err.message }), null];
+    }
+    throw err;
+  }
+  const provider = att.provider;
+  const adapter = has(table, provider) ? adapters.get(provider) : undefined;
+  if (adapter === undefined) return [line("not_checked", ["no_adapter"], { provider }), att];
+  const [status, entry] = providerPolicy(policy, provider);
+  if (status !== "ok") {
+    return [line("not_checked", [status === "none" ? "no_policy" : "policy_unreadable"], { provider }), att];
+  }
+
+  const at = evaluationTime(opening);
+  let answer: AdapterResult;
+  try {
+    const declared = declaredKinds(adapter);
+    if (declared === null) throw new TypeError("the adapter declares no kinds");
+    answer = await adapter.check(att, { policy: entry, at });
+    const answerKinds: unknown = answer?.kinds ?? [];
+    const answerBinding: unknown = answer?.binding ?? null;
+    const answerIssuedAt: unknown = answer?.issuedAt ?? null;
+    if (
+      !isPlainObject(answer) ||
+      !(ENCLAVE_STATES as readonly string[]).includes(answer.state) ||
+      !Array.isArray(answerKinds) ||
+      answerKinds.some((k) => typeof k !== "string" || !declared.has(k)) ||
+      !(answerBinding === null || isBinding(answerBinding)) ||
+      !(answerIssuedAt === null || Number.isSafeInteger(answerIssuedAt))
+    ) {
+      throw new TypeError("not an AdapterResult");
+    }
+    // A differs answer names the checks that failed, and only a differs
+    // answer names any.
+    if ((answer.state === "differs") !== (answerKinds.length > 0)) {
+      throw new TypeError("kinds that do not fit the state");
+    }
+    // A not_checked line carries one kind (section 6), and a not_checked
+    // answer names none, so it has no kind for the line to carry.
+    if (answer.state === "not_checked") {
+      throw new TypeError("not_checked, with no kind for the line");
+    }
+    // Confirmed means the adapter verified a binding: without one, checks 7
+    // and 11 would have nothing to run on.
+    if (answer.state === "confirmed" && answerBinding === null) {
+      throw new TypeError("confirmed without the binding it verified");
+    }
+    // Where the kernel read the binding itself (a registered provider), the
+    // adapter verified that binding and no other.
+    if (answerBinding !== null && att.binding !== null && bindingText(answerBinding as Binding) !== bindingText(att.binding)) {
+      throw new TypeError("a binding other than the one the evidence carries");
+    }
+  } catch {
+    return [line("not_checked", ["adapter_failed"], { provider }), att];
+  }
+
+  const kinds: string[] = [];
+  const notes: string[] = [];
+  // Check 1.
+  if (att.runnerPublicKey !== opening.publicKey) kinds.push("subject_key_not_signer");
+  const event = record.event;
+  const contentHash = isPlainObject(event) ? event.content_hash : undefined;
+  if (contentHash !== att.manifestHash) kinds.push("manifest_not_content");
+  // Check 7: on the binding the adapter verified, or, where the adapter did
+  // not confirm, on the one the kernel read from the evidence.
+  const b = answer.binding ?? att.binding;
+  if (b !== null) {
+    if (b.runId !== att.runId) kinds.push("binding_other_run");
+    if (b.manifestHash !== att.manifestHash) kinds.push("binding_other_manifest");
+    if (b.runnerPublicKey !== att.runnerPublicKey || b.agentPublicKey !== att.agentPublicKey) {
+      kinds.push("binding_other_keys");
+    }
+  }
+  kinds.push(...(answer.kinds ?? []));
+  // Check 9.
+  const issuedAt = answer.issuedAt ?? null;
+  if (issuedAt !== null) {
+    const tolerance = wholeNumber(entry.signed_at_tolerance_seconds) ?? 0;
+    if (!within(opening.signedAt, issuedAt, tolerance)) kinds.push("signed_at_outside_tolerance");
+  } else if (answer.state === "confirmed") {
+    // A provider whose evidence has no issue time: check 9 did not run.
+    notes.push("no_issue_time");
+  }
+  // Check 11.
+  if (opening.content === null) {
+    notes.push("manifest_withheld");
+  } else if ((await sha256Hex(opening.content)) !== att.manifestHash) {
+    kinds.push("manifest_content_mismatch");
+  } else {
+    const caseHash = await manifestCaseHash(opening.content);
+    if (caseHash === null) kinds.push("manifest_unreadable");
+    else if (b !== null && caseHash !== b.caseHash) kinds.push("case_hash_differs");
+  }
+  // Check 10.
+  for (const h of held) {
+    if (h === opening || !h.verified || h.record === null) continue;
+    const runnerType = (eventType(h) ?? "").startsWith(RUNNER_PREFIX);
+    if (h.publicKey === att.runnerPublicKey && !runnerType) {
+      if (!kinds.includes("agent_record_under_runner_key")) kinds.push("agent_record_under_runner_key");
+    }
+  }
+  if (opening.stampEnd !== null && !opening.stampWitnessed) notes.push("stamp_unwitnessed");
+
+  let evaluation: EnclaveLine["evaluation"] = null;
+  let evaluatedAt: string | null = null;
+  const tokenChecked = answer.tokenChecked === true;
+  if (tokenChecked) {
+    if (at !== null) {
+      evaluation = "stamp";
+      evaluatedAt = at;
+    } else {
+      evaluation = "token_issue_time";
+      if (issuedAt !== null) evaluatedAt = rfc3339(issuedAt);
+    }
+  }
+  return [
+    line(kinds.length > 0 ? "differs" : answer.state, kinds, {
+      notes,
+      provider,
+      evaluatedAt,
+      evaluation,
+      tokenChecked,
+    }),
+    att,
+  ];
+}
+
+// ---- The run account -----------------------------------------------------------------
+
+const CLOSING_KEYS = new Set([
+  "outcome",
+  "payload_hashes",
+  "record_count",
+  "record_ids",
+  "unacknowledged_payload_hashes",
+  "unacknowledged_record_ids",
+]);
+
+class ClosingRefused extends Error {}
+
+function idList(value: unknown, path: string): string[] {
+  if (!Array.isArray(value)) throw new ClosingRefused(`${path} must be a list`);
+  for (const v of value) {
+    if (typeof v !== "string" || v === "") throw new ClosingRefused(`${path} must hold non-empty strings`);
+  }
+  if (new Set(value).size !== value.length) throw new ClosingRefused(`${path} names one record twice`);
+  return value as string[];
+}
+
+function hashList(value: unknown, path: string, n: number): string[] {
+  if (!Array.isArray(value)) throw new ClosingRefused(`${path} must be a list`);
+  for (const v of value) {
+    if (typeof v !== "string" || !LOWER_HEX64.test(v)) {
+      throw new ClosingRefused(`${path} must hold 64 lowercase hex characters each`);
+    }
+  }
+  if (value.length !== n) throw new ClosingRefused(`${path} is not one hash per id`);
+  return value as string[];
+}
+
+function readClosing(record: Record<string, unknown>): [string[], string[] | null, string[], string[]] {
+  const path = "metadata.closing";
+  const metadata = record.metadata;
+  const closing = isPlainObject(metadata) ? metadata.closing : undefined;
+  if (!isPlainObject(closing)) throw new ClosingRefused(`${path} must be an object`);
+  const unknown = Object.keys(closing)
+    .filter((k) => !CLOSING_KEYS.has(k))
+    .sort();
+  if (unknown.length > 0) throw new ClosingRefused(`${path}: unknown member ${renderKey(unknown[0]!)}`);
+  for (const k of ["record_count", "record_ids", "outcome"]) {
+    if (!has(closing, k)) throw new ClosingRefused(`${path}.${k} is required`);
+  }
+  const ids = idList(closing.record_ids, `${path}.record_ids`);
+  const count = wholeNumber(closing.record_count);
+  if (count === null || count !== ids.length) {
+    throw new ClosingRefused(`${path}.record_count is not the number of record_ids`);
+  }
+  if (!isPlainObject(closing.outcome)) throw new ClosingRefused(`${path}.outcome must be an object`);
+  const hashes = has(closing, "payload_hashes")
+    ? hashList(closing.payload_hashes, `${path}.payload_hashes`, ids.length)
+    : null;
+  const hasUids = has(closing, "unacknowledged_record_ids");
+  const hasUhashes = has(closing, "unacknowledged_payload_hashes");
+  if (hasUids !== hasUhashes) {
+    throw new ClosingRefused(
+      `${path}: unacknowledged_record_ids and unacknowledged_payload_hashes travel together`,
+    );
+  }
+  let uids: string[] = [];
+  let uhashes: string[] = [];
+  if (hasUids) {
+    uids = idList(closing.unacknowledged_record_ids, `${path}.unacknowledged_record_ids`);
+    uhashes = hashList(
+      closing.unacknowledged_payload_hashes,
+      `${path}.unacknowledged_payload_hashes`,
+      uids.length,
+    );
+  }
+  const idSet = new Set(ids);
+  if (uids.some((u) => idSet.has(u))) {
+    throw new ClosingRefused(`${path}: a record is both acknowledged and not`);
+  }
+  return [ids, hashes, uids, uhashes];
+}
+
+function entry(kind: string, eventId: string | null = null): AccountEntry {
+  return { kind, eventId };
+}
+
+function runAccount(
+  runnerKey: string,
+  agentKey: string | null,
+  held: Held[],
+  ignored: Set<Held>,
+): RunAccountLine {
+  const notes: AccountEntry[] = [];
+  if (agentKey === null) notes.push(entry("agent_key_unknown"));
+  const keys = new Set<string>([runnerKey]);
+  if (agentKey !== null) keys.add(agentKey);
+  for (const h of ignored) {
+    if (agentKey !== null && h.publicKey === agentKey) {
+      notes.push(entry("runner_record_under_agent_key", h.eventId));
+    }
+  }
+  const members = held.filter((h) => h.verified && keys.has(h.publicKey) && !ignored.has(h));
+  for (const h of members) {
+    if (h.publicKey === runnerKey && !h.bytesSupplied) {
+      notes.push(entry("runner_record_bytes_withheld", h.eventId));
+    }
+  }
+  const closings = members.filter((h) => h.publicKey === runnerKey && eventType(h) === RUN_CLOSED);
+  const base = { findings: [] as AccountEntry[], closingEventId: null as string | null, reason: null as string | null };
+  if (closings.length === 0) return { ...base, state: "not_closed", notes };
+  if (closings.length > 1) {
+    return {
+      ...base,
+      state: "differs",
+      findings: closings.map((h) => entry("more_than_one_closing_record", h.eventId)),
+      notes,
+    };
+  }
+  const closing = closings[0]!;
+  let ids: string[], hashes: string[] | null, uids: string[], uhashes: string[];
+  try {
+    [ids, hashes, uids, uhashes] = readClosing(closing.record ?? {});
+  } catch (err) {
+    if (!(err instanceof ClosingRefused)) throw err;
+    return {
+      state: "differs",
+      findings: [entry("closing_malformed", closing.eventId)],
+      notes,
+      closingEventId: closing.eventId,
+      reason: err.message,
+    };
+  }
+  if (hashes === null) notes.push(entry("payload_hashes_absent", closing.eventId));
+  const listed = new Map<string, string | null>(ids.map((id, i) => [id, hashes ? hashes[i]! : null]));
+  const unacked = new Map<string, string>(uids.map((id, i) => [id, uhashes[i]!]));
+  const findings: AccountEntry[] = [];
+  const others = members.filter((h) => h !== closing);
+  for (const h of others) {
+    if (listed.has(h.eventId)) {
+      const want = listed.get(h.eventId)!;
+      if (want === null || want === h.payloadHash) continue;
+    } else if (unacked.has(h.eventId) && unacked.get(h.eventId) === h.payloadHash) {
+      continue;
+    }
+    findings.push(entry("record_not_listed", h.eventId));
+  }
+  // Presence is presence: a listed record the account ignores (a runner.*
+  // record under the agent key) is still in the drop.
+  const pool = held.filter(
+    (h) => h.verified && h !== closing && (agentKey === null || keys.has(h.publicKey)),
+  );
+  for (const [eventId, want] of listed) {
+    if (!pool.some((h) => h.eventId === eventId && (want === null || h.payloadHash === want))) {
+      findings.push(entry("listed_record_absent", eventId));
+    }
+  }
+  for (const [eventId, want] of unacked) {
+    if (!pool.some((h) => h.eventId === eventId && h.payloadHash === want)) {
+      notes.push(entry("unacknowledged_record_absent", eventId));
+    }
+  }
+  return {
+    state: findings.length > 0 ? "differs" : "closed",
+    findings,
+    notes,
+    closingEventId: closing.eventId,
+    reason: null,
+  };
+}
+
+// ---- Putting it together -----------------------------------------------------------------
+
+/**
+ * Read every run in a drop: one reading per opening record, and one per closing
+ * record whose runner key opened nothing readable. `adapters` maps a provider
+ * id to a loaded adapter; only ids in `ADAPTER_MODULES` are ever consulted, and
+ * an empty map is a reader with no adapter. Never throws on a pack.
+ */
+async function onlineLine(
+  opening: Held,
+  att: Attestation | null,
+  policy: unknown,
+  adapters: ReadonlyMap<string, EnclaveAdapter>,
+  rpc: string | null,
+): Promise<OnlineLine | null> {
+  if (rpc === null || att === null || !has(ADAPTER_MODULES, att.provider)) return null;
+  const adapter = adapters.get(att.provider);
+  if (adapter === undefined || typeof adapter.online !== "function") return null;
+  const [status, entry] = providerPolicy(policy, att.provider);
+  if (status !== "ok") return null;
+  const content = opening.content;
+  const manifest =
+    content !== null && (await sha256Hex(content)) === att.manifestHash ? content : null;
+  try {
+    const answer: unknown = await adapter.online(att, { policy: entry, at: evaluationTime(opening), manifest, rpc });
+    if (!isPlainObject(answer) || !Array.isArray(answer.kinds)) throw new TypeError("not an OnlineLine");
+    const kinds = answer.kinds as unknown[];
+    const allowed: readonly string[] | undefined =
+      answer.state === "confirmed"
+        ? []
+        : answer.state === "not_checked"
+          ? ONLINE_NOT_CHECKED_KINDS
+          : answer.state === "differs"
+            ? ONLINE_DIFFERS_KINDS
+            : undefined;
+    if (
+      allowed === undefined ||
+      kinds.length !== (answer.state === "confirmed" ? 0 : 1) ||
+      kinds.some((k) => typeof k !== "string" || !allowed.includes(k))
+    ) {
+      throw new TypeError("not an OnlineLine");
+    }
+    return { state: answer.state as OnlineLine["state"], kinds: kinds as string[] };
+  } catch {
+    return { state: "not_checked", kinds: ["adapter_failed"] };
+  }
+}
+
+/**
+ * What makes a pack the same pack: SHA-256 of the JCS of its wrapper (the bytes
+ * the wrapper's signature covers, and the signature) together with its side
+ * content, each entry as the bytes the kernel binds to `content_hash`. Never
+ * the reader's name for it. `null` where either part cannot be put in that
+ * form: a pack with no identity is never the same as another.
+ */
+async function packIdentity(pack: RunPack): Promise<string | null> {
+  try {
+    const side: [string, string][] = [];
+    for (const id of sideContentKeys(pack.content).sort()) {
+      const value = sideContentEntry(pack.content, id).value;
+      if (value instanceof Uint8Array) {
+        side.push([id, "b:" + bytesToHex(value)]);
+      } else if (typeof value === "string") {
+        try {
+          side.push([id, "b:" + bytesToHex(hexToBytes(value))]);
+        } catch {
+          side.push([id, "s:" + value]);
+        }
+      } else {
+        return null;
+      }
+    }
+    return await sha256Hex(utf8(jcs({ bundle: pack.bundle, content: side })));
+  } catch {
+    return null;
+  }
+}
+
+/** A verified `runner.*` record under one of `keys`. */
+function runnerRecordUnder(h: Held, keys: ReadonlySet<string>): boolean {
+  return h.verified && keys.has(h.publicKey) && (eventType(h) ?? "").startsWith(RUNNER_PREFIX);
+}
+
+export async function readRuns(
+  packs: readonly RunPack[],
+  options: {
+    policy?: unknown;
+    adapters?: ReadonlyMap<string, EnclaveAdapter> | null;
+    /** A chain endpoint for the online line, handed to an adapter that reads one. */
+    rpc?: string | null;
+    /**
+     * For each pack by position, the `stamp_ref` of every stamp whose witness
+     * the caller looked up and the public record confirmed (the on-chain
+     * half's `confirm`). A token is evaluated at a stamp's interval end only
+     * there, and at its own issue time otherwise. Absent: no lookup.
+     */
+    witnessed?: readonly (readonly string[] | null | undefined)[] | null;
+  } = {},
+): Promise<RunsReading> {
+  const adapters = options.adapters ?? new Map<string, EnclaveAdapter>();
+  const held: Held[] = [];
+  // A pack handed in again with the same bytes is read once, at its first
+  // position, and the lookups made for every copy count for it
+  // (specs/run-records.md section 3).
+  const lookups: Set<string>[] = [];
+  const first = new Map<string, number>();
+  const keep: number[] = [];
+  for (let i = 0; i < packs.length; i++) {
+    const confirmed = new Set<string>();
+    for (const r of options.witnessed?.[i] ?? []) if (typeof r === "string") confirmed.add(r);
+    const identity = await packIdentity(packs[i]!);
+    if (identity !== null && first.has(identity)) {
+      for (const r of confirmed) lookups[first.get(identity)!]!.add(r);
+      continue;
+    }
+    if (identity !== null) first.set(identity, keep.length);
+    keep.push(i);
+    lookups.push(confirmed);
+  }
+  for (let k = 0; k < keep.length; k++) {
+    held.push(...(await heldRecords(packs[keep[k]!]!, keep[k]!, lookups[k]!)));
+  }
+
+  const openings = held.filter((h) => eventType(h) === RUN_OPENED && h.verified);
+  const read = new Map<Held, Attestation | null>(openings.map((h) => [h, tryRead(h)]));
+  // A key's runner role is proven by an attested opening: one whose
+  // attestation reads and names, as the runner key, the key that signed it.
+  // That opening's word on its agent key is taken; any other record's claim
+  // that a proven runner key is an agent key is only that record's word
+  // (proof#238). The agent keys are decided before any opening is admitted,
+  // and a key that is an agent key and no proven runner key opens no run:
+  // its runner.run_opened record is a runner.* record under an agent key.
+  const attested = openings.filter((h) => {
+    const a = read.get(h);
+    return a !== null && a !== undefined && a.runnerPublicKey === h.publicKey;
+  });
+  const proven = new Set(attested.map((h) => h.publicKey));
+  const agentKeys = new Set<string>();
+  for (const h of attested) {
+    const k = read.get(h)!.agentPublicKey;
+    if (!proven.has(k)) agentKeys.add(k);
+  }
+  // A runner.* record under a run's agent key is not the runner's.
+  const ignored = new Set(held.filter((h) => runnerRecordUnder(h, agentKeys)));
+
+  const runs: RunReading[] = [];
+  const runnerKeys = new Set<string>();
+  for (const opening of openings) {
+    if (ignored.has(opening)) continue;
+    const [enclave, att] = await enclaveLine(opening, held, options.policy, adapters);
+    const agentKey = att !== null ? att.agentPublicKey : null;
+    runnerKeys.add(opening.publicKey);
+    // Where the run's agent key is also a proven runner key, this run still
+    // ignores, and notes, the runner.* records under it.
+    const own = new Set<string>(agentKey !== null && agentKey !== opening.publicKey ? [agentKey] : []);
+    const runIgnored = new Set([...ignored, ...held.filter((h) => !ignored.has(h) && runnerRecordUnder(h, own))]);
+    runs.push({
+      packRef: opening.packRef,
+      packIndex: opening.packIndex,
+      eventId: opening.eventId,
+      runnerPublicKey: opening.publicKey,
+      agentPublicKey: agentKey,
+      enclave,
+      account: runAccount(opening.publicKey, agentKey, held, runIgnored),
+      online: await onlineLine(opening, att, options.policy, adapters, options.rpc ?? null),
+    });
+  }
+  for (const h of held) {
+    if (h.verified && eventType(h) === RUN_CLOSED && !ignored.has(h) && !runnerKeys.has(h.publicKey)) {
+      runnerKeys.add(h.publicKey);
+      runs.push({
+        packRef: h.packRef,
+        packIndex: h.packIndex,
+        eventId: h.eventId,
+        runnerPublicKey: h.publicKey,
+        agentPublicKey: null,
+        enclave: line("not_checked", ["no_opening_record"]),
+        account: runAccount(h.publicKey, null, held, ignored),
+        online: null,
+      });
+    }
+  }
+  return { runs };
+}
+
+// ---- What a command prints ------------------------------------------------------
+//
+// DRAFT wording: the line's words wait for the glossary. The twin of the
+// renderers at the foot of `run.py`; the case commands print them beside the
+// witness line.
+
+function runRef(r: RunReading): string {
+  const verb = r.enclave.kinds.includes("no_opening_record") ? "closed" : "opened";
+  return `the run ${verb} by record ${r.eventId} in ${r.packRef}`;
+}
+
+/** The enclave line, the revocation sentence where a token was checked, and the online line. */
+export function renderEnclaveLines(r: RunReading): string[] {
+  const e = r.enclave;
+  let s = `enclave attestation: ${e.state}`;
+  if (e.kinds.length > 0) s += ` (${e.kinds.join(", ")})`;
+  s += `, ${runRef(r)}`;
+  if (e.provider !== null) s += `, provider ${e.provider}`;
+  if (e.evaluation === "stamp") {
+    s += `; evaluated at ${e.evaluatedAt}, the interval end of a stamp that holds the opening record, its witness confirmed on the public record`;
+  } else if (e.evaluation === "token_issue_time") {
+    const at = e.evaluatedAt !== null ? ` (${e.evaluatedAt})` : "";
+    s += `; evaluated at the token's own issue time${at}: no stamp whose witness was confirmed says when the opening record was witnessed`;
+  }
+  if (e.notes.length > 0) s += `; note: ${e.notes.join(", ")}`;
+  if (e.reason !== null) s += `; ${e.reason}`;
+  const lines = [s];
+  if (e.tokenChecked) lines.push(REVOCATION_SENTENCE);
+  if (r.online !== null) {
+    let o = `opening on Flare: ${r.online.state}`;
+    if (r.online.kinds.length > 0) o += ` (${r.online.kinds.join(", ")})`;
+    lines.push(o);
+  }
+  return lines;
+}
+
+const entries = (xs: readonly AccountEntry[]): string =>
+  xs.map((x) => (x.eventId !== null ? `${x.kind} ${x.eventId}` : x.kind)).join(", ");
+
+/** The run-account line (specs/run-records.md). */
+export function renderAccountLine(r: RunReading): string {
+  const a = r.account;
+  let s = `run account: ${a.state}`;
+  if (a.findings.length > 0) s += ` (${entries(a.findings)})`;
+  s += `, ${runRef(r)}`;
+  if (a.notes.length > 0) s += `; note: ${entries(a.notes)}`;
+  if (a.reason !== null) s += `; ${a.reason}`;
+  return s;
+}