@intentius/chant 0.82.0 → 0.84.0

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

package/src/workspace/record-assets.ts

@@ -0,0 +1,207 @@
+/**
+ * Asset pins and record links (#2549; #2524 D4, D6, D18).
+ *
+ * Artifact relationships are derived from decisions. A decision record pins
+ * the workspace files it rests on in `evidence`, each as `{title, path,
+ * sha256}`, and names what it governs in `constrains`, as `member:<name>` or
+ * `path:<path>`. There is no direct link from a design artifact to code or to
+ * another artifact: a reader walks from a file to the decisions whose
+ * `constrains` cover it, and from them to their pinned assets.
+ *
+ * A pin is checked against the tree a read looks at (the working tree, or a
+ * revision's git objects). A file whose bytes hash differently is `drifted`,
+ * and one that is gone is `missing`. Neither makes the record invalid: the
+ * record is still what was decided, and the drift is reported beside it.
+ *
+ * Which front-matter fields hold pins and links is the kind's data
+ * (`pins.field`, `constrains.field`), so this module never names `evidence`.
+ */
+
+import { sha256Hex } from "../content-digest";
+import type { RecordWarning } from "./records";
+import type { WorkspaceTree } from "./tree";
+
+/**
+ * A path from the workspace root: `/` separators, no leading `/`, no `.` or
+ * `..` segment, no empty segment, no backslash or control character and no
+ * trailing `/`. The decision schema holds the same pattern.
+ */
+export const WORKSPACE_PATH_PATTERN = String.raw`(?!/)(?!(?:[^/]*/)*\.{1,2}(?:/|$))(?!.*//)[^\\\u0000-\u001f]*[^/\\\u0000-\u001f]`;
+const WORKSPACE_PATH = new RegExp(`^${WORKSPACE_PATH_PATTERN}$`, "u");
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export function isWorkspacePath(value: unknown): value is string {
+  return typeof value === "string" && WORKSPACE_PATH.test(value);
+}
+
+/**
+ * `pinned`: the file hashes to the pin. `drifted`: it doesn't. `missing`: it
+ * isn't there. `stale`: it hashes to the pin, which a record this one
+ * supersedes pinned too, so the decision changed and the artifact did not.
+ */
+export type PinState = "pinned" | "drifted" | "missing" | "stale";
+
+/** One pinned file, as the tree read has it. */
+export interface AssetPin {
+  /** From the workspace root. */
+  path: string;
+  /** The hash the record pins. */
+  sha256: string;
+  /** The hash of the file in the tree read, or null when it is missing. */
+  actual: string | null;
+  state: PinState;
+}
+
+/** The well-formed pins in a record's `field` list: entries with a workspace path and a hex sha256. */
+export function pinEntries(data: Record<string, unknown> | null, field: string): { path: string; sha256: string }[] {
+  const list = data?.[field];
+  if (!Array.isArray(list)) return [];
+  const out: { path: string; sha256: string }[] = [];
+  for (const e of list) {
+    if (e === null || typeof e !== "object" || Array.isArray(e)) continue;
+    const { path, sha256 } = e as Record<string, unknown>;
+    if (isWorkspacePath(path) && typeof sha256 === "string" && SHA256.test(sha256)) out.push({ path, sha256 });
+  }
+  return out;
+}
+
+/** The hex SHA-256 of the file at `path` in `tree`, or undefined when it is not a file there. */
+export function fileDigest(tree: WorkspaceTree, path: string): string | undefined {
+  if (tree.stat(path) !== "file") return undefined;
+  const bytes = tree.bytes ? tree.bytes(path) : Buffer.from(tree.read(path), "utf-8");
+  return sha256Hex(bytes);
+}
+
+/** Check each pin against `tree`, rooted at the workspace root. */
+export function checkPins(pins: { path: string; sha256: string }[], tree: WorkspaceTree): { assets: AssetPin[]; warnings: RecordWarning[] } {
+  const assets: AssetPin[] = [];
+  const warnings: RecordWarning[] = [];
+  for (const pin of pins) {
+    const actual = fileDigest(tree, pin.path) ?? null;
+    const state: PinState = actual === null ? "missing" : actual === pin.sha256 ? "pinned" : "drifted";
+    assets.push({ ...pin, actual, state });
+    if (state === "missing") {
+      warnings.push({ code: "asset-missing", message: `evidence pins ${pin.path}, which does not exist${tree.label}` });
+    } else if (state === "drifted") {
+      warnings.push({
+        code: "asset-drift",
+        message: `${pin.path} changed since it was pinned: sha256 ${pin.sha256.slice(0, 12)} is pinned, the file${tree.label} hashes to ${actual!.slice(0, 12)}`,
+      });
+    }
+  }
+  return { assets, warnings };
+}
+
+// ── Record links ─────────────────────────────────────────────────────────────
+
+/** The kinds of link a record has in `chant workspace graph`. Closed. */
+export const RECORD_LINK_KINDS = ["asset", "constrains"] as const;
+
+/** A link from a record to a workspace path or member, a row of the graph's `links`. */
+export interface RecordLinkRow {
+  kind: (typeof RECORD_LINK_KINDS)[number];
+  origin: "declared";
+  resolves: "source";
+  /** The record's kind, such as `decision`. */
+  recordKind: string;
+  /** The record's id. */
+  record: string;
+  /** The record file, from the repository root. */
+  recordPath: string;
+  /** For `asset`, the pinned path; for `constrains`, the entry as written (`member:<name>` or `path:<path>`). */
+  target: string;
+  /** The member the target is, or holds it; null when no member does. */
+  member: string | null;
+  /** `pinned`, `drifted`, `missing` or `stale` for an asset; `resolved` or `missing` for constrains. */
+  status: PinState | "resolved";
+  reason: string | null;
+  /** For an asset: the pinned hash and the hash in the tree read. */
+  sha256?: string;
+  actual?: string | null;
+}
+
+/** The member whose directory holds `path` (the deepest one), or null. */
+export function memberHolding(path: string, members: readonly { name: string; dir: string }[]): string | null {
+  let best: { name: string; dir: string } | null = null;
+  for (const m of members) {
+    const inside = m.dir === "." || path === m.dir || path.startsWith(`${m.dir}/`);
+    if (inside && (!best || best.dir === "." || m.dir.length > best.dir.length)) best = m;
+  }
+  return best?.name ?? null;
+}
+
+/** Whether a `path:` constraint covers `file`: the same path, or a directory above it. */
+export function constraintCovers(constraint: string, file: string): boolean {
+  return file === constraint || file.startsWith(`${constraint}/`);
+}
+
+/** A record as the link rows read it. */
+export interface LinkedRecord {
+  id: string | null;
+  path: string;
+  supersededBy: string | null;
+  data: Record<string, unknown> | null;
+  assets: AssetPin[];
+}
+
+/**
+ * The link rows of the records of one kind: an `asset` row per pin and a
+ * `constrains` row per `member:` or `path:` entry. Superseded records and
+ * records with no id have none, since their links no longer hold. Paths
+ * resolve in `tree` (the workspace root), members in `members`.
+ */
+export function recordLinkRows(
+  kindName: string,
+  records: readonly LinkedRecord[],
+  constrainsField: string | undefined,
+  tree: WorkspaceTree,
+  members: readonly { name: string; dir: string }[],
+): RecordLinkRow[] {
+  const rows: RecordLinkRow[] = [];
+  for (const r of records) {
+    if (r.id === null || r.supersededBy !== null) continue;
+    const base = { origin: "declared" as const, resolves: "source" as const, recordKind: kindName, record: r.id, recordPath: r.path };
+    for (const a of r.assets) {
+      rows.push({
+        kind: "asset",
+        ...base,
+        target: a.path,
+        member: memberHolding(a.path, members),
+        status: a.state,
+        reason:
+          a.state === "missing"
+            ? `${a.path} does not exist${tree.label}`
+            : a.state === "drifted"
+              ? `${a.path} changed since ${r.id} pinned it`
+              : a.state === "stale"
+                ? `${a.path} has not changed since a record ${r.id} supersedes pinned it`
+                : null,
+        sha256: a.sha256,
+        actual: a.actual,
+      });
+    }
+    const list = constrainsField ? r.data?.[constrainsField] : undefined;
+    if (!Array.isArray(list)) continue;
+    for (const entry of list) {
+      if (typeof entry !== "string") continue;
+      if (entry.startsWith("member:")) {
+        const name = entry.slice("member:".length);
+        const known = members.some((m) => m.name === name);
+        rows.push({ kind: "constrains", ...base, target: entry, member: known ? name : null, status: known ? "resolved" : "missing", reason: known ? null : `${name} is not a member of this workspace` });
+      } else if (entry.startsWith("path:")) {
+        const path = entry.slice("path:".length);
+        if (!isWorkspacePath(path)) continue;
+        const exists = tree.stat(path) !== undefined;
+        rows.push({
+          kind: "constrains",
+          ...base,
+          target: entry,
+          member: memberHolding(path, members),
+          status: exists ? "resolved" : "missing",
+          reason: exists ? null : `${path} does not exist${tree.label}`,
+        });
+      }
+    }
+  }
+  return rows;
+}