@intentset/verification 0.6.1 → 0.7.1

package/src/classify.ts

@@ -1,13 +1,21 @@
 /**
- * Evidence freshness (Core §8, invariant 3). Only a `pass` at the assessed
- * commit and graph hash is current; everything else is something else, and
- * says which. A failing run at the snapshot stays visible however many older
- * passes there are, because the status is decided by the latest run at the
- * snapshot and every run is kept in the history.
+ * Evidence freshness (Core §8, invariant 3). Only a `pass` whose binding holds
+ * is current: under commit binding, at the assessed commit and graph hash;
+ * under subject binding, while the subject it checked is unchanged. Everything
+ * else is something else, and says which. A failing current run stays visible
+ * however many older passes there are, because the status is decided by the
+ * latest current run and every run is kept in the history.
  */
-import { type Diagnostic, type Graph, sortDiagnostics } from "@intentset/core";
+import {
+  type Diagnostic,
+  type EvidenceBinding,
+  type EvidenceBindingReason,
+  type Graph,
+  sortDiagnostics,
+} from "@intentset/core";
 import { compareStrings, evidenceDiagnostic } from "./diagnostic.ts";
 import { CURRENT, compareRecords, type RunRecord, type RunResult, type RunScope } from "./records.ts";
+import { partsChangedAmong, type Subject } from "./subject.ts";
 
 export const EVIDENCE_STATUSES = [
   "current-pass",
@@ -28,6 +36,23 @@ export interface EvidenceSnapshot {
   graphHash: string;
   /** The exact product and release under assessment. Absent or null considers records of every scope, and reports that it did. */
   scope?: RunScope | null;
+  /** The binding in force (Core §8); commit when absent, as before the field existed. */
+  binding?: EvidenceBinding;
+  /**
+   * Why the binding is the one in force: `configured` (the repository asked), `default` (subject, because slices
+   * exist) or `no-slices` (commit, because the repository has no slice claims to hash and did not ask for it,
+   * which EVID004 says). Absent reads as `configured`.
+   */
+  bindingReason?: EvidenceBindingReason;
+  /** Under subject binding: the subject of each verification at the snapshot, by verification ID. */
+  subjects?: ReadonlyMap<string, Subject>;
+  /**
+   * The files changed between a record's commit and the assessed commit, or null when the commit is not an
+   * ancestor of it or git is unavailable. Optional: it only makes the notes and EVID005 more specific.
+   */
+  changedSince?: (commit: string) => readonly string[] | null;
+  /** True for a file that can move some subject: claimed, a used resource's, a global input, a test, a record. */
+  covers?: (path: string) => boolean;
 }
 
 export type ResultCounts = Record<RunResult, number>;
@@ -36,6 +61,10 @@ export interface VerificationEvidence {
   verificationId: string;
   method: "automated" | "manual";
   status: EvidenceStatus;
+  /** The binding that judged this verification. */
+  binding: EvidenceBinding;
+  /** Under subject binding, the hash of the subject it was judged at; null under commit binding and when none could be computed. */
+  subject: string | null;
   /** Why the status is qualified or what was set aside, when anything was. */
   note?: string;
   /** The record that decided the status: the latest at the snapshot, else the latest in scope; null when there is none. */
@@ -54,7 +83,14 @@ export interface RejectedRecord {
 }
 
 export interface Classification {
-  snapshot: { commit: string | null; graphHash: string; scope: RunScope | null };
+  snapshot: {
+    commit: string | null;
+    graphHash: string;
+    scope: RunScope | null;
+    binding: EvidenceBinding;
+    /** Why this binding is in force (`configured` when the caller did not say). */
+    bindingReason: EvidenceBindingReason;
+  };
   /** One entry per verification artifact in the graph, keyed and ordered by ID. */
   verifications: Record<string, VerificationEvidence>;
   /** Records whose scope named another product or release, across every verification. */
@@ -63,7 +99,7 @@ export interface Classification {
   unknown: RunRecord[];
   /** Records that cannot be evidence for the verification they name (EVID001), by evidence ID. */
   rejected: RejectedRecord[];
-  /** EVID001 and EVID002, sorted. */
+  /** EVID001, EVID002, EVID004, EVID005, EVID006 and EVID007, sorted. */
   diagnostics: Diagnostic[];
 }
 
@@ -74,6 +110,25 @@ export interface ClassifyOptions {
 
 const NOTE_COMMIT_UNKNOWN = "commit unknown; matched on graph hash";
 
+/** The most files EVID005 lists; the rest are counted. */
+export const UNCLAIMED_LIMIT = 20;
+
+/** The most verifications EVID006 lists, and the most files it lists for each resource; the rest are counted. */
+export const UNEXERCISED_LIMIT = 20;
+const UNEXERCISED_FILES = 5;
+
+/** The most verifications EVID007 lists, and the most files it lists for each dependency slice; the rest are counted. */
+export const DEPENDENCY_INTERNALS_LIMIT = 20;
+const DEPENDENCY_INTERNALS_FILES = 5;
+
+/** What EVID007 collects: per dependency slice, the changed files of it outside its entrypoints and the current verifications that depend on it. */
+type Internals = Map<string, { files: Set<string>; verifications: Set<string> }>;
+
+/** What EVID006 collects: per resource, the changed files of it and the current verifications that use it without exercising it. */
+type Unexercised = Map<string, { files: Set<string>; verifications: Set<string> }>;
+
+const short = (commit: string) => commit.slice(0, 9);
+
 /** Core §8: classify every verification in the graph against the snapshot. Deterministic for identical inputs. */
 export function classifyEvidence(
   graph: Graph,
@@ -139,7 +194,26 @@ export function classifyEvidence(
     inScope.get(record.verificationId)?.push(record);
   }
 
+  const binding = snapshot.binding ?? "commit";
+  if (snapshot.bindingReason === "no-slices") {
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID004",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message:
+          "No slice claims files, so there is no subject to bind evidence to: it is judged by commit binding (a record is current only at the assessed commit and graph hash).",
+        remediation:
+          "Declare slices with claims (VSA §3) so evidence can stay current while its subject is unchanged, or set `evidence.binding: commit` in .intentset/config.yaml to choose this on purpose (Core §8).",
+      }),
+    );
+  }
+
   const verifications: Record<string, VerificationEvidence> = {};
+  const unclaimed = new Set<string>();
+  const unexercised: Unexercised = new Map();
+  const internals: Internals = new Map();
   for (const id of ids) {
     const artifact = graph.artifacts.get(id);
     const history = (inScope.get(id) ?? []).sort(compareRecords);
@@ -149,11 +223,85 @@ export function classifyEvidence(
       history,
       outOfScope.get(id) ?? 0,
       snapshot,
+      binding,
+      unclaimed,
+      unexercised,
+      internals,
+    );
+  }
+  // A file of a resource EVID006 reports is not listed here as well: EVID006 says more (which verifications use it).
+  for (const entry of unexercised.values()) for (const file of entry.files) unclaimed.delete(file);
+  if (unclaimed.size > 0) {
+    const files = [...unclaimed].sort(compareStrings);
+    const listed = files.slice(0, UNCLAIMED_LIMIT);
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID005",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message: `${files.length} file${files.length === 1 ? "" : "s"} changed since the commit of a subject-bound record and no slice claims, no exercised resource names and no global input lists ${files.length === 1 ? "it" : "them"}, so ${files.length === 1 ? "it" : "they"} cannot make any evidence stale: ${listed.join(", ")}${files.length > listed.length ? `, and ${files.length - listed.length} more` : ""}.`,
+        remediation:
+          "Claim the file in a slice (the architecture check's unclaimed files rule), name its resource in a verification's `exercises`, or list it in `evidence.globalInputs` if it affects every check (Core §8).",
+      }),
+    );
+  }
+  if (unexercised.size > 0) {
+    const resources = [...unexercised].sort(([a], [b]) => compareStrings(a, b));
+    const all = new Set<string>();
+    for (const [, entry] of resources) for (const id of entry.verifications) all.add(id);
+    const verifications = [...all].sort(compareStrings);
+    const listed = verifications.slice(0, UNEXERCISED_LIMIT);
+    const what = resources.map(([id, entry]) => {
+      const files = [...entry.files].sort(compareStrings);
+      const shown = files.slice(0, UNEXERCISED_FILES).join(", ");
+      return `${id} (${shown}${files.length > UNEXERCISED_FILES ? `, and ${files.length - UNEXERCISED_FILES} more` : ""})`;
+    });
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID006",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message: `${verifications.length} verification${verifications.length === 1 ? " is" : "s are"} current though a resource ${verifications.length === 1 ? "it uses" : "they use"} and ${verifications.length === 1 ? "does" : "do"} not exercise changed since the commit of ${verifications.length === 1 ? "its" : "their"} record: ${what.join("; ")}; ${listed.join(", ")}${verifications.length > listed.length ? `, and ${verifications.length - listed.length} more` : ""}.`,
+        remediation:
+          "Where a check does depend on that resource, name it in the verification's `exercises` so a change to it makes the record stale, or set `evidence.resources: used` to hash every resource a slice lists (Core §8).",
+      }),
+    );
+  }
+
+  if (internals.size > 0) {
+    const slices = [...internals].sort(([a], [b]) => compareStrings(a, b));
+    const all = new Set<string>();
+    for (const [, entry] of slices) for (const id of entry.verifications) all.add(id);
+    const verifications = [...all].sort(compareStrings);
+    const listed = verifications.slice(0, DEPENDENCY_INTERNALS_LIMIT);
+    const what = slices.map(([id, entry]) => {
+      const files = [...entry.files].sort(compareStrings);
+      const shown = files.slice(0, DEPENDENCY_INTERNALS_FILES).join(", ");
+      return `${id} (${shown}${files.length > DEPENDENCY_INTERNALS_FILES ? `, and ${files.length - DEPENDENCY_INTERNALS_FILES} more` : ""})`;
+    });
+    diagnostics.push(
+      evidenceDiagnostic({
+        code: "EVID007",
+        severity: "warning",
+        artifact: null,
+        path: null,
+        message: `${verifications.length} verification${verifications.length === 1 ? " is" : "s are"} current though a slice ${verifications.length === 1 ? "it depends" : "they depend"} on changed outside its entrypoints and contracts since the commit of ${verifications.length === 1 ? "its" : "their"} record: ${what.join("; ")}; ${listed.join(", ")}${verifications.length > listed.length ? `, and ${verifications.length - listed.length} more` : ""}.`,
+        remediation:
+          "Where a check does depend on that slice's internals, name the slice in the verification's `exercises` so a change to it makes the record stale, or set `evidence.dependencies: files` to hash every file a dependency claims (Core §8).",
+      }),
     );
   }
 
   return {
-    snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash, scope },
+    snapshot: {
+      commit: snapshot.commit,
+      graphHash: snapshot.graphHash,
+      scope,
+      binding,
+      bindingReason: snapshot.bindingReason ?? "configured",
+    },
     verifications,
     ignoredOutOfScope,
     unknown,
@@ -173,9 +321,14 @@ function classifyOne(
   history: RunRecord[],
   outOfScope: number,
   snapshot: EvidenceSnapshot,
+  binding: EvidenceBinding,
+  unclaimed: Set<string>,
+  unexercised: Unexercised,
+  internals: Internals,
 ): VerificationEvidence {
   const counts: ResultCounts = { pass: 0, fail: 0, skip: 0, error: 0 };
-  const base = { verificationId, method, history, atSnapshot: counts, outOfScope };
+  const subjectHash = binding === "subject" ? (snapshot.subjects?.get(verificationId)?.hash ?? null) : null;
+  const base = { verificationId, method, binding, subject: subjectHash, history, atSnapshot: counts, outOfScope };
   const ignored =
     outOfScope > 0 ? `${outOfScope} record${outOfScope === 1 ? "" : "s"} for another product or release ignored` : null;
 
@@ -194,25 +347,146 @@ function classifyOne(
     ]);
   }
 
-  const current = history.filter((record) => atSnapshot(record, snapshot));
+  const subject = snapshot.subjects?.get(verificationId);
+  if (binding === "subject" && subject === undefined) {
+    return withNote({ ...base, status: "unresolved", latest: history[history.length - 1] }, [
+      "subject binding is in force but no subject could be computed for this verification",
+      ignored,
+    ]);
+  }
+
+  const current =
+    binding === "subject"
+      ? history.filter((record) => record.binding === "subject" && record.subjectHash === subject?.hash)
+      : history.filter((record) => record.binding !== "subject" && atSnapshot(record, snapshot));
   for (const record of current) counts[record.result]++;
   if (current.length === 0) {
-    return withNote({ ...base, status: "stale", latest: history[history.length - 1] }, [ignored]);
+    const latest = history[history.length - 1];
+    return withNote({ ...base, status: "stale", latest }, [staleNote(latest, binding, subject, snapshot), ignored]);
   }
 
   const latest = current[current.length - 1];
   const status: EvidenceStatus =
     latest.result === "pass" ? "current-pass" : latest.result === "fail" ? "current-fail" : latest.result;
-  return withNote({ ...base, status, latest }, [snapshot.commit === null ? NOTE_COMMIT_UNKNOWN : null, ignored]);
+  const notes: (string | null)[] = [];
+  if (binding === "subject") {
+    const unlisted = collectUnclaimed(latest, snapshot, unclaimed);
+    collectUnexercised(verificationId, latest, subject, snapshot, unexercised);
+    collectInternals(verificationId, latest, subject, snapshot, internals);
+    notes.push(`judged by subject binding; the run was at commit ${short(latest.commit)}${unlisted}`);
+  } else if (snapshot.commit === null) notes.push(NOTE_COMMIT_UNKNOWN);
+  notes.push(ignored);
+  return withNote({ ...base, status, latest }, notes);
+}
+
+/** Why the latest record is not current under the binding in force, with what moved when that can be said. */
+function staleNote(
+  latest: RunRecord,
+  binding: EvidenceBinding,
+  subject: Subject | undefined,
+  snapshot: EvidenceSnapshot,
+): string | null {
+  if (binding === "commit") {
+    return latest.binding === "subject"
+      ? "latest record is bound to a subject, not to a commit; a gate that asks for commit binding needs a run imported at this commit with commit binding"
+      : null;
+  }
+  if (latest.binding !== "subject") {
+    return `latest record is bound to commit ${short(latest.commit)}, not to a subject, so subject binding judges it stale; it can be re-imported to bind it to the subject`;
+  }
+  if (snapshot.changedSince === undefined || subject === undefined) return "the subject changed since the run";
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null) {
+    return `the subject changed since the run; which part moved is unknown, because commit ${short(latest.commit)} is not an ancestor of the assessed commit or git is unavailable`;
+  }
+  const parts = partsChangedAmong(subject, new Set(changed));
+  return parts.length === 0
+    ? `the subject changed since the run at commit ${short(latest.commit)}, in a part no changed file names (a file that left the subject, or a record moved)`
+    : `the subject changed since the run at commit ${short(latest.commit)}: ${parts.slice(0, 5).join(", ")}${parts.length > 5 ? `, and ${parts.length - 5} more` : ""}`;
+}
+
+/** Collects what changed outside every subject since a current record's commit (EVID005), and says when that cannot be known. */
+function collectUnclaimed(latest: RunRecord, snapshot: EvidenceSnapshot, unclaimed: Set<string>): string {
+  if (snapshot.changedSince === undefined || snapshot.covers === undefined) return "";
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null) {
+    return `; files changed since then could not be listed, because the commit is not an ancestor of the assessed commit or git is unavailable`;
+  }
+  for (const path of changed) if (!snapshot.covers(path)) unclaimed.add(path);
+  return "";
+}
+
+/**
+ * Collects the resources a current record's verification uses without exercising (EVID006) whose files changed since
+ * the record's commit: the subject cannot see them, so the record stays current, and the report says so. It asks for
+ * the same `changedSince` as EVID005, and has nothing to say when that cannot be answered (EVID005's note says so).
+ */
+function collectUnexercised(
+  verificationId: string,
+  latest: RunRecord,
+  subject: Subject | undefined,
+  snapshot: EvidenceSnapshot,
+  unexercised: Unexercised,
+): void {
+  if (snapshot.changedSince === undefined || subject === undefined || subject.unexercised.length === 0) return;
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null || changed.length === 0) return;
+  const moved = new Set(changed);
+  for (const resource of subject.unexercised) {
+    const files = resource.files.filter((path) => moved.has(path));
+    if (files.length === 0) continue;
+    const entry = unexercised.get(resource.id) ?? { files: new Set<string>(), verifications: new Set<string>() };
+    for (const path of files) entry.files.add(path);
+    entry.verifications.add(verificationId);
+    unexercised.set(resource.id, entry);
+  }
+}
+
+/**
+ * Collects the dependency slices a current record's verification counts only through their entrypoints and contracts
+ * (EVID007) whose other files changed since the record's commit: the subject cannot see them, so the record stays
+ * current, and the report says so. Like EVID006 it has nothing to say when git cannot answer.
+ */
+function collectInternals(
+  verificationId: string,
+  latest: RunRecord,
+  subject: Subject | undefined,
+  snapshot: EvidenceSnapshot,
+  internals: Internals,
+): void {
+  if (snapshot.changedSince === undefined || subject === undefined || subject.dependencyInternals.length === 0) return;
+  const changed = snapshot.changedSince(latest.commit);
+  if (changed === null || changed.length === 0) return;
+  const moved = new Set(changed);
+  for (const slice of subject.dependencyInternals) {
+    const files = slice.files.filter((path) => moved.has(path));
+    if (files.length === 0) continue;
+    const entry = internals.get(slice.id) ?? { files: new Set<string>(), verifications: new Set<string>() };
+    for (const path of files) entry.files.add(path);
+    entry.verifications.add(verificationId);
+    internals.set(slice.id, entry);
+  }
 }
 
 function withNote(evidence: Omit<VerificationEvidence, "note">, notes: (string | null)[]): VerificationEvidence {
   const present = notes.filter((note): note is string => note !== null);
-  const { verificationId, method, status, latest, history, atSnapshot: counts, outOfScope } = evidence;
+  const {
+    verificationId,
+    method,
+    binding,
+    subject,
+    status,
+    latest,
+    history,
+    atSnapshot: counts,
+    outOfScope,
+  } = evidence;
   return {
     verificationId,
     method,
     status,
+    binding,
+    subject,
     ...(present.length > 0 ? { note: present.join("; ") } : {}),
     latest,
     history,

package/src/fixture.ts

@@ -12,9 +12,26 @@
  * 4. Check locators against the tree's paths (documents and sources) only
  *    when the case supplies `sources`; a case without them has no tree to
  *    check against, and its locators are reported unresolved instead.
- * 5. The case's diagnostics are validation's plus the reader's plus the check's.
+ * 5. Decide the binding (`resolveBinding`): the case's `.intentset/config.yaml`
+ *    `evidence.binding`, else subject where the graph has slice claims, else
+ *    commit with EVID004. Under subject binding the driver resolves what the
+ *    architecture package knows (claimed files, import closures) over the
+ *    tree of documents and sources into a `SubjectSource`, and every
+ *    verification's subject is computed from it (`subjectsFor`).
+ * 6. The case's `changedSince`, when it has one, answers the question git
+ *    would: the files changed between a record's commit and the snapshot.
+ *    A commit it does not list is one that is not an ancestor.
+ * 7. The case's diagnostics are validation's plus the reader's plus the check's.
  */
-import { type Diagnostic, type Graph, graphHash, type Level, sortDiagnostics } from "@intentset/core";
+import {
+  type Diagnostic,
+  type EvidenceBinding,
+  type Graph,
+  graphHash,
+  type Level,
+  sortDiagnostics,
+} from "@intentset/core";
+import { hasSliceClaims, resolveBinding, type SubjectSource, subjectsFor } from "./binding.ts";
 import { type EvidenceCheck, checkEvidence } from "./check.ts";
 import type { EvidenceSnapshot } from "./classify.ts";
 import { bindPlaceholders, FIXTURE_COMMIT, requestedScope } from "./placeholders.ts";
@@ -34,6 +51,12 @@ export interface FixtureEvidenceInput {
   documents: Iterable<string>;
   /** Paths of the case's `sources`. */
   sources: Iterable<string>;
+  /** `evidence.binding` of the case's configuration; null or absent when it states none. */
+  configuredBinding?: EvidenceBinding | null;
+  /** What the architecture package resolved over the tree; needed only when the binding in force is subject. */
+  subjectSource?: SubjectSource;
+  /** The case's `changedSince`: for a commit, the files changed between it and the snapshot. */
+  changedSince?: Readonly<Record<string, readonly string[]>>;
 }
 
 export interface FixtureEvidenceRun extends EvidenceCheck {
@@ -43,11 +66,21 @@ export interface FixtureEvidenceRun extends EvidenceCheck {
 }
 
 export function checkFixtureEvidence(input: FixtureEvidenceInput): FixtureEvidenceRun {
-  const snapshot: EvidenceSnapshot = {
+  const decision = resolveBinding(input.configuredBinding ?? null, hasSliceClaims(input.graph));
+  const base: EvidenceSnapshot = {
     commit: FIXTURE_COMMIT,
     graphHash: graphHash(input.graph),
     scope: requestedScope(input.request),
   };
+  const snapshot: EvidenceSnapshot = { ...base, binding: decision.binding, bindingReason: decision.reason };
+  if (decision.binding === "subject" && input.subjectSource !== undefined) {
+    snapshot.subjects = subjectsFor(input.graph, input.subjectSource);
+    snapshot.covers = input.subjectSource.covers;
+    if (input.changedSince !== undefined) {
+      const changed = input.changedSince;
+      snapshot.changedSince = (commit) => changed[commit] ?? null;
+    }
+  }
   const read = readRunRecords(bindPlaceholders(input.evidence, snapshot), FIXTURE_EVIDENCE_PATH);
   const sources = [...input.sources];
   const files = sources.length > 0 ? new Set([...input.documents, ...sources]) : undefined;

package/src/index.ts

@@ -6,7 +6,9 @@
  */
 export * from "./adapters/common.ts";
 export * from "./adapters/node-test.ts";
+export * from "./adapters/playwright.ts";
 export * from "./adapters/vitest.ts";
+export * from "./binding.ts";
 export * from "./check.ts";
 export * from "./classify.ts";
 export * from "./coverage.ts";
@@ -14,3 +16,5 @@ export * from "./fixture.ts";
 export * from "./placeholders.ts";
 export * from "./records.ts";
 export * from "./report.ts";
+export * from "./stale.ts";
+export * from "./subject.ts";

package/src/records.ts

@@ -15,13 +15,17 @@ import { compareStrings, evidenceDiagnostic, pointerToken } from "./diagnostic.t
 export const RUN_RESULTS = ["pass", "fail", "skip", "error"] as const;
 export type RunResult = (typeof RUN_RESULTS)[number];
 
+/** What a record is bound to (Core §8): the subject the run checked, or the commit and graph hash it ran at. */
+export const RUN_BINDINGS = ["subject", "commit"] as const;
+export type RunBinding = (typeof RUN_BINDINGS)[number];
+
 /** The literal a fixture writes for "the snapshot's commit" or "the snapshot's graph hash". */
 export const CURRENT = "@current";
 
 export interface RunScope {
   /** The product's artifact ID. */
   product: string;
-  /** The exact release label; v0.1 matches release labels exactly (Core §7). */
+  /** The exact release label; v0.2 matches release labels exactly (Core §7). */
   release: string;
 }
 
@@ -48,6 +52,10 @@ export interface RunRecord {
   finishedAt: string;
   result: RunResult;
   uri: string;
+  /** Absent means commit binding, as every record written before the field existed. */
+  binding?: RunBinding;
+  /** SHA-256 of the subject the run checked (subject.ts); present on every subject-binding record. */
+  subjectHash?: string;
   rationale?: string;
   /** Namespaced extensions (`org.example/key`), preserved and never interpreted. */
   extensions?: Record<string, unknown>;
@@ -67,7 +75,7 @@ const REQUIRED = [
   "result",
   "uri",
 ] as const;
-const KNOWN = new Set<string>([...REQUIRED, "rationale", "extensions"]);
+const KNOWN = new Set<string>([...REQUIRED, "binding", "subjectHash", "rationale", "extensions"]);
 
 const TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/;
 const GRAPH_HASH = /^[0-9a-f]{64}$/;
@@ -261,6 +269,34 @@ function readRecord(entry: unknown, index: number, problems: Problem[]): RunReco
       );
   }
 
+  let binding: RunBinding | undefined;
+  if (Object.hasOwn(entry, "binding")) {
+    if ((RUN_BINDINGS as readonly unknown[]).includes(entry.binding)) binding = entry.binding as RunBinding;
+    else
+      problem(
+        "binding",
+        `\`binding\` of run record ${index} must be subject or commit, but it is ${describe(entry.binding)}.`,
+        "Write `binding: subject` for a record bound to its subject, or leave it out for a commit-binding record (Core §8).",
+      );
+  }
+  let subjectHash: string | undefined;
+  if (Object.hasOwn(entry, "subjectHash")) {
+    if (typeof entry.subjectHash === "string" && GRAPH_HASH.test(entry.subjectHash)) subjectHash = entry.subjectHash;
+    else
+      problem(
+        "subjectHash",
+        `\`subjectHash\` of run record ${index} must be 64 lowercase hex characters, but it is ${describe(entry.subjectHash)}.`,
+        "Record the subject hash `intentset evidence import` computed for the verification (Core §8).",
+      );
+  }
+  if (binding === "subject" && !Object.hasOwn(entry, "subjectHash")) {
+    problem(
+      "subjectHash",
+      `Run record ${index} has binding subject but no \`subjectHash\`, so nothing says what it was bound to.`,
+      "Add the subject hash, or leave `binding` out to make it a commit-binding record (Core §8).",
+    );
+  }
+
   let rationale: string | undefined;
   if (Object.hasOwn(entry, "rationale")) {
     if (typeof entry.rationale === "string" && /\S/.test(entry.rationale)) rationale = entry.rationale;
@@ -336,6 +372,8 @@ function readRecord(entry: unknown, index: number, problems: Problem[]): RunReco
     result: result as RunResult,
     uri: uri as string,
   };
+  if (binding !== undefined) record.binding = binding;
+  if (subjectHash !== undefined) record.subjectHash = subjectHash;
   if (rationale !== undefined) record.rationale = rationale;
   if (extensions !== undefined) record.extensions = extensions;
   return record;

package/src/report.ts

@@ -16,10 +16,14 @@ export function evidenceReport(check: EvidenceCheck, records: number): EvidenceR
     graphHash: classification.snapshot.graphHash,
     scope: classification.snapshot.scope,
     records,
+    binding: classification.snapshot.binding,
+    bindingReason: classification.snapshot.bindingReason,
     verifications: Object.values(classification.verifications).map((v) => ({
       id: v.verificationId,
       method: v.method,
       status: v.status,
+      binding: v.binding,
+      subject: v.subject,
       note: v.note ?? null,
       latest: v.latest,
       atSnapshot: { ...v.atSnapshot },