@intentius/chant 0.124.46 → 0.124.48

package/dist/workspace/records-cli.js

@@ -35,6 +35,7 @@ import { locateWorkspace } from "./which-chant.js";
 import { computeQuorum, DEFAULT_QUORUM, loadRecordKind, normalisePrincipal, readRecords, readSessionSubjects, RECORD_SEAL_FIELD, RecordReadError, } from "./records.js";
 import { readCheckoutHead, worktreeStates } from "./records-checkout.js";
 import { lastWriteReader } from "./write-lock.js";
+import { FilterError, matchesWhere, parseWhere } from "../read-filter.js";
 function readTextOrNull(file) {
     try {
         return readFileSync(file, "utf-8");
@@ -51,7 +52,7 @@ import { returnedPolicy } from "./trust/policy.js";
 export const RECORDS_CONTRACT_VERSION = 1;
 /** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
-const USAGE = "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
+const USAGE = "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--where <field><op><value>]... [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -500,8 +501,13 @@ export async function runWorkspaceRecords(ctx) {
         console.error(formatError({ message: pairing, hint: USAGE }));
         return 1;
     }
+    const filter = recordsWhere(args);
+    if ("error" in filter) {
+        console.error(formatError({ message: filter.error, hint: USAGE }));
+        return 1;
+    }
     if (!args.kind)
-        return runDeclaredRecords(args);
+        return runDeclaredRecords(args, filter.clauses);
     if (args.require !== undefined && args.require !== "attested") {
         console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
         return 1;
@@ -522,7 +528,7 @@ export async function runWorkspaceRecords(ctx) {
             console.log(formatSince(since));
         return "error" in since ? 1 : 0;
     }
-    const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+    const doc = filterRecordsDocument(await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true }), filter.clauses, args.where ?? []);
     if (args.json) {
         console.log(JSON.stringify(doc, null, 2));
     }
@@ -563,7 +569,7 @@ export async function runWorkspaceRecords(ctx) {
  * declaration-level code the schema doesn't carry (`declaration-invalid` and
  * the rest of `WorkspaceErrorCode`) still prints text on stderr only.
  */
-async function runDeclaredRecords(args) {
+async function runDeclaredRecords(args, clauses = []) {
     if (args.require !== undefined && args.require !== "attested") {
         console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
         return 1;
@@ -590,7 +596,9 @@ async function runDeclaredRecords(args) {
     }
     if (args.since !== undefined)
         return runDeclaredSince(declared, args);
-    const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+    const read = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+    // The spec stays the whole current spec; --where narrows only the records each kind lists.
+    const set = { ...read, kinds: read.kinds.map((k) => filterRecordsDocument(k, clauses, args.where ?? [])) };
     if (args.json)
         console.log(JSON.stringify(set, null, 2));
     for (const doc of args.json ? [] : set.kinds) {
@@ -663,6 +671,50 @@ export function belowRequired(records, required) {
     return records.filter((r) => r.provenance.level !== required);
 }
 /** Why `--uncommitted` can't be given with the other flags given, or undefined when it can (#3160). */
+/**
+ * The fields `records --where` filters on (#4363). `data` is the record's
+ * own fields, so `data.<key>` names any of them.
+ */
+export const RECORD_FILTER_FIELDS = {
+    id: "text",
+    path: "text",
+    state: "text",
+    valid: "boolean",
+    supersededBy: "text",
+    digest: "text",
+    ready: "boolean",
+    attested: "boolean",
+    worktree: "text",
+    ledger: "text",
+    "provenance.level": "text",
+    data: "json",
+};
+/** Keep the records every clause matches, counting `summary` over the records listed. A failure is left as it is. */
+export function filterRecordsDocument(doc, clauses, where) {
+    if (where.length === 0 || "error" in doc)
+        return doc;
+    const records = doc.records.filter((r) => matchesWhere(r, clauses));
+    return {
+        ...doc,
+        records,
+        summary: { ...doc.summary, total: records.length, valid: records.filter((r) => r.valid).length, invalid: records.filter((r) => !r.valid).length },
+        where: [...where],
+    };
+}
+/** The `--where` clauses, or a message for a person. */
+function recordsWhere(args) {
+    const where = args.where ?? [];
+    if (where.length > 0 && args.since !== undefined)
+        return { error: "--where filters a records read and takes no --since: --since compares two revisions" };
+    try {
+        return { clauses: parseWhere(where, RECORD_FILTER_FIELDS) };
+    }
+    catch (err) {
+        if (err instanceof FilterError)
+            return { error: err.message };
+        throw err;
+    }
+}
 function uncommittedPairing(args) {
     if (!args.uncommitted)
         return undefined;

package/dist/workspace/records.schema.json

@@ -152,6 +152,11 @@
           "description": "Added in contract 1 by #2683, for a work kind only. Every decision the kind file named in the work kind's work.decisions reads at the same revision, whether or not a work record names it, each with the work records implementing it. A decision with an empty implementedBy has no work item yet.",
           "type": "array",
           "items": { "$ref": "#/$defs/decisionWork" }
+        },
+        "where": {
+          "description": "Added in contract 1 by #4363. Each --where clause, <field><op><value>, as given; every one held for each record listed, and summary's total, valid and invalid count the records listed. Absent without --where.",
+          "type": "array",
+          "items": { "type": "string" }
         }
       },
       "allOf": [

package/dist/workspace/release-candidates.d.ts

@@ -135,6 +135,8 @@ export interface ReleaseCandidatesQuery {
     /** Only this environment's view: the walk stops at what it runs, and `newFor` names only it. */
     env?: string;
     limit?: number;
+    /** Walk this branch of `ci.green.branch` (#4325) instead of the first. */
+    branch?: string;
 }
 /** The work ids and `<kind>:<id>` records a commit's `Chant-Record` trailers name. */
 export declare function recordTrailers(trailers: Record<string, string[]>): {

package/dist/workspace/release-candidates.d.ts.map

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

package/dist/workspace/release-candidates.js

@@ -38,7 +38,7 @@ import { latestPerComponent, readReleaseLedger } from "../lifecycle/release-ledg
 import { readAllReleases, readCuts } from "../lifecycle/release-store.js";
 import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
 import { readBlobFromPath } from "../lifecycle/git.js";
-import { readerVersion } from "./declaration.js";
+import { greenBranches, readerVersion } from "./declaration.js";
 export const RELEASE_CANDIDATES_CONTRACT_VERSION = 1;
 export const RELEASE_CANDIDATES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json";
 /** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
@@ -113,7 +113,10 @@ export async function releaseCandidatesDocument(query) {
         const { commitDetails } = await import("./intent.js");
         const source = scopeSource(cwd);
         const green = source.declaration?.ci?.green ?? null;
-        const trunk = resolveTrunk(top, green?.branch ?? null);
+        if (query.branch !== undefined && !(green && greenBranches(green).includes(query.branch))) {
+            throw new Error(`--branch ${query.branch} is not a branch ci.green judges${green ? ` (${greenBranches(green).join(", ")})` : ", and the declaration has no ci.green"}`);
+        }
+        const trunk = resolveTrunk(top, query.branch ?? green?.branch ?? null);
         const tip = tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${trunk.remote}/${trunk.branch}^{commit}`]) ??
             tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk.branch}^{commit}`]);
         const ledger = await resolveMemberLedger(cwd);

package/dist/workspace/release-train.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Release trains (#2554, #2524 D19, ws-043): one record that pins a release
+ * of every `chant` member, so several members move together.
+ *
+ * Releases stay per member (ws-043): each is a digest over its artifacts and
+ * a git commit, written to the member's own ledger by `chant release cut`. A
+ * train names one of them per member: by default the newest cut release, or
+ * the one `--pin <member>=<label|digest>` picks. It refuses unless every
+ * `chant` member of the declaration has a release, so a train never leaves a
+ * member out. It is written to `_members/_workspace/<env>/trains.jsonl`.
+ */
+import type { CommandContext } from "../cli/registry.js";
+export interface TrainMember {
+    member: string;
+    releaseDigest: string;
+    /** The release's git commit. */
+    commit: string;
+    /** The label its newest cut gave it, or null. */
+    label: string | null;
+}
+export interface ReleaseTrainRecord {
+    version: 1;
+    id: string;
+    env: string;
+    timestamp: string;
+    actor: string;
+    /** Every `chant` member, by name. */
+    members: TrainMember[];
+}
+/** What one member offers a train: its releases, newest cut first. */
+export interface MemberReleases {
+    member: string;
+    releases: TrainMember[];
+}
+/**
+ * Pick each member's release, pure. `pins` maps a member to a label or a
+ * digest; a member with no pin takes its newest. Returns the members, or
+ * the problems that stop the train.
+ */
+export declare function pickTrain(members: readonly MemberReleases[], pins?: ReadonlyMap<string, string>): {
+    members: TrainMember[];
+} | {
+    problems: string[];
+};
+/** Every `chant` member's releases, newest cut first, read from its ledger. */
+export declare function readMemberReleases(cwd: string): Promise<MemberReleases[]>;
+export declare function readReleaseTrains(cwd: string, env: string): Promise<{
+    records: ReleaseTrainRecord[];
+    malformed: number;
+}>;
+export declare function appendReleaseTrain(cwd: string, record: ReleaseTrainRecord): Promise<string>;
+export declare function runWorkspaceTrain(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=release-train.d.ts.map

package/dist/workspace/release-train.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-train.d.ts","sourceRoot":"","sources":["../../src/workspace/release-train.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMtD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAID,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,EAAE,IAAI,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG;IAAE,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBhK;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB/E;AAOD,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAE/H;AAED,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjG;AAID,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAiD5E"}

package/dist/workspace/release-train.js

@@ -0,0 +1,134 @@
+/**
+ * Release trains (#2554, #2524 D19, ws-043): one record that pins a release
+ * of every `chant` member, so several members move together.
+ *
+ * Releases stay per member (ws-043): each is a digest over its artifacts and
+ * a git commit, written to the member's own ledger by `chant release cut`. A
+ * train names one of them per member: by default the newest cut release, or
+ * the one `--pin <member>=<label|digest>` picks. It refuses unless every
+ * `chant` member of the declaration has a release, so a train never leaves a
+ * member out. It is written to `_members/_workspace/<env>/trains.jsonl`.
+ */
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format.js";
+import { readAllReleases, readCuts } from "../lifecycle/release-store.js";
+import { readDeclaration, WorkspaceReadError } from "./declaration.js";
+import { locateWorkspace } from "./which-chant.js";
+import { appendWorkspaceLine, readWorkspaceLines } from "./workspace-ledger.js";
+const TRAINS_FILE = "trains.jsonl";
+/**
+ * Pick each member's release, pure. `pins` maps a member to a label or a
+ * digest; a member with no pin takes its newest. Returns the members, or
+ * the problems that stop the train.
+ */
+export function pickTrain(members, pins = new Map()) {
+    const problems = [];
+    const picked = [];
+    for (const name of pins.keys()) {
+        if (!members.some((m) => m.member === name))
+            problems.push(`--pin ${name}: not a chant member of the workspace`);
+    }
+    for (const m of members) {
+        const pin = pins.get(m.member);
+        const r = pin === undefined ? m.releases[0] : m.releases.find((x) => x.releaseDigest === pin || x.label === pin);
+        if (!r) {
+            problems.push(pin === undefined ? `member ${m.member} has no release; cut one with chant release cut in its directory` : `member ${m.member} has no release ${pin}`);
+            continue;
+        }
+        picked.push(r);
+    }
+    return problems.length > 0 ? { problems } : { members: picked };
+}
+/** Every `chant` member's releases, newest cut first, read from its ledger. */
+export async function readMemberReleases(cwd) {
+    const located = locateWorkspace(cwd);
+    const declaration = readDeclaration(located.tree, "", { rootChant: true });
+    const out = [];
+    for (const m of declaration.members) {
+        if (m.kind !== "chant")
+            continue;
+        const loc = { cwd: located.rootOnDisk, member: m.dir === "." ? "." : m.name };
+        const { releases } = await readAllReleases(loc);
+        const { cuts } = await readCuts(loc);
+        const newest = (digest) => cuts.filter((c) => c.releaseDigest === digest).map((c) => c.timestamp).sort().at(-1) ?? "";
+        const label = (digest) => cuts.filter((c) => c.releaseDigest === digest && c.label !== null).sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1)).at(-1)?.label ?? null;
+        const list = releases
+            .filter((r) => newest(r.releaseDigest) !== "")
+            .sort((a, b) => (newest(b.releaseDigest) < newest(a.releaseDigest) ? -1 : newest(b.releaseDigest) > newest(a.releaseDigest) ? 1 : 0))
+            .map((r) => ({ member: m.name, releaseDigest: r.releaseDigest, commit: r.commit, label: label(r.releaseDigest) }));
+        out.push({ member: m.name, releases: list });
+    }
+    return out;
+}
+function isTrain(v) {
+    const t = v;
+    return typeof t === "object" && t !== null && t.version === 1 && typeof t.id === "string" && typeof t.env === "string" && Array.isArray(t.members);
+}
+export async function readReleaseTrains(cwd, env) {
+    return readWorkspaceLines(cwd, env, TRAINS_FILE, isTrain);
+}
+export async function appendReleaseTrain(cwd, record) {
+    return appendWorkspaceLine(cwd, record.env, TRAINS_FILE, record, `Release train: ${record.env} ${record.id}`);
+}
+const USAGE = "chant workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json] | chant workspace train list <env> [--json]";
+export async function runWorkspaceTrain(ctx) {
+    const words = ctx.args.positionals ?? [];
+    const rest = words[0] === "train" ? words.slice(1) : words;
+    const listing = rest[0] === "list";
+    const env = listing ? rest[1] : rest[0];
+    if (!env) {
+        console.error(formatError({ message: "chant workspace train needs an environment", hint: USAGE }));
+        return 1;
+    }
+    const cwd = resolve(".");
+    try {
+        if (listing) {
+            const root = locateWorkspace(cwd).rootOnDisk;
+            const { records } = await readReleaseTrains(root, env);
+            if (ctx.args.json)
+                console.log(JSON.stringify({ env, trains: records }, null, 2));
+            else if (records.length === 0)
+                console.log(`No release train recorded for ${env}.`);
+            else
+                for (const t of records)
+                    console.log(`${t.timestamp}  ${t.id}  ${t.members.map((m) => `${m.member}@${m.label ?? m.releaseDigest.slice(0, 19)}`).join(" ")}`);
+            return 0;
+        }
+        const pins = new Map();
+        for (const p of ctx.args.pins ?? []) {
+            const at = p.indexOf("=");
+            if (at <= 0) {
+                console.error(formatError({ message: `--pin ${p}: expected <member>=<label|digest>`, hint: USAGE }));
+                return 1;
+            }
+            pins.set(p.slice(0, at), p.slice(at + 1));
+        }
+        const root = locateWorkspace(cwd).rootOnDisk;
+        const picked = pickTrain(await readMemberReleases(root), pins);
+        if ("problems" in picked) {
+            console.error(formatError({ message: `no release train for ${env}: every chant member needs a release`, hint: USAGE }));
+            for (const p of picked.problems)
+                console.error(`  ${p}`);
+            return 1;
+        }
+        const actor = ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+        const record = { version: 1, id: `train-${randomUUID()}`, env, timestamp: new Date().toISOString(), actor, members: picked.members };
+        if (!ctx.args.dryRun)
+            await appendReleaseTrain(root, record);
+        if (ctx.args.json)
+            console.log(JSON.stringify({ ...record, written: !ctx.args.dryRun }, null, 2));
+        else {
+            console.log(`${ctx.args.dryRun ? "Would record" : "Recorded"} release train ${record.id} for ${env}:`);
+            for (const m of record.members)
+                console.log(`  ${m.member.padEnd(24)} ${m.label ?? "(no label)"}  ${m.releaseDigest}  ${m.commit.slice(0, 12)}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: USAGE }));
+        return 1;
+    }
+}

package/dist/workspace/release-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAwDzE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CvG"}
+{"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAwDzE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CvG"}

package/dist/workspace/release-workflow.js

@@ -16,6 +16,7 @@
  * there: it costs nothing, and with it what the job uploads carries
  * provenance whether or not the group requires it.
  */
+import { ACTION_PINS, tagComments, usesRef } from "../action-pins.js";
 import { GENERATED_MARKER } from "../discovery/files.js";
 export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"];
 /** Where each forge's publish workflow is written, relative to the repository root. */
@@ -71,10 +72,10 @@ export function renderReleaseWorkflow(input) {
         "    runs-on: ubuntu-latest",
         ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
         "    steps:",
-        "      - uses: actions/checkout@v4",
+        `      - uses: ${usesRef(ACTION_PINS.checkout4)}`,
         "        with:",
         "          fetch-depth: 0",
-        "      - uses: actions/setup-node@v4",
+        `      - uses: ${usesRef(ACTION_PINS.setupNode4)}`,
         "        with:",
         "          node-version: 24",
         "          registry-url: https://registry.npmjs.org",
@@ -85,7 +86,7 @@ export function renderReleaseWorkflow(input) {
         ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
         `      - run: ${chant} release publish ${label} ${flags}`,
     ];
-    return `${lines.join("\n")}\n`;
+    return tagComments(`${lines.join("\n")}\n`);
 }
 /** The header that marks the file generated, naming the command that regenerates it. */
 export function releaseWorkflowHeader(command) {

package/dist/workspace/repo-ref.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Another repository's workspace, named by URL and pinned revision (#3168).
+ *
+ * A member of kind `repo` is read the way a nested `workspace` member is
+ * (./nested-graph.ts): through that repository's own `chant workspace graph`,
+ * at the pinned revision, and nothing is ever written there. To have a tree
+ * to run that read in, chant fetches the revision into the user's cache
+ * directory, never under the workspace: one clone per URL, and one detached
+ * worktree per revision, which is immutable once made, so two reads of one
+ * revision share it and a read never moves another's checkout.
+ *
+ * This is the only place `chant workspace graph` reaches a remote, and only
+ * for repo members. `chant workspace check` never fetches.
+ *
+ * The read contract's identity names the repository a document came from
+ * (`workspace.repo`): the URL of the `origin` remote, credentials removed.
+ */
+import type { RepoRef } from "./declaration.js";
+/** A URL with any user name and password removed; scp-style and local paths are returned as they are. */
+export declare function redactUrl(url: string): string;
+/**
+ * The repository a workspace on disk came from (#3168): its git repository's
+ * `origin` URL, redacted, or null without git or an origin. Reads local git
+ * config only; never reaches the remote.
+ */
+export declare function repoIdentity(dir: string): string | null;
+/** Where fetched repositories live: `<cache>/repos`, with the cache dir as the graph cache finds it. */
+export declare function repoCacheDir(env?: NodeJS.ProcessEnv): string;
+/** The URL git is handed: a relative local path is resolved from the workspace root, since git runs in the cache. */
+export declare function fetchUrl(url: string, workspaceRoot: string): string;
+export type RepoFetch = {
+    ok: true;
+    dir: string;
+    worktree: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Make `ref`'s revision available in the cache, fetching it when the cache
+ * doesn't hold it, and return the directory of its workspace root there.
+ * Never throws; a failure says why.
+ */
+export declare function fetchRepoAt(ref: RepoRef, workspaceRoot: string, env?: NodeJS.ProcessEnv): RepoFetch;
+//# sourceMappingURL=repo-ref.d.ts.map

package/dist/workspace/repo-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-ref.d.ts","sourceRoot":"","sources":["../../src/workspace/repo-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,yGAAyG;AACzG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAW7C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvD;AAED,wGAAwG;AACxG,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGzE;AAED,qHAAqH;AACrH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAInE;AAED,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAcrG;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAyBhH"}

package/dist/workspace/repo-ref.js

@@ -0,0 +1,114 @@
+/**
+ * Another repository's workspace, named by URL and pinned revision (#3168).
+ *
+ * A member of kind `repo` is read the way a nested `workspace` member is
+ * (./nested-graph.ts): through that repository's own `chant workspace graph`,
+ * at the pinned revision, and nothing is ever written there. To have a tree
+ * to run that read in, chant fetches the revision into the user's cache
+ * directory, never under the workspace: one clone per URL, and one detached
+ * worktree per revision, which is immutable once made, so two reads of one
+ * revision share it and a read never moves another's checkout.
+ *
+ * This is the only place `chant workspace graph` reaches a remote, and only
+ * for repo members. `chant workspace check` never fetches.
+ *
+ * The read contract's identity names the repository a document came from
+ * (`workspace.repo`): the URL of the `origin` remote, credentials removed.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { CACHE_DIR_ENV } from "./graph-cache.js";
+import { urlCredential } from "./checks/org.js";
+/** A URL with any user name and password removed; scp-style and local paths are returned as they are. */
+export function redactUrl(url) {
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url))
+        return url;
+    try {
+        const u = new URL(url);
+        if (u.username === "" && u.password === "")
+            return url;
+        u.username = "";
+        u.password = "";
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * The repository a workspace on disk came from (#3168): its git repository's
+ * `origin` URL, redacted, or null without git or an origin. Reads local git
+ * config only; never reaches the remote.
+ */
+export function repoIdentity(dir) {
+    try {
+        const url = execFileSync("git", ["-C", dir, "config", "--get", "remote.origin.url"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return url ? redactUrl(url) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Where fetched repositories live: `<cache>/repos`, with the cache dir as the graph cache finds it. */
+export function repoCacheDir(env = process.env) {
+    const base = env[CACHE_DIR_ENV] || join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "chant");
+    return join(base, "repos");
+}
+/** The URL git is handed: a relative local path is resolved from the workspace root, since git runs in the cache. */
+export function fetchUrl(url, workspaceRoot) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url))
+        return url;
+    if (/^(?:[^@/\s]+@)?[^:/\s]+:(?!\/\/)/.test(url) && !isAbsolute(url) && !/^[a-z]:[\\/]/i.test(url))
+        return url;
+    return resolve(workspaceRoot, url);
+}
+const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+function git(args, cwd) {
+    try {
+        const out = execFileSync("git", args, { cwd, encoding: "utf-8", env: GIT_ENV, stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+        return { ok: true, out };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, out: String(e.stderr ?? e.message).trim().split("\n").slice(-3).join("; ") };
+    }
+}
+/**
+ * Make `ref`'s revision available in the cache, fetching it when the cache
+ * doesn't hold it, and return the directory of its workspace root there.
+ * Never throws; a failure says why.
+ */
+export function fetchRepoAt(ref, workspaceRoot, env = process.env) {
+    if (urlCredential(ref.url))
+        return { ok: false, message: `the repo url carries a credential, which chant refuses to use (WSP016)` };
+    const url = fetchUrl(ref.url, workspaceRoot);
+    const clone = join(repoCacheDir(env), createHash("sha256").update(url).digest("hex").slice(0, 24));
+    const worktree = join(clone, "at", ref.rev);
+    const dir = ref.workspace === "." ? worktree : join(worktree, ...ref.workspace.split("/"));
+    if (existsSync(join(worktree, ".git")))
+        return { ok: true, dir, worktree };
+    if (!existsSync(join(clone, ".git"))) {
+        mkdirSync(clone, { recursive: true });
+        const init = git(["init", "-q", clone]);
+        if (!init.ok)
+            return { ok: false, message: `could not make the cache clone in ${clone}: ${init.out}` };
+        git(["-C", clone, "remote", "add", "origin", url]);
+    }
+    const has = () => git(["-C", clone, "cat-file", "-e", `${ref.rev}^{commit}`]).ok;
+    if (!has()) {
+        // A pinned commit by id first; a server that refuses unadvertised ids gets a full fetch.
+        const byId = git(["-C", clone, "fetch", "-q", "origin", ref.rev]);
+        if (!has()) {
+            const all = git(["-C", clone, "fetch", "-q", "origin", "+refs/heads/*:refs/remotes/origin/*", "+refs/tags/*:refs/tags/*"]);
+            if (!has())
+                return { ok: false, message: `could not fetch ${ref.rev} from ${redactUrl(ref.url)}: ${all.ok ? (byId.ok ? "the repository has no such commit" : byId.out) : all.out}` };
+        }
+    }
+    const add = git(["-C", clone, "worktree", "add", "-q", "--detach", worktree, ref.rev]);
+    if (!add.ok && !existsSync(join(worktree, ".git")))
+        return { ok: false, message: `could not check out ${ref.rev} in the cache: ${add.out}` };
+    return { ok: true, dir, worktree };
+}

package/dist/workspace/run-event.schema.json

@@ -296,8 +296,8 @@
             "resolvedBy": { "type": "string", "description": "Who approved it." },
             "resolvedAt": { "type": "string", "description": "When the approval was recorded, ISO-8601." },
             "via": {
-              "enum": ["quorum", "policy", "point", "alias", "empty", null],
-              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it."
+              "enum": ["quorum", "policy", "point", "alias", "empty", "workspace", null],
+              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it. workspace (added within contract 1 by #2554, chant 0.124.47 and newer): a workspace gate's approval stood in for this member gate, because the member opts in at base and the approval covers this plan."
             },
             "url": { "type": "string", "description": "Where the approval was made, when known." }
           }

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

@@ -23,6 +23,7 @@
  */
 import type { CommandContext } from "../cli/registry.js";
 import { type RunLedgerWrite, type RunView } from "./runs.js";
+import { type FilterFields } from "../read-filter.js";
 import { type DsseEnvelope } from "./trust/dsse.js";
 import { type BaseSource } from "./trust/provenance.js";
 import type { TrustPolicy } from "./trust/policy.js";
@@ -84,6 +85,13 @@ export interface RunsQuery {
     base?: string;
     /** Follow squash merges on HEAD to their pull requests' original commits, fetching missing pull request refs (#3035). */
     followSquash?: boolean;
+    /** Typed filters (#4363), each `<field><op><value>` over {@link RUN_FILTER_FIELDS}; every one has to hold. Applied before the totals. */
+    where?: readonly string[];
+}
+/** The fields `runs --where` filters on (#4363). */
+export declare const RUN_FILTER_FIELDS: FilterFields;
+/** Thrown for a `--where` that can't be applied: a usage error, before the ledger is read. */
+export declare class RunsFilterError extends Error {
 }
 export interface RunsReason {
     code: RunsReasonCode;
@@ -129,6 +137,7 @@ export type RunsDocument = {
         by: string | null;
         since: string | null;
         followSquash?: boolean;
+        where?: string[];
     };
     /** The trust policy the run statements are judged by (#3192). */
     trust: RunsTrust;