@intentius/chant 0.82.0 → 0.84.0

package/src/workspace/records-cli.ts

@@ -12,12 +12,16 @@
  * nothing is inferred (#2525 rule 1).
  */
 
+import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { relative } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
+import { findWorkspaceRoot } from "../project-root";
+import { fileDigest, isWorkspacePath } from "./record-assets";
 import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
-import { loadRecordKind, readRecords, RecordReadError, type ReadErrorCode, type RecordEntry } from "./records";
+import { loadRecordKind, readRecords, RecordReadError, type LoadedRecordKind, type ReadErrorCode, type ReadRecordsResult, type RecordEntry, type RecordHistory } from "./records";
+import { gitTree, workingTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
 
@@ -27,7 +31,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 /** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
-const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]";
+const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records pin <path>";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -63,6 +67,8 @@ export type RecordsDocument =
       contract: number;
       kind: { name: string; schema: string; file: string };
       at: string | null;
+      /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
+      workspaceRoot: string;
       current: boolean;
       trust: TrustView;
       records: RecordView[];
@@ -70,23 +76,84 @@ export type RecordsDocument =
     }
   | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
 
-/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
-export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
+/** A records read, before provenance. */
+export interface RecordsRead {
+  loaded: LoadedRecordKind;
+  /** The repository root, or the working directory outside git. Record paths are relative to it. */
+  root: string;
+  /** The git top, or undefined outside git. */
+  top: string | undefined;
+  at: string | null;
+  /** Where pinned paths resolve, relative to `root` ("." for the root itself). */
+  workspaceRoot: string;
+  result: ReadRecordsResult;
+}
+
+/**
+ * Where a kind's pinned paths resolve: the workspace whose declaration sits
+ * nearest above the kind file, when it is inside the repository, or else the
+ * repository root. Relative to `root`, with / separators.
+ */
+function pinRoot(kindFile: string, root: string): string {
+  const found = findWorkspaceRoot(dirname(kindFile));
+  if (!found) return ".";
+  const rel = relative(root, realpathOr(found.dir)).split(sep).join("/");
+  return rel === "" || rel.startsWith("..") ? "." : rel;
+}
+
+/**
+ * Commit times from the history of `rev` in the repository at `top`, asked
+ * only for a pin that might be stale. `prefix` is the workspace root from the
+ * repository root.
+ */
+function gitHistory(top: string, rev: string, prefix: string): RecordHistory {
+  const times = (args: string[]): number[] => {
+    try {
+      const out = execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+      return out.split("\n").filter(Boolean).map(Number);
+    } catch {
+      // No commits yet, or a path git doesn't know.
+      return [];
+    }
+  };
+  return {
+    fileChanged: (path) => times(["log", "-1", "--format=%ct", rev, "--", prefix === "." ? path : `${prefix}/${path}`])[0] ?? null,
+    // The latest commit that added the file: a record deleted and written again counts from the second time.
+    recorded: (path) => times(["log", "--diff-filter=A", "--format=%ct", rev, "--", path])[0] ?? null,
+  };
+}
+
+/**
+ * Load the kind and read its records, in the working tree or at `query.at`,
+ * with each pin checked in the same tree. Throws a {@link RecordReadError}.
+ * `chant workspace graph` and `check` read records through this too.
+ */
+export async function readRecordsFor(query: Omit<RecordsQuery, "base">): Promise<RecordsRead> {
   // git reports its top through symlinks resolved (/var is /private/var on
   // macOS), so the directory has to be too, or record paths leave the repository.
   const cwd = realpathOr(query.cwd);
   const top = gitRoot(cwd);
   const root = top ?? cwd;
+  const loaded = await loadRecordKind(query.kind, cwd);
+  const workspaceRoot = pinRoot(loaded.file, root);
+  let at: string | null = null;
+  let source = workingTreeSource(root);
+  let assets = workingTree(workspaceRoot === "." ? root : join(root, ...workspaceRoot.split("/")));
+  if (query.at !== undefined) {
+    if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+    at = resolveRevision(top, query.at);
+    source = gitRevisionSource(top, at);
+    assets = gitTree(top, at, workspaceRoot === "." ? "" : workspaceRoot);
+  }
+  const history = top ? gitHistory(top, at ?? "HEAD", workspaceRoot) : undefined;
+  const result = await readRecords(loaded, { root, source, current: !!query.current, assets, ...(history ? { history } : {}) });
+  return { loaded, root, top, at, workspaceRoot, result };
+}
+
+/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
+export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
   try {
-    const loaded = await loadRecordKind(query.kind, cwd);
-    let at: string | null = null;
-    let source = workingTreeSource(root);
-    if (query.at !== undefined) {
-      if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
-      at = resolveRevision(top, query.at);
-      source = gitRevisionSource(top, at);
-    }
-    const result = await readRecords(loaded, { root, source, current: !!query.current });
+    const { loaded, root, top, at, workspaceRoot, result } = await readRecordsFor(query);
     // Provenance, judged by the policy at base and never by the tree read (#2547).
     const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
     const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
@@ -106,6 +173,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
         file: relative(root, loaded.file).split("\\").join("/"),
       },
       at,
+      workspaceRoot,
       current: !!query.current,
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
       records: result.records.map((r) => ({ ...r, provenance: provenance.get(r.path)! })),
@@ -117,8 +185,42 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   }
 }
 
+/**
+ * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
+ * evidence entry holds for a file, with the path from the workspace root
+ * (the nearest declaration above the file, or the repository root).
+ */
+export function pinFile(file: string, cwd: string): { path: string; sha256: string } | { error: string } {
+  const abs = realpathOr(resolve(cwd, file));
+  const top = gitRoot(dirname(abs));
+  const ws = findWorkspaceRoot(dirname(abs));
+  const base = ws ? realpathOr(ws.dir) : top ? realpathOr(top) : realpathOr(cwd);
+  const path = relative(base, abs).split(sep).join("/");
+  if (path.startsWith("..") || !isWorkspacePath(path)) return { error: `${file} is not a file path inside the workspace at ${base}` };
+  const sha256 = fileDigest(workingTree(base), path);
+  if (sha256 === undefined) return { error: `${file} is not a file` };
+  return { path, sha256 };
+}
+
 export async function runWorkspaceRecords(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (args.extraPositional === "pin") {
+    if (!args.extraPositional2) {
+      console.error(formatError({ message: "pin needs the path of a file", hint: USAGE }));
+      return 1;
+    }
+    const pin = pinFile(args.extraPositional2, process.cwd());
+    if ("error" in pin) {
+      console.error(formatError({ message: pin.error, hint: USAGE }));
+      return 1;
+    }
+    console.log(JSON.stringify(pin, null, 2));
+    return 0;
+  }
+  if (args.extraPositional) {
+    console.error(formatError({ message: `chant workspace records takes no argument but pin (got ${args.extraPositional})`, hint: USAGE }));
+    return 1;
+  }
   if (!args.kind) {
     console.error(formatError({ message: "--kind <kind file> is required", hint: USAGE }));
     return 1;
@@ -178,6 +280,7 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${flag}`);
     for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
+    for (const warning of r.warnings) lines.push(`${" ".repeat(idWidth + 2)}warning ${warning.code}: ${warning.message} (${r.path})`);
   }
   lines.push(
     `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,

package/src/workspace/records.schema.json

@@ -26,6 +26,10 @@
           "type": ["string", "null"],
           "pattern": "^[0-9a-f]{40,64}$"
         },
+        "workspaceRoot": {
+          "type": "string",
+          "description": "Added in contract 1 by #2549. The directory a record's pinned paths resolve in, from the repository root with / separators: the workspace whose declaration sits nearest above the kind file, or \".\" for the repository root."
+        },
         "error": false,
         "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
         "trust": { "$ref": "#/$defs/trust" },
@@ -63,7 +67,17 @@
           "type": ["object", "null"],
           "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
         },
-        "provenance": { "$ref": "#/$defs/provenance" }
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "assets": {
+          "description": "Added in contract 1 by #2549. Each workspace file the record pins by hash, checked against the tree read: the working tree, or the revision under --at. Empty for a kind that pins nothing.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/asset" }
+        },
+        "warnings": {
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, or a supersedes link that has no effect yet. valid and --current do not look at them.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/warning" }
+        }
       },
       "allOf": [
         {
@@ -73,6 +87,24 @@
         }
       ]
     },
+    "asset": {
+      "type": "object",
+      "required": ["path", "sha256", "actual", "state"],
+      "properties": {
+        "path": { "type": "string", "description": "From the workspace root (workspaceRoot), with / separators." },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The hash the record pins." },
+        "actual": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "The hash of the file's bytes in the tree read, or null when the file is missing." },
+        "state": { "enum": ["pinned", "drifted", "missing", "stale"], "description": "pinned when the hashes match; drifted when they differ (a warning asset-drift); missing when the file is not there (a warning asset-missing); stale when the hashes match and a record this one supersedes pinned the same hash, with the file unchanged since this record was recorded (a warning asset-stale)." }
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"] },
+        "message": { "type": "string" }
+      }
+    },
     "trust": {
       "description": "Added in contract 1 by #2547. Where provenance was judged from: the policy read at the base revision, never the tree read.",
       "type": "object",

package/src/workspace/records.test.ts

@@ -133,6 +133,56 @@ describe("readRecords", () => {
     ]);
   });
 
+  test("a decided record supersedes a decided one, under an equal approval rule (#2524 D4)", async () => {
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.valid, r.warnings])).toEqual([
+      ["ws-001", "ws-002", true, []],
+      ["ws-002", null, true, []],
+    ]);
+    const current = await read({ current: true });
+    expect(current.records.map((r) => r.id)).toEqual(["ws-002"]);
+  });
+
+  test("a proposed record supersedes nothing: the link is pending, as a warning on the new record", async () => {
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "proposed", ["ws-001"]).replace(/^choice:\n  option: .*\n  reason: .*\n/m, "choice: null\n"));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.valid])).toEqual([
+      ["ws-001", null, true],
+      ["ws-002", null, true],
+    ]);
+    expect(all.records[1].warnings.map((w) => w.code)).toEqual(["record-supersedes-pending"]);
+    expect((await read({ current: true })).records.map((r) => r.id)).toEqual(["ws-001", "ws-002"]);
+  });
+
+  test("a decided record can't supersede a ratified one; a ratified record supersedes any", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    write("ws-003-c.md", decision("ws-003", "decided"));
+    write("ws-004-d.md", decision("ws-004", "ratified", ["ws-003"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-001", null, []],
+      ["ws-002", null, ["record-supersedes-pending"]],
+      ["ws-003", "ws-004", []],
+      ["ws-004", null, []],
+    ]);
+  });
+
+  test("a kind without approval ranks keeps the closed-state rule", async () => {
+    const kind = readFileSync(join(dir, "decisions", "decision.kind.mjs"), "utf-8").replace(/^  approval: .*\n/m, "");
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), kind);
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.warnings])).toEqual([
+      ["ws-001", null, []],
+      ["ws-002", null, []],
+    ]);
+  });
+
   test("a record superseded twice keeps the first and flags the second", async () => {
     write("ws-001-a.md", decision("ws-001", "ratified"));
     write("ws-002-b.md", decision("ws-002", "ratified", ["ws-001"]));

package/src/workspace/records.ts

@@ -22,7 +22,9 @@ import yaml from "js-yaml";
 import { z } from "zod";
 import { importLexiconModule, registerLexiconDeclarations } from "../lexicon-module";
 import type { ReasonCode } from "./reason-codes";
+import { checkPins, pinEntries, type AssetPin } from "./record-assets";
 import type { RecordSource } from "./record-source";
+import type { WorkspaceTree } from "./tree";
 
 // ── Reason codes ─────────────────────────────────────────────────────────────
 
@@ -44,6 +46,30 @@ export const RECORD_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
 
+/**
+ * Why a record carries a warning. Closed, like the reason codes. A warning
+ * never makes a record invalid, and `--current` still lists the record.
+ */
+export const RECORD_WARNING_CODES = [
+  /** A pinned file's bytes no longer hash to the pinned sha256 (#2549). */
+  "asset-drift",
+  /** A pinned file does not exist in the tree read (#2549). */
+  "asset-missing",
+  /**
+   * A pinned file is unchanged since a record this one supersedes pinned it at
+   * the same hash: the decision changed and the artifact did not follow (#2549).
+   */
+  "asset-stale",
+  /** A supersedes link from a record whose state is weaker than the one it names, so it has no effect yet (#2524 D4). */
+  "record-supersedes-pending",
+] as const satisfies readonly ReasonCode[];
+export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
+
+export interface RecordWarning {
+  code: RecordWarningCode;
+  message: string;
+}
+
 /**
  * Why the read as a whole failed. Also closed. The command exits 1 with one of
  * these and returns no records.
@@ -114,11 +140,34 @@ export const recordKindSchema = z
     closedStates: z.array(z.string().min(1)),
     /** The front-matter list of links to superseded records, and the key in each entry that holds the target id. */
     supersedes: z.object({ field: z.string().min(1), key: z.string().min(1) }).strict(),
+    /**
+     * How strongly each state is approved (#2524 D4). With it, a supersedes
+     * link takes effect when the new record's rank is above 0 and at least the
+     * old record's, "under an equal or stricter approval rule". A state it
+     * leaves out ranks 0. Without it, a link takes effect only from a record
+     * in a closed state.
+     */
+    approval: z.record(z.string(), z.number().int().min(0)).optional(),
+    /**
+     * The front-matter list whose entries may pin a workspace file, as
+     * `{path, sha256}` (#2549). Optional: a kind without it pins nothing.
+     */
+    pins: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter list of what a record governs. Its `member:<name>` and
+     * `path:<path>` entries are the record's links in `chant workspace graph`
+     * (#2549). Optional.
+     */
+    constrains: z.object({ field: z.string().min(1) }).strict().optional(),
   })
   .strict()
   .refine((k) => k.closedStates.every((s) => k.states.includes(s)), {
     message: "every closed state must be listed in states",
     path: ["closedStates"],
+  })
+  .refine((k) => Object.keys(k.approval ?? {}).every((s) => k.states.includes(s)), {
+    message: "every state approval ranks must be listed in states",
+    path: ["approval"],
   });
 
 export type RecordKind = z.infer<typeof recordKindSchema>;
@@ -138,7 +187,7 @@ export interface LoadedRecordKind {
  * The kind is registered under a name no lexicon package can have (npm names
  * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
  */
-async function importKindModule(path: string): Promise<Record<string, unknown>> {
+export async function importKindModule(path: string): Promise<Record<string, unknown>> {
   const name = `record-kind:${path}`;
   registerLexiconDeclarations([{ name, module: path }], dirname(path));
   try {
@@ -255,6 +304,10 @@ export interface RecordEntry {
   supersededBy: string | null;
   /** The front matter as JSON, or null when it could not be parsed. */
   data: Record<string, unknown> | null;
+  /** Each workspace file the record pins, checked against the tree read (#2549). Empty when nothing was checked. */
+  assets: AssetPin[];
+  /** Findings that leave the record valid, such as a pinned file that changed (#2549). */
+  warnings: RecordWarning[];
 }
 
 export interface ReadRecordsOptions {
@@ -263,6 +316,25 @@ export interface ReadRecordsOptions {
   source: RecordSource;
   /** Leave out records a closed record supersedes. */
   current?: boolean;
+  /**
+   * The workspace root the kind's pins resolve in: the working tree, or the
+   * revision read (#2549). Without it no pin is checked.
+   */
+  assets?: WorkspaceTree;
+  /**
+   * When files last changed and records were recorded, in the history of the
+   * revision read, for `asset-stale` (#2549). Without it only the hashes are
+   * compared.
+   */
+  history?: RecordHistory;
+}
+
+/** Commit times, in seconds since the epoch, read from git. */
+export interface RecordHistory {
+  /** The last commit that changed `path` (from the workspace root), or null when unknown. */
+  fileChanged(path: string): number | null;
+  /** The commit that added the record at `path` (from the repository root), or null when it is not committed. */
+  recorded(path: string): number | null;
 }
 
 export interface ReadRecordsResult {
@@ -304,7 +376,7 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   const entries: RecordEntry[] = [];
   for (const name of names.filter((n) => match.test(n)).sort()) {
     const path = dirRel === "." ? name : `${dirRel}/${name}`;
-    const entry: RecordEntry = { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null };
+    const entry: RecordEntry = { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null, assets: [], warnings: [] };
     entries.push(entry);
     const fm = parseFrontMatter(options.source.read(path));
     if (!fm.ok) {
@@ -320,6 +392,11 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     if (!result.ok) {
       entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
     }
+    if (kind.pins && options.assets) {
+      const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
+      entry.assets = checked.assets;
+      entry.warnings = checked.warnings;
+    }
   }
 
   // Ids: the first file in path order keeps an id; later ones are flagged.
@@ -332,10 +409,14 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   }
 
   // Supersession comes from the new record's links, never from the old record.
-  // A link takes effect only from a closed record (#2555: a later ratified
-  // decision replaces an earlier one), and a record is superseded at most once
-  // (#2524 D4).
+  // With approval ranks, a link takes effect under an equal or stricter
+  // approval rule: from a record ranked above 0 and at least as high as the
+  // one it names (#2524 D4). Without them, only from a closed record (#2555).
+  // A record is superseded at most once.
   const closed = new Set(kind.closedStates);
+  const rank = (state: string | null): number => (state === null ? 0 : (kind.approval?.[state] ?? 0));
+  const takesEffect = (from: RecordEntry, to: RecordEntry): boolean =>
+    kind.approval ? rank(from.state) > 0 && rank(from.state) >= rank(to.state) : from.state !== null && closed.has(from.state);
   for (const e of entries) {
     const links = e.data?.[kind.supersedes.field];
     if (!Array.isArray(links)) continue;
@@ -348,7 +429,16 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
         e.reasons.push({ code: "record-supersedes-unknown", message: `supersedes ${target}, which no record has` });
         continue;
       }
-      if (e.state === null || !closed.has(e.state) || old === e) continue;
+      if (old === e) continue;
+      if (!takesEffect(e, old)) {
+        if (kind.approval) {
+          e.warnings.push({
+            code: "record-supersedes-pending",
+            message: `supersedes ${target}, which is ${old.state ?? "stateless"}; a ${e.state ?? "stateless"} record can't supersede it, so the link takes effect once this record is approved at least as strongly`,
+          });
+        }
+        continue;
+      }
       if (old.supersededBy !== null && old.supersededBy !== e.id) {
         e.reasons.push({
           code: "record-supersedes-conflict",
@@ -360,6 +450,26 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     }
   }
 
+  // A pin that still matches, at the hash a record this one supersedes
+  // pinned, while the file has not changed since this record was recorded:
+  // the decision moved on and the artifact did not (#2549).
+  for (const e of entries) {
+    for (const a of e.assets) {
+      if (a.state !== "pinned") continue;
+      const old = entries.find((o) => o.supersededBy !== null && o.supersededBy === e.id && o.assets.some((p) => p.path === a.path && p.sha256 === a.sha256));
+      if (!old) continue;
+      const changed = options.history?.fileChanged(a.path) ?? null;
+      const recorded = options.history ? options.history.recorded(e.path) : null;
+      // A record not yet committed is recorded now, after every commit.
+      if (changed !== null && recorded !== null && changed > recorded) continue;
+      a.state = "stale";
+      e.warnings.push({
+        code: "asset-stale",
+        message: `${a.path} is pinned at the hash ${old.id} pinned, and it has not changed since: ${e.id} supersedes ${old.id}, and the artifact did not follow`,
+      });
+    }
+  }
+
   for (const e of entries) e.valid = e.reasons.length === 0;
   const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;
   return {

package/src/workspace/template-pins.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Re-pinning records after template substitution (#2549): a pin that held in
+ * the template follows the substituted file, one that didn't stays, and the
+ * rest of the record is kept byte for byte.
+ */
+
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { repinSubstituted } from "./template-pins";
+
+const sha = (s: string) => createHash("sha256").update(s).digest("hex");
+const buf = (s: string) => Buffer.from(s, "utf-8");
+
+function record(pins: [string, string][]): string {
+  const evidence = pins.map(([path, hash]) => `  - title: "t"\n    path: "${path}"\n    sha256: "${hash}"\n`).join("");
+  return `---\nschema: 1\nid: "ref-002"\nevidence:\n  - title: "a link"\n    url: "https://example.com"\n${evidence}constrains:\n  - "member:design"\n---\n\n# Body mentions ${pins[0]?.[1] ?? ""}\n`;
+}
+
+describe("repinSubstituted", () => {
+  const before = "title {{chant:name}}\n";
+  const after = "title Acme\n";
+  const other = "unchanged\n";
+
+  test("a pin that held on a substituted file gets the new hash; nothing else in the file changes", () => {
+    const text = record([["design/home.json", sha(before)], ["design/other.json", sha(other)]]);
+    const original = new Map([
+      ["chant.workspace.json", buf("{}")],
+      ["design/home.json", buf(before)],
+      ["design/other.json", buf(other)],
+      ["decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("design/home.json", buf(after));
+    const { files, repinned } = repinSubstituted(original, substituted, ["design/home.json"]);
+    expect(repinned).toEqual([{ record: "decisions/ref-002-x.md", paths: ["design/home.json"] }]);
+    const expected = text.replace(`    sha256: "${sha(before)}"`, `    sha256: "${sha(after)}"`);
+    expect(files.get("decisions/ref-002-x.md")!.toString("utf-8")).toBe(expected);
+    // The body's copy of the old hash is not front matter, so it stays.
+    expect(expected).toContain(`# Body mentions ${sha(before)}`);
+  });
+
+  test("a pin that was already drifted in the template stays drifted", () => {
+    const text = record([["design/home.json", sha("something else")]]);
+    const original = new Map([
+      ["design/home.json", buf(before)],
+      ["decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("design/home.json", buf(after));
+    const { files, repinned } = repinSubstituted(original, substituted, ["design/home.json"]);
+    expect(repinned).toEqual([]);
+    expect(files.get("decisions/ref-002-x.md")!.toString("utf-8")).toBe(text);
+  });
+
+  test("paths resolve from the workspace declaration nearest above the record", () => {
+    const text = record([["design/home.json", sha(before)]]);
+    const original = new Map([
+      ["ws/chant.workspace.json", buf("{}")],
+      ["ws/design/home.json", buf(before)],
+      ["ws/decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("ws/design/home.json", buf(after));
+    const { repinned } = repinSubstituted(original, substituted, ["ws/design/home.json"]);
+    expect(repinned).toEqual([{ record: "ws/decisions/ref-002-x.md", paths: ["design/home.json"] }]);
+  });
+
+  test("nothing substituted, nothing re-pinned", () => {
+    const original = new Map([["decisions/ref-002-x.md", buf(record([["design/home.json", sha(before)]]))]]);
+    expect(repinSubstituted(original, original, []).repinned).toEqual([]);
+  });
+});