@intentius/chant 0.81.0 → 0.83.0

package/dist/workspace/record-assets.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 type { RecordWarning } from "./records.js";
+import type { WorkspaceTree } from "./tree.js";
+/**
+ * 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 declare const WORKSPACE_PATH_PATTERN: string;
+export declare function isWorkspacePath(value: unknown): value is string;
+/**
+ * `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 declare function pinEntries(data: Record<string, unknown> | null, field: string): {
+    path: string;
+    sha256: string;
+}[];
+/** The hex SHA-256 of the file at `path` in `tree`, or undefined when it is not a file there. */
+export declare function fileDigest(tree: WorkspaceTree, path: string): string | undefined;
+/** Check each pin against `tree`, rooted at the workspace root. */
+export declare function checkPins(pins: {
+    path: string;
+    sha256: string;
+}[], tree: WorkspaceTree): {
+    assets: AssetPin[];
+    warnings: RecordWarning[];
+};
+/** The kinds of link a record has in `chant workspace graph`. Closed. */
+export declare const RECORD_LINK_KINDS: readonly ["asset", "constrains"];
+/** 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 declare function memberHolding(path: string, members: readonly {
+    name: string;
+    dir: string;
+}[]): string | null;
+/** Whether a `path:` constraint covers `file`: the same path, or a directory above it. */
+export declare function constraintCovers(constraint: string, file: string): boolean;
+/** 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 declare function recordLinkRows(kindName: string, records: readonly LinkedRecord[], constrainsField: string | undefined, tree: WorkspaceTree, members: readonly {
+    name: string;
+    dir: string;
+}[]): RecordLinkRow[];
+//# sourceMappingURL=record-assets.d.ts.map

package/dist/workspace/record-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-assets.d.ts","sourceRoot":"","sources":["../../src/workspace/record-assets.ts"],"names":[],"mappings":"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"}

package/dist/workspace/records-cli.d.ts

@@ -12,7 +12,7 @@
  * nothing is inferred (#2525 rule 1).
  */
 import type { CommandContext } from "../cli/registry.js";
-import { type ReadErrorCode, type RecordEntry } from "./records.js";
+import { type LoadedRecordKind, type ReadErrorCode, type ReadRecordsResult, type RecordEntry } from "./records.js";
 import { type ProvenanceLevel } from "./trust/attestor.js";
 import { type BaseSource, type RecordProvenance } from "./trust/provenance.js";
 /** The version of the `records` output this chant writes. */
@@ -54,6 +54,8 @@ export type RecordsDocument = {
         file: string;
     };
     at: string | null;
+    /** The directory pinned paths resolve in, from the repository root: the workspace holding the kind file, or the repository root (#2549). */
+    workspaceRoot: string;
     current: boolean;
     trust: TrustView;
     records: RecordView[];
@@ -71,8 +73,37 @@ export type RecordsDocument = {
         message: string;
     };
 };
+/** A records read, before provenance. */
+export interface RecordsRead {
+    loaded: LoadedRecordKind;
+    /** The repository root, or the working directory outside git. Record paths are relative to it. */
+    root: string;
+    /** The git top, or undefined outside git. */
+    top: string | undefined;
+    at: string | null;
+    /** Where pinned paths resolve, relative to `root` ("." for the root itself). */
+    workspaceRoot: string;
+    result: ReadRecordsResult;
+}
+/**
+ * Load the kind and read its records, in the working tree or at `query.at`,
+ * with each pin checked in the same tree. Throws a {@link RecordReadError}.
+ * `chant workspace graph` and `check` read records through this too.
+ */
+export declare function readRecordsFor(query: Omit<RecordsQuery, "base">): Promise<RecordsRead>;
 /** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
 export declare function queryRecords(query: RecordsQuery): Promise<RecordsDocument>;
+/**
+ * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
+ * evidence entry holds for a file, with the path from the workspace root
+ * (the nearest declaration above the file, or the repository root).
+ */
+export declare function pinFile(file: string, cwd: string): {
+    path: string;
+    sha256: string;
+} | {
+    error: string;
+};
 export declare function runWorkspaceRecords(ctx: CommandContext): Promise<number>;
 /** Records whose provenance falls below `required`. Only `attested` can be required. */
 export declare function belowRequired(records: RecordView[], required: ProvenanceLevel): RecordView[];

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

@@ -1 +1 @@
-{"version":3,"file":"records-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/records-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAgD,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC/G,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAA+C,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEzH,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,gFAAgF,CAAC;AAItH,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAExE,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,uFAAuF;IACvF,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,GACvB;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,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,GACD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE3F,oGAAoG;AACpG,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CA4ChF;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC9E;AAUD,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,eAAe,GAAG,UAAU,EAAE,CAE5F;AAoBD,yCAAyC;AACzC,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAS9E"}
+{"version":3,"file":"records-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/records-cli.ts"],"names":[],"mappings":"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"}

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. */
@@ -96,6 +115,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 +126,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.81.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/handlers/init.ts

@@ -54,14 +54,15 @@ export async function runInitLexicon(ctx: CommandContext): Promise<number> {
  * `chant init --from <repo>@<ref>[#<member>] [--param <name>=<value>]... [path]`
  * (#2540, #2627): copy a template repository at a ref, substitute the
  * parameters its `chant.template.json` declares, and record its lineage.
+ * `--from <dir>[#<member>]` copies a template directory on disk instead (#2647).
  * The template brings its own lexicons and configuration, so `--lexicon` and
  * `--template` do not apply.
  */
 async function runInitFrom(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
-  const usage = "Usage: chant init --from <repo>@<ref>[#<member>] [--param <name>=<value>]... [path]";
+  const usage = "Usage: chant init --from <repo>@<ref>[#<member>] | <dir>[#<member>] [--param <name>=<value>]... [path]";
   if (!args.migrateFrom) {
-    console.error(formatError({ message: "--from needs a template: <repo>@<ref>[#<member>]", hint: usage }));
+    console.error(formatError({ message: "--from needs a template: <repo>@<ref>[#<member>] or <dir>[#<member>]", hint: usage }));
     return 1;
   }
   if (args.lexicon || args.template) {
@@ -95,7 +96,10 @@ async function runInitFrom(ctx: CommandContext): Promise<number> {
   console.log(formatSuccess("Created:"));
   for (const file of result.createdFiles) console.log(`  ${file}`);
   console.log("");
-  console.log(`Lineage: ${result.spec!.id} at ${result.spec!.ref} (${result.commit!.slice(0, 12)}), recorded in .chant/workspace.lock.json`);
+  const from = result.spec
+    ? `${result.spec.id} at ${result.spec.ref} (${result.commit!.slice(0, 12)})`
+    : `${result.template} (a directory, recorded by digest only)`;
+  console.log(`Lineage: ${from}, recorded in .chant/workspace.lock.json`);
   const parameters = Object.entries(result.parameters ?? {});
   if (parameters.length > 0) console.log(`Parameters: ${parameters.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(", ")}`);
   return 0;

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") {
@@ -549,7 +549,9 @@ Usage:
 Commands:
   init                  Initialize a new chant project
                         (--from <repo>@<ref>[#<member>] copies a template
-                        repository and records its lineage; --param
+                        repository and records its lineage, and --from
+                        <dir>[#<member>] copies a template directory on
+                        disk; --param
                         <name>=<value> sets a parameter the template's
                         chant.template.json declares, repeatable)
   init lexicon <name>   Scaffold a new lexicon plugin project
@@ -717,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
@@ -729,18 +735,19 @@ Workspace (level 1, #2524):
                         manual steps. Needs no workspace file
   workspace lineage resolve <path>
                         Close a manual step once the file is merged by hand
-  workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run] [--output <file>]
+  workspace upgrade [<scope>] [--to <ref|dir>] [--allow-code] [--dry-run] [--output <file>]
                         Bring a lineage scope to a newer template version: fetch
                         it, migrate and merge per file in a worktree, run build,
                         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]
@@ -754,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/behold-kinds.test.ts

@@ -1,15 +1,14 @@
 /**
  * behold's two closed member kinds, read through chant's workspace (#2545).
  *
- * `terraform` ships from the terraform lexicon's `./workspace-kinds` subpath,
- * and `choudoufu` from the kinds-only package
- * `@intentius/workspace-kind-choudoufu`. A workspace that pins both lists
- * members of either kind through `chant workspace ls --json`, with the kinds
- * behold gave the same directories, and reading the kinds imports neither
- * package.
+ * Both ship from the terraform lexicon's `./workspace-kinds` subpath, since
+ * a choudoufu estate is a Terraform root the lexicon's choudoufu mode reads.
+ * A workspace that pins the lexicon lists members of either kind through
+ * `chant workspace ls --json`, with the kinds behold gave the same
+ * directories, and reading the kinds never imports the lexicon.
  *
- * The installed packages are the repo's own: their package.json and kinds
- * file are copied as they ship, and every code entry their `exports` name is
+ * The installed package is the repo's own: its package.json and kinds file
+ * are copied as they ship, and every code entry its `exports` names is
  * replaced by a module that leaves a marker file when it is imported.
  */
 
@@ -25,7 +24,6 @@ import { workingTree } from "./tree";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 const TERRAFORM = join(REPO, "lexicons", "terraform");
-const CHOUDOUFU = join(REPO, "packages", "workspace-kind-choudoufu");
 const FIXTURES = join(TERRAFORM, "src", "__fixtures__");
 
 const scratch: string[] = [];
@@ -65,7 +63,7 @@ function install(root: string, from: string): string {
 function workspace(): { root: string; installed: string[] } {
   const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-behold-kinds-")));
   scratch.push(root);
-  const installed = [install(root, TERRAFORM), install(root, CHOUDOUFU)];
+  const installed = [install(root, TERRAFORM)];
   // Estates in the shapes behold serves: a stock root, a choudoufu root with
   // the sidecar, one with the live block, and a chant project beside .tf files.
   cpSync(join(FIXTURES, "no-backend"), join(root, "estates", "stock"), { recursive: true });
@@ -82,7 +80,6 @@ function workspace(): { root: string; installed: string[] } {
         schema: 1,
         pins: [
           { package: "@intentius/chant-lexicon-terraform", version: version(TERRAFORM) },
-          { package: "@intentius/workspace-kind-choudoufu", version: version(CHOUDOUFU) },
         ],
         members: [
           { name: "stock", dir: "estates/stock", kind: "terraform" },
@@ -106,7 +103,7 @@ describe("behold's member kinds from their packages (#2545)", () => {
   });
   afterEach(() => vi.restoreAllMocks());
 
-  test("chant workspace ls --json lists terraform and choudoufu members, readable, and imports neither package", async () => {
+  test("chant workspace ls --json lists terraform and choudoufu members, readable, and never imports the lexicon", async () => {
     const { root, installed } = workspace();
     const code = await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
     expect(code).toBe(0);
@@ -126,12 +123,11 @@ describe("behold's member kinds from their packages (#2545)", () => {
     const { root } = workspace();
     const pins = [
       { package: "@intentius/chant-lexicon-terraform", version: version(TERRAFORM), path: null },
-      { package: "@intentius/workspace-kind-choudoufu", version: version(CHOUDOUFU), path: null },
     ];
     const { registry, problems } = loadKindRegistry(pins, root);
     expect(problems).toEqual([]);
     expect(registry.get("terraform")).toMatchObject({ source: "@intentius/chant-lexicon-terraform", precedence: 400 });
-    expect(registry.get("choudoufu")).toMatchObject({ source: "@intentius/workspace-kind-choudoufu", precedence: 450 });
+    expect(registry.get("choudoufu")).toMatchObject({ source: "@intentius/chant-lexicon-terraform", precedence: 450 });
     const tree = workingTree(root);
     const winner = (dir: string) => resolveKind(registry, tree, dir).winner?.name;
     expect(winner("estates/stock")).toBe("terraform");

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