@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/status-gates.js

@@ -0,0 +1,162 @@
+/**
+ * Gate state for `chant workspace status --json` (#2674): each member's gates
+ * as its gate ledger on `chant/lifecycle` records them, so a reader such as
+ * hud never runs `git show` on the branch itself.
+ *
+ * A member's gate ledger is the `_gates/` directory under its ledger prefix:
+ * `_members/<member>/_gates/<component>.jsonl` for a member that writes the
+ * member layout (#2538), and the flat `_gates/<component>.jsonl` otherwise,
+ * chosen the same way as its release ledger. Each file is keyed by the
+ * component, or by the op for a gate an Op run reached, and holds both the
+ * pending facts a run records and the approvals `chant approve` records
+ * (`../lifecycle/gate-ledger.ts`).
+ *
+ * A gate's state is decided the way a run decides it (`evaluateGate` in
+ * `../op/gate.ts`), without writing anything: the newest pending fact for the
+ * gate in its environment is the anchor, only approvals recorded since it and
+ * for its plan count, and a gate with an `approval` block counts them with
+ * `tallyGateApprovals`, as `describeApprovalProgress` does after an approve.
+ * Its human quorum reaches back to `humanQuorumSince` (#3206), as a run's does.
+ */
+import { execFileSync } from "node:child_process";
+import { samePlanDigest } from "../lifecycle/plan-digest.js";
+import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, parseGateLedger } from "../lifecycle/gate-ledger.js";
+import { humanQuorumSince, tallyGateApprovals } from "../op/gate.js";
+/** Why a member's gates can't be listed. Closed: a new code is a contract change. */
+export const GATE_REASON_CODES = [
+    /** The checkout has no `chant/lifecycle` branch, so there is no ledger to read gates from. */
+    "gates-no-ledger",
+    /** The branch has no gate ledger for the member: no run of it has reached a gate. */
+    "gates-no-gate-ledger",
+    /** Reading the member's gate ledger failed, so no gate is listed. */
+    "gates-ledger-unreadable",
+];
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+}
+export const defaultGateLedgerReader = async (dir, commit, cwd) => {
+    try {
+        git(cwd, ["rev-parse", "--verify", "--quiet", `${commit}:${dir}`]);
+    }
+    catch {
+        return null;
+    }
+    const files = new Map();
+    for (const name of git(cwd, ["ls-tree", "--name-only", `${commit}:${dir}`]).split("\n")) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        files.set(name.slice(0, -".jsonl".length), git(cwd, ["cat-file", "blob", `${commit}:${dir}/${name}`]));
+    }
+    return files;
+};
+/**
+ * The exact `chant approve` line for a gate. A gate bound to a plan (#2300)
+ * gets `--plan <digest>` too (#2832), so running the line back approves the
+ * plan this read showed and not whatever happens to be pending by the time
+ * someone runs it.
+ */
+export function approveCommand(component, gate, env, planDigest, signed = false) {
+    return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}${planDigest ? ` --plan ${planDigest}` : ""}${signed ? " --sign" : ""}`;
+}
+const approvalOf = (r) => ({ principal: r.resolvedBy, channel: r.origin ?? null, relayedBy: r.relayedBy ?? null, at: r.timestamp });
+/** One gate in one environment, decided against its newest pending fact. */
+function decide(component, standing, facts, all, now, rule) {
+    const gate = standing.gate;
+    // #3163: under identity.gates, an unsigned approval, or one from outside the class, doesn't count, as a run reads it.
+    const resolutions = rule === null ? all : all.filter((r) => r.gate !== gate || rule.refuses(r) === null);
+    const env = standing.environment ?? null;
+    const since = standing.timestamp;
+    const planDigest = standing.planDigest;
+    // #2574: an approval recorded for another environment doesn't count; one
+    // that records none is kept, so it reads as a mismatch, as a run reads it.
+    const own = env === null ? resolutions : resolutions.filter((r) => r.environment === undefined || r.environment === env);
+    let approved;
+    let approvals;
+    let needed = 1;
+    let mismatched;
+    if (standing.approval) {
+        // #3206: a human approval from before a fact re-recorded for a mode or context change still counts.
+        const tally = tallyGateApprovals(own, gate, since, planDigest, standing.approval, humanQuorumSince(facts, standing));
+        approved = tally.permit !== undefined || tally.counted.length >= tally.need;
+        approvals = tally.permit && !tally.counted.includes(tally.permit) ? [...tally.counted, tally.permit] : tally.counted;
+        needed = tally.need;
+        mismatched = tally.mismatched;
+    }
+    else {
+        const at = (r) => new Date(r.timestamp).getTime();
+        approvals = own
+            .filter((r) => r.gate === gate && at(r) >= new Date(since).getTime() && (planDigest === undefined || samePlanDigest(r.planDigest, planDigest)))
+            .sort((a, b) => at(a) - at(b));
+        approved = approvals.length > 0;
+        mismatched = latestResolutionForPlan(own, gate, since, planDigest).mismatched;
+    }
+    const state = approved ? "approved" : isPendingGateExpired(standing, now) ? "expired" : mismatched ? "superseded" : "pending";
+    return {
+        component,
+        name: gate,
+        env,
+        planDigest: planDigest ?? null,
+        state,
+        recordedAt: standing.timestamp,
+        expiresAt: standing.expiresAt,
+        approvals: approvals.map(approvalOf),
+        needed,
+        signed: rule === null ? null : { class: rule.requirement.class },
+        approve: standing.answer ? `chant workspace points answer ${standing.answer.id} --answer <value> --by <name>` : approveCommand(component, gate, env, planDigest, rule !== null),
+        ...(standing.answer ? { answer: { point: standing.answer.point, id: standing.answer.id, path: standing.answer.path } } : {}),
+    };
+}
+/**
+ * Every gate in one ledger file, one per gate and environment, for the
+ * environments in `envs`. A gate whose facts record no environment (an Op
+ * gate) is listed whatever `envs` is. A pending fact with no environment on a
+ * gate whose other facts have one is left out, as a run leaves it out: such a
+ * line binds no environment, and `chant approve --expire` writes one.
+ */
+export function gatesInLedger(component, content, envs, now, rules = () => null) {
+    const { pending, resolutions, malformed } = parseGateLedger(content);
+    const gates = [];
+    for (const gate of [...new Set(pending.map((p) => p.gate))].sort()) {
+        const facts = pending.filter((p) => p.gate === gate);
+        const bound = facts.some((p) => p.environment !== undefined);
+        const byEnv = new Map();
+        for (const p of facts) {
+            const env = p.environment ?? null;
+            if (bound && env === null)
+                continue;
+            if (env !== null && !envs.includes(env))
+                continue;
+            byEnv.set(env, [...(byEnv.get(env) ?? []), p]);
+        }
+        for (const env of [...byEnv.keys()].sort((a, b) => envs.indexOf(a ?? "") - envs.indexOf(b ?? ""))) {
+            const envFacts = byEnv.get(env);
+            gates.push(decide(component, latestPendingGate(envFacts, gate), envFacts, resolutions, now, rules(gate)));
+        }
+    }
+    return { gates, malformed };
+}
+/** Read one member's gate ledger directory at `commit` and list its gates. */
+export async function readMemberGates(dir, layout, commit, envs, cwd, now, read = defaultGateLedgerReader, rules = () => null) {
+    const ledger = { layout, path: dir, shared: false, malformed: 0, reason: null };
+    if (commit === null) {
+        return { gates: [], ledger: { ...ledger, reason: { code: "gates-no-ledger", message: "the checkout has no chant/lifecycle branch, so no gate is recorded in it" } } };
+    }
+    let files;
+    try {
+        files = await read(dir, commit, cwd);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        return { gates: [], ledger: { ...ledger, reason: { code: "gates-ledger-unreadable", message: `${dir}: ${message}` } } };
+    }
+    if (files === null) {
+        return { gates: [], ledger: { ...ledger, reason: { code: "gates-no-gate-ledger", message: `${dir} does not exist on chant/lifecycle: no run has reached a gate` } } };
+    }
+    const gates = [];
+    for (const component of [...files.keys()].sort()) {
+        const read = gatesInLedger(component, files.get(component), envs, now, rules);
+        gates.push(...read.gates);
+        ledger.malformed += read.malformed;
+    }
+    return { gates, ledger };
+}

package/dist/workspace/status-stewards.js

@@ -0,0 +1,330 @@
+/**
+ * Stewards in `chant workspace status --json` (#2731): which steward runs a
+ * member's operational work, the form it takes in the environment asked for,
+ * its Ops with their schedules, and each Op's last run.
+ *
+ * The steward itself is read from its declaration, the same `*.op.ts` files
+ * `chant operator --steward` reads (`../op/discover.ts`), through the index
+ * kept per tree (`./steward-index.ts`, #3636), and only for a member
+ * of kind `chant` that is a chant project of its own (a `chant.config.ts` or
+ * `.json` in its directory), so a member never lists a parent project's
+ * steward. Everything
+ * else is read from the local `chant/lifecycle` branch and refs, never
+ * fetched, as the rest of status is:
+ *
+ * - each Op's last run is the newest record in its run ledger,
+ *   `<env>/runs__<op>.jsonl` under the member's ledger prefix, where `<env>`
+ *   is the Op's own `labels.Env` or `local`;
+ * - an Op's `inFlight` is the run of it in flight now, from the record a
+ *   run keeps beside the checkout's git directory while it runs
+ *   (`../op/run-live.ts`): its phase and step, the phases it has finished and
+ *   its newest activity lines. Null once the run's ledger record is written,
+ *   or when the process that wrote it is gone;
+ * - `waiting` lists the open decision points the steward waits on (#2749):
+ *   each Op whose newest run is the steward's own and stopped on a question
+ *   that is still open. The question's state is read now, the way `points`
+ *   reads it (`readQuestionStates`), not copied from the run ledger, which
+ *   keeps the state the run stopped with. A question answered since, or
+ *   whose record is gone, is not waited on; nor is one whose Op has a newer
+ *   run in flight that has not written its record yet: the Op's lease or one
+ *   of its work leases was taken after the waiting run ended
+ *   (`newerRunInFlight`). When the questions can't be read, the ledger's
+ *   state stands, as the operator's does. A run is the steward's when its
+ *   record names it (`steward`, written for a run started in the steward's
+ *   turn or under `CHANT_STEWARD`), so this also covers the member's other
+ *   Ops, those no steward lists, that such a run belongs to, such as an Op
+ *   the steward's process starts itself;
+ * - `lease` is the local steward's own lease ref
+ *   (`refs/chant/lease/[<prefix>]_stewards/<name>`), present while a
+ *   `chant operator --steward` holds it or until it expires;
+ * - an Op's `workLease.held` is the work leases its turns hold (#2748): those
+ *   whose holder is `<steward>/<op>@...` (`stewardWorkHolder`), read from the
+ *   ledger of the Op's work kind, or the member's own;
+ * - an Op the steward runs beside its turns (#2861) has `beside`: whether it
+ *   declares a ready step, and the Op's own lease
+ *   (`refs/chant/lease/[<prefix>]<op>`), which a run of it holds while it runs.
+ *   Its waiting run and its work leases are listed as for any of its Ops.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { stewardFormFor, stewardLeaseName } from "../op/steward.js";
+import { readRunLedger, runEnvOf } from "../lifecycle/run-ledger.js";
+import { readConvergeLedger } from "../lifecycle/converge-ledger.js";
+import { leaseRef } from "../lifecycle/lease.js";
+import { readBlobBySha, readRefSha } from "../lifecycle/git.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { listWorkLeases } from "../lifecycle/work-lease.js";
+import { stewardWorkHolder } from "../op/work-lease-run.js";
+import { readStewardIndex } from "./steward-index.js";
+import { readInFlightRun } from "../op/run-live.js";
+import { approveCommand } from "./status-gates.js";
+/** Why a member's stewards can't be fully listed. Closed: a new code is a contract change. */
+export const STEWARD_REASON_CODES = [
+    /** An `*.op.ts` file could not be imported, so a steward it declares may be missing. */
+    "stewards-unreadable",
+    /** A steward was dropped: its name, or an Op it lists, belongs to another steward. */
+    "stewards-conflict",
+    /** Reading an Op's run ledger, or a ConvergeOp's converge ledger, failed, so its last run or last tick is null. */
+    "steward-runs-unreadable",
+];
+async function readQuestionStates(cwd) {
+    const { readQuestionStates: read } = await import("./points-cli.js");
+    return read(cwd);
+}
+/**
+ * The point a run stopped on, with the question's state now and whether it
+ * is still open. A question whose record is gone is not open, as the
+ * operator reads it (`stewardWaits` in `../op/operator.ts`); when the
+ * questions can't be read, the run ledger's state stands and it is open.
+ */
+function pointOf(p, states) {
+    const recorded = p.state === "proposed" ? "proposed" : "escalated";
+    const now = states?.get(p.id);
+    const state = now === "escalated" || now === "proposed" || now === "answered" ? now : recorded;
+    return {
+        wait: { id: p.id, point: p.point, state, path: p.path, subject: p.subject ?? null, since: p.since },
+        open: states === null || (now !== undefined && now !== "answered"),
+    };
+}
+/**
+ * Whether a newer run of the Op is in flight than the one that ended at
+ * `ended`: the Op's own lease is live, or one of its work leases is active,
+ * and was taken after that run ended. A run writes its record when it ends,
+ * so until then the ledger's newest record is the older run's.
+ */
+function newerRunInFlight(ended, lease, held) {
+    const after = (at) => Date.parse(at) >= Date.parse(ended);
+    return (lease?.live === true && after(lease.acquiredAt)) || held.some((l) => l.state === "active" && after(l.acquiredAt));
+}
+/** The Op's run in flight, unless its ledger record is already the newest. Never throws. */
+async function inFlightOf(memberDir, env, op, lastRunId) {
+    try {
+        const run = await readInFlightRun(memberDir, env, op);
+        if (!run || run.id === lastRunId)
+            return null;
+        return {
+            id: run.id,
+            started: run.started,
+            updated: run.updated,
+            steward: run.steward,
+            item: run.item,
+            phase: run.phase,
+            step: run.step,
+            phases: run.phases.map((p) => ({ name: p.name, status: p.status, durationMs: p.durationMs })),
+            activity: run.activity,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function gateOf(g, opName) {
+    const op = g.op ?? opName;
+    return { name: g.name, since: g.since, op, approve: approveCommand(op, g.name, null) };
+}
+function tickOf(t) {
+    return {
+        id: t.id ?? null,
+        timestamp: t.timestamp,
+        log: t.log,
+        firedRuleIds: [...t.firedRuleIds],
+        outcomes: t.outcomes.map((o) => ({
+            ruleId: o.ruleId,
+            action: o.action,
+            op: o.op ?? null,
+            resource: o.resource ?? null,
+            reason: o.reason ?? null,
+        })),
+        resources: t.resources ? t.resources.map((r) => ({ name: r.name, status: r.status, detail: r.detail ?? null })) : null,
+    };
+}
+/** Whether a directory is a chant project of its own. */
+function isChantProject(dir) {
+    return existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"));
+}
+/** A lease ref of the member, by its lease name (`_stewards/<name>`, or an Op's). */
+async function readLeaseRef(leaseName, memberDir, now) {
+    try {
+        const { prefix } = await resolveMemberLedger(memberDir);
+        const sha = await readRefSha(leaseRef(leaseName, prefix), { cwd: memberDir });
+        if (!sha)
+            return null;
+        const record = JSON.parse((await readBlobBySha(sha, { cwd: memberDir })) ?? "");
+        if (typeof record.holder !== "string" || typeof record.expiresAt !== "string" || typeof record.acquiredAt !== "string")
+            return null;
+        return {
+            holder: record.holder,
+            acquiredAt: record.acquiredAt,
+            expiresAt: record.expiresAt,
+            live: new Date(record.expiresAt).getTime() > new Date(now).getTime(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** An Op's `beside` entry (#2861): null for an Op run as one of the steward's turns. */
+async function besideOf(steward, op, memberDir, now) {
+    const beside = steward.beside.find((b) => b.op === op);
+    if (!beside)
+        return null;
+    return { ready: beside.ready, lease: await readLeaseRef(op, memberDir, now) };
+}
+/** The work leases `steward`'s turns of `op` hold, from the ledger of the Op's kind or the member's. */
+async function readHeldWorkLeases(steward, op, memberDir, now) {
+    try {
+        const kind = op.workLease?.kind;
+        const cwd = kind ? dirname(resolve(memberDir, kind)) : memberDir;
+        const { prefix } = await resolveMemberLedger(cwd);
+        const mine = stewardWorkHolder(steward, op.name, "");
+        return (await listWorkLeases({ cwd, memberPrefix: prefix, now: new Date(now) }))
+            .filter((l) => l.holder.startsWith(mine))
+            .map((l) => ({ item: l.item, holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt, state: l.state }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The stewards declared in one member, for `env`. `memberDir` is absolute.
+ * Only a member of kind `chant` with a config of its own is read.
+ */
+export async function readMemberStewards(memberDir, env, now, kind = "chant", box = null, deps = {}) {
+    const reasons = [];
+    // Read once per member, and only when a run stopped on a question.
+    let states;
+    const questionStates = () => (states ?? (states = (deps.readQuestions ?? readQuestionStates)(memberDir)));
+    if (kind !== "chant" || !isChantProject(memberDir))
+        return { stewards: [], reasons };
+    let index;
+    try {
+        index = await (deps.readIndex ?? readStewardIndex)(memberDir);
+    }
+    catch (err) {
+        reasons.push({ code: "stewards-unreadable", message: err instanceof Error ? err.message.split("\n")[0] : String(err) });
+        return { stewards: [], reasons };
+    }
+    for (const message of index.errors)
+        reasons.push({ code: "stewards-unreadable", message });
+    for (const message of index.conflicts)
+        reasons.push({ code: "stewards-conflict", message });
+    const stewards = [];
+    for (const declaration of [...index.stewards].sort((a, b) => a.name.localeCompare(b.name))) {
+        const ops = [];
+        const waiting = [];
+        for (const op of declaration.ops) {
+            const opEnv = runEnvOf(op);
+            const workLease = op.workLease
+                ? { kind: op.workLease.kind ?? null, held: await readHeldWorkLeases(declaration.name, op, memberDir, now) }
+                : null;
+            const beside = await besideOf(declaration, op.name, memberDir, now);
+            let lastRun = null;
+            try {
+                const newest = (await readRunLedger(opEnv, op.name, { cwd: memberDir })).records.at(-1);
+                if (newest) {
+                    const point = newest.point ? pointOf(newest.point, await questionStates()) : null;
+                    lastRun = {
+                        id: newest.id,
+                        status: newest.status,
+                        started: newest.started,
+                        ended: newest.ended,
+                        gate: newest.gate ? gateOf(newest.gate, op.name) : null,
+                        point: point?.wait ?? null,
+                        phases: newest.phases.map((p) => ({
+                            name: p.name,
+                            status: p.status,
+                            durationMs: p.durationMs ?? p.steps.reduce((sum, st) => sum + st.durationMs, 0),
+                        })),
+                    };
+                    if (newest.status === "waiting" &&
+                        point?.open &&
+                        newest.steward === declaration.name &&
+                        !newerRunInFlight(newest.ended, beside?.lease ?? null, workLease?.held ?? [])) {
+                        waiting.push({ op: op.name, run: newest.id, ...point.wait });
+                    }
+                }
+            }
+            catch (err) {
+                reasons.push({
+                    code: "steward-runs-unreadable",
+                    message: `${opEnv}/runs__${op.name}.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+                });
+            }
+            const inFlight = await inFlightOf(memberDir, opEnv, op.name, lastRun?.id ?? null);
+            let lastTick = null;
+            if (op.labels?.Converge === "true") {
+                try {
+                    const newest = (await readConvergeLedger(opEnv, { cwd: memberDir })).records.filter((r) => r.op === op.name).at(-1);
+                    if (newest)
+                        lastTick = tickOf(newest);
+                }
+                catch (err) {
+                    reasons.push({
+                        code: "steward-runs-unreadable",
+                        message: `${opEnv}/converge.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+                    });
+                }
+            }
+            ops.push({
+                name: op.name,
+                schedule: op.schedule ? { cron: op.schedule.cron, overlap: "skip" } : null,
+                env: opEnv,
+                lastRun,
+                inFlight,
+                lastTick,
+                changesCheckout: op.changesCheckout === true,
+                workLease,
+                beside,
+            });
+        }
+        stewards.push({
+            name: declaration.name,
+            file: relative(realpathSync(memberDir), realpathSync(declaration.filePath)).split("\\").join("/"),
+            form: stewardFormFor(declaration, env),
+            forms: { default: declaration.form.default, environments: { ...declaration.form.environments } },
+            vault: declaration.vault,
+            capabilities: declaration.capabilities.map((name) => {
+                const declared = box?.capabilities.find((c) => c.name === name);
+                return { name, broker: declared?.broker ?? null, declared: declared !== undefined };
+            }),
+            lease: await readLeaseRef(stewardLeaseName(declaration.name), memberDir, now),
+            ops,
+            waiting,
+        });
+    }
+    if (stewards.length > 0 && index.otherOps)
+        await addUndeclaredWaits(memberDir, stewards, index.otherOps, reasons, now, questionStates);
+    return { stewards, reasons };
+}
+/**
+ * The waiting runs of the member's Ops that no steward lists, each under the
+ * steward its record names. A steward's process can start an Op itself
+ * with `CHANT_STEWARD` set (studio#137), and the run ledger then records
+ * the run as the steward's though the declaration does not list the Op.
+ * `ops` are the member's Ops no steward lists, from the index; import
+ * failures are left out there, as discovering the stewards reported them as
+ * `stewards-unreadable`.
+ */
+async function addUndeclaredWaits(memberDir, stewards, ops, reasons, now, questionStates) {
+    const byName = new Map(stewards.map((s) => [s.name, s]));
+    for (const op of [...ops].sort((a, b) => a.name.localeCompare(b.name))) {
+        const opEnv = runEnvOf(op);
+        try {
+            const newest = (await readRunLedger(opEnv, op.name, { cwd: memberDir })).records.at(-1);
+            const steward = newest?.steward ? byName.get(newest.steward) : undefined;
+            if (steward && newest?.status === "waiting" && newest.point) {
+                const point = pointOf(newest.point, await questionStates());
+                const held = op.workLease ? await readHeldWorkLeases(steward.name, op, memberDir, now) : [];
+                if (point.open && !newerRunInFlight(newest.ended, await readLeaseRef(op.name, memberDir, now), held)) {
+                    steward.waiting.push({ op: op.name, run: newest.id, ...point.wait });
+                }
+            }
+        }
+        catch (err) {
+            reasons.push({
+                code: "steward-runs-unreadable",
+                message: `${opEnv}/runs__${op.name}.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+            });
+        }
+    }
+}