@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/gate-ledger.js

@@ -0,0 +1,193 @@
+/**
+ * Gate resolution ledger (#1485, epic #1487) — the durable counterpart to a
+ * converge tick's gate-as-fact outcome (`./converge-ledger.ts`'s
+ * `ConvergeRuleOutcome.action === "gated"`). Same append-only, content-
+ * addressed shape as the converge/release ledgers, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly — one line per
+ * resolution at `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch.
+ *
+ * Keyed by op name rather than environment (`_gates`, not `<env>/gates...`)
+ * because a gate belongs to the *dispatched* op — the thing a converge
+ * rule's `run()` action names — and that op's own env, if it declares one at
+ * all, isn't always the calling `ConvergeOp`'s env. `writeBlobToPath`'s own
+ * doc already establishes this generic-namespace pattern
+ * (`./build-ledger-store.ts`'s `_builds`); this is the same move for a
+ * second non-env top-level directory.
+ *
+ * `chant approve <op> <gate>` (`../cli/handlers/operator.ts`) is what
+ * appends a resolution — issue #1485's "resolution is an out-of-band act
+ * that writes the counterpart fact". Per that issue's leaning on open
+ * question 3 ("local trust in v1, signature as an additive follow-up"),
+ * this record is *not* itself an authorization check — anyone who can run
+ * `chant approve` locally can write one, the same trust boundary a local
+ * commit already has.
+ *
+ * Since #2300 both halves also carry a plan identity (`./plan-digest.ts`): a
+ * run records the plan it reached the gate with, `chant approve` records the
+ * plan it approves, and {@link latestResolutionForPlan} matches on that
+ * rather than on recency alone. Before it, an approval authorised the next
+ * run of an op rather than the plan its approver had read
+ * (INTENTIUS/choudoufu#1026).
+ *
+ * Since #2119 the file carries both halves of the loop. A `gate` step the
+ * local executor reaches (`../op/local-executor.ts`) appends a
+ * {@link PendingGateRecord} and ends that run with status `gated`; `chant
+ * approve` appends the {@link GateResolutionRecord} that answers it; the next
+ * run reads both, finds a resolution newer than the pending fact, and walks
+ * through the gate carrying the approver. A resolution older than the newest
+ * pending fact is not an answer to it — {@link latestResolutionSince} applies
+ * that rule for the executor and for `chant operator status` alike. Both kinds
+ * of line share one file, told apart by {@link GateLedgerRecord}'s `kind`
+ * (absent on the resolution lines written before #2119, which is why
+ * `"resolution"` is the default reading).
+ */
+import { isNeverOverMcpGateOp } from "../op/gate-name.js";
+import { sortedJsonReplacer } from "../utils.js";
+import { currentGateOrigin } from "./gate-origin.js";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git.js";
+// The facts a pending record is written with live apart, so a bundle can import them without git (#3816).
+export { DEFAULT_GATE_EXPIRY, isApprovalUrl, resolveApprovalUrl } from "./gate-pending.js";
+// The selection rules a gate decides by live apart, so a bundle can import them without git (#3763).
+export { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, latestResolutionSince, } from "./gate-ledger-select.js";
+const DIR = "_gates";
+/** The directory on the `chant/lifecycle` branch that holds gate ledgers, under a member's prefix when it has one. */
+export const GATES_DIR = DIR;
+const APPEND_RETRY_ATTEMPTS = 5;
+function filename(op) {
+    return `${op}.jsonl`;
+}
+/**
+ * Where an Op's gate ledger lives, as a path a human can go and read:
+ * `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch. Exported so a
+ * renderer that tells someone a gate is pending can name the file the pending
+ * fact was appended to (#2243) rather than describing it in prose that drifts
+ * from `DIR`.
+ */
+export function gateLedgerPath(op, memberPrefix = "") {
+    return `${memberPrefix}${DIR}/${filename(op)}`;
+}
+/** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
+export async function appendGateResolution(input, opts) {
+    const record = { version: 1, ...input };
+    const commit = await appendGateLine(record, "Gate resolution record", opts);
+    return { commit, record };
+}
+/**
+ * Append one immutable pending-gate record (#2119) — the fact a run leaves
+ * behind when it reaches a gate nobody has approved. Same file, same
+ * append-and-retry discipline, same "does not push" contract as
+ * {@link appendGateResolution}.
+ */
+export async function appendPendingGate(input, opts) {
+    // chant#2384 — stamped here rather than at each caller, because every pending
+    // fact goes through this function and a channel is a property of the process
+    // rather than of the call. An explicit `origin` on the input still wins, so a
+    // caller that knows better can say so.
+    const record = {
+        version: 1,
+        kind: "pending",
+        origin: currentGateOrigin(),
+        // chant#3485: an Op MCP cannot discover declares nothing, so the gate
+        // records the rule for it: fan-out, workspace-upgrade (chant#3513) and
+        // the pull-request gate's `pr-<number>` op.
+        ...(isNeverOverMcpGateOp(input.op) ? { neverOverMcp: true } : {}),
+        ...input,
+    };
+    const commit = await appendGateLine(record, "Pending gate record", opts);
+    return { commit, record };
+}
+async function appendGateLine(record, message, opts) {
+    const json = JSON.stringify(record, sortedJsonReplacer);
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const priorSha = await readPathSha(DIR, filename(record.op), opts);
+            const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+            return await writeBlobToPath(DIR, filename(record.op), content, message, {
+                ...opts,
+                expectPriorPathSha: priorSha,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Read every line of `op`'s gate file, oldest first, split into the two kinds
+ * (#2119). Malformed lines are skipped and counted, not thrown on — the same
+ * graceful-degradation stance `readConvergeLedger` takes. Returns empty arrays
+ * (never throws) when `op` has nothing recorded yet.
+ */
+export async function readGateLedger(op, opts) {
+    const content = await readBlobFromPath(DIR, filename(op), opts);
+    if (!content)
+        return { resolutions: [], pending: [], malformed: 0 };
+    return parseGateLedger(content);
+}
+/**
+ * Split the text of one gate ledger file into its two kinds of line, oldest
+ * first, the way {@link readGateLedger} reads it. Exported for a reader that
+ * fetches the file itself, such as `chant workspace status` (#2674), which
+ * reads every member's ledger by its full path from the workspace root.
+ */
+export function parseGateLedger(content) {
+    const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+    const resolutions = [];
+    const pending = [];
+    let malformed = 0;
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            const common = parsed.version === 1 && typeof parsed.op === "string" &&
+                typeof parsed.gate === "string" && typeof parsed.timestamp === "string";
+            if (!common) {
+                malformed++;
+                continue;
+            }
+            // #2300: a `planDigest` that is present but not a string is a
+            // malformed line, not a line with a field to ignore. Ignoring it would
+            // silently demote a plan-bound record to a digest-less one, which is
+            // the shape `latestResolutionForPlan` refuses — a corrupted approval
+            // must not read as an approval of anything at all.
+            const rawDigest = parsed.planDigest;
+            if (rawDigest !== undefined && typeof rawDigest !== "string") {
+                malformed++;
+                continue;
+            }
+            // #2574: the same reasoning for the environment a component gate
+            // approval is bound to.
+            const rawEnv = parsed.environment;
+            if (rawEnv !== undefined && typeof rawEnv !== "string") {
+                malformed++;
+                continue;
+            }
+            if (parsed.kind === "pending") {
+                if (typeof parsed.expiresAt !== "string") {
+                    malformed++;
+                    continue;
+                }
+                pending.push(parsed);
+                continue;
+            }
+            if (typeof parsed.resolvedBy !== "string") {
+                malformed++;
+                continue;
+            }
+            resolutions.push(parsed);
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { resolutions, pending, malformed };
+}
+/** Read every gate-*resolution* record for `op`, oldest first — {@link readGateLedger} narrowed to the half every caller before #2119 wanted. Pending facts are not malformed lines and are not counted as such. */
+export async function readGateResolutions(op, opts) {
+    const { resolutions, malformed } = await readGateLedger(op, opts);
+    return { records: resolutions, malformed };
+}

package/dist/lifecycle/gate-origin.js

@@ -0,0 +1,117 @@
+/**
+ * Which channel a gate fact was authored on — chant#2384.
+ *
+ * The gate is the strongest thing chant says about agent-driven change: a run
+ * that reaches an unapproved gate records a pending fact and exits 3, and since
+ * #2300 a resolution counts only for the plan it names. That property rests on
+ * the two halves being authored by different parties.
+ *
+ * `gate-ledger.ts` already states the trust boundary, and is right about it:
+ *
+ * > this record is *not* itself an authorization check — anyone who can run
+ * > `chant approve` locally can write one, the same trust boundary a local
+ * > commit already has.
+ *
+ * That holds at a shell. A person who can run `chant approve` can also run
+ * `chant run`, and the ledger records what they did. It stops holding on MCP
+ * and ACP, because the person's only act was launching the server once; every
+ * call after that is authored by the model. `op-run` returns the gate it
+ * stopped on and `op-approve` resolves it, so the same caller writes both
+ * halves and the separation is gone.
+ *
+ * The ledger could not tell those situations apart, because both produce a
+ * `resolvedBy` string with no record of where it came from. This records the
+ * where.
+ *
+ * ## Why an ambient value rather than a parameter
+ *
+ * A channel is a property of the process, not of a call. A `chant mcp` server
+ * is launched once by a person and then serves a model for its lifetime; there
+ * is no call on it that is not model-authored. So the origin is established at
+ * the entry point and read by whoever writes a ledger line, rather than
+ * threaded through every runtime, executor and step that sits between them.
+ *
+ * This is provenance, not authentication. It records the door a fact came
+ * through. It does not prove who was behind it, and nothing here should be read
+ * as if it did — see {@link UNATTESTED_APPROVER}.
+ */
+/**
+ * Channels where the caller is a model rather than a person.
+ *
+ * The distinction this type exists to draw. On `cli` a human typed each
+ * command and the existing trust boundary is the right one. On `mcp` and `acp`
+ * a human launched a server and a model authored everything after, so a gate
+ * resolved from the same channel that produced it has no second party in it.
+ */
+const MODEL_AUTHORED = new Set(["mcp", "acp"]);
+/** Whether a channel's calls are authored by a model rather than by a person. */
+export function isModelAuthored(origin) {
+    return origin !== undefined && MODEL_AUTHORED.has(origin);
+}
+/**
+ * What `resolvedBy` says for a resolution recorded on a channel that cannot
+ * attest to a name.
+ *
+ * `op-approve` used to take a free-text `approver` and write it down. Recording
+ * a name the model chose is worse than recording nothing, because it reads in
+ * the ledger exactly like a name a person gave. This is the honest value.
+ */
+export const UNATTESTED_APPROVER = "unattested";
+let ambient = "cli";
+/**
+ * The environment variable a model-authored channel carries into child
+ * processes (chant#3817), as a steward's turn carries `CHANT_STEWARD`: a
+ * `chant workspace points answer` or `chant approve` a process on MCP or ACP
+ * starts is that channel's too. Only `mcp` and `acp` are read from it, so it
+ * can make a process model-authored and never make one a person's.
+ */
+export const GATE_ORIGIN_ENV = "CHANT_GATE_ORIGIN";
+/**
+ * Declare the channel this process serves. Called once at an entry point, not
+ * per call: `chant mcp` sets `"mcp"` before it serves anything, `chant acp`
+ * sets `"acp"`, and the CLI leaves the default. A model-authored channel is
+ * also exported as {@link GATE_ORIGIN_ENV}, so a child process knows it too.
+ */
+export function setGateOrigin(origin) {
+    ambient = origin;
+    if (isModelAuthored(origin))
+        process.env[GATE_ORIGIN_ENV] = origin;
+}
+/**
+ * The channel this process serves. `"cli"` unless an entry point said
+ * otherwise, or this process was started by one on MCP or ACP.
+ */
+export function currentGateOrigin() {
+    if (ambient !== "cli")
+        return ambient;
+    const inherited = process.env[GATE_ORIGIN_ENV];
+    return inherited === "mcp" || inherited === "acp" ? inherited : ambient;
+}
+/** Restore the default. For tests, which must not leak a channel into each other. */
+export function resetGateOrigin() {
+    ambient = "cli";
+    delete process.env[GATE_ORIGIN_ENV];
+}
+/**
+ * Why a resolution from this origin cannot answer a pending fact from the same
+ * one, or `undefined` when it can.
+ *
+ * The rule, and the two cases it deliberately leaves alone:
+ *
+ *   - Same channel, model-authored. Refused. `op-run` produced the pending
+ *     fact and `op-approve` would resolve it, both authored by the same model
+ *     in the same session. Nothing about that is an approval.
+ *   - Same channel, `cli`. Allowed. A person ran `chant run`, read the plan and
+ *     ran `chant approve`. That is the intended workflow and the trust boundary
+ *     the ledger already documents.
+ *   - Different channels. Allowed, and the point: a model's run approved by a
+ *     person at a shell is exactly the separation the gate is for.
+ */
+export function sameOriginRefusal(pendingOrigin, resolutionOrigin) {
+    if (!isModelAuthored(resolutionOrigin))
+        return undefined;
+    if (pendingOrigin !== resolutionOrigin)
+        return undefined;
+    return (`the gate was reached over ${resolutionOrigin} and this resolution arrived over ${resolutionOrigin} too, ` +
+        "so the same caller wrote both halves");
+}

package/dist/lifecycle/gate-pending.js

@@ -0,0 +1,58 @@
+/**
+ * What a pending gate fact is written with, apart from the ledger's git code
+ * (#3816): its default expiry and the address of its approval surface. A
+ * bundle that records a pending fact through its own port, such as
+ * `@intentius/chant/point-decision`, imports these without git.
+ * `./gate-ledger.ts` re-exports them.
+ */
+/** The default a gate's pending fact expires after when its `GateStep` declares no `timeout` — the same 48h `GateStep.timeout` documents as its own default. */
+export const DEFAULT_GATE_EXPIRY = "48h";
+/**
+ * The address of the approval surface for a gate, resolved from the CI
+ * environment (#2028).
+ *
+ * #1485's argument for gate-as-fact was that approval gets an address:
+ * "gate-as-PR gives approval a URL, a review surface, and CODEOWNERS as the
+ * authorization model." What shipped recorded the gate and not the address,
+ * so a pending-approval card had nothing to link to and gate-as-PR stayed a
+ * convention. This is the narrow, honest half of that: when a tick (or a
+ * `chant approve`) runs inside the PR/MR job that carries the change, the
+ * loop genuinely knows where approval happens, and says so. Anywhere else it
+ * returns `undefined` and the field is simply absent — never a guess, never a
+ * synthesized link.
+ *
+ * The env-var fallback chain is the same one `--actor` and `--run-id` already
+ * use (`../cli/handlers/components.ts`): GitHub Actions first, then GitLab CI.
+ *
+ * - GitHub Actions on a `pull_request` event: `GITHUB_SERVER_URL` +
+ *   `GITHUB_REPOSITORY` + the PR number, which `GITHUB_REF_NAME` carries as
+ *   `<n>/merge`. A push-event run has no PR, so it resolves to nothing.
+ * - GitLab CI on a merge-request pipeline: `CI_MERGE_REQUEST_PROJECT_URL` +
+ *   `CI_MERGE_REQUEST_IID`.
+ */
+export function resolveApprovalUrl(env = process.env) {
+    const prNumber = /^(\d+)\/(merge|head)$/.exec(env.GITHUB_REF_NAME ?? "")?.[1];
+    if (prNumber && env.GITHUB_REPOSITORY) {
+        const server = (env.GITHUB_SERVER_URL ?? "https://github.com").replace(/\/$/, "");
+        return `${server}/${env.GITHUB_REPOSITORY}/pull/${prNumber}`;
+    }
+    if (env.CI_MERGE_REQUEST_PROJECT_URL && env.CI_MERGE_REQUEST_IID) {
+        return `${env.CI_MERGE_REQUEST_PROJECT_URL.replace(/\/$/, "")}/-/merge_requests/${env.CI_MERGE_REQUEST_IID}`;
+    }
+    return undefined;
+}
+/**
+ * Whether `raw` is an address worth recording as one: an absolute `http`/
+ * `https` URL. A gate's address is a link a reader is expected to follow, so
+ * a relative path or a `file:`/`javascript:` scheme is refused at the CLI
+ * boundary rather than written into an immutable record.
+ */
+export function isApprovalUrl(raw) {
+    try {
+        const parsed = new URL(raw);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}