@intentius/chant 0.82.0 → 0.84.0

package/dist/workspace/records.d.ts

@@ -16,13 +16,25 @@
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 import { z } from "zod";
+import { type AssetPin } from "./record-assets.js";
 import type { RecordSource } from "./record-source.js";
+import type { WorkspaceTree } from "./tree.js";
 /**
  * Why one record is not valid. The list is closed: a reader may switch on it,
  * and a new code is a contract change (#2536).
  */
 export declare const RECORD_REASON_CODES: readonly ["record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict"];
 export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
+/**
+ * Why a record carries a warning. Closed, like the reason codes. A warning
+ * never makes a record invalid, and `--current` still lists the record.
+ */
+export declare const RECORD_WARNING_CODES: readonly ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"];
+export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
+export interface RecordWarning {
+    code: RecordWarningCode;
+    message: string;
+}
 /**
  * Why the read as a whole failed. Also closed. The command exits 1 with one of
  * these and returns no records.
@@ -53,6 +65,13 @@ export declare const recordKindSchema: z.ZodObject<{
         field: z.ZodString;
         key: z.ZodString;
     }, z.core.$strict>;
+    approval: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    pins: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+    }, z.core.$strict>>;
+    constrains: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type RecordKind = z.infer<typeof recordKindSchema>;
 /** A kind as loaded: its data, where it came from, and its schema. */
@@ -64,6 +83,12 @@ export interface LoadedRecordKind {
     dir: string;
     schema: Record<string, unknown>;
 }
+/**
+ * Import the kind file at `path` through the path loader lexicons use (#2520).
+ * The kind is registered under a name no lexicon package can have (npm names
+ * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
+ */
+export declare function importKindModule(path: string): Promise<Record<string, unknown>>;
 /** Load a kind file and the schema it names. `path` is resolved against `cwd`. */
 export declare function loadRecordKind(path: string, cwd?: string): Promise<LoadedRecordKind>;
 export type FrontMatter = {
@@ -96,6 +121,10 @@ export interface RecordEntry {
     supersededBy: string | null;
     /** The front matter as JSON, or null when it could not be parsed. */
     data: Record<string, unknown> | null;
+    /** Each workspace file the record pins, checked against the tree read (#2549). Empty when nothing was checked. */
+    assets: AssetPin[];
+    /** Findings that leave the record valid, such as a pinned file that changed (#2549). */
+    warnings: RecordWarning[];
 }
 export interface ReadRecordsOptions {
     /** Where record paths are reported from, and what `source` reads relative to. */
@@ -103,6 +132,24 @@ export interface ReadRecordsOptions {
     source: RecordSource;
     /** Leave out records a closed record supersedes. */
     current?: boolean;
+    /**
+     * The workspace root the kind's pins resolve in: the working tree, or the
+     * revision read (#2549). Without it no pin is checked.
+     */
+    assets?: WorkspaceTree;
+    /**
+     * When files last changed and records were recorded, in the history of the
+     * revision read, for `asset-stale` (#2549). Without it only the hashes are
+     * compared.
+     */
+    history?: RecordHistory;
+}
+/** Commit times, in seconds since the epoch, read from git. */
+export interface RecordHistory {
+    /** The last commit that changed `path` (from the workspace root), or null when unknown. */
+    fileChanged(path: string): number | null;
+    /** The commit that added the record at `path` (from the repository root), or null when it is not committed. */
+    recorded(path: string): number | null;
 }
 export interface ReadRecordsResult {
     records: RecordEntry[];

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

@@ -1 +1 @@
-{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/workspace/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,4IAWU,CAAC;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,2KAiBa,CAAC;AAC3C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,aAAa;gBAAnB,IAAI,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAMD,oDAAoD;AACpD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;kBAoCzB,CAAC;AAEL,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAmBD,kFAAkF;AAClF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiCzG;AAID,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExG;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAgB1D;AA0BD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AAsBD,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgFnH"}
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/workspace/records.ts"],"names":[],"mappings":"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"}

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.84.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/main.test.ts

@@ -688,6 +688,17 @@ describe("workspace records (#2546)", () => {
   });
 });
 
+describe("workspace graph --intent (#2651)", () => {
+  test("parses the region and every --kind, in order", () => {
+    const args = parseArgs(["workspace", "graph", "--intent", "app/server.mjs:3-7", "--kind", "a.kind.mjs", "--kind", "b.kind.mjs", "--at", "HEAD", "--json"]);
+    expect(args).toMatchObject({ command: "workspace", path: "graph", intent: "app/server.mjs:3-7", kinds: ["a.kind.mjs", "b.kind.mjs"], kind: "b.kind.mjs", at: "HEAD", json: true });
+    expect(parseArgs(["workspace", "graph", "--intent=app"]).intent).toBe("app");
+    expect(() => parseArgs(["workspace", "graph", "--intent"])).toThrow(/--intent needs a region/);
+    expect(() => parseArgs(["workspace", "graph", "--intent", "--json"])).toThrow(/--intent needs a region/);
+    expect(resolveCommand(args, commandRegistry)?.def.name).toBe("workspace graph");
+  });
+});
+
 describe("workspace init and ls (#2534)", () => {
   test("resolve to their commands in the one workspace group, with the directory as extra positional", () => {
     const ls = parseArgs(["workspace", "ls", "examples", "--at", "HEAD", "--json"]);

package/src/cli/main.ts

@@ -360,9 +360,15 @@ 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>");
+      // Repeatable for `workspace graph --intent` (#2651); the others read the last one.
+      (result.kinds ??= []).push(result.kind);
+    } else if (arg === "--intent") {
+      // `chant workspace graph --intent <path[:start-end]>` (#2651)
+      result.intent = args[++i];
+      if (!result.intent || result.intent.startsWith("-")) throw new Error("--intent needs a region: --intent <path[:start-end]>");
     } else if (arg === "--current") {
       result.current = true;
     } else if (arg === "--require") {
@@ -719,7 +725,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 +747,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 +767,16 @@ 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
+  workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]
+                        The intent graph over one region: the commits that
+                        touched it, the decisions whose constrains cover it,
+                        the artifacts they pin, and findings with closed codes
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/registry.ts

@@ -283,6 +283,10 @@ export interface ParsedArgs {
   at?: string;
   /** `chant workspace records --kind <path>` (#2546): the record kind file to read records through. */
   kind?: string;
+  /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
+  kinds?: string[];
+  /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
+  intent?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */
   current?: boolean;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */

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,13 @@
 /**
- * `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`).
+ *
+ * With `--intent <path[:start-end]>` it prints the intent graph over one
+ * region instead (#2651, `intent.ts`), a document of its own in the read
+ * contract.
  *
  * 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 +33,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 +47,8 @@ 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] | chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
 interface Head {
   $schema: string;
@@ -64,6 +72,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 +185,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 };
@@ -191,6 +221,9 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
   const handed = await handToRootChant(cwd, args.at);
   if (handed !== undefined) return handed;
 
+  // The intent graph over one region (#2651) is its own document.
+  if (args.intent !== undefined) return (await import("./intent-cli")).runWorkspaceIntent(ctx, cwd);
+
   if (args.dryRun) {
     let plan: MemberPlan;
     try {
@@ -209,6 +242,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"]);
   });
 });