@intentius/chant 0.124.27 → 0.124.29

package/dist/workspace/flags.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Feature flags as workspace records (#4024, decided in #4016).
+ *
+ * A flag is a record of a kind with a `flag` block (`records.ts`). It names a
+ * member, one of that member's declared build-time parameters, an owner, the
+ * work item the flag hides and a value per environment. The member's build
+ * reads it as that parameter (`../flag-params.ts`), so turning a flag on in
+ * an environment is a commit that changes the record, and the release cut
+ * from that commit carries the new value as a `params` entry whose `source`
+ * is `flag:<id>` (ws-104).
+ *
+ * This module and `./flags-read.ts` do three things:
+ *
+ * - {@link applyFlags}: on a `records` read of a flag kind, gives each record
+ *   its work item with that item's state, the decisions the item implements,
+ *   and whether the flag is due for removal, with the warnings
+ *   `flag-work-unknown` and `flag-stale`.
+ * - `readWorkspaceFlags` (`./flags-read.ts`): every flag of every flag kind
+ *   the declaration names, for `workspace status` (`featureFlags`) and the
+ *   build.
+ * - `memberFlagBindings` (`./flags-read.ts`): the flags of the member holding
+ *   a directory, by parameter, for one environment.
+ *
+ * The readers live apart so that `records.ts`, which loads this module for a
+ * flag kind, never reaches `records-cli.ts` and what it imports.
+ *
+ * A flag is due for removal when its work item implements at least one
+ * decision and every decision it implements is confirmed: in one of its
+ * kind's closed states and superseded by nothing. For chant's decision kind
+ * that is `ratified` (a superseded decision has a superseder). The work is
+ * then settled, and the flag that hid it is dead weight.
+ */
+import { type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records.js";
+import type { WorkLink } from "./work.js";
+/** Why a flag record carries a warning. Closed, like the record warning codes. */
+export declare const FLAG_WARNING_CODES: readonly ["flag-work-unknown", "flag-stale"];
+export type FlagWarningCode = (typeof FLAG_WARNING_CODES)[number];
+/** A flag's value in one environment: what a build-time parameter can hold. */
+export type FlagValue = string | number | boolean;
+/** A decision a flag's work item implements, with whether it is confirmed. */
+export interface FlagDecision extends WorkLink {
+    /** In one of its kind's closed states and superseded by nothing. */
+    confirmed: boolean;
+}
+/** What a read of a flag kind adds to each record (#4024). */
+export interface FlagState {
+    /** The work item the flag hides, with its state, or null when the record names none. The state is null when no record has the id. */
+    work: WorkLink | null;
+    /** Each decision the work item implements, with its state. Empty when the item is unknown or implements none. */
+    implements: FlagDecision[];
+    /** True when the work item implements at least one decision and every one is confirmed: the flag is due for removal. */
+    stale: boolean;
+}
+/** A flag as `workspace status` and the build read it. */
+export interface WorkspaceFlag {
+    /** The flag's name, its record's id. */
+    id: string;
+    /** The kind file from the workspace root. */
+    kind: string;
+    /** The record file from the workspace root, with / separators. */
+    path: string;
+    member: string;
+    param: string;
+    owner: string;
+    /** The value per environment, as the record writes it, in key order. */
+    values: Record<string, FlagValue>;
+    work: WorkLink | null;
+    implements: FlagDecision[];
+    stale: boolean;
+}
+/** A flag record that is not valid, so no build trusts it. */
+export interface InvalidFlag {
+    kind: string;
+    path: string;
+    /** The member the record names, or null when it names none that can be read. */
+    member: string | null;
+    message: string;
+}
+/** Every flag a workspace's declared flag kinds hold. */
+export interface WorkspaceFlags {
+    flags: WorkspaceFlag[];
+    invalid: InvalidFlag[];
+}
+/**
+ * Whether a decision is confirmed: in one of its kind's `closed` states and
+ * superseded by nothing. An unknown decision is not. The overlap report
+ * (#4025) shares it: a work item is in flight while any decision it
+ * implements is not confirmed.
+ */
+export declare function decisionConfirmed(decision: {
+    state: string | null;
+    supersededBy: string | null;
+} | undefined, closed: ReadonlySet<string>): boolean;
+/**
+ * Give each record of a flag kind its {@link FlagState} and warnings, in
+ * place. Throws a `RecordReadError` when the work kind it names can't be read
+ * or is not a work kind.
+ */
+export declare function applyFlags(loaded: LoadedRecordKind, entries: RecordEntry[], options: ReadRecordsOptions): Promise<void>;
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/workspace/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAgD,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3I,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,8CAKW,CAAC;AAC3C,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,8EAA8E;AAC9E,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,qIAAqI;IACrI,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,iHAAiH;IACjH,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,wHAAwH;IACxH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAEnJ;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuC7H"}

package/dist/workspace/flags.js

@@ -0,0 +1,98 @@
+/**
+ * Feature flags as workspace records (#4024, decided in #4016).
+ *
+ * A flag is a record of a kind with a `flag` block (`records.ts`). It names a
+ * member, one of that member's declared build-time parameters, an owner, the
+ * work item the flag hides and a value per environment. The member's build
+ * reads it as that parameter (`../flag-params.ts`), so turning a flag on in
+ * an environment is a commit that changes the record, and the release cut
+ * from that commit carries the new value as a `params` entry whose `source`
+ * is `flag:<id>` (ws-104).
+ *
+ * This module and `./flags-read.ts` do three things:
+ *
+ * - {@link applyFlags}: on a `records` read of a flag kind, gives each record
+ *   its work item with that item's state, the decisions the item implements,
+ *   and whether the flag is due for removal, with the warnings
+ *   `flag-work-unknown` and `flag-stale`.
+ * - `readWorkspaceFlags` (`./flags-read.ts`): every flag of every flag kind
+ *   the declaration names, for `workspace status` (`featureFlags`) and the
+ *   build.
+ * - `memberFlagBindings` (`./flags-read.ts`): the flags of the member holding
+ *   a directory, by parameter, for one environment.
+ *
+ * The readers live apart so that `records.ts`, which loads this module for a
+ * flag kind, never reaches `records-cli.ts` and what it imports.
+ *
+ * A flag is due for removal when its work item implements at least one
+ * decision and every decision it implements is confirmed: in one of its
+ * kind's closed states and superseded by nothing. For chant's decision kind
+ * that is `ratified` (a superseded decision has a superseder). The work is
+ * then settled, and the flag that hid it is dead weight.
+ */
+import { dirname } from "node:path";
+import { loadRecordKind, readRecords, RecordReadError } from "./records.js";
+/** Why a flag record carries a warning. Closed, like the record warning codes. */
+export const FLAG_WARNING_CODES = [
+    /** The flag names a work item no record of its kind's work kind has. */
+    "flag-work-unknown",
+    /** Every decision the flag's work item implements is confirmed, so the flag is due for removal. `check` reports it (WSP118). */
+    "flag-stale",
+];
+const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+/**
+ * Whether a decision is confirmed: in one of its kind's `closed` states and
+ * superseded by nothing. An unknown decision is not. The overlap report
+ * (#4025) shares it: a work item is in flight while any decision it
+ * implements is not confirmed.
+ */
+export function decisionConfirmed(decision, closed) {
+    return decision !== undefined && decision.state !== null && closed.has(decision.state) && decision.supersededBy === null;
+}
+/**
+ * Give each record of a flag kind its {@link FlagState} and warnings, in
+ * place. Throws a `RecordReadError` when the work kind it names can't be read
+ * or is not a work kind.
+ */
+export async function applyFlags(loaded, entries, options) {
+    const flag = loaded.kind.flag;
+    const workKind = await loadRecordKind(flag.work.kind, dirname(loaded.file));
+    if (!workKind.kind.work) {
+        throw new RecordReadError("kind-invalid", `flag kind ${loaded.kind.name} names ${flag.work.kind} as its work kind, and that kind has no work block`);
+    }
+    const decisionKind = await loadRecordKind(workKind.kind.work.decisions, dirname(workKind.file));
+    const read = await readRecords(workKind, { root: options.root, source: options.source });
+    const items = new Map();
+    for (const r of read.records)
+        if (r.id !== null && !items.has(r.id))
+            items.set(r.id, r);
+    const decisions = new Map((read.decisions ?? []).map((d) => [d.id, d]));
+    const closed = new Set(decisionKind.kind.closedStates ?? []);
+    for (const e of entries) {
+        if (e.data === null)
+            continue;
+        const named = str(e.data[flag.work.field]);
+        if (named === null) {
+            e.flag = { work: null, implements: [], stale: false };
+            continue;
+        }
+        const item = items.get(named);
+        if (!item) {
+            e.flag = { work: { id: named, state: null }, implements: [], stale: false };
+            e.warnings.push({ code: "flag-work-unknown", message: `hides the work item ${named}, which no record in ${flag.work.kind} has` });
+            continue;
+        }
+        const implementsList = (item.implements ?? []).map((d) => {
+            const decision = decisions.get(d.id);
+            return { ...d, confirmed: decisionConfirmed(decision, closed) };
+        });
+        const stale = implementsList.length > 0 && implementsList.every((d) => d.confirmed);
+        e.flag = { work: { id: named, state: item.state }, implements: implementsList, stale };
+        if (stale) {
+            e.warnings.push({
+                code: "flag-stale",
+                message: `is due for removal: its work item ${named} implements ${implementsList.map((d) => `${d.id} (${d.state})`).join(", ")}, and every one is confirmed`,
+            });
+        }
+    }
+}

package/dist/workspace/graph-cli.js

@@ -51,7 +51,7 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 export const GRAPH_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "live-at-revision"];
 /** Why `--live` and `--at` don't go together (#2875). */
 const LIVE_AT_REVISION = "--live reads the account as it stands now, and --at reads the source at a revision; chant workspace graph takes one of them";
-const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 /** The command line a member runs for its component graph (#2662). */
 export function componentGraphArgv(args) {
     return ["graph", ".", "--components", "--format", "ir", ...(args.env ? ["--env", args.env] : [])];

package/dist/workspace/identity-gate-rule.d.ts

@@ -62,4 +62,41 @@ export declare function grantedClasses(classes: readonly ClassGrant[], roles: Re
  * know lets nothing through.
  */
 export declare function admitApprover(rule: GateAdmissionRule, a: SealedGateApproval): string | null;
+/** The gate whose `identity.gates` entry says who may cut a release (#4031). */
+export declare const RELEASE_GATE = "release";
+/** The ssh signature namespace of a release cut's signature (#4031), so no other signature can stand in for one. */
+export declare const RELEASE_SEAL_NAMESPACE = "chant-release";
+/** A cut line's fields its signature covers (#4031), and the signature. */
+export interface SignedReleaseCut {
+    releaseDigest: string;
+    label: string | null;
+    actor: string;
+    timestamp: string;
+    /** The armored ssh signature, or null for an unsigned cut. */
+    signature: string | null;
+}
+/**
+ * The bytes a release cut's signature signs (#4031): the release digest,
+ * the label (empty for none), the actor who cut it and the cut's time,
+ * joined by LF with no final newline.
+ */
+export declare function releaseSealPayload(cut: Omit<SignedReleaseCut, "signature">): Buffer;
+/**
+ * Why `cut` may not be made under the `release` gate's rule, or null when
+ * it may (#4031): its signature verifies for its actor against the signers
+ * at base and, when the gate names a class, the role grants at base put the
+ * actor in it. The same rule {@link admitApprover} applies to an approval,
+ * over the cut's own signed bytes.
+ */
+export declare function admitReleaseCut(rule: GateAdmissionRule, cut: SignedReleaseCut): string | null;
+/** Whether a cut's signature verifies, as `release list` and `workspace status` report it (#4031). */
+export interface ReleaseSignatureCheck {
+    /** `verified`: it verifies for the actor, who is in the release gate's class when it names one. `unsigned`: the cut has none. `unverified`: it does not, and `reason` says why. */
+    status: "verified" | "unsigned" | "unverified";
+    /** The fingerprint of the key in the signature, or null for an unsigned cut or one that can't be read. */
+    key: string | null;
+    reason: string;
+}
+/** Judge a stored cut's signature against `rule`, read at base. A rule with no class checks the signature alone. */
+export declare function checkReleaseSignature(rule: GateAdmissionRule, cut: SignedReleaseCut): ReleaseSignatureCheck;
 //# sourceMappingURL=identity-gate-rule.d.ts.map

package/dist/workspace/identity-gate-rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-gate-rule.d.ts","sourceRoot":"","sources":["../../src/workspace/identity-gate-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAkF,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5I,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,YAAI,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AACvF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,cAAc,EAKjD,CAAC;AAEF,kHAAkH;AAClH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE/D,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9E,6DAA6D;IAC7D,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID,iIAAiI;AACjI,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAIrJ;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAa3F"}
+{"version":3,"file":"identity-gate-rule.d.ts","sourceRoot":"","sources":["../../src/workspace/identity-gate-rule.ts"],"names":[],"mappings":"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"}

package/dist/workspace/identity-gate-rule.js

@@ -13,7 +13,7 @@
  * The module imports node:crypto through `./trust/gate-seal.ts` and nothing
  * else: no zod, no ajv, no package loading, so it bundles small.
  */
-import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, verifySshSignatureWith } from "./trust/gate-seal.js";
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, sshKeyFingerprint, sshSignatureKey, verifySshSignatureWith } from "./trust/gate-seal.js";
 /** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
 export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"];
 export const CORE_CLASSES = [
@@ -39,20 +39,85 @@ export function grantedClasses(classes, roles, principal) {
  */
 export function admitApprover(rule, a) {
     const { gate, signers } = rule;
-    const want = rule.class;
-    if (want !== null && !rule.classes.some((c) => c.name === want)) {
-        return `identity.gates.${gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no approval can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
-    }
+    const unknown = unknownClassRefusal(rule, "approval");
+    if (unknown !== null)
+        return unknown;
     if (!signers.active)
         return `gate ${gate} needs a signed approval, and there is no signers file (${signers.signersPath}) at base to check one against`;
     const seal = sealRefusal(gate, signers, a);
     if (seal !== null)
         return seal;
+    return classRefusal(rule, a.resolvedBy);
+}
+/** Why no signature can show a principal is in the rule's class: the class is one the rule does not know. Null otherwise. */
+function unknownClassRefusal(rule, what) {
+    const want = rule.class;
+    if (want === null || rule.classes.some((c) => c.name === want))
+        return null;
+    return `identity.gates.${rule.gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no ${what} can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
+}
+/** Why `principal` is not in the rule's class, or null when it is or the rule names none. */
+function classRefusal(rule, principal) {
+    const want = rule.class;
     if (want === null)
         return null;
-    const granted = grantedClasses(rule.classes, rule.roles, a.resolvedBy);
+    const granted = grantedClasses(rule.classes, rule.roles, principal);
     const inClass = want === "human" ? granted.length === 0 : granted.includes(want);
-    return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+    return inClass ? null : `${principal} is not in the class ${want} that gate ${rule.gate} needs: no role grant at base puts them there`;
+}
+// ── release cuts (#4031) ─────────────────────────────────────────────────
+/** The gate whose `identity.gates` entry says who may cut a release (#4031). */
+export const RELEASE_GATE = "release";
+/** The ssh signature namespace of a release cut's signature (#4031), so no other signature can stand in for one. */
+export const RELEASE_SEAL_NAMESPACE = "chant-release";
+/**
+ * The bytes a release cut's signature signs (#4031): the release digest,
+ * the label (empty for none), the actor who cut it and the cut's time,
+ * joined by LF with no final newline.
+ */
+export function releaseSealPayload(cut) {
+    return Buffer.from(`${cut.releaseDigest}\n${cut.label ?? ""}\n${cut.actor}\n${cut.timestamp}`, "utf-8");
+}
+/** Why the cut's signature does not verify for its actor against the signers at base, or null when it does. */
+function releaseSignatureRefusal(signers, cut) {
+    if (cut.signature === null)
+        return `the cut by ${cut.actor} is not signed`;
+    if (!signers.active)
+        return `there is no signers file (${signers.signersPath}) at base to check the cut's signature against`;
+    const where = `${signers.signersPath} at base`;
+    const listed = signers.signers.filter((s) => normalise(s.principal) === normalise(cut.actor));
+    if (listed.length === 0)
+        return `${cut.actor} has no key in ${where}, so the cut's signature can't count`;
+    const keys = listed.filter((s) => namespaceAllowed(s.namespaces, RELEASE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+    const r = verifySshSignatureWith(cut.signature, releaseSealPayload(cut), RELEASE_SEAL_NAMESPACE, keys);
+    return r.ok ? null : `the cut's signature does not verify for ${cut.actor} against ${where}: ${r.reason}`;
+}
+/**
+ * Why `cut` may not be made under the `release` gate's rule, or null when
+ * it may (#4031): its signature verifies for its actor against the signers
+ * at base and, when the gate names a class, the role grants at base put the
+ * actor in it. The same rule {@link admitApprover} applies to an approval,
+ * over the cut's own signed bytes.
+ */
+export function admitReleaseCut(rule, cut) {
+    const unknown = unknownClassRefusal(rule, "cut");
+    if (unknown !== null)
+        return unknown;
+    const seal = releaseSignatureRefusal(rule.signers, cut);
+    if (seal !== null)
+        return `${seal}; identity.gates.${rule.gate} needs a release cut signed with chant release cut --sign`;
+    return classRefusal(rule, cut.actor);
+}
+/** Judge a stored cut's signature against `rule`, read at base. A rule with no class checks the signature alone. */
+export function checkReleaseSignature(rule, cut) {
+    if (cut.signature === null)
+        return { status: "unsigned", key: null, reason: "the cut carries no signature" };
+    const blob = sshSignatureKey(cut.signature);
+    const key = blob ? sshKeyFingerprint(blob) : null;
+    const why = unknownClassRefusal(rule, "cut") ?? releaseSignatureRefusal(rule.signers, cut) ?? classRefusal(rule, cut.actor);
+    if (why !== null)
+        return { status: "unverified", key, reason: why };
+    return { status: "verified", key, reason: `signed by ${cut.actor}${rule.class !== null ? `, in the class ${rule.class}` : ""}` };
 }
 /** The seal step, worded as `checkGateSeal` (`./trust/seal.ts`) words it against an active signers file at base. */
 function sealRefusal(gate, signers, a) {

package/dist/workspace/identity.d.ts

@@ -25,6 +25,7 @@
  * sealed by a signer, from a class when it names one.
  */
 import type { Declaration, SignedGate } from "./declaration.js";
+import { type GateAdmissionRule } from "./identity-gate-rule.js";
 import { type ClassRegistry } from "./principal-classes.js";
 import type { TrustPolicy } from "./trust/policy.js";
 import type { SealedGateApproval } from "./trust/gate-seal.js";
@@ -103,6 +104,17 @@ export interface GateRuleSource extends IdentitySource {
  * the one at base, never a returned work's copy.
  */
 export declare function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdmission | null;
+/**
+ * The rule a release cut is judged by (#4031): the declaration's
+ * `identity.gates.release` entry with its class, read at base, or, when the
+ * declaration names no `release` gate, a rule with no class, which checks a
+ * cut's signature alone. `requirement` is null in that case, and a cut may
+ * then be made unsigned.
+ */
+export declare function releaseRuleFrom(source: GateRuleSource): {
+    requirement: SignedGate | null;
+    rule: GateAdmissionRule;
+};
 /**
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.

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

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/workspace/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,4CAA4C;AAC5C,eAAO,MAAM,MAAM,YAAI,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AACxE,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAK5C,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf;AAKD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAO1E;AAED,8HAA8H;AAC9H,wBAAgB,cAAc,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAExD;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,+EAA+E;IAC/E,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CAC7B;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAE,WAAW,GAAG,IAAW,GAAG,UAAU,CAQnH;AAED,uDAAuD;AACvD,eAAO,MAAM,cAAc,qCAAsE,CAAC;AAClG,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAA4B;IACvD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,8GAA8G;AAC9G,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAAG,IAAI,CAS7I;AAED,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAElD,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,UAAU,CAAC;IACxB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAC;CACpD;AAED,sHAAsH;AACtH,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAM5F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAE5F"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/workspace/identity.ts"],"names":[],"mappings":"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"}

package/dist/workspace/identity.js

@@ -24,7 +24,7 @@
  * write, and `gates.<gate>` lets a gate of that name pass only on an approval
  * sealed by a signer, from a class when it names one.
  */
-import { admitApprover } from "./identity-gate-rule.js";
+import { admitApprover, RELEASE_GATE } from "./identity-gate-rule.js";
 import { classesOf, coreClassRegistry, roleGrants } from "./principal-classes.js";
 import { normalisePrincipal } from "./records.js";
 import { scopeSource } from "./write-scope.js";
@@ -114,6 +114,18 @@ export function gateAdmissionFrom(source, gate) {
     const rule = { gate, class: requirement.class, signers: policy, roles: roleGrants(policy), classes: classes.all() };
     return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
+/**
+ * The rule a release cut is judged by (#4031): the declaration's
+ * `identity.gates.release` entry with its class, read at base, or, when the
+ * declaration names no `release` gate, a rule with no class, which checks a
+ * cut's signature alone. `requirement` is null in that case, and a cut may
+ * then be made unsigned.
+ */
+export function releaseRuleFrom(source) {
+    const requirement = source.declaration?.identity?.gates[RELEASE_GATE] ?? null;
+    const { policy, classes } = source;
+    return { requirement, rule: { gate: RELEASE_GATE, class: requirement?.class ?? null, signers: policy, roles: roleGrants(policy), classes: classes.all() } };
+}
 /**
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.

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

@@ -1,5 +1,5 @@
 /**
- * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
+ * `chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
  * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
@@ -7,10 +7,13 @@
  * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
  * to the person about it (#2656). Without `--kind`, the walk reads every
- * record kind the declaration names (#2680).
+ * record kind the declaration names (#2680). Last comes the why chain (#4023):
+ * each commit's work item, ci tag and release, and each release's gates and
+ * deploys.
  */
 import type { CommandContext } from "../cli/registry.js";
 import { type IntentRecordDocument } from "./intent-record.js";
+import type { IntentTrace } from "./intent-trace.js";
 import { type IntentDocument, type WhyAnswer } from "./intent.js";
 type Result = Exclude<IntentDocument, {
     error: unknown;
@@ -22,6 +25,12 @@ type RecordResult = Exclude<IntentRecordDocument, {
 export declare const IN_WINDOW_QUESTION = "is this drift, a superseding decision nobody wrote down, or the decision being wrong?";
 /** Why the region is like this (#3034): the decisions most relevant first, then who made each span of its current lines, then the gaps. */
 export declare function whyLines(doc: Result, why: WhyAnswer): string[];
+/**
+ * The why chain (#4023), in its order: for each commit that names a work item
+ * or was tagged, released or deployed, a line; then each release with its
+ * cuts, gates and deploys, and the deploys of no release.
+ */
+export declare function traceLines(trace: IntentTrace): string[];
 /** The walk as text, one line each, in the order of #2650 section B. */
 export declare function formatIntent(doc: Result): string;
 /** The record walk as text: the record, its window, then each commit with its bucket, and the counts. */

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

@@ -1 +1 @@
-{"version":3,"file":"intent-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/intent-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAsE,KAAK,cAAc,EAAkD,KAAK,SAAS,EAAiB,MAAM,UAAU,CAAC;AAKlM,KAAK,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAC1D,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAYtE,gIAAgI;AAChI,eAAO,MAAM,kBAAkB,0FAA0F,CAAC;AAwG1H,2IAA2I;AAC3I,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,CAsB9D;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6BhD;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAwB5D;AAcD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB1F"}
+{"version":3,"file":"intent-cli.d.ts","sourceRoot":"","sources":["../../src/workspace/intent-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAsE,KAAK,cAAc,EAAkD,KAAK,SAAS,EAAiB,MAAM,UAAU,CAAC;AAKlM,KAAK,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAC1D,KAAK,YAAY,GAAG,OAAO,CAAC,oBAAoB,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAYtE,gIAAgI;AAChI,eAAO,MAAM,kBAAkB,0FAA0F,CAAC;AAwG1H,2IAA2I;AAC3I,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,CAsB9D;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CA0BvD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+BhD;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAwB5D;AAcD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB1F"}

package/dist/workspace/intent-cli.js

@@ -1,5 +1,5 @@
 /**
- * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
+ * `chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
  * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
@@ -7,13 +7,15 @@
  * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
  * to the person about it (#2656). Without `--kind`, the walk reads every
- * record kind the declaration names (#2680).
+ * record kind the declaration names (#2680). Last comes the why chain (#4023):
+ * each commit's work item, ci tag and release, and each release's gates and
+ * deploys.
  */
 import { resolve } from "node:path";
 import { formatError } from "../cli/format.js";
 import { intentRecord } from "./intent-record.js";
 import { intentGraph } from "./intent.js";
-const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 function edgesFrom(doc, from, kind) {
     return doc.edges.filter((e) => e.from === from && e.kind === kind);
@@ -157,6 +159,48 @@ export function whyLines(doc, why) {
         out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
     return out;
 }
+const gateLabel = (g) => `${g.op}/${g.gate}${g.environment ? ` ${g.environment}` : ""}: ${g.empty ? "passed over an empty change set" : `${g.resolvedBy}${g.relayedBy ? ` relayed by ${g.relayedBy}` : ""}`}${g.channel ? ` on ${g.channel}` : ""} at ${g.at}${g.planDigest ? `, plan ${g.planDigest.slice(0, 24)}${g.changeSet ? " (change set stored)" : ""}` : ""}${g.sealed ? ", sealed" : ""}`;
+/**
+ * The why chain (#4023), in its order: for each commit that names a work item
+ * or was tagged, released or deployed, a line; then each release with its
+ * cuts, gates and deploys, and the deploys of no release.
+ */
+export function traceLines(trace) {
+    const out = [];
+    const label = (digest) => trace.releases.find((r) => r.releaseDigest === digest)?.label ?? digest.slice(0, 24);
+    for (const c of trace.commits) {
+        const parts = [];
+        if (c.work && c.work.state !== "unlinked")
+            parts.push(c.work.state === "linked" ? `work ${c.work.items.map((w) => `${w.id} (${w.source.field})`).join(", ") || "by a lease not checked"}` : `work ${c.work.state}`);
+        if (c.windowMatches.length > 0)
+            parts.push(`in the window of ${c.windowMatches.map((w) => w.id).join(", ")}`);
+        if (c.tag.state !== "none")
+            parts.push(c.tag.state);
+        for (const r of c.releases)
+            parts.push(`${r.link === "cut-from" ? "released as" : "shipped in"} ${label(r.release)}`);
+        for (const d of c.deploys)
+            parts.push(`${d.env} since ${trace.deploys.find((x) => x.id === d.deploy)?.timestamp ?? "?"}`);
+        if (parts.length > 0)
+            out.push(`trace     ${short(c.sha)} ${parts.join("; ")}`);
+    }
+    for (const r of trace.releases) {
+        const cut = r.cuts[0];
+        out.push(`release   ${r.label ?? r.releaseDigest.slice(0, 24)} from ${short(r.commit)}, ${r.tag.state}${cut ? `; cut by ${cut.actor} at ${cut.timestamp}${cut.signed ? ", signed" : ""}` : ""}`);
+        for (const g of r.gates)
+            out.push(`  gate      ${gateLabel(g)}`);
+        for (const id of r.deploys) {
+            const d = trace.deploys.find((x) => x.id === id);
+            if (d)
+                out.push(`  deploy    ${d.env} ${d.component} at ${d.timestamp} by ${d.actor}${d.admittedBy ? `, admitted by ${d.admittedBy.op}/${d.admittedBy.gate} (${d.admittedBy.resolvedBy})` : ""}`);
+        }
+    }
+    for (const d of trace.deploys.filter((x) => x.release === null)) {
+        out.push(`deploy    ${d.env} ${d.component} at ${d.timestamp} by ${d.actor} from ${short(d.gitSha)}, no release${d.admittedBy ? `; admitted by ${gateLabel(d.admittedBy)}` : ""}${d.plan ? `; plan ${d.plan.document.digest.slice(0, 24)}` : ""}`);
+    }
+    for (const x of trace.reasons)
+        out.push(`reason    ${x.code}: ${x.message}`);
+    return out;
+}
 /** The walk as text, one line each, in the order of #2650 section B. */
 export function formatIntent(doc) {
     const out = [];
@@ -165,7 +209,10 @@ export function formatIntent(doc) {
         const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
         const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
         const symbol = region.symbol ? `#${region.symbol.name} (${region.symbol.kind} ${region.symbol.qualified}, lines ${region.lines ? span(region.lines) : "none"})` : lines;
-        out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+        if (region.commit)
+            out.push(`region    commit ${short(region.commit)} (member ${region.member ?? "none"}) ${doc.at ? `at ${short(doc.at)}` : "in the working tree"}`);
+        else
+            out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
     }
     const files = ofKind(doc, "file");
     if (files.length > 0)
@@ -190,6 +237,8 @@ export function formatIntent(doc) {
         out.push(`reason    ${r.code}: ${r.message}`);
     if (doc.why)
         out.push(...whyLines(doc, doc.why));
+    if (doc.trace)
+        out.push(...traceLines(doc.trace));
     const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
     const work = ofKind(doc, "work").length;
     out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
@@ -245,7 +294,7 @@ export async function runWorkspaceIntent(ctx, cwd) {
         return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
     }
     if (!args.intent) {
-        console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end or path#symbol", hint: USAGE }));
+        console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end, path#symbol, a graph node id or a commit sha", hint: USAGE }));
         return 1;
     }
     // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).