@intentius/chant 0.82.0 → 0.83.0

package/dist/workspace/template-pins.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Re-pinning records after template parameters are substituted (#2549, #2627).
+ *
+ * A template's decision records may pin a file of the template by hash. When
+ * `chant init --from` or `chant workspace upgrade` fills that file's
+ * `{{chant:<name>}}` placeholders, the copy's bytes differ from the
+ * template's, and every copy would report the pin as drifted on day one. So
+ * after substitution, each pin that held in the template and names a
+ * substituted file gets the hash of the substituted content.
+ *
+ * A record is any Markdown file whose front matter has an `evidence` list
+ * with path pins. Its paths resolve from the nearest directory above it that
+ * holds a workspace declaration, as `chant workspace records` resolves them.
+ * A pin that did not hold in the template stays as it is: re-pinning follows
+ * the substitution and never hides drift the template already had. Only the
+ * `sha256` value on the pin's line changes; the rest of the file is kept byte
+ * for byte.
+ */
+/** A record whose pins were rewritten: its path in the template, and the pinned paths, from its workspace root. */
+export interface RepinnedRecord {
+    record: string;
+    paths: string[];
+}
+/**
+ * Rewrite, in `substituted`, the pins of every record that name a file in
+ * `changed` and held against `original`. Returns the files with the records
+ * rewritten, and which records were.
+ */
+export declare function repinSubstituted(original: ReadonlyMap<string, Buffer>, substituted: ReadonlyMap<string, Buffer>, changed: readonly string[]): {
+    files: Map<string, Buffer>;
+    repinned: RepinnedRecord[];
+};
+//# sourceMappingURL=template-pins.d.ts.map

package/dist/workspace/template-pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-pins.d.ts","sourceRoot":"","sources":["../../src/workspace/template-pins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,mHAAmH;AACnH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAYD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,cAAc,EAAE,CAAA;CAAE,CA+B5D"}

package/dist/workspace/tree.d.ts

@@ -17,6 +17,11 @@ export interface WorkspaceTree {
     }[] | undefined;
     /** The text of the file at `path`. Throws when it can't be read. */
     read(path: string): string;
+    /**
+     * The bytes of the file at `path`, for hashing (#2549). Throws when it can't
+     * be read. A tree without it is read as UTF-8 text.
+     */
+    bytes?(path: string): Uint8Array;
 }
 /** Join tree-relative path parts, leaving out `""` and `"."`. */
 export declare function joinPath(...parts: string[]): string;

package/dist/workspace/tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/workspace/tree.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAC/C,kGAAkG;IAClG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;IACzE,oEAAoE;IACpE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAqCvD;AAMD,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMtD;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,aAAa,CA+B/E;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/workspace/tree.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAC/C,kGAAkG;IAClG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;IACzE,oEAAoE;IACpE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;CAClC;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAwCvD;AAMD,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMtD;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,aAAa,CAmC/E;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/main.ts

@@ -360,7 +360,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--at") {
       result.at = args[++i];
     } else if (arg === "--kind") {
-      // `chant workspace records --kind <kind file>` (#2546)
+      // `chant workspace records|graph|check --kind <kind file>` (#2546, #2549)
       result.kind = args[++i];
       if (!result.kind || result.kind.startsWith("-")) throw new Error("--kind needs a kind file: --kind <path>");
     } else if (arg === "--current") {
@@ -719,7 +719,11 @@ Workspace (level 1, #2524):
                         Each record reports its provenance level, judged by
                         the signers at --base (default: the target branch);
                         --require attested exits 2 if any record is not
-                        attested
+                        attested. A pinned file that changed is a warning,
+                        asset-drift or asset-missing
+  workspace records pin <path>
+                        Print the path from the workspace root and the
+                        sha256 of a file, for a decision's evidence pin
   workspace verify [--base <rev>] [--head <rev>] [--require attested]
                         Check the commits in base..head against the signers
                         and roles read from base. A change to the signers file
@@ -737,12 +741,13 @@ Workspace (level 1, #2524):
                         lint and workspace check there, then gate on the digest
                         of the patch (chant approve workspace-upgrade <scope>).
                         A second run with the approval applies the patch
-  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]
                         Fail on an unreadable lineage lock or an open manual
                         step, and, in a declared workspace, on a WSP check of
                         the declaration, member ledgers, pipelines or
                         generated files. --generated runs declared generators
-                        and compares their output. Needs no workspace file.
+                        and compares their output. --kind warns on records
+                        whose pinned files changed. Needs no workspace file.
                         --at reads a commit's git objects; --format json
                         prints the read-contract document
   workspace build [dir] [--member <name>] [-o <dir>] [--dry-run]
@@ -756,11 +761,12 @@ Workspace (level 1, #2524):
   workspace audit [dir] [--json] [--member <name>]
                         Audit each chant member with its own .chant-audit.json;
                         every finding carries a member field
-  workspace graph [dir] [--at <rev>] [--member <name>] [-o <file>]
+  workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>]
                         Compose each chant member's chant graph into one IR,
                         with <member>/<id> ids and groups.byMember: the
                         read-contract document. --at <rev> runs each member's
-                        source as it was at that commit
+                        source as it was at that commit; --kind adds the
+                        records' asset and constrains links
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/content-digest.ts

@@ -19,3 +19,8 @@ import { createHash } from "node:crypto";
 export function contentDigest(input: string): string {
   return `sha256:${createHash("sha256").update(input, "utf8").digest("hex")}`;
 }
+
+/** Lowercase hex SHA-256 of `bytes`, with no prefix: the form a decision's evidence pin holds (#2549). */
+export function sha256Hex(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}

package/src/workspace/checks/records.ts

@@ -0,0 +1,83 @@
+/**
+ * The record checks, WSP111 to WSP114 (#2549; #2524 D4, D18).
+ *
+ * With `--kind <kind file>`, `chant workspace check` reads the records the
+ * kind locates, in the tree it checks, and reports the files they pin by hash
+ * that have changed or gone since. A decision stays valid when its evidence
+ * drifts, so drift is a warning: it asks for the decision to be looked at
+ * again, and the declaration's `checks` can raise it to an error.
+ *
+ * | Id | Finds |
+ * |---|---|
+ * | WSP111 | a pinned file whose bytes no longer hash to the pinned sha256 |
+ * | WSP112 | a pinned file that does not exist |
+ * | WSP113 | a pinned file that a superseding record pins at the old hash: the artifact did not follow the decision |
+ * | WSP114 | the records of `--kind` can't be read (fixed) |
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { ReadErrorCode, RecordEntry } from "../records";
+
+/** The records `check --kind` read, or why they could not be read. */
+export type RecordFacts =
+  | { kind: string; records: readonly (RecordEntry & { file: string })[] }
+  | { kind: string; error: { code: ReadErrorCode; message: string } };
+
+function warningFindings(check: WorkspaceCheck, facts: RecordFacts | undefined, code: "asset-drift" | "asset-missing" | "asset-stale"): WorkspaceDiagnostic[] {
+  if (!facts || "error" in facts) return [];
+  const out: WorkspaceDiagnostic[] = [];
+  for (const r of facts.records) {
+    // A superseded record's evidence no longer backs anything current.
+    if (r.supersededBy !== null) continue;
+    for (const w of r.warnings) {
+      if (w.code !== code) continue;
+      out.push({ checkId: check.id, severity: check.severity, message: `${r.id ?? r.path}: ${w.message}`, pointer: "", file: r.file });
+    }
+  }
+  return out;
+}
+
+export const RECORD_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP111",
+    name: "record-asset-drift",
+    description: "Every file a current record pins by hash still hashes to the pinned sha256. A changed file asks for the record to be revisited.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return warningFindings(this, ctx.facts?.records, "asset-drift");
+    },
+  },
+  {
+    id: "WSP112",
+    name: "record-asset-missing",
+    description: "Every file a current record pins by hash exists.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return warningFindings(this, ctx.facts?.records, "asset-missing");
+    },
+  },
+  {
+    id: "WSP113",
+    name: "record-asset-stale",
+    description: "No current record pins a file at the same hash as a record it supersedes while the file is unchanged since: when a decision changes, the artifacts it rests on follow.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return warningFindings(this, ctx.facts?.records, "asset-stale");
+    },
+  },
+  {
+    id: "WSP114",
+    name: "records-unreadable",
+    description: "The records of the kind named with --kind can be read.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const facts = ctx.facts?.records;
+      if (!facts || !("error" in facts)) return [];
+      return [{ checkId: this.id, severity: this.severity, message: `--kind ${facts.kind}: ${facts.error.code}: ${facts.error.message}`, pointer: "" }];
+    },
+  },
+];

package/src/workspace/checks.test.ts

@@ -56,6 +56,8 @@ describe("the WSP catalog", () => {
       "flat-ledger-environment-shared",
       "link-target-unknown",
       "link-kind-unknown",
+      // --kind names a record kind, and records that can't be read check nothing (#2549).
+      "records-unreadable",
     ]);
   });
 

package/src/workspace/checks.ts

@@ -26,6 +26,7 @@
  * | WSP081 to WSP083 | recorded pipelines |
  * | WSP091 to WSP097 | member links (#2539) |
  * | WSP101 to WSP106 | generated files |
+ * | WSP111 to WSP114 | records read with `--kind` (#2549) |
  */
 
 import { realpathSync } from "node:fs";
@@ -42,6 +43,7 @@ import type { LinkTableRow } from "./links";
 import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from "./checks/generated";
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
+import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -55,6 +57,8 @@ export interface WorkspaceFacts {
   pipelines?: readonly MemberPipelineFacts[];
   /** Each declared or implicit generated file, with what its generator produced. */
   generated?: readonly GeneratedFileFacts[];
+  /** The records of the kind named with `--kind`, with their pins checked (#2549). */
+  records?: RecordFacts;
 }
 
 /** What every declaration check reads. */
@@ -77,6 +81,8 @@ export interface WorkspaceCheckContext {
 export interface WorkspaceDiagnostic extends PostSynthDiagnostic {
   /** A JSON Pointer into the declaration. */
   pointer: string;
+  /** An absolute path, for a finding about a file other than the declaration, such as a record (#2549). It is reported at its first line. */
+  file?: string;
 }
 
 export interface WorkspaceCheck {
@@ -295,6 +301,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...LINK_CHECKS,
   // Generated files (#2541).
   ...GENERATED_CHECKS,
+  // Records read with --kind (#2549).
+  ...RECORD_CHECKS,
 ];
 
 const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
@@ -370,6 +378,8 @@ export interface DeclarationCheckOptions {
    * gathered: they describe the working tree, not the revision.
    */
   tree?: WorkspaceTree;
+  /** The records read with `--kind`, in the same tree (#2549). Given with or without `tree`. */
+  records?: RecordFacts;
 }
 
 /**
@@ -433,7 +443,8 @@ export async function runDeclarationChecks(
     return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
-  const facts = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+  const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+  const facts: WorkspaceFacts = options.records ? { ...gathered, records: options.records } : gathered;
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);
@@ -442,8 +453,7 @@ export async function runDeclarationChecks(
   const locate = (pointer: string): TextLocation => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
   const file = display(declaration.file);
   const toFinding = (d: WorkspaceDiagnostic): WorkspaceFinding => ({
-    file,
-    ...locate(d.pointer),
+    ...(d.file !== undefined ? { file: display(relative(root, d.file).split(sep).join("/")), line: 1, column: 1 } : { file, ...locate(d.pointer) }),
     ruleId: d.checkId,
     severity: d.severity,
     message: d.message,

package/src/workspace/compose-graph.test.ts

@@ -7,6 +7,7 @@ import { describe, expect, test } from "vitest";
 import { GRAPH_IR_VERSION, type GraphIR } from "../graph-ir";
 import { parseDeclaration } from "./declaration";
 import { composeWorkspaceGraph, readMemberIr, WORKSPACE_GRAPH_VERSION, type ComposedMember } from "./compose-graph";
+import type { LinkTableRow } from "./links";
 
 const member = (name: string, dir: string): ComposedMember => ({
   name,
@@ -136,7 +137,7 @@ describe("the links section (#2539)", () => {
     ];
     const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, inputs, { declaration });
     expect(
-      doc.links.map((r) => (r.status === "ambiguous" ? "" : `${r.origin} ${r.label} ${r.from ?? r.consumer} -> ${r.to}`)),
+      (doc.links as LinkTableRow[]).map((r) => (r.status === "ambiguous" ? "" : `${r.origin} ${r.label} ${r.from ?? r.consumer} -> ${r.to}`)),
     ).toEqual([
       "declared exact app -> web/Bucket",
       "inferred:joinKey folded jobs/BUCKET_ARN -> web/Bucket",

package/src/workspace/compose-graph.ts

@@ -16,8 +16,9 @@
  * - `links` holds the member links (#2524 D6, #2539): the declared links and
  *   the joins inferred from members' `imports` and `exports` with the core
  *   `joinKey()`, labelled `exact` or `folded` (`./links.ts`). A declared link
- *   suppresses the inferred edge it covers. `records` is the section record
- *   kinds fill (#2524 D4), empty so far.
+ *   suppresses the inferred edge it covers. `records` holds the records
+ *   read through a record kind (`--kind`, #2549), and their `asset` and
+ *   `constrains` links follow the member links in `links`.
  *
  * A member's IR with no `version` field comes from a chant older than #2529.
  * It is version 1, and it is upgraded in place by stamping that version. An IR
@@ -31,6 +32,7 @@
 import type { Declaration } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { graphLinks, type LinkTableRow } from "./links";
+import type { RecordLinkRow } from "./record-assets";
 import type { ReasonCode } from "./reason-codes";
 import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
 
@@ -92,10 +94,25 @@ export interface WorkspaceGraph {
   exports: (IRExport & { member: string })[];
   imports: (IRImport & { member: string })[];
   derivedAttrs?: Record<string, string[]>;
-  /** Member links (#2524 D6, #2539), declared and inferred. Empty when no declaration is given. */
-  links: LinkTableRow[];
-  /** Record sections (#2524 D4). Empty until record kinds join the graph. */
-  records: unknown[];
+  /**
+   * Member links (#2524 D6, #2539), declared and inferred, then the links of
+   * the records read with `--kind` (#2549). Empty when no declaration is given.
+   */
+  links: (LinkTableRow | RecordLinkRow)[];
+  /** The records read with `--kind` (#2524 D4, #2549). Empty without it. */
+  records: GraphRecord[];
+}
+
+/** A record in the composed graph: enough to name it from a link row. */
+export interface GraphRecord {
+  /** The record kind's name, such as `decision`. */
+  kind: string;
+  id: string | null;
+  /** From the repository root. */
+  path: string;
+  state: string | null;
+  valid: boolean;
+  supersededBy: string | null;
 }
 
 /** Read one member's `chant graph --format ir` output, upgrading an unversioned (v1) IR in place. */

package/src/workspace/graph-cli.ts

@@ -1,8 +1,9 @@
 /**
- * `chant workspace graph [dir] [--at <rev>] [--member <name>] [-o <file>]
- * [--env <env>] [--dry-run]` (#2537, #2536): every `chant` member's IR, read
- * through the member's own toolchain and composed into one document
- * (`compose-graph.ts`).
+ * `chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>]
+ * [-o <file>] [--env <env>] [--dry-run]` (#2537, #2536): every `chant`
+ * member's IR, read through the member's own toolchain and composed into one
+ * document (`compose-graph.ts`). With `--kind`, the records of that kind and
+ * their asset and constrains links join it (#2549, `record-assets.ts`).
  *
  * The document is part of the read contract, described by `graph.schema.json`
  * beside this file. It is printed for a failure too, with the error's reason
@@ -28,6 +29,8 @@ import { composeWorkspaceGraph, readMemberIr, type ComposeInput, type WorkspaceG
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
 import { loadKindRegistry } from "./kinds";
+import { recordLinkRows } from "./record-assets";
+import { RecordReadError } from "./records";
 import { workingTree } from "./tree";
 import { handToRootChant, locateWorkspace, type LocatedWorkspace } from "./which-chant";
 
@@ -40,7 +43,7 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 /** Why the graph couldn't be read at all: the declaration's codes, `--at`'s included. */
 export const GRAPH_ERROR_CODES = WORKSPACE_ERROR_CODES;
 
-const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [-o <file>] [--env <env>] [--dry-run]";
+const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]";
 
 interface Head {
   $schema: string;
@@ -64,6 +67,12 @@ export interface GraphQuery {
   reader?: Toolchain;
   /** Called with each member's stderr, so the command can pass it on. */
   onStderr?: (text: string) => void;
+  /**
+   * A record kind file, absolute or relative to `cwd` (#2549). Its records
+   * fill `records`, and their asset pins and `constrains` entries become
+   * rows of `links`.
+   */
+  kind?: string;
 }
 
 export interface GraphResult {
@@ -171,7 +180,23 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
     const kinds = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
     const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds });
-    return { doc: { ...head, at: located.at, ...graph }, failed };
+    let recordsFailed = false;
+    if (query.kind !== undefined) {
+      // Artifact relationships come from records (#2549): a record's pins and
+      // what it constrains, read at the same revision as the declaration.
+      const { readRecordsFor } = await import("./records-cli");
+      try {
+        const read = await readRecordsFor({ kind: query.kind, cwd: query.cwd, at: query.at });
+        const name = read.loaded.kind.name;
+        graph.records = read.result.records.map((r) => ({ kind: name, id: r.id, path: r.path, state: r.state, valid: r.valid, supersededBy: r.supersededBy }));
+        graph.links.push(...recordLinkRows(name, read.result.records, read.loaded.kind.constrains?.field, located.tree, declaration.members));
+      } catch (err) {
+        if (!(err instanceof RecordReadError)) throw err;
+        recordsFailed = true;
+        query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
+      }
+    }
+    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
@@ -209,6 +234,7 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
     at: args.at,
     members: args.members,
     args,
+    ...(args.kind !== undefined ? { kind: resolve(args.kind) } : {}),
     onStderr: (text) => process.stderr.write(text),
   });
   emitDocument(doc, args.output);

package/src/workspace/graph-contract.test.ts

@@ -18,6 +18,7 @@ import { cleanScratch, commitAll, contract, declaration, declaration as declarat
 import type { GraphIR } from "../graph-ir";
 import { composeWorkspaceGraph, MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { parseDeclaration, WORKSPACE_ERROR_CODES } from "./declaration";
+import type { LinkTableRow } from "./links";
 import { GRAPH_CONTRACT_VERSION, GRAPH_ERROR_CODES, GRAPH_OUTPUT_SCHEMA_ID, workspaceGraph, type GraphDocument } from "./graph-cli";
 import schema from "./graph.schema.json";
 
@@ -101,7 +102,7 @@ describe("the links section (#2539)", () => {
     );
     const doc = { $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: 1, chant: "0.81.0", at: null, ...graph };
     expectValid(doc);
-    expect(doc.links.map((r) => `${r.consumer} ${r.origin} ${r.status}`)).toEqual(["app declared resolved", "app declared missing", "jobs inferred:joinKey ambiguous"]);
+    expect((doc.links as LinkTableRow[]).map((r) => `${r.consumer} ${r.origin} ${r.status}`)).toEqual(["app declared resolved", "app declared missing", "jobs inferred:joinKey ambiguous"]);
   });
 });
 

package/src/workspace/graph.schema.json

@@ -218,14 +218,17 @@
         },
         "links": {
           "type": "array",
-          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set.",
+          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set. With --kind, the links of the records read follow (#2549): an `asset` row for each file a record pins by hash, and a `constrains` row for each member or path it governs. These rows have `record` and `target` instead of `consumer` and `producer`.",
           "items": {
             "$ref": "#/$defs/link"
           }
         },
         "records": {
           "type": "array",
-          "description": "Record sections (#2524 D4). Empty until record kinds join the graph."
+          "description": "The records read with --kind (#2524 D4, #2549), sorted by path; empty without it. A record link in `links` names its record by id.",
+          "items": {
+            "$ref": "#/$defs/record"
+          }
         }
       }
     },
@@ -655,8 +658,134 @@
               }
             }
           }
+        },
+        {
+          "type": "object",
+          "description": "A record link (#2549): from a current record to a file it pins (kind asset) or to a member or path it constrains (kind constrains). Superseded records have none. A reader finds the artifacts behind a file by taking the decisions whose constrains cover it and then their asset rows.",
+          "required": [
+            "kind",
+            "origin",
+            "resolves",
+            "recordKind",
+            "record",
+            "recordPath",
+            "target",
+            "member",
+            "status",
+            "reason"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "asset",
+                "constrains"
+              ]
+            },
+            "origin": {
+              "const": "declared"
+            },
+            "resolves": {
+              "const": "source"
+            },
+            "recordKind": {
+              "type": "string",
+              "description": "The record's kind, such as decision."
+            },
+            "record": {
+              "type": "string",
+              "description": "The record's id."
+            },
+            "recordPath": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "target": {
+              "type": "string",
+              "description": "For asset, the pinned path from the workspace root. For constrains, the entry as written: member:<name> or path:<path>."
+            },
+            "member": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The member the target names or sits in; null when no member does."
+            },
+            "status": {
+              "enum": [
+                "pinned",
+                "drifted",
+                "missing",
+                "stale",
+                "resolved"
+              ],
+              "description": "For asset: pinned, drifted, missing or stale, as records reports the pin. For constrains: resolved, or missing when the member is not declared or the path does not exist."
+            },
+            "reason": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Why the row is not pinned or resolved, or null."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the pinned hash."
+            },
+            "actual": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the hash of the file in the tree read, or null when it is missing."
+            }
+          }
         }
       ]
+    },
+    "record": {
+      "type": "object",
+      "required": [
+        "kind",
+        "id",
+        "path",
+        "state",
+        "valid",
+        "supersededBy"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "The record kind's name, such as decision."
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, from the repository root, with / separators."
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "valid": {
+          "type": "boolean",
+          "description": "As chant workspace records reports it."
+        },
+        "supersededBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
     }
   }
 }