@sanning/proof 0.19.1 → 0.20.0

package/src/agent-record.ts

@@ -0,0 +1,608 @@
+// Reading a `sanning.agent` record: agent-events.md §10, steps 1 to 7, as the
+// pinned specs release states them (vendor/specs/agent-events.md).
+//
+// A record reaches this layer after the envelope layer verified its signature
+// and payload hash. Steps 1 to 6 read the record on its own against the schemas
+// bundled in agent-schemas.generated.ts; step 7 reads it with the records the
+// verifier holds beside it. Nothing here reads a file or the network.
+
+import { AGENT_SCHEMA_VERSIONS } from "./agent-schemas.generated.js";
+import { sha256Hex, utf8 } from "./crypto.js";
+import { deepEqual, escapeToken, has, isObject, SchemaSet, type SchemaError, unescapeToken } from "./json-schema.js";
+import { jcs } from "./verifier.js";
+
+/** A reading's verdict. `null`: the record is outside this vocabulary and this layer gives none. */
+export type AgentVerdict = "verified" | "failed" | "incomplete";
+
+/** One reason (section 10.1) and a JSON Pointer into the record for the field it is about. */
+export interface AgentReason {
+  readonly reason: string;
+  readonly at: string;
+}
+
+export interface AgentRecordReading {
+  readonly verdict: AgentVerdict | null;
+  /** The first reason of the verdict, when the verdict is not `verified`. */
+  readonly reason?: string;
+  /** Where `reason` is about. */
+  readonly at?: string;
+  /** Every reason, in step order, when the verdict is not `verified`. */
+  readonly reasons?: readonly AgentReason[];
+  /** Findings in the order step 6, then steps 7a to 7j, produce them. */
+  readonly findings: string[];
+  /**
+   * For each `listed_record_absent` reason, in order, the `event_id` the closing record
+   * lists and the verifier does not hold. Not part of the reading as `expected.json`
+   * spells it: present only where there is one, and not enumerable, so `JSON.stringify`
+   * leaves it out. The claims name each record by it.
+   */
+  readonly absent?: readonly string[];
+}
+
+/** A record as the verifier holds it after the envelope layer: its envelope's `event_id` and key. */
+export interface AgentHeldRecord {
+  readonly event_id: string;
+  readonly public_key: string;
+  readonly record: unknown;
+}
+
+/** The `sanning.events/v2` types outside the agent vocabulary (§3), read by the profile and run-records.md. */
+export const RECORD_TYPES_OUTSIDE_AGENT: readonly string[] = Object.freeze([
+  "event",
+  "checkpoint",
+  "declaration",
+  "runner.run_opened",
+  "runner.run_closed",
+  "runner.egress",
+  "runner.relay",
+]);
+
+/** The `agent.*` types of each vocabulary version this kernel knows, keyed by `extras.event_schema`. With RECORD_TYPES_OUTSIDE_AGENT they are that version's closed set. */
+export const AGENT_EVENT_TYPES: Readonly<Record<string, readonly string[]>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(AGENT_SCHEMA_VERSIONS).map(([version, v]) => [version, Object.freeze(Object.keys(v.types))]),
+  ),
+);
+
+// Step 2: sanning.agent/<major>[.<minor>], each 1 to 9 ASCII digits with no
+// leading zero, minor never 0. No `m` flag: `$` is the end of the string.
+const EVENT_SCHEMA_RE = /^sanning\.agent\/[1-9][0-9]{0,8}(\.[1-9][0-9]{0,8})?$/;
+const OUTSIDE = new Set(RECORD_TYPES_OUTSIDE_AGENT);
+const SALT_RE = /^[0-9a-f]{32}$/;
+// The two reasons that read incomplete: a check that could not be completed. Every
+// other reason reads failed, with the reason kind nonconforming.
+export const INCOMPLETE_REASONS: ReadonlySet<string> = new Set(["event_schema_unknown", "listed_record_absent"]);
+
+const OPENER: Readonly<Record<string, string>> = {
+  "agent.step.ended": "agent.step.started",
+  "agent.model_call.ended": "agent.model_call.started",
+  "agent.tool_call.ended": "agent.tool_call.started",
+  "agent.retrieval.ended": "agent.retrieval.started",
+  "agent.approval.resolved": "agent.approval.requested",
+};
+const CLOSER: Readonly<Record<string, string>> = Object.fromEntries(Object.entries(OPENER).map(([c, o]) => [o, c]));
+
+// Step 7a: the checks on a candidate start, worst first.
+const PAIR_REASONS = ["pair_type_mismatch", "pair_run_mismatch", "pair_call_mismatch", "pair_field_mismatch"];
+// §9.1: the fields both halves of one operation agree on, in the order they are checked.
+const PAIR_FIELDS = [
+  "gen_ai.operation.name",
+  "gen_ai.provider.name",
+  "gen_ai.tool.name",
+  "approval.subject_event_id",
+  "approval.actor",
+  "approval.policy_hash",
+];
+// Step 7h: the approval verdicts that tell the adapter not to run the tool.
+const REFUSALS = new Set(["rejected", "responded"]);
+// §10.1: of several schema errors, the reason first here is reported, then the smallest pointer.
+const SCHEMA_REASONS = ["unknown_field", "missing_field", "bad_value"];
+
+// A record's shape is known once it passed the schema check.
+type Rec = any;
+
+const schemaSet = new SchemaSet(
+  Object.values(AGENT_SCHEMA_VERSIONS).flatMap((v) => [v.common, ...Object.values(v.types)]),
+);
+const TYPES: ReadonlyMap<string, ReadonlyMap<string, { id: string; schema: Rec }>> = new Map(
+  Object.entries(AGENT_SCHEMA_VERSIONS).map(([version, v]) => [
+    version,
+    new Map(
+      Object.entries(v.types).map(([type, s]) => [type, { id: (s as Rec).$id as string, schema: s as Rec }]),
+    ),
+  ]),
+);
+
+function revealableOf(schema: Rec): string[] {
+  return schema.properties.context.properties.revealed?.items.enum ?? [];
+}
+
+/**
+ * One reading in the words both kernels print: the verdict, every reason and
+ * where, then the findings, which are reported beside the verdict and never
+ * move it. Byte-identical to `render_agent_reading` in the Python kernel.
+ */
+export function renderAgentReading(reading: AgentRecordReading): string {
+  let text = reading.verdict ?? "no verdict";
+  if (reading.reasons !== undefined && reading.reasons.length > 0) {
+    text += `: ${reading.reasons.map((r) => `${r.reason} at ${r.at}`).join(", ")}`;
+  }
+  if (reading.findings.length > 0) text += `; findings: ${reading.findings.join(", ")}`;
+  return text;
+}
+
+/** Steps 1 to 6 of agent-events.md §10: one record on its own. */
+export function readAgentRecord(record: unknown): AgentRecordReading {
+  const r = record as Rec;
+  const type = isObject(r) ? r.event_type : undefined;
+  const extras = isObject(r) ? r.extras : undefined;
+  const hasSchema = isObject(extras) && has(extras, "event_schema");
+  // Step 1: the namespace.
+  if (typeof type === "string" && OUTSIDE.has(type)) {
+    if (hasSchema) return failed("event_schema_misplaced", "/extras/event_schema");
+    // The salt is defined for every record; on these types only its form is read.
+    const ctx = r.context;
+    if (isObject(ctx) && has(ctx, "salt") && !(typeof ctx.salt === "string" && SALT_RE.test(ctx.salt))) {
+      return failed("bad_value", "/context/salt");
+    }
+    return { verdict: null, findings: ["not_an_agent_record"] };
+  }
+  if (typeof type !== "string" || !type.startsWith("agent.")) {
+    return failed("event_type_not_in_set", "/event_type");
+  }
+  // Step 2: the version, before the type, so a type a later minor adds reads incomplete.
+  if (!hasSchema) return failed("event_schema_missing", "/extras/event_schema");
+  const version = extras.event_schema;
+  if (typeof version !== "string" || !EVENT_SCHEMA_RE.test(version)) {
+    return failed("event_schema_invalid", "/extras/event_schema");
+  }
+  const types = TYPES.get(version);
+  if (types === undefined) {
+    const at = "/extras/event_schema";
+    return {
+      verdict: "incomplete",
+      reason: "event_schema_unknown",
+      at,
+      reasons: [{ reason: "event_schema_unknown", at }],
+      findings: [],
+    };
+  }
+  // Step 3: the type, in the closed set of that version.
+  const entry = types.get(type);
+  if (entry === undefined) return failed("event_type_not_in_set", "/event_type");
+  // Step 4: the schema.
+  const errors = schemaSet.validate(entry.id, r);
+  if (errors.length > 0) {
+    const e = pickError(r, errors);
+    return failed(e.reason, e.at);
+  }
+  // Step 5: the rules the schema cannot state, in this order.
+  const ctx = r.context;
+  const meta = r.metadata;
+  for (const path of Object.keys(ctx.hidden ?? {}).sort()) {
+    if (present(meta, path)) return failed("hidden_field_present", pointer(path));
+  }
+  const revealed = new Set<string>(ctx.revealed ?? []);
+  for (const path of [...revealed].sort()) {
+    if (!present(meta, path)) return failed("revealed_field_absent", pointer(path));
+  }
+  for (const path of [...revealableOf(entry.schema)].sort()) {
+    if (present(meta, path) && !revealed.has(path)) return failed("revealed_field_unlisted", pointer(path));
+  }
+  if (meta.capture !== undefined && meta.run.seq !== 0) return failed("capture_not_at_head", "/metadata/capture");
+  if (type.startsWith("agent.handoff.")) {
+    const h = meta.handoff;
+    if (h.file_parts > h.parts) return failed("file_parts_exceed_parts", "/metadata/handoff/file_parts");
+    if (type === "agent.handoff.received") {
+      const indexes: number[] | undefined = h.unchecked_held_parts;
+      const count: number | undefined = ctx.unchecked_held_part_count;
+      if (indexes !== undefined && count === undefined) {
+        return failed("unchecked_held_parts_missing", "/context/unchecked_held_part_count");
+      }
+      if (indexes === undefined && count !== undefined) {
+        return failed("unchecked_held_parts_missing", "/metadata/handoff/unchecked_held_parts");
+      }
+      if (count !== undefined && count !== indexes!.length) {
+        return failed("unchecked_held_parts_mismatch", "/context/unchecked_held_part_count");
+      }
+      if (count !== undefined && count > h.file_parts) {
+        return failed("unchecked_held_parts_exceed_file_parts", "/context/unchecked_held_part_count");
+      }
+      for (const [i, index] of (indexes ?? []).entries()) {
+        if (index >= h.parts) return failed("part_index_out_of_range", `/metadata/handoff/unchecked_held_parts/${i}`);
+      }
+    }
+  }
+  if (type === "agent.run_closed" && meta.closing.record_ids.length !== meta.closing.record_count) {
+    return failed("closing_count_mismatch", "/metadata/closing/record_count");
+  }
+  if (type === "agent.file") {
+    const unhashed = meta.outcome.status === "failed";
+    if (unhashed !== (meta.artifact?.reason !== undefined)) {
+      return failed("artifact_reason_mismatch", "/metadata/artifact/reason");
+    }
+  }
+  // Step 6: verified, with the findings a reader shows.
+  const findings: string[] = [];
+  if (meta.run.plumbing === true) findings.push("plumbing");
+  if (ctx.content_scrubbed === true) findings.push("content_scrubbed");
+  return { verdict: "verified", findings };
+}
+
+/**
+ * Steps 1 to 7 of agent-events.md §10: `subject` read with the records the
+ * verifier holds beside it. Asynchronous only because 7a hashes a field to
+ * compare it with a hidden one.
+ */
+export async function readAgentRecordWithHeld(
+  subject: AgentHeldRecord,
+  held: readonly AgentHeldRecord[] = [],
+): Promise<AgentRecordReading> {
+  const one = readAgentRecord(isObject(subject) ? subject.record : undefined);
+  if (one.verdict !== "verified") return one;
+  // The held records are a set. An entry that is not an object with a string
+  // event_id is no record and is skipped. Step 7 reads only the held records
+  // that read verified at steps 1 to 6.
+  const all = distinct(
+    held.filter((h): h is AgentHeldRecord => isObject(h) && typeof h.event_id === "string"),
+  );
+  const peers = all.filter((h) => readAgentRecord(h.record).verdict === "verified");
+  return readBeside(subject, one, peers, await commitmentsOf([subject, ...peers]));
+}
+
+/**
+ * Read a pile: each item through steps 1 to 7, with every item held beside it.
+ * Each item is a `sanning.events/v2` record whose envelope verified and whose
+ * record bytes bound to it. Step 1 runs on every item, so a type outside the
+ * closed set reads `failed` whatever its namespace. `null` for an item
+ * that is not an object and for one of the seven types outside this vocabulary
+ * with no `event_schema`, which step 1 gives no verdict unless its salt is in
+ * the wrong form. The item is set aside from its own pile: a record is never
+ * one of its own held records. The one reading `verify`, `case` and the bundle
+ * verifiers wire in.
+ */
+export async function readAgentRecords(
+  items: readonly AgentHeldRecord[],
+): Promise<(AgentRecordReading | null)[]> {
+  const all = distinct(
+    items.filter((h): h is AgentHeldRecord => isObject(h) && typeof h.event_id === "string"),
+  );
+  const peers = all.filter((h) => readAgentRecord(h.record).verdict === "verified");
+  const readable = items.filter((h) => isObject(h) && readAgentRecord(h.record).verdict === "verified");
+  const commitments = await commitmentsOf(readable);
+  return items.map((item) => {
+    if (!isObject(item)) return null;
+    const one = readAgentRecord(item.record);
+    if (one.verdict === null) return null;
+    if (one.verdict !== "verified") return one;
+    return readBeside(item, one, peers, commitments);
+  });
+}
+
+/**
+ * Step 7: `subject`, which read `one` (verified) on its own, with the held
+ * records. A held copy of `subject` (`sameRecord`) is set aside first: a record
+ * is never one of its own held records. A held record with the subject's
+ * event_id and other bytes is another record and stays.
+ */
+function readBeside(
+  subject: AgentHeldRecord,
+  one: AgentRecordReading,
+  held: readonly AgentHeldRecord[],
+  commitments: Commitments,
+): AgentRecordReading {
+  const peers = held.filter((h) => !sameRecord(h, subject));
+  const record = subject.record as Rec;
+  const type: string = record.event_type;
+  const run = record.metadata.run;
+  const key = keyOf(subject.public_key);
+  const findings = [...one.findings];
+  // Every sub-step of step 7 runs, and every reason it gives is kept, in step order.
+  const reasons: AgentReason[] = [];
+  const absentIds: string[] = [];
+  const mine = distinct([subject, ...peers]).filter(
+    (h) => keyOf(h.public_key) === key && (h.record as Rec).metadata.run.root_run_id === run.root_run_id,
+  );
+  const grade = (end: Rec, start: Rec, opener: string): Grade | undefined =>
+    gradePair(end, start, opener, commitments);
+  const endsOf = (start: AgentHeldRecord): AgentHeldRecord[] => {
+    const s = start.record as Rec;
+    const closer = CLOSER[s.event_type];
+    return peers.filter((h) => {
+      const e = h.record as Rec;
+      return (
+        e.event_type === closer &&
+        keyOf(h.public_key) === keyOf(start.public_key) &&
+        e.metadata.run.started_event_id === start.event_id &&
+        grade(e, s, s.event_type) === undefined
+      );
+    });
+  };
+
+  // Step 7a: an end and the record it names.
+  const opener = OPENER[type];
+  if (opener !== undefined && run.started_event_id === null) {
+    // The invocation's first record is its one record at run.seq 0.
+    const heads = mine.filter((h) => (h.record as Rec).metadata.run.seq === 0);
+    const declared =
+      heads.length === 1 && ((heads[0]!.record as Rec).metadata.capture?.not_captured ?? []).includes(opener);
+    findings.push(declared ? "start_not_captured" : "start_undeclared");
+  } else if (opener !== undefined) {
+    // A candidate is a record this key signed: a record another key signed is never this end's start.
+    const candidates = peers.filter((h) => h.event_id === run.started_event_id && keyOf(h.public_key) === key);
+    if (candidates.length === 0) findings.push("start_absent");
+    if (candidates.length > 1) findings.push("start_ambiguous");
+    let worst: Grade | undefined;
+    for (const c of candidates) {
+      const g = grade(record, c.record, opener);
+      if (g !== undefined && (worst === undefined || compareGrade(g, worst) < 0)) worst = g;
+    }
+    if (worst !== undefined) reasons.push({ reason: worst.reason, at: worst.at });
+  }
+  // Step 7b: a start and the records that end it.
+  if (CLOSER[type] !== undefined) {
+    const ends = endsOf(subject);
+    if (ends.length === 0) findings.push("unended");
+    if (ends.length > 1) findings.push("ended_more_than_once");
+  }
+  // Step 7c: a closing record, judged only on every record it lists.
+  if (type === "agent.run_closed") {
+    const ids: string[] = record.metadata.closing.record_ids;
+    let absent = 0;
+    for (const [i, id] of ids.entries()) {
+      if (!peers.some((h) => h.event_id === id && keyOf(h.public_key) === key)) {
+        reasons.push({ reason: "listed_record_absent", at: `/metadata/closing/record_ids/${i}` });
+        absentIds.push(id);
+        absent++;
+      }
+    }
+    if (absent === 0 && record.metadata.closing.outcome.observed.status === "completed") {
+      const listed = new Set(ids);
+      const open = peers.some(
+        (h) =>
+          listed.has(h.event_id) &&
+          keyOf(h.public_key) === key &&
+          CLOSER[(h.record as Rec).event_type] !== undefined &&
+          !endsOf(h).some((e) => listed.has(e.event_id)),
+      );
+      if (open) findings.push("completed_with_open_operation");
+    }
+  }
+  // Step 7d: the two records of one hand-off message agree on its parts.
+  if (type.startsWith("agent.handoff.")) {
+    const other = type === "agent.handoff.sent" ? "agent.handoff.received" : "agent.handoff.sent";
+    const named = keyOf(record.event.counterparty_public_key);
+    const hash = String(record.event.message_hash).toLowerCase();
+    // Candidates for each other: each is signed by the key the other names.
+    const counterparts = peers.filter((h) => {
+      const c = h.record as Rec;
+      return (
+        c.event_type === other &&
+        keyOf(h.public_key) === named &&
+        keyOf(c.event.counterparty_public_key) === key &&
+        String(c.event.message_hash).toLowerCase() === hash
+      );
+    });
+    // A finding on both records, never a verdict: two keys signed them, so a verdict
+    // would let one side's count make the other side's honest record read failed.
+    const counts = (r: Rec): string => `${r.metadata.handoff.parts}/${r.metadata.handoff.file_parts}`;
+    if (counterparts.some((h) => counts(h.record) !== counts(record))) findings.push("handoff_parts_mismatch");
+  }
+  // Step 7e is not in sanning.agent/1: the runner cross-check waits for the runner's fields.
+  // Step 7f: one invocation, one data mode.
+  const mixed = peers.some((h) => {
+    const p = h.record as Rec;
+    return (
+      keyOf(h.public_key) === key &&
+      p.metadata.run.root_run_id === run.root_run_id &&
+      p.context.data_mode !== record.context.data_mode
+    );
+  });
+  if (mixed) findings.push("data_mode_mixed");
+  // Step 7g: one record at each position of the invocation's chain.
+  if (mine.some((h) => !sameRecord(h, subject) && (h.record as Rec).metadata.run.seq === run.seq)) {
+    findings.push("seq_duplicate");
+  }
+  // Step 7h: a tool call that ran after its approval refused it. A refusal is an
+  // answer, under this key, whose subject is this call's start and whose verdict
+  // is rejected or responded.
+  if (type === "agent.tool_call.ended" && run.started_event_id !== null) {
+    const refused = peers.some((h) => {
+      const a = h.record as Rec;
+      return (
+        a.event_type === "agent.approval.resolved" &&
+        keyOf(h.public_key) === key &&
+        a.metadata.approval.subject_event_id === run.started_event_id &&
+        REFUSALS.has(a.metadata.approval.verdict)
+      );
+    });
+    const status = record.metadata.outcome.status;
+    if (refused && (status === "completed" || status === "failed")) findings.push("ran_after_refusal");
+  }
+  // Step 7i: the position directly before this record is not held, and an earlier
+  // one of this invocation is. The verifier cannot tell a missing record from one
+  // never written.
+  const seqs = mine.map((h) => (h.record as Rec).metadata.run.seq as number);
+  if (run.seq > 0 && seqs.some((n) => n < run.seq) && !seqs.some((n) => n === run.seq - 1)) {
+    findings.push("seq_gap");
+  }
+  // Step 7j: the run promised a closing record, and none of this invocation is held.
+  if (type === "agent.run_opened" && !mine.some((h) => (h.record as Rec).event_type === "agent.run_closed")) {
+    findings.push("closing_not_held");
+  }
+  return reading(reasons, findings, absentIds);
+}
+
+/**
+ * Step 7: the reading from every reason step 7 gave. The verdict is the worst
+ * (failed, then incomplete); `reason` and `at` are the first reason of that verdict.
+ */
+function reading(reasons: AgentReason[], findings: string[], absent: string[]): AgentRecordReading {
+  if (reasons.length === 0) return { verdict: "verified", findings };
+  const failed = reasons.some((r) => !INCOMPLETE_REASONS.has(r.reason));
+  const first = reasons.find((r) => INCOMPLETE_REASONS.has(r.reason) !== failed)!;
+  const out: AgentRecordReading = {
+    verdict: failed ? "failed" : "incomplete",
+    reason: first.reason,
+    at: first.at,
+    reasons,
+    findings,
+  };
+  // Carried for the claims and never serialized: not part of the reading `expected.json`
+  // spells, as Python's `to_dict` leaves it out.
+  if (absent.length > 0) Object.defineProperty(out, "absent", { value: absent, enumerable: false });
+  return out;
+}
+
+interface Grade {
+  readonly reason: string;
+  readonly at: string;
+  readonly rank: readonly [number, number];
+}
+
+type Commitments = ReadonlyMap<unknown, ReadonlyMap<string, string | undefined>>;
+
+/** Step 7a: one candidate start, under the end's key, graded against the end. undefined when it is the end's start. */
+function gradePair(end: Rec, start: Rec, opener: string, commitments: Commitments): Grade | undefined {
+  const at = "/metadata/run/started_event_id";
+  if (start.event_type !== opener) return grade("pair_type_mismatch", at);
+  const a = end.metadata;
+  const b = start.metadata;
+  if (a.run.run_id !== b.run.run_id || a.run.root_run_id !== b.run.root_run_id) {
+    // The one exception: an approval answered in a later invocation of the same
+    // conversation, where both ids differ.
+    const approval = end.event_type === "agent.approval.resolved";
+    const conv = a.gen_ai?.conversation?.id;
+    const both = a.run.run_id !== b.run.run_id && a.run.root_run_id !== b.run.root_run_id;
+    if (!approval || !both || conv === undefined || conv !== b.gen_ai?.conversation?.id) {
+      return grade("pair_run_mismatch", at);
+    }
+  }
+  if (end.event_type === "agent.tool_call.ended" && a.gen_ai.tool.call.id !== b.gen_ai.tool.call.id) {
+    return grade("pair_call_mismatch", at);
+  }
+  for (const [i, path] of PAIR_FIELDS.entries()) {
+    const x = commitments.get(end)?.get(path);
+    const y = commitments.get(start)?.get(path);
+    if (x !== undefined && y !== undefined && x !== y) return grade("pair_field_mismatch", pointer(path), i);
+  }
+  return undefined;
+}
+
+function grade(reason: string, at: string, field = -1): Grade {
+  return { reason, at, rank: [PAIR_REASONS.indexOf(reason), field] };
+}
+
+function compareGrade(a: Grade, b: Grade): number {
+  return a.rank[0] - b.rank[0] || a.rank[1] - b.rank[1];
+}
+
+/**
+ * What each record commits to for each field of §9.1: SHA-256 of the JCS bytes
+ * of its value, or its hidden hash. A value JCS cannot encode commits to
+ * nothing a hidden hash can equal, and still equals the same value in clear.
+ */
+async function commitmentsOf(items: readonly AgentHeldRecord[]): Promise<Commitments> {
+  const out = new Map<unknown, Map<string, string | undefined>>();
+  for (const h of items) {
+    const record = h.record as Rec;
+    if (out.has(record)) continue;
+    const m = new Map<string, string | undefined>();
+    for (const path of PAIR_FIELDS) {
+      if (present(record.metadata, path)) {
+        const value = lookup(record.metadata, path);
+        const bytes = jcsOrUndefined(value);
+        m.set(path, bytes === undefined ? `unencodable:${String(value)}` : await sha256Hex(utf8(bytes)));
+      } else {
+        m.set(path, record.context.hidden?.[path]);
+      }
+    }
+    out.set(record, m);
+  }
+  return out;
+}
+
+function jcsOrUndefined(value: unknown): string | undefined {
+  try {
+    return jcs(value);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Two held records are one when their event ids, their keys and their JCS bytes
+ * are equal. Equal JSON values have equal JCS bytes, so this compares values:
+ * a copy JCS refuses to encode is still a copy.
+ */
+function sameRecord(x: AgentHeldRecord, y: AgentHeldRecord): boolean {
+  if (x.event_id !== y.event_id || keyOf(x.public_key) !== keyOf(y.public_key)) return false;
+  return deepEqual(x.record, y.record);
+}
+
+/** The held records as a set: the first of each group of copies. */
+function distinct(list: readonly AgentHeldRecord[]): AgentHeldRecord[] {
+  return list.filter((h, i) => list.findIndex((x) => sameRecord(x, h)) === i);
+}
+
+/** A key compared as a key: 64 hex characters, case ignored. */
+function keyOf(k: unknown): string {
+  return String(k).toLowerCase();
+}
+
+/** Steps 1 to 6 stop at the first failure: one reason. */
+function failed(reason: string, at: string): AgentRecordReading {
+  return { verdict: "failed", reason, at, reasons: [{ reason, at }], findings: [] };
+}
+
+/** A member is present when its key is there, whatever its value: a null value is present. */
+function present(obj: unknown, dotted: string): boolean {
+  let cur = obj;
+  for (const k of dotted.split(".")) {
+    if (!isObject(cur) || !has(cur, k)) return false;
+    cur = cur[k];
+  }
+  return true;
+}
+
+function lookup(obj: Rec, dotted: string): unknown {
+  let cur = obj;
+  for (const k of dotted.split(".")) cur = cur[k];
+  return cur;
+}
+
+function pointer(dotted: string): string {
+  return "/metadata/" + dotted.split(".").map(escapeToken).join("/");
+}
+
+/**
+ * §10.1: of several schema errors, `unknown_field` before `missing_field`
+ * before `bad_value`, then the smallest pointer. Pointers compare token by
+ * token, an array index as a number and any other token by UTF-16 code units; a
+ * pointer comes before every pointer it is a prefix of.
+ */
+function pickError(record: Rec, errors: readonly SchemaError[]): SchemaError {
+  return [...errors].sort(
+    (a, b) =>
+      SCHEMA_REASONS.indexOf(a.reason) - SCHEMA_REASONS.indexOf(b.reason) || comparePointers(record, a.at, b.at),
+  )[0]!;
+}
+
+function tokens(p: string): string[] {
+  return p === "" ? [] : p.slice(1).split("/").map(unescapeToken);
+}
+
+function comparePointers(record: Rec, a: string, b: string): number {
+  const x = tokens(a);
+  const y = tokens(b);
+  let container: Rec = record;
+  for (let i = 0; i < Math.min(x.length, y.length); i++) {
+    if (x[i] !== y[i]) {
+      if (Array.isArray(container)) return Number(x[i]) - Number(y[i]);
+      return x[i]! < y[i]! ? -1 : 1;
+    }
+    container = container?.[x[i]!];
+  }
+  return x.length - y.length;
+}
+