@intentius/chant 0.81.0 → 0.83.0

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

@@ -9,7 +9,8 @@
  * 1. Fetch the target version of the template. For a git source that is one
  *    `git fetch` of the target ref, plus the commit the scope was made from.
  *    This is the command's only network step, catalogued in
- *    `test/egress-catalogue.ts`. A local repository reaches nothing.
+ *    `test/egress-catalogue.ts`. A local repository reaches nothing, and
+ *    neither does a directory source (#2647), which reads `--to <dir>`.
  * 2. Rebuild the merge base offline: each recorded file's content at the base
  *    commit, kept only when it has the hash the lock recorded. A file the
  *    project never edited is its own merge base. Vendor sources keep no
@@ -39,12 +40,26 @@ import { basename, join, relative, resolve, sep } from "node:path";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { ResolvedGateApproval } from "../op/gate-approval";
 import { checkLineage, findingKey, type CheckFinding } from "./lineage-check";
-import { git, readTemplateTree } from "./lineage-init";
-import { LOCK_FILE, LockError, fileHash, readLock, renderLock, scopeKey, writeLock, type Lineage, type LineageLock, type ManualStep } from "./lineage-lock";
+import { dirLabel, git, parseDirSpec, readTemplateDir, readTemplateTree, recordedDirPath } from "./lineage-init";
+import {
+  LOCK_FILE,
+  LockError,
+  contentDigest,
+  fileHash,
+  readLock,
+  renderLock,
+  scopeKey,
+  writeLock,
+  type Lineage,
+  type LineageLock,
+  type LineageSource,
+  type ManualStep,
+} from "./lineage-lock";
 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";
@@ -95,7 +110,12 @@ export interface UpgradeOptions {
   root: string;
   /** The scope to upgrade: `"."` or a vendor scope's directory. */
   scope?: string;
-  /** The target ref (git) or label (vendor). Defaults to the ref the scope is pinned at. */
+  /**
+   * The target ref (git) or label (vendor). Defaults to the ref the scope is
+   * pinned at. For a directory source, the directory holding the new version,
+   * as `<dir>[#<member>]`, resolved from the current directory; the member
+   * defaults to the recorded one.
+   */
   to?: string;
   /** Run migrations whose body is code. */
   allowCode?: boolean;
@@ -163,20 +183,31 @@ interface Upstream {
   modules: Map<string, Buffer>;
   commit?: string;
   tree?: string;
-  /** The parameter values substituted into `files` (#2627), for a git source. */
+  /** 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;
 }
 
 /**
  * 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 .*$/, "")}`);
   }
@@ -243,12 +274,84 @@ 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 });
   }
 }
 
+/**
+ * Why a directory scope cannot be upgraded, with the way out. A directory
+ * has no history, so the merge base exists only while the files the scope
+ * was made from are still on disk.
+ */
+function dirRefusal(lineage: Lineage, why: string): UpgradeError {
+  const source = lineage.source as Extract<LineageSource, { type: "dir" }>;
+  return new UpgradeError(
+    `${why}. The scope was made from the directory ${dirLabel(source.path, source.member)}, which has no git history to rebuild a merge base from. ` +
+      `Upgrade with --to <dir> while ${source.path} still holds the files the scope was made from, or adopt the scope into a git lineage with \`chant workspace adopt-lineage\` (#2551).`,
+  );
+}
+
+/**
+ * The upstream of a directory source (#2647): the new version from the
+ * directory `to` names, and the merge base from the recorded directory, used
+ * only when its files, instantiated with the recorded parameters, still have
+ * the recorded digest. Anything else is refused: a base that is not the one
+ * the scope was made from would turn the project's edits into upstream
+ * changes. Reaches no network.
+ */
+function readDir(root: string, lineage: Lineage, to: string | undefined): Upstream {
+  const source = lineage.source;
+  if (source.type !== "dir") throw new UpgradeError("not a directory source");
+  if (!to) throw dirRefusal(lineage, "no --to directory");
+
+  let target;
+  try {
+    target = parseDirSpec(to);
+  } catch {
+    target = null;
+  }
+  if (!target) throw new UpgradeError(`--to ${to}: a scope made from a directory upgrades from a directory, and ${to} is not one`);
+  const member = to.includes("#") ? target.member : source.member;
+  const label = dirLabel(target.path, member);
+  const read = readTemplateDir(target.abs, member, label);
+  const raw = new Map<string, Buffer>();
+  const executable = new Set<string>();
+  for (const [path, f] of read.files) {
+    raw.set(path, f.data);
+    if (f.executable) executable.add(path);
+  }
+  const instantiated = instantiate(raw, lineage.parameters, label);
+
+  // The merge base: the recorded directory, only while it holds exactly what the scope was made from.
+  const original = resolve(root, source.path);
+  const originalLabel = dirLabel(source.path, source.member);
+  let base: Map<string, Buffer>;
+  try {
+    const old = readTemplateDir(original, source.member, originalLabel);
+    base = splitMigrations(instantiate(new Map([...old.files].map(([path, f]) => [path, f.data])), lineage.parameters, originalLabel).files).files;
+  } catch {
+    throw dirRefusal(lineage, `${originalLabel} is gone`);
+  }
+  if (!lineage.address || contentDigest(base) !== lineage.address.digest) {
+    throw dirRefusal(lineage, `${originalLabel} no longer holds the files the scope was made from (its digest is not ${lineage.address?.digest ?? "recorded"})`);
+  }
+
+  const split = splitMigrations(instantiated.files);
+  return {
+    files: split.files,
+    executable,
+    base,
+    migrations: split.migrations,
+    modules: split.modules,
+    parameters: instantiated.parameters,
+    repinned: instantiated.repinned,
+    source: { type: "dir", path: recordedDirPath(target.path, target.abs, root), ...(member ? { member } : {}) },
+  };
+}
+
 async function fetchUpstream(root: string, lineage: Lineage, ref: string | undefined): Promise<Upstream> {
   const source = lineage.source;
   if (source.type === "git") {
@@ -260,6 +363,7 @@ async function fetchUpstream(root: string, lineage: Lineage, ref: string | undef
     const files = await resolveVendorSource(source, root);
     return { files, executable: new Set(), base: new Map(), migrations: [], modules: new Map() };
   }
+  if (source.type === "dir") return readDir(root, lineage, ref);
   throw new UpgradeError(
     `scope made by \`chant init --template\` (${lineage.template}) cannot be upgraded yet: its merge base is the older lexicon's render, which is not available offline. Upgrade git-sourced and vendor scopes for now.`,
   );
@@ -404,9 +508,10 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     );
   }
 
-  // 1. Fetch.
-  const ref = options.to ?? lineage.ref;
-  const upstream = await fetchUpstream(root, lineage, ref);
+  // 1. Fetch. A directory source has no ref: `--to` names the directory.
+  const fromDir = lineage.source.type === "dir";
+  const ref = fromDir ? undefined : options.to ?? lineage.ref;
+  const upstream = await fetchUpstream(root, lineage, fromDir ? options.to : ref);
 
   // 2. The merge base, offline from here on.
   const base = rebuildBase(join(root, scope), lineage, upstream.base);
@@ -468,7 +573,14 @@ 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);
     const lockText = renderLock(next);
 
@@ -512,8 +624,8 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
       scope,
       template: lineage.template,
       kind: lineage.kind,
-      from: lineage.ref ?? null,
-      to: staged.ref ?? null,
+      from: fromDir ? sourcePin(lineage.source) : lineage.ref ?? null,
+      to: fromDir ? sourcePin(staged.source) : staged.ref ?? null,
       ...(upstream.commit ? { commit: { ...(lineage.address?.commit ? { from: lineage.address.commit } : {}), to: upstream.commit } } : {}),
       migrations: plan.chain.map((m) => m.migration.id),
       written: result.written,
@@ -542,6 +654,11 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
   }
 }
 
+/** A directory source's pin, for the summary: the directory it reads. */
+function sourcePin(source: LineageSource): string | null {
+  return source.type === "dir" ? dirLabel(source.path, source.member) : null;
+}
+
 /**
  * `chant workspace check` in the worktree. A finding already present at HEAD
  * is not the upgrade's doing, and the upgrade's own manual steps are what the

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");
+  });
+});