@intentius/chant 0.82.0 → 0.83.0

package/src/workspace/lineage-check.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]`:
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]`:
  * the lineage checks (#2550, D9), and the declaration checks (#2535, D16)
  * when a declaration sits between the current directory and the git root.
  *
@@ -10,7 +10,9 @@
  * check. The declaration checks report `WSP` findings through lint's
  * reporters (`./checks.ts`), and cover member ledgers (#2538), recorded
  * pipelines (#2542) and generated files (#2541) as well as the declaration
- * itself (#2641). `--generated` runs each declared generator too.
+ * itself (#2641). `--generated` runs each declared generator too. `--kind`
+ * reads a record kind's records and reports the files they pin by hash that
+ * have changed since (#2549).
  *
  * `chant workspace upgrade` runs the same checks in its staging worktree
  * before it reaches its gate.
@@ -23,6 +25,7 @@ import type { CommandContext } from "../cli/registry";
 import type { LintDiagnostic, LintRule } from "../lint/rule";
 import { findWorkspaceRoot } from "../project-root";
 import type { DeclarationCheckReport } from "./checks";
+import type { RecordFacts } from "./checks/records";
 import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
@@ -81,7 +84,7 @@ export function findingKey(f: CheckFinding): string {
   return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
 }
 
-const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]";
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -142,7 +145,7 @@ export type CheckDocument =
  * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
  * since the member facts describe the working tree, not the revision.
  */
-export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean } = {}): Promise<CheckDocument> {
+export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean; kind?: string } = {}): Promise<CheckDocument> {
   // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
   const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
     import("./declaration"),
@@ -184,9 +187,11 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   if (found) {
     const { runDeclarationChecks } = await import("./checks");
     const { dir, tree } = found;
+    const records = options.kind !== undefined ? await readRecordFacts(options.kind, cwd, commit) : undefined;
     declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
       runGenerators: options.runGenerators === true,
       ...(commit !== null ? { tree } : {}),
+      ...(records ? { records } : {}),
     });
     let name: string | null = null;
     try {
@@ -200,6 +205,18 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
 }
 
+/** The records of the kind file `kind` for the record checks (#2549), at `commit` or in the working tree. */
+async function readRecordFacts(kind: string, cwd: string, commit: string | null): Promise<RecordFacts> {
+  const [{ readRecordsFor }, { RecordReadError }] = await Promise.all([import("./records-cli"), import("./records")]);
+  try {
+    const read = await readRecordsFor({ kind, cwd, ...(commit !== null ? { at: commit } : {}) });
+    return { kind, records: read.result.records.map((r) => ({ ...r, file: join(read.root, ...r.path.split("/")) })) };
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+    return { kind, error: { code: err.code, message: err.message } };
+  }
+}
+
 export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
   const root = process.cwd();
   if (ctx.args.extraPositional) {
@@ -218,7 +235,7 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     const handed = await handToRootChant(root, ctx.args.at);
     if (handed !== undefined) return handed;
   }
-  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true });
+  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}) });
   if ("error" in doc) {
     if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
     else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/lineage-init.ts

@@ -36,6 +36,7 @@ import {
 } from "./lineage-lock";
 import { MIGRATIONS_DIR } from "./lineage-migrations";
 import { TEMPLATE_MANIFEST, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
+import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 // ── The template spec ────────────────────────────────────────────────────────
 
@@ -413,11 +414,13 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
   // so a refused --param leaves the target untouched.
   let parameters: Record<string, string>;
   let contents: Map<string, Buffer>;
+  let repinned: RepinnedRecord[];
   try {
     const raw = new Map([...fetched.files].map(([path, f]) => [path, f.data]));
     const manifest = readManifest(raw);
     parameters = resolveParameters(manifest, options.params ?? {});
-    contents = substituteParameters(raw, manifest, parameters);
+    // Records that pin a substituted file get its new hash, so a copy's pins hold (#2549).
+    ({ files: contents, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []));
   } catch (err) {
     return { success: false, createdFiles, warnings, error: (err as Error).message };
   }
@@ -442,6 +445,7 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
 
   const common = {
     parameters,
+    ...(repinned.length > 0 ? { repinned: repinned.filter((r) => written.has(r.record)) } : {}),
     migrations: [],
     files: fileEntries(written, declaredFilesAt(targetDir)),
     manualSteps: [],

package/src/workspace/lineage-lock.ts

@@ -133,6 +133,12 @@ const LineageSchema = z
     address: AddressSchema.nullable(),
     /** The parameter values the template was instantiated with. Always empty for vendor scopes. */
     parameters: z.record(z.string(), z.unknown()),
+    /**
+     * Records whose evidence pins were re-pinned to the substituted content
+     * of a parameterised file (#2549): each record's path in the scope, and the
+     * pinned paths. An upgrade re-pins the base and the target the same way.
+     */
+    repinned: z.array(z.object({ record: z.string().min(1), paths: z.array(z.string().min(1)) }).strict()).optional(),
     /** Migrations applied since instantiation (#2550). */
     migrations: z.array(z.string()),
     /** Per file, relative to the scope directory, in sorted order. */
@@ -249,6 +255,7 @@ function canonical(lock: LineageLock): LineageLock {
       ...(s.ref !== undefined ? { ref: s.ref } : {}),
       address: s.address,
       parameters: s.parameters,
+      ...(s.repinned !== undefined ? { repinned: s.repinned } : {}),
       migrations: s.migrations,
       files,
       manualSteps: [...s.manualSteps].sort((a, b) => a.path.localeCompare(b.path)),

package/src/workspace/lineage-upgrade.test.ts

@@ -7,6 +7,7 @@
 
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -455,6 +456,34 @@ describe("chant workspace upgrade with template parameters (#2627)", () => {
     }
   });
 
+  test("a record that pins a substituted file is re-pinned on the base and the target, so it updates with no manual step (#2549)", async () => {
+    const sha = (s: string) => createHash("sha256").update(s).digest("hex");
+    const record = (hash: string) => `---\nschema: 1\nid: "tpl-001"\nevidence:\n  - title: "readme"\n    path: "README.md"\n    sha256: "${hash}"\n---\n`;
+    // A second project, from a v1 whose record pins the template's README.
+    tpl = join(root, "rtpl");
+    proj = join(root, "rproj");
+    mkdirSync(tpl);
+    git(tpl, ["init", "-q", "-b", "main"]);
+    const manifest = JSON.stringify({ parameters: { name: { type: "string", default: "Starter" } }, files: ["README.md"] });
+    release("v1.0.0", { "chant.template.json": manifest, "README.md": "# {{chant:name}}\n", "decisions/tpl-001-x.md": record(sha("# {{chant:name}}\n")) });
+    const made = await initFromCommand({ from: `${tpl}@v1.0.0`, path: proj, params: { name: "Acme" } });
+    expect(made.error).toBeUndefined();
+    expect(read(proj, "decisions/tpl-001-x.md")).toBe(record(sha("# Acme\n")));
+    expect(readLock(proj)!.scopes["."].repinned).toEqual([{ record: "decisions/tpl-001-x.md", paths: ["README.md"] }]);
+    git(proj, ["init", "-q", "-b", "main"]);
+    commitProject("init");
+
+    release("v2.0.0", { "README.md": "# {{chant:name}} v2\n", "decisions/tpl-001-x.md": record(sha("# {{chant:name}} v2\n")) });
+    const staged = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: passing });
+    try {
+      expect(staged.manualSteps).toEqual([]);
+      expect(read(staged.worktreeProject, "decisions/tpl-001-x.md")).toBe(record(sha("# Acme v2\n")));
+      expect(readLock(staged.worktreeProject)!.scopes["."].repinned).toEqual([{ record: "decisions/tpl-001-x.md", paths: ["README.md"] }]);
+    } finally {
+      staged.dispose();
+    }
+  });
+
   test("an upgrade to the same version changes nothing", async () => {
     const staged = await stageUpgrade({ root: proj, to: "v1.0.0", runChant: passing });
     try {

package/src/workspace/lineage-upgrade.ts

@@ -59,6 +59,7 @@ import { mergeFile } from "./lineage-merge";
 import { assertCodeAllowed, planMigrations, runMigration, splitMigrations, type LoadedMigration } from "./lineage-migrations";
 import { applyUpstream, type UpdateResult } from "./lineage-update";
 import { carryParameters, readManifest, substituteParameters } from "./template-manifest";
+import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 /** The kind the patch digest is taken under, so it never collides with another kind of plan. */
 export const UPGRADE_PLAN_KIND = "workspace-upgrade";
@@ -184,6 +185,8 @@ interface Upstream {
   tree?: string;
   /** The parameter values substituted into `files` (#2627), for a git or directory source. */
   parameters?: Record<string, string>;
+  /** The records re-pinned to substituted files (#2549). */
+  repinned?: RepinnedRecord[];
   /** The source the lock records after the upgrade, when it moves (a directory source). */
   source?: LineageSource;
 }
@@ -191,13 +194,20 @@ interface Upstream {
 /**
  * The template's files as the project would have them (#2627): the manifest
  * removed and the parameters substituted, with the recorded values and the
- * defaults of parameters this version adds.
+ * defaults of parameters this version adds. Records that pin a substituted
+ * file are re-pinned as init re-pinned them (#2549), for the base and the
+ * target alike, so an unedited record compares equal to its base.
  */
-function instantiate(raw: Map<string, Buffer>, recorded: Record<string, unknown>, label: string): { files: Map<string, Buffer>; parameters: Record<string, string> } {
+function instantiate(
+  raw: Map<string, Buffer>,
+  recorded: Record<string, unknown>,
+  label: string,
+): { files: Map<string, Buffer>; parameters: Record<string, string>; repinned: RepinnedRecord[] } {
   try {
     const manifest = readManifest(raw);
     const parameters = carryParameters(manifest, recorded);
-    return { files: substituteParameters(raw, manifest, parameters), parameters };
+    const { files, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []);
+    return { files, parameters, repinned };
   } catch (err) {
     throw new UpgradeError(`${label}: ${(err as Error).message.replace(/; pass --param .*$/, "")}`);
   }
@@ -264,6 +274,7 @@ function fetchGit(root: string, lineage: Lineage, ref: string): Upstream {
       commit,
       tree: target.tree,
       parameters: instantiated.parameters,
+      repinned: instantiated.repinned,
     };
   } finally {
     rmSync(scratch, { recursive: true, force: true });
@@ -336,6 +347,7 @@ function readDir(root: string, lineage: Lineage, to: string | undefined): Upstre
     migrations: split.migrations,
     modules: split.modules,
     parameters: instantiated.parameters,
+    repinned: instantiated.repinned,
     source: { type: "dir", path: recordedDirPath(target.path, target.abs, root), ...(member ? { member } : {}) },
   };
 }
@@ -561,6 +573,12 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     for (const path of result.written) if (upstream.executable.has(path)) chmodSync(join(scopeDir, path), 0o755);
     if (ref !== undefined) staged.ref = ref;
     if (upstream.parameters) staged.parameters = upstream.parameters;
+    if (upstream.repinned) {
+      // The records this version re-pins, among the files the scope keeps (#2549).
+      const kept = upstream.repinned.filter((r) => staged.files[r.record] !== undefined || existsSync(join(scopeDir, r.record)));
+      if (kept.length > 0) staged.repinned = kept;
+      else delete staged.repinned;
+    }
     if (upstream.commit) staged.address = { ...staged.address!, commit: upstream.commit, tree: upstream.tree };
     if (upstream.source) staged.source = upstream.source;
     writeLock(worktreeProject, next);

package/src/workspace/member-commands.ts

@@ -379,7 +379,7 @@ const USAGE: Record<WorkspaceVerb, string> = {
   build: "chant workspace build [dir] [--member <name>] [-o <dir>] [--format json|yaml] [--env <env>] [--param k=v] [--dry-run]",
   lint: "chant workspace lint [dir] [--member <name>] [--format stylish|json|sarif] [-o <file>] [--fix] [--dry-run]",
   audit: "chant workspace audit [dir] [--member <name>] [--format stylish|json] [-o <file>] [--tier <tier>] [--fail-on <level>] [--dry-run]",
-  graph: "chant workspace graph [dir] [--member <name>] [-o <file>] [--env <env>] [--dry-run]",
+  graph: "chant workspace graph [dir] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]",
 };
 
 export function describePlan(plan: MemberPlan): string {

package/src/workspace/reason-codes.test.ts

@@ -15,7 +15,7 @@ import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
-import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
 
 const HERE = import.meta.dirname;
@@ -31,6 +31,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   RECORD_REASON_CODES,
+  RECORD_WARNING_CODES,
   READ_ERROR_CODES,
 };
 

package/src/workspace/reason-codes.ts

@@ -59,6 +59,11 @@ export const REASONS = {
   "record-id-duplicate": "Another record earlier in path order has the same id.",
   "record-supersedes-unknown": "A supersedes link names an id no record has.",
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // A record that is valid but warned about (records, #2549).
+  "asset-drift": "A file the record pins by hash has changed: its bytes no longer hash to the pinned sha256.",
+  "asset-missing": "A file the record pins by hash does not exist in the tree read.",
+  "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
+  "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",

package/src/workspace/record-assets.test.ts

@@ -0,0 +1,319 @@
+/**
+ * Asset pins and record links (#2549): a decision's evidence may pin a
+ * workspace file by path and hash; `records` checks the pin in the tree it
+ * reads and reports drift as a warning that leaves the record valid; `graph
+ * --kind` emits `asset` and `constrains` rows; `check --kind` reports drift
+ * as WSP111.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import Ajv from "ajv";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, declaration, repo, REPO } from "./__fixtures__/contract-repo";
+import { runChecks } from "./lineage-check";
+import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTERN } from "./record-assets";
+import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
+import { parseFrontMatter, RECORD_WARNING_CODES } from "./records";
+import { workspaceGraph } from "./graph-cli";
+import graphSchema from "./graph.schema.json";
+import recordsSchema from "./records.schema.json";
+
+afterAll(cleanScratch);
+
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const SAMPLE = readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8");
+const KIND = readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8");
+const SCHEMA = readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8");
+const sha = (text: string | Buffer) => createHash("sha256").update(text).digest("hex");
+
+/** ws-003 with its id replaced, and extra evidence and constrains entries. */
+function decision(id: string, evidence: string[], constrains: string[] = [], state = "decided", supersedes: string[] = []): string {
+  let text = SAMPLE.replace(/^id: .*$/m, `id: "${id}"`).replace(/^state: .*$/m, `state: "${state}"`);
+  text = text.replace(/^evidence:\n/m, `evidence:\n${evidence.join("")}`);
+  text = text.replace(/^constrains:(?: \[\])?\n/m, `constrains:\n${constrains.map((c) => `  - "${c}"\n`).join("")}`);
+  const links = supersedes.length === 0 ? "supersedes: []" : `supersedes:\n${supersedes.map((d) => `  - decision: "${d}"`).join("\n")}`;
+  return text.replace(/^supersedes:(?: \[\])?\n(?:  .*\n)*/m, `${links}\n`);
+}
+
+const pin = (path: string, hash: string) => `  - title: "the spec"\n    path: "${path}"\n    sha256: "${hash}"\n`;
+
+const SPEC = '{ "screen": "home" }\n';
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff, 0xfe]);
+
+/** A git repository holding a workspace at `ws/`, whose decisions pin files in its `design` member. */
+function workspace(extra: Record<string, string> = {}): string {
+  const root = repo({
+    "ws/chant.workspace.json": declaration([
+      { name: "app", dir: "app", kind: "other", because: "an app" },
+      { name: "design", dir: "design", kind: "other", because: "design data" },
+    ]),
+    "ws/app/src/server.mjs": "export {};\n",
+    "ws/design/screens/home.json": SPEC,
+    "ws/decisions/decision.kind.mjs": KIND,
+    "ws/decisions/decision.schema.json": SCHEMA,
+    "ws/decisions/ws-101-spec.md": decision("ws-101", [pin("design/screens/home.json", sha(SPEC))], ["member:design", "path:app/src", "path:app/nope", "member:ghost"]),
+    ...extra,
+  });
+  writeFileSync(join(root, "ws", "design", "screens", "home.png"), PNG);
+  return root;
+}
+
+function records(doc: RecordsDocument) {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("the path grammar", () => {
+  test("the decision schema holds the same pattern for evidence and constrains", () => {
+    const schema = JSON.parse(SCHEMA) as { definitions: { workspacePath: { pattern: string } }; properties: { constrains: { items: { pattern: string } } } };
+    expect(schema.definitions.workspacePath.pattern).toBe(`^${WORKSPACE_PATH_PATTERN}$`);
+    expect(schema.properties.constrains.items.pattern).toContain(`|path:${WORKSPACE_PATH_PATTERN})$`);
+  });
+
+  test.each([
+    ["design/screens/home.json", true],
+    [".github/workflows/ci.yml", true],
+    ["app", true],
+    ["/etc/passwd", false],
+    ["../outside", false],
+    ["a/../b", false],
+    ["./a", false],
+    ["a//b", false],
+    ["a/", false],
+    ["a\\b", false],
+    ["", false],
+  ])("%s is a workspace path: %s", (path, ok) => {
+    expect(isWorkspacePath(path)).toBe(ok);
+  });
+
+  test("the schema takes a path pin with a hash, refuses one without, and keeps url entries as they were", () => {
+    const validate = new Ajv({ allErrors: true, strict: false }).compile(JSON.parse(SCHEMA) as object);
+    const base = { title: "t" };
+    const withEvidence = (evidence: unknown[]) => {
+      const fm = parseFrontMatter(decision("ws-101", []));
+      if (!fm.ok) throw new Error(fm.message);
+      return { ...fm.value, evidence };
+    };
+    expect(validate(withEvidence([{ ...base, path: "design/a.json", sha256: sha("x") }]))).toBe(true);
+    expect(validate(withEvidence([{ ...base, url: "https://example.com", sha256: null }]))).toBe(true);
+    expect(validate(withEvidence([{ ...base, path: "design/a.json" }]))).toBe(false);
+    expect(validate(withEvidence([{ ...base, path: "design/a.json", sha256: null }]))).toBe(false);
+    expect(validate(withEvidence([{ ...base, path: "../a.json", sha256: sha("x") }]))).toBe(false);
+    expect(validate(withEvidence([{ ...base, path: "a.json", url: "https://example.com", sha256: sha("x") }]))).toBe(false);
+    expect(validate({ ...withEvidence([{ ...base, url: "https://example.com" }]), constrains: ["path:app/src", "member:app", "INTENTIUS/chant#1"] })).toBe(true);
+    expect(validate({ ...withEvidence([{ ...base, url: "https://example.com" }]), constrains: ["path:../x"] })).toBe(false);
+  });
+
+  test("a path belongs to the deepest member holding it, and a path: constraint covers what is below it", () => {
+    const members = [
+      { name: "root", dir: "." },
+      { name: "app", dir: "app" },
+      { name: "api", dir: "app/api" },
+    ];
+    expect(memberHolding("app/api/x.ts", members)).toBe("api");
+    expect(memberHolding("app/x.ts", members)).toBe("app");
+    expect(memberHolding("apps/x.ts", members)).toBe("root");
+    expect(memberHolding("x", [{ name: "app", dir: "app" }])).toBeNull();
+    expect(constraintCovers("app", "app/src/server.mjs")).toBe(true);
+    expect(constraintCovers("app", "apps/x")).toBe(false);
+  });
+});
+
+describe("chant workspace records checks each pin", () => {
+  const { expectValid } = contract(recordsSchema);
+
+  test("a pin that matches is pinned, resolved from the workspace holding the kind", async () => {
+    const root = workspace();
+    const doc = records(await queryRecords({ kind: "ws/decisions/decision.kind.mjs", cwd: root }));
+    expectValid(doc);
+    expect(doc.workspaceRoot).toBe("ws");
+    const [r] = doc.records;
+    expect(r.valid).toBe(true);
+    expect(r.warnings).toEqual([]);
+    expect(r.assets).toEqual([{ path: "design/screens/home.json", sha256: sha(SPEC), actual: sha(SPEC), state: "pinned" }]);
+  });
+
+  test("an edited file is asset-drift and a missing one asset-missing; the record stays valid and current", async () => {
+    const root = workspace({
+      "ws/decisions/ws-102-gone.md": decision("ws-102", [pin("design/screens/gone.json", sha("x"))]),
+    });
+    writeFileSync(join(root, "ws", "design", "screens", "home.json"), '{ "screen": "home", "edited": true }\n');
+    const doc = records(await queryRecords({ kind: "ws/decisions/decision.kind.mjs", current: true, cwd: root }));
+    expectValid(doc);
+    expect(doc.records.map((r) => [r.id, r.valid, r.warnings.map((w) => w.code), r.assets.map((a) => a.state)])).toEqual([
+      ["ws-101", true, ["asset-drift"], ["drifted"]],
+      ["ws-102", true, ["asset-missing"], ["missing"]],
+    ]);
+    expect(doc.summary.invalid).toBe(0);
+    expect(doc.records[1].assets[0].actual).toBeNull();
+  });
+
+  test("the bytes are hashed, not the text", async () => {
+    const root = workspace({ "ws/decisions/ws-103-png.md": decision("ws-103", [pin("design/screens/home.png", sha(PNG))]) });
+    const doc = records(await queryRecords({ kind: "ws/decisions/decision.kind.mjs", cwd: root }));
+    expect(doc.records.find((r) => r.id === "ws-103")!.assets[0].state).toBe("pinned");
+  });
+
+  test("--at checks the pin against the file as committed at that revision", async () => {
+    const root = workspace();
+    const first = commitAll(root, "one");
+    writeFileSync(join(root, "ws", "design", "screens", "home.json"), "{}\n");
+    const second = commitAll(root, "two");
+    const at = async (rev: string) => records(await queryRecords({ kind: "ws/decisions/decision.kind.mjs", at: rev, cwd: root })).records[0].assets[0].state;
+    expect(await at(first)).toBe("pinned");
+    expect(await at(second)).toBe("drifted");
+  });
+
+  test("the schema lists exactly the warning codes", () => {
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES]);
+  });
+
+  test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {
+    const root = workspace();
+    expect(pinFile("screens/home.json", join(root, "ws", "design"))).toEqual({ path: "design/screens/home.json", sha256: sha(SPEC) });
+    expect(pinFile("ws/design/screens/home.png", root)).toEqual({ path: "design/screens/home.png", sha256: sha(PNG) });
+    expect(pinFile("design", join(root, "ws"))).toEqual({ error: "design is not a file" });
+  });
+});
+
+describe("chant workspace graph --kind", () => {
+  const { expectValid } = contract(graphSchema);
+
+  test("emits an asset row per pin and a constrains row per member or path, and the document validates", async () => {
+    const root = workspace({ "ws/decisions/ws-104-old.md": decision("ws-104", [pin("design/screens/home.json", sha("old"))]) });
+    writeFileSync(join(root, "ws", "decisions", "ws-105-new.md"), decision("ws-105", [], [], "ratified", ["ws-104"]));
+    const { doc, failed } = await workspaceGraph({ cwd: join(root, "ws"), kind: join(root, "ws", "decisions", "decision.kind.mjs") });
+    expect(failed).toBe(false);
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records.map((r) => [r.kind, r.id, r.supersededBy])).toEqual([
+      ["decision", "ws-101", null],
+      ["decision", "ws-104", "ws-105"],
+      ["decision", "ws-105", null],
+    ]);
+    const rows = doc.links.map((r) => ("record" in r ? [r.kind, r.record, r.target, r.member, r.status] : []));
+    // ws-104 is superseded, so its drifted pin is no row.
+    expect(rows).toEqual([
+      ["asset", "ws-101", "design/screens/home.json", "design", "pinned"],
+      ["constrains", "ws-101", "member:design", "design", "resolved"],
+      ["constrains", "ws-101", "path:app/src", "app", "resolved"],
+      ["constrains", "ws-101", "path:app/nope", "app", "missing"],
+      ["constrains", "ws-101", "member:ghost", null, "missing"],
+    ]);
+  });
+
+  test("a kind that can't be read fails the command and leaves the records empty", async () => {
+    const root = workspace();
+    const errors: string[] = [];
+    const { doc, failed } = await workspaceGraph({ cwd: join(root, "ws"), kind: join(root, "nope.mjs"), onStderr: (t) => errors.push(t) });
+    expect(failed).toBe(true);
+    expectValid(doc);
+    expect(errors.join("")).toContain("kind-unreadable");
+  });
+});
+
+describe("chant workspace check --kind", () => {
+  test("reports a drifted pin as a WSP111 warning on the record, and passes", async () => {
+    const root = workspace();
+    writeFileSync(join(root, "ws", "design", "screens", "home.json"), "{}\n");
+    const doc = await runChecks(join(root, "ws"), undefined, { kind: "decisions/decision.kind.mjs" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const found = doc.declaration!.diagnostics.filter((d) => d.ruleId.startsWith("WSP11"));
+    expect(found.map((d) => [d.ruleId, d.severity, d.file])).toEqual([["WSP111", "warning", "decisions/ws-101-spec.md"]]);
+    expect(doc.ok).toBe(true);
+  });
+
+  test("without --kind no record is read; an unreadable kind is a WSP114 error", async () => {
+    const root = workspace();
+    writeFileSync(join(root, "ws", "design", "screens", "home.json"), "{}\n");
+    const plain = await runChecks(join(root, "ws"));
+    if ("error" in plain) throw new Error(plain.error.message);
+    expect(plain.declaration!.diagnostics.some((d) => d.ruleId.startsWith("WSP11"))).toBe(false);
+    const bad = await runChecks(join(root, "ws"), undefined, { kind: "decisions/nope.mjs" });
+    if ("error" in bad) throw new Error(bad.error.message);
+    expect(bad.declaration!.diagnostics.map((d) => d.ruleId)).toContain("WSP114");
+    expect(bad.ok).toBe(false);
+  });
+});
+
+describe("asset-stale: the decision changed and the artifact did not follow", () => {
+  /** Commit everything in `root` at `seconds` since the epoch, so commit times are ordered. */
+  const commitAt = (root: string, seconds: number) => {
+    const env = { ...process.env, GIT_AUTHOR_DATE: `@${seconds} +0000`, GIT_COMMITTER_DATE: `@${seconds} +0000`, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" };
+    execFileSync("git", ["add", "-A"], { cwd: root, env });
+    execFileSync("git", ["commit", "-q", "--allow-empty", "-m", String(seconds)], { cwd: root, env });
+  };
+  const kind = "ws/decisions/decision.kind.mjs";
+  const superseding = (hash: string) => decision("ws-106", [pin("design/screens/home.json", hash)], [], "decided", ["ws-101"]);
+
+  test("a superseding record that pins the old hash of an unchanged file is stale; drift and missing stay apart", async () => {
+    const root = workspace({
+      // ws-107 supersedes ws-102 and pins a file that is gone; ws-108 supersedes ws-103 and pins a file that changed.
+      "ws/decisions/ws-102-gone.md": decision("ws-102", [pin("design/screens/gone.json", sha("x"))]),
+      "ws/decisions/ws-103-other.md": decision("ws-103", [pin("design/screens/other.json", sha("one\n"))]),
+      "ws/design/screens/other.json": "one\n",
+    });
+    commitAt(root, 1_700_000_000);
+    writeFileSync(join(root, "ws", "decisions", "ws-106-new.md"), superseding(sha(SPEC)));
+    writeFileSync(join(root, "ws", "decisions", "ws-107-gone.md"), decision("ws-107", [pin("design/screens/gone.json", sha("x"))], [], "decided", ["ws-102"]));
+    writeFileSync(join(root, "ws", "decisions", "ws-108-other.md"), decision("ws-108", [pin("design/screens/other.json", sha("one\n"))], [], "decided", ["ws-103"]));
+    writeFileSync(join(root, "ws", "design", "screens", "other.json"), "two\n");
+    commitAt(root, 1_700_000_100);
+
+    const doc = records(await queryRecords({ kind, current: true, cwd: root }));
+    contract(recordsSchema).expectValid(doc);
+    expect(doc.records.map((r) => [r.id, r.valid, r.assets.map((a) => a.state), r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-106", true, ["stale"], ["asset-stale"]],
+      ["ws-107", true, ["missing"], ["asset-missing"]],
+      ["ws-108", true, ["drifted"], ["asset-drift"]],
+    ]);
+
+    // The same read at the revision agrees.
+    const at = records(await queryRecords({ kind, current: true, at: "HEAD", cwd: root }));
+    expect(at.records[0].assets[0].state).toBe("stale");
+
+    const { doc: graph } = await workspaceGraph({ cwd: join(root, "ws"), kind: join(root, kind) });
+    contract(graphSchema).expectValid(graph);
+    if ("error" in graph) throw new Error(graph.error.message);
+    expect(graph.links.flatMap((r) => ("record" in r && r.kind === "asset" ? [[r.record, r.status]] : []))).toEqual([
+      ["ws-106", "stale"],
+      ["ws-107", "missing"],
+      ["ws-108", "drifted"],
+    ]);
+
+    const check = await runChecks(join(root, "ws"), undefined, { kind: "decisions/decision.kind.mjs" });
+    if ("error" in check) throw new Error(check.error.message);
+    expect(check.declaration!.diagnostics.filter((d) => d.ruleId.startsWith("WSP11")).map((d) => d.ruleId).sort()).toEqual(["WSP111", "WSP112", "WSP113"]);
+  });
+
+  test("re-pinning the new version of the file clears it", async () => {
+    const root = workspace();
+    commitAt(root, 1_700_000_000);
+    const next = '{ "screen": "home", "v": 2 }\n';
+    writeFileSync(join(root, "ws", "design", "screens", "home.json"), next);
+    writeFileSync(join(root, "ws", "decisions", "ws-106-new.md"), superseding(sha(next)));
+    const doc = records(await queryRecords({ kind, current: true, cwd: root }));
+    expect(doc.records.map((r) => [r.id, r.assets.map((a) => a.state), r.warnings])).toEqual([["ws-106", ["pinned"], []]]);
+  });
+
+  test("a file committed again after the record was recorded is not stale, even at the same hash", async () => {
+    const root = workspace();
+    commitAt(root, 1_700_000_000);
+    writeFileSync(join(root, "ws", "decisions", "ws-106-new.md"), superseding(sha(SPEC)));
+    commitAt(root, 1_700_000_100);
+    const spec = join(root, "ws", "design", "screens", "home.json");
+    rmSync(spec);
+    commitAt(root, 1_700_000_200);
+    writeFileSync(spec, SPEC);
+    commitAt(root, 1_700_000_300);
+    const doc = records(await queryRecords({ kind, current: true, cwd: root }));
+    expect(doc.records[0].assets[0].state).toBe("pinned");
+    // At the revision where the record was recorded, the file had not moved since ws-101 pinned it.
+    const log = execFileSync("git", ["log", "--format=%H"], { cwd: root, encoding: "utf-8" }).trim().split("\n");
+    const at = records(await queryRecords({ kind, current: true, at: log[2], cwd: root }));
+    expect(at.records[0].assets[0].state).toBe("stale");
+  });
+});