@intentius/chant 0.124.46 → 0.124.48

package/dist/workspace/workspace-gates.js

@@ -0,0 +1,140 @@
+/**
+ * Workspace gates (#2554, #2524 D17, ws-039).
+ *
+ * A workspace gate is one approval for a change across members. A run of
+ * `chant workspace run --gate <name>` whose member runs stop at their own
+ * gates records a pending fact under `_members/_workspace/_gates/<name>.jsonl`
+ * that lists each stopped member gate and the plan it waits on (a cover),
+ * with the digest of that list. `chant workspace run approve <name>` records
+ * an approval of one such digest.
+ *
+ * The rule (ws-039): a workspace gate never satisfies a member gate, unless
+ * both hold:
+ *
+ * 1. its approval's digest covers the member's plan: the approval lists the
+ *    member, the Op, the gate and the plan digest the member run reached it
+ *    with, and the list still hashes to the approval's digest;
+ * 2. the member opts in at base: its entry in `chant.workspace.json`, read
+ *    from the base revision as other policy is, sets
+ *    `acceptWorkspaceGates: true`. A declaration read only from the working
+ *    tree never opts a member in.
+ *
+ * A member run started under the gate (`CHANT_WORKSPACE_GATE`) asks this
+ * module through `GateCheckInput.workspace` after its own approvals have
+ * not passed the gate. Nothing is written to the member's gate ledger: the
+ * run's step record says `via: "workspace"` and names the workspace gate.
+ */
+import { samePlanDigest } from "../lifecycle/plan-digest.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { appendWorkspaceLine, canonicalDigest, readWorkspaceLines, WORKSPACE_GATES_DIR } from "./workspace-ledger.js";
+/** Covers in one order, so the same set always has the same digest. */
+export function sortCovers(covers) {
+    const key = (c) => `${c.member}\u0000${c.op}\u0000${c.gate}\u0000${c.environment ?? ""}\u0000${c.planDigest}`;
+    return [...covers]
+        .map((c) => ({ member: c.member, op: c.op, gate: c.gate, planDigest: c.planDigest, ...(c.environment !== undefined ? { environment: c.environment } : {}) }))
+        .sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+/** The digest a workspace gate's pending fact and approval carry: the member plans it covers. */
+export function workspaceGateDigest(covers) {
+    return canonicalDigest(sortCovers(covers));
+}
+/**
+ * The rule of ws-039, pure: the newest approval that stands in for the
+ * member gate `q`, or null. Null whenever the member has not opted in.
+ */
+export function workspaceGateStandsIn(q, ctx) {
+    if (!ctx.optedIn)
+        return null;
+    const covering = ctx.approvals.filter((a) => 
+    // The covers must still hash to the digest that was approved.
+    workspaceGateDigest(a.covers) === a.digest &&
+        a.covers.some((c) => c.member === ctx.member && c.op === q.op && c.gate === q.gate &&
+            samePlanDigest(c.planDigest, q.planDigest) &&
+            (c.environment ?? null) === (q.environment ?? null)));
+    return covering.sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0)).at(-1) ?? null;
+}
+const fileFor = (gate) => `${gate}.jsonl`;
+function isCover(v) {
+    const c = v;
+    return typeof c === "object" && c !== null && typeof c.member === "string" && typeof c.op === "string" && typeof c.gate === "string" && typeof c.planDigest === "string";
+}
+function isGateLine(v) {
+    const l = v;
+    if (typeof l !== "object" || l === null || l.version !== 1 || typeof l.gate !== "string" || typeof l.digest !== "string" || typeof l.timestamp !== "string")
+        return false;
+    if (!Array.isArray(l.covers) || !l.covers.every(isCover))
+        return false;
+    if (l.kind === "pending")
+        return typeof l.run === "string";
+    if (l.kind === "approval")
+        return typeof l.approvedBy === "string";
+    return false;
+}
+/** A workspace gate's ledger, oldest first. */
+export async function readWorkspaceGate(cwd, gate) {
+    const { records, malformed } = await readWorkspaceLines(cwd, WORKSPACE_GATES_DIR, fileFor(gate), isGateLine);
+    return {
+        pending: records.filter((r) => r.kind === "pending"),
+        approvals: records.filter((r) => r.kind === "approval"),
+        malformed,
+    };
+}
+export async function appendWorkspaceGatePending(cwd, input) {
+    const covers = sortCovers(input.covers);
+    const record = { version: 1, kind: "pending", gate: input.gate, run: input.run, timestamp: input.timestamp, digest: workspaceGateDigest(covers), covers };
+    await appendWorkspaceLine(cwd, WORKSPACE_GATES_DIR, fileFor(input.gate), record, `Workspace gate pending: ${input.gate}`);
+    return record;
+}
+/**
+ * Approve a workspace gate's pending fact: the newest one, or the one whose
+ * digest is `digest`. The approval copies its covers. Throws when there is no
+ * such fact.
+ */
+export async function approveWorkspaceGate(cwd, input) {
+    const { pending } = await readWorkspaceGate(cwd, input.gate);
+    const candidates = input.digest === undefined ? pending : pending.filter((p) => p.digest === input.digest);
+    const fact = candidates.at(-1);
+    if (!fact) {
+        throw new Error(input.digest === undefined
+            ? `workspace gate "${input.gate}" has no pending fact to approve; a chant workspace run --gate ${input.gate} whose members stop at their gates records one`
+            : `workspace gate "${input.gate}" has no pending fact with digest ${input.digest}`);
+    }
+    const record = {
+        version: 1,
+        kind: "approval",
+        gate: input.gate,
+        digest: fact.digest,
+        covers: fact.covers,
+        approvedBy: input.approvedBy,
+        timestamp: input.timestamp,
+        ...(input.note ? { note: input.note } : {}),
+    };
+    await appendWorkspaceLine(cwd, WORKSPACE_GATES_DIR, fileFor(input.gate), record, `Workspace gate approval: ${input.gate}`);
+    return record;
+}
+/**
+ * Whether the member holding `cwd` opts in to workspace gates at base, and
+ * its name. A member of a nested workspace, the root member and a directory
+ * no member owns never opt in.
+ */
+export async function memberAcceptsWorkspaceGates(cwd) {
+    const ledger = await resolveMemberLedger(cwd);
+    if (ledger.members.length !== 1)
+        return { member: ledger.members.join("/") || null, accepts: false };
+    const member = ledger.members[0];
+    const { scopeSource } = await import("./write-scope.js");
+    const source = scopeSource(cwd);
+    if (source.from !== "base" || !source.declaration)
+        return { member, accepts: false };
+    const entry = source.declaration.members.find((m) => m.name === member);
+    return { member, accepts: entry?.acceptWorkspaceGates === true };
+}
+/** The stand-in a member run started under workspace gate `gate` asks (`GateCheckInput.workspace`). */
+export async function memberGateStandIn(cwd, gate, q) {
+    const { member, accepts } = await memberAcceptsWorkspaceGates(cwd);
+    if (!member || !accepts)
+        return null;
+    const { approvals } = await readWorkspaceGate(cwd, gate);
+    const found = workspaceGateStandsIn(q, { member, optedIn: accepts, approvals });
+    return found ? { gate, digest: found.digest, approvedBy: found.approvedBy, timestamp: found.timestamp } : null;
+}

package/dist/workspace/workspace-kinds.schema.json

@@ -46,7 +46,7 @@
         "name": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "The kind's name, as a member's kind field names it. chant, workspace, other and examples are built in and can't be supplied."
+          "description": "The kind's name, as a member's kind field names it. chant, workspace, repo, design, other and examples are built in and can't be supplied."
         },
         "description": {
           "type": "string",
@@ -82,7 +82,10 @@
         "reader": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "A link reader chant ships, by name, that derives a member's links from the member's own files (#3932): dbt-project reads a dbt project's sources. The reader is chant's code and runs offline, parsing files as data; the package supplies only the name. A name this chant doesn't have keeps the kind without a reader, and the load reports it. A chant older than this field fails a kinds file that uses it."
+          "description": "A link reader chant ships, by name, that derives a member's links from the member's own files (#3932): dbt-project reads a dbt project's sources; goose-dir, golang-migrate-dir, clickhouse-migrations-dir and flyway-dir list a migrations directory in order (#4400). The reader is chant's code and runs offline, parsing files as data; the package supplies only the name. A name this chant doesn't have keeps the kind without a reader, and the load reports it. A chant older than this field fails a kinds file that uses it."
+        },
+        "memberFile": {
+          "$ref": "#/$defs/memberFile"
         }
       },
       "patternProperties": {
@@ -159,13 +162,41 @@
             }
           },
           "additionalProperties": false
+        },
+        "anyLine": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, has a line that starts with one of starts, after leading space and ignoring case (#4400). A goose directory is found by -- +goose Up. Added by the chant that adds the goose-dir reader.",
+          "required": [
+            "in",
+            "starts"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "starts": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
     },
     "fileName": {
       "type": "string",
-      "description": "A file name, with no directory part. A * matches any run of characters.",
+      "description": "A file name, with no directory part. A * matches any run of characters, and [0-9] one digit.",
       "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
     },
     "graph": {
@@ -281,6 +312,30 @@
         }
       },
       "additionalProperties": false
+    },
+    "memberFile": {
+      "type": "object",
+      "description": "A file every member of this kind has, and the JSON Schema it must pass (#3672). chant workspace check reads the file from the member's directory, parses it as YAML when its name ends in .yml or .yaml and as JSON otherwise, and validates it against the schema (WSP012). The schema is a JSON file inside the supplying package, read as data with draft 2020-12. A chant older than this field fails a kinds file that uses it.",
+      "required": [
+        "path",
+        "schema"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "The file, relative to the member's directory, such as terragucci.yml. Forward slashes; no .. segment and no leading /.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.?(/|$))[^\\\\]+$"
+        },
+        "schema": {
+          "type": "string",
+          "description": "The JSON Schema the file must pass, relative to the supplying package's directory, such as schemas/terragucci.schema.json. It must be a .json file inside the package.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.?(/|$))[^\\\\]+\\.json$"
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     }
   }
 }

package/dist/workspace/workspace-ledger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The workspace's own ledger (#2554, #2524 D17, ws-030): `_members/_workspace/`
+ * on the `chant/lifecycle` branch, beside every member's `_members/<member>/`.
+ * `_workspace` is a reserved member name, so no member writes here.
+ *
+ * Three stores, each a JSON Lines file appended with the read-modify-write
+ * and CAS retry every ledger here uses:
+ *
+ * - `<env>/runs.jsonl`: one record per `chant workspace run`, naming every
+ *   `<member>/<op>` step, how it ended, and the member run it started. Each
+ *   member run cites the workspace run back (`OpRunRecord.workspaceRun`).
+ * - `_gates/<gate>.jsonl`: a workspace gate's pending facts and approvals.
+ *   Each names the member plans it covers and their digest
+ *   (`./workspace-gates.ts`).
+ * - `<env>/trains.jsonl`: release trains, each pinning one release of every
+ *   `chant` member (`./release-train.ts`).
+ *
+ * A malformed line is skipped and counted, never thrown on.
+ */
+/** The reserved member name the workspace's own ledger sits under. */
+export declare const WORKSPACE_LEDGER_NAME = "_workspace";
+/** The branch prefix of the workspace's ledger. */
+export declare const WORKSPACE_LEDGER_PREFIX = "_members/_workspace/";
+/** The environment directory a run with no `--env` records under, as a member Op run does. */
+export declare const DEFAULT_WORKSPACE_ENV = "local";
+export declare const WORKSPACE_GATES_DIR = "_gates";
+/** Append one line to `<dir>/<file>` in the workspace ledger. Returns the ledger commit. */
+export declare function appendWorkspaceLine(cwd: string, dir: string, file: string, value: unknown, message: string): Promise<string>;
+/** Read every line of `<dir>/<file>` that `accept` takes, oldest first. */
+export declare function readWorkspaceLines<T>(cwd: string, dir: string, file: string, accept: (v: unknown) => v is T): Promise<{
+    records: T[];
+    malformed: number;
+}>;
+/** `sha256:<hex>` over a value's canonical JSON (keys sorted). */
+export declare function canonicalDigest(value: unknown): string;
+/** How one `<member>/<op>` step of a workspace run ended. */
+export type WorkspaceStepStatus = "ok" | "fail" | "gated" | "not-run";
+export interface WorkspaceRunStep {
+    /** `<member>/<op>`. */
+    target: string;
+    member: string;
+    op: string;
+    status: WorkspaceStepStatus;
+    /** The member's `chant run` exit code; null for a step that did not run. */
+    exitCode: number | null;
+    /** The member run's id, read back from the member's run ledger, where it cites this run. Null when none was found. */
+    memberRun: string | null;
+    /** For a gated step: the member gate it stopped at and the plan it waits on. */
+    gate?: {
+        op: string;
+        name: string;
+        planDigest: string | null;
+        environment: string | null;
+    };
+}
+export interface WorkspaceRunRecord {
+    version: 1;
+    id: string;
+    started: string;
+    ended: string;
+    /** `gated` when a step stopped at a gate; `fail` when a step failed. A run stops at the first step that does not pass. */
+    status: "ok" | "fail" | "gated";
+    /** `--env`, or null. */
+    env: string | null;
+    /** The workspace gate the run was started under (`--gate`), or null. */
+    gate: string | null;
+    /** `--dependents-of`, the member whose dependents the run ran, or null. */
+    dependentsOf: string | null;
+    steps: WorkspaceRunStep[];
+}
+export declare function appendWorkspaceRun(cwd: string, record: WorkspaceRunRecord): Promise<string>;
+export declare function readWorkspaceRuns(cwd: string, env?: string): Promise<{
+    records: WorkspaceRunRecord[];
+    malformed: number;
+}>;
+//# sourceMappingURL=workspace-ledger.d.ts.map

package/dist/workspace/workspace-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-ledger.d.ts","sourceRoot":"","sources":["../../src/workspace/workspace-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAClD,mDAAmD;AACnD,eAAO,MAAM,uBAAuB,yBAA6C,CAAC;AAClF,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAC7C,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAQ5C,4FAA4F;AAC5F,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAelI;AAED,2EAA2E;AAC3E,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBhK;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAID,6DAA6D;AAC7D,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,mBAAmB,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sHAAsH;IACtH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC5F;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,0HAA0H;IAC1H,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,wBAAwB;IACxB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AASD,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjG;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAA8B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvJ"}

package/dist/workspace/workspace-ledger.js

@@ -0,0 +1,91 @@
+/**
+ * The workspace's own ledger (#2554, #2524 D17, ws-030): `_members/_workspace/`
+ * on the `chant/lifecycle` branch, beside every member's `_members/<member>/`.
+ * `_workspace` is a reserved member name, so no member writes here.
+ *
+ * Three stores, each a JSON Lines file appended with the read-modify-write
+ * and CAS retry every ledger here uses:
+ *
+ * - `<env>/runs.jsonl`: one record per `chant workspace run`, naming every
+ *   `<member>/<op>` step, how it ended, and the member run it started. Each
+ *   member run cites the workspace run back (`OpRunRecord.workspaceRun`).
+ * - `_gates/<gate>.jsonl`: a workspace gate's pending facts and approvals.
+ *   Each names the member plans it covers and their digest
+ *   (`./workspace-gates.ts`).
+ * - `<env>/trains.jsonl`: release trains, each pinning one release of every
+ *   `chant` member (`./release-train.ts`).
+ *
+ * A malformed line is skipped and counted, never thrown on.
+ */
+import { createHash } from "node:crypto";
+import { readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeBlobToPath } from "../lifecycle/git.js";
+import { MEMBERS_DIR } from "../lifecycle/member-ledger.js";
+import { sortedJsonReplacer } from "../utils.js";
+/** The reserved member name the workspace's own ledger sits under. */
+export const WORKSPACE_LEDGER_NAME = "_workspace";
+/** The branch prefix of the workspace's ledger. */
+export const WORKSPACE_LEDGER_PREFIX = `${MEMBERS_DIR}/${WORKSPACE_LEDGER_NAME}/`;
+/** The environment directory a run with no `--env` records under, as a member Op run does. */
+export const DEFAULT_WORKSPACE_ENV = "local";
+export const WORKSPACE_GATES_DIR = "_gates";
+const APPEND_RETRY_ATTEMPTS = 5;
+function at(cwd) {
+    return { cwd, ledgerPrefix: WORKSPACE_LEDGER_PREFIX };
+}
+/** Append one line to `<dir>/<file>` in the workspace ledger. Returns the ledger commit. */
+export async function appendWorkspaceLine(cwd, dir, file, value, message) {
+    const json = JSON.stringify(value, sortedJsonReplacer);
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const priorSha = await readPathSha(dir, file, at(cwd));
+            const existing = priorSha ? await readBlobBySha(priorSha, { cwd }) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+            return await writeBlobToPath(dir, file, content, message, { ...at(cwd), expectPriorPathSha: priorSha });
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/** Read every line of `<dir>/<file>` that `accept` takes, oldest first. */
+export async function readWorkspaceLines(cwd, dir, file, accept) {
+    const content = await readBlobFromPath(dir, file, at(cwd));
+    if (!content)
+        return { records: [], malformed: 0 };
+    const records = [];
+    let malformed = 0;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const v = JSON.parse(line);
+            if (accept(v))
+                records.push(v);
+            else
+                malformed++;
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { records, malformed };
+}
+/** `sha256:<hex>` over a value's canonical JSON (keys sorted). */
+export function canonicalDigest(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify(value, sortedJsonReplacer)).digest("hex")}`;
+}
+const RUNS_FILE = "runs.jsonl";
+function isRunRecord(v) {
+    const r = v;
+    return typeof r === "object" && r !== null && r.version === 1 && typeof r.id === "string" && Array.isArray(r.steps);
+}
+export async function appendWorkspaceRun(cwd, record) {
+    return appendWorkspaceLine(cwd, record.env ?? DEFAULT_WORKSPACE_ENV, RUNS_FILE, record, `Workspace run record: ${record.id}`);
+}
+export async function readWorkspaceRuns(cwd, env = DEFAULT_WORKSPACE_ENV) {
+    return readWorkspaceLines(cwd, env, RUNS_FILE, isRunRecord);
+}

package/dist/workspace/workspace-run.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `chant workspace run` (#2554, #2524 D17, ws-030): Ops that span members.
+ *
+ * A workspace run names `<member>/<op>` targets, or asks for the dependents
+ * of one member with `--dependents-of <member> --op <op>`. It:
+ *
+ * 1. reads every member's graph under the member's own toolchain, as
+ *    `chant workspace graph` does (`readMembers` in `./graph-cli.ts`), and
+ *    turns each composed member into a build root for the cross-root mode of
+ *    post-synth checks (#1939): its graph nodes, Ops among them, become the
+ *    root's entities;
+ * 2. runs OPS019 over those roots, so every target names a composed member
+ *    and an Op it declares, and runs nothing when one doesn't;
+ * 3. orders the targets so a producer runs before the members that link to
+ *    it (the declared and inferred member links of the composed graph), and
+ *    otherwise keeps the order given;
+ * 4. runs each target's `chant run <op>` in the member's directory under the
+ *    member's toolchain, one at a time, stopping at the first that does not
+ *    pass. Each member run gets the workspace run's id in its environment
+ *    (`CHANT_WORKSPACE_RUN`), and its run record cites it;
+ * 5. writes the workspace run's record under `_members/_workspace/<env>/`.
+ *
+ * With `--gate <name>`, member runs that stop at their own gates are
+ * gathered into one pending fact of the workspace gate `<name>`; see
+ * `./workspace-gates.ts` for when its approval stands in for theirs.
+ *
+ * `chant run` at a declared root is untouched: it runs the root's own Ops,
+ * and Op discovery leaves member directories out (#2527).
+ */
+import type { CommandContext } from "../cli/registry.js";
+import { type CrossRootInput, type PostSynthDiagnostic } from "../lint/post-synth.js";
+import { type WorkspaceOpTarget } from "../lint/rules/op/ops019-workspace-op-target.js";
+import type { WorkspaceGraph } from "./compose-graph.js";
+import { type WorkspaceRunRecord } from "./workspace-ledger.js";
+import { type WorkspaceGatePending } from "./workspace-gates.js";
+/**
+ * One build root per composed member (#1939's `CrossRootInput`): the member's
+ * graph nodes become its entities, keyed by the member's own ids, with their
+ * attributes as `props`. The member was read under its own toolchain, so
+ * this process builds nothing. Members that were skipped or failed have no root.
+ */
+export declare function crossRootInputs(graph: Pick<WorkspaceGraph, "members" | "nodes">, env?: string): CrossRootInput[];
+/** Producer to consumers, from the composed graph's member links (declared and inferred, any status but invalid). */
+export declare function memberDependents(links: WorkspaceGraph["links"]): Map<string, Set<string>>;
+/** Every member that links to `member`, directly or through others, nearest first. */
+export declare function dependentsOf(member: string, links: WorkspaceGraph["links"]): string[];
+/**
+ * Order targets so a producer's targets run before its consumers', keeping
+ * the given order otherwise. A cycle among the targets' members keeps the
+ * given order for the members in it.
+ */
+export declare function orderTargets(targets: readonly WorkspaceOpTarget[], links: WorkspaceGraph["links"]): WorkspaceOpTarget[];
+/** What a member's `chant run` answered. */
+export interface MemberOpResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface WorkspaceRunQuery {
+    cwd: string;
+    /** `<member>/<op>` targets. Empty with {@link dependentsOf}. */
+    targets: string[];
+    /** Run `op` in every member that links to this one, directly or not, and not in the member itself. */
+    dependentsOf?: string;
+    /** The Op `dependentsOf` runs. */
+    op?: string;
+    env?: string;
+    /** The workspace gate member gates may wait on together. */
+    gate?: string;
+    dryRun?: boolean;
+    /** Extra flags each member's `chant run` gets, such as `--on <lexicon>`. */
+    runArgs?: string[];
+    /** Overrides, for tests. */
+    readGraph?: (cwd: string) => Promise<{
+        graph: WorkspaceGraph;
+        failed: boolean;
+    } | {
+        error: string;
+    }>;
+    runMember?: (member: {
+        name: string;
+        dir: string;
+    }, argv: string[], env: Record<string, string>) => Promise<MemberOpResult>;
+    now?: () => string;
+    /** Where the member's output goes as each step ends. */
+    onOutput?: (target: string, result: MemberOpResult) => void;
+}
+/** A step a dependents run left out, and why. */
+export interface WorkspaceRunSkip {
+    member: string;
+    reason: string;
+}
+export type WorkspaceRunOutcome = {
+    kind: "refused";
+    message: string;
+    findings: PostSynthDiagnostic[];
+} | {
+    kind: "planned";
+    id: string;
+    targets: string[];
+    skipped: WorkspaceRunSkip[];
+} | {
+    kind: "ran";
+    record: WorkspaceRunRecord;
+    skipped: WorkspaceRunSkip[];
+    pending: WorkspaceGatePending | null;
+    ledgerError: string | null;
+};
+/** Plan and, unless `dryRun`, run a workspace run. Throws a {@link WorkspaceReadError} when the declaration can't be read. */
+export declare function workspaceRun(query: WorkspaceRunQuery): Promise<WorkspaceRunOutcome>;
+export declare function runWorkspaceRun(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=workspace-run.d.ts.map

package/dist/workspace/workspace-run.d.ts.map

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