@intentius/chant 0.124.13 → 0.124.14

package/dist/op/steward.js

@@ -0,0 +1,317 @@
+/**
+ * A steward's declaration (#2731): the one writer for an environment, as data
+ * core can read without any lexicon loaded.
+ *
+ * A steward runs a fixed list of Ops, each on its own `schedule` when it has
+ * one, one Op at a time. Where it runs is its form:
+ *
+ * - `fountain`: the fountain lexicon's `Steward` composite, an `acp` Agent on
+ *   a persistent sandbox bound to a Teammate, with a Fountain `Schedule` per
+ *   scheduled Op. A turn is one `chant run <op>` on the teammate's thread.
+ * - `local`: `chant operator --steward <name>` in the box itself, for a box
+ *   with no Fountain behind it (a docker compose box, a Sprites box). The same
+ *   Ops on the same crons, each run under its operator lease, and the steward
+ *   itself under a lease of its own so a second local operator is refused.
+ *
+ * One declaration covers both. `form` is either one of the two, or a default
+ * with per-environment exceptions, so a box whose `minimal` environment has no
+ * Fountain and whose `fountain-k3d` one does still has exactly one steward:
+ *
+ * ```ts
+ * // ops/steward.op.ts
+ * export const steward = declareSteward({
+ *   name: "box-steward",
+ *   ops: [converge, dispatch, release, upgrade],
+ *   form: { default: "local", environments: { "fountain-k3d": "fountain" } },
+ * });
+ * ```
+ *
+ * The fountain composite builds this same declaration from its own options and
+ * returns it as `declaration`, so a project that declares its steward there
+ * exports that object from an `*.op.ts` file instead of calling this function.
+ *
+ * ## Discovery
+ *
+ * A steward is discovered from the same `*.op.ts` files Ops are
+ * (`./discover.ts`), because it is chant's own run-time declaration and sits
+ * beside the Ops it runs. It is plain data with a `kind` marker, not a
+ * Declarable, so `chant build` never serializes it and a copy of core linked
+ * twice still recognises it.
+ *
+ * ## What a steward writes
+ *
+ * A steward's writes are chant writes: run, converge and gate records on the
+ * `chant/lifecycle` branch, the answer records of the decision points its
+ * Ops ask (`_answers/`, #2786), and lease refs under `refs/chant/lease/`, all made
+ * with git plumbing (`../lifecycle/git.ts`: `hash-object`, `mktree`,
+ * `commit-tree`, `update-ref`). None of them reads or writes the checkout's
+ * index or working tree, so a coding agent editing the app in the same
+ * checkout, and holding git's index lock while it commits, never collides with
+ * a steward turn. The app's files are the coding agent's; the steward does not
+ * edit them.
+ *
+ * An Op that has to change the checkout (applying a build, a workspace
+ * upgrade) says so with `changesCheckout` and runs under a work item's lease
+ * (`workLease`, #2748): its leased steps get a worktree of their own on
+ * `chant/work/<item>`. `declareSteward` refuses such an Op without the lease,
+ * and a scheduled Op whose lease leaves the item to the run.
+ *
+ * ## Beside the turns
+ *
+ * An Op listed under `beside` (#2861) is the steward's too, but its runs are
+ * not turns. A build that takes half an hour would otherwise hold every other
+ * Op of the steward, converge included, for its whole length. The local
+ * operator starts a run of it as a `chant run <op>` process of its own, with
+ * `CHANT_STEWARD` set so the run is still the steward's, and goes on with its
+ * rounds. One run at a time: the run holds the Op's own lease
+ * (`refs/chant/lease/<op>`), renewed while it runs, and never the turn lease.
+ * The operator starts one on the Op's cron, when its `ready` step says there
+ * is work, or to resume a run of the steward's that waited on a question now
+ * answered (or a gate now approved).
+ *
+ * ```ts
+ * export const steward = declareSteward({
+ *   name: "box-steward",
+ *   ops: [converge, release],
+ *   beside: [{ op: dispatch, ready: shell("node ops/ready.mjs", { json: true }) }],
+ * });
+ * ```
+ *
+ * `ops` on the normalised declaration is every Op the steward runs, beside
+ * ones last, so a reader that only asks "whose Op is this" (discovery's
+ * two-writers check, `chant run`, `workspace status`) needs nothing new.
+ * `beside` names the ones that run beside the turns.
+ */
+import { collectStepOutputRefs } from "./step-output-ref.js";
+import { isValidCronExpression, cronSyntaxMessage } from "./cron.js";
+import { workLeaseNeedsRunItem, workLeaseProblems } from "./work-lease-decl.js";
+/** The entity marker a steward declaration carries. */
+export const STEWARD_KIND = "Chant::Steward";
+/** Where a steward runs. */
+export const STEWARD_FORMS = ["local", "fountain"];
+/** The environment a form is chosen for when none is named: the same default a run ledger uses. */
+export const DEFAULT_STEWARD_ENV = "local";
+/** Names a steward's lease ref and a ledger path can hold. */
+export const STEWARD_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/** The config inside an op, whether it arrived as a declaration or as itself. */
+export function stewardOpConfig(op) {
+    const declared = op.props;
+    return (declared && typeof declared === "object" ? declared : op);
+}
+function checkForm(steward, form, where) {
+    if (!STEWARD_FORMS.includes(form)) {
+        throw new Error(`Steward "${steward}": ${where} is ${JSON.stringify(form)}; a steward's form is "local" or "fountain"`);
+    }
+    return form;
+}
+/** Normalise a form spec, refusing an unknown form or an environment name no ledger could hold. */
+export function normaliseStewardForm(steward, spec) {
+    if (spec === undefined)
+        return { default: "local", environments: {} };
+    if (typeof spec === "string")
+        return { default: checkForm(steward, spec, "form"), environments: {} };
+    const environments = {};
+    for (const [env, form] of Object.entries(spec.environments ?? {})) {
+        if (!STEWARD_NAME_PATTERN.test(env) || env.includes("..")) {
+            throw new Error(`Steward "${steward}": form.environments names ${JSON.stringify(env)}, which can't be an environment`);
+        }
+        environments[env] = checkForm(steward, form, `form.environments[${JSON.stringify(env)}]`);
+    }
+    return { default: checkForm(steward, spec.default, "form.default"), environments };
+}
+/** A `beside` entry's Op and ready step, whichever of the two forms it was given in. */
+function besideEntry(entry) {
+    const e = entry;
+    if (e && typeof e === "object" && e.op !== undefined && e.phases === undefined && e.props === undefined) {
+        return { op: stewardOpConfig(e.op), ready: e.ready ?? null };
+    }
+    return { op: stewardOpConfig(entry), ready: null };
+}
+/**
+ * Declare a steward. Refuses what would make it more than one writer or a
+ * promise it can't keep: an Op listed twice, a schedule whose overlap isn't
+ * `skip` (a fire while a turn runs is dropped in both forms), a cron that
+ * doesn't parse, and a name a lease ref can't hold. For an Op beside the
+ * turns (#2861), also a `ready` that is not one activity step, or that reads
+ * another step's output (it runs on its own, outside any run).
+ */
+export function declareSteward(config) {
+    const name = config.name;
+    if (!STEWARD_NAME_PATTERN.test(name) || name.includes("..")) {
+        throw new Error(`Steward ${JSON.stringify(name)}: a steward's name is letters, digits, ".", "_" and "-", starting with a letter or digit`);
+    }
+    const besides = (config.beside ?? []).map(besideEntry);
+    const ops = [...config.ops.map(stewardOpConfig), ...besides.map((b) => b.op)];
+    const seen = new Set();
+    for (const op of ops) {
+        if (!op || typeof op.name !== "string" || !Array.isArray(op.phases)) {
+            throw new Error(`Steward "${name}": every entry in ops must be an Op`);
+        }
+        if (seen.has(op.name))
+            throw new Error(`Steward "${name}": op "${op.name}" is listed twice`);
+        seen.add(op.name);
+        // An Op that changes the checkout runs under a work item's lease, on a
+        // branch of its own (#2748): one that doesn't declare the lease, or
+        // declares it badly, is refused here as the executor would refuse it.
+        const leaseProblems = workLeaseProblems(op);
+        if (leaseProblems.length > 0)
+            throw new Error(`Steward "${name}": ${leaseProblems.join("; ")}`);
+        if (op.schedule && workLeaseNeedsRunItem(op)) {
+            throw new Error(`Steward "${name}": op "${op.name}" is scheduled, but its workLease names no item, and a scheduled run can't be given one. ` +
+                `Name the item, candidates, or the step whose output picks it.`);
+        }
+        const beside = besides.find((b) => b.op === op);
+        if (beside?.ready) {
+            const ready = beside.ready;
+            if (!ready || ready.kind !== "activity" || typeof ready.fn !== "string") {
+                throw new Error(`Steward "${name}": op "${op.name}": ready is one activity step, such as shell("...", { json: true })`);
+            }
+            if (collectStepOutputRefs(ready.args ?? {}).length > 0) {
+                throw new Error(`Steward "${name}": op "${op.name}": its ready step reads another step's output, and it runs outside any run`);
+            }
+            if (workLeaseNeedsRunItem(op)) {
+                throw new Error(`Steward "${name}": op "${op.name}" is started when its ready step says so, but its workLease names no item, and such a run can't be given one. ` +
+                    `Name the item, candidates, or the step whose output picks it.`);
+            }
+        }
+        const schedule = op.schedule;
+        if (!schedule)
+            continue;
+        if (!isValidCronExpression(schedule.cron)) {
+            throw new Error(`Steward "${name}": op "${op.name}": ${cronSyntaxMessage(schedule.cron)}`);
+        }
+        if (schedule.overlap !== undefined && schedule.overlap !== "skip") {
+            throw new Error(`Steward "${name}": op "${op.name}" schedules overlap "${schedule.overlap}". ` +
+                `A fire while the steward is busy is dropped, so "skip" is the only policy a steward can honour.`);
+        }
+    }
+    const capabilities = [...new Set(config.capabilities ?? [])];
+    for (const c of capabilities) {
+        if (typeof c !== "string" || c.trim() === "")
+            throw new Error(`Steward "${name}": a capability is named by a non-empty string`);
+    }
+    const vault = config.vault ?? null;
+    if (vault !== null && capabilities.length > 0) {
+        throw new Error(`Steward "${name}": it reaches ${capabilities.join(", ")} through the box's broker and also holds the vault "${vault}". ` +
+            `A brokered steward holds no credential of its own: drop the vault, or name no capabilities.`);
+    }
+    return Object.freeze({
+        kind: STEWARD_KIND,
+        name,
+        ops: Object.freeze([...ops]),
+        beside: Object.freeze(besides.map((b) => Object.freeze({ op: b.op.name, ready: b.ready }))),
+        form: normaliseStewardForm(name, config.form),
+        capabilities: Object.freeze(capabilities),
+        vault,
+    });
+}
+/** Is this value a steward declaration? Duck-typed, like `isOpEntity`. */
+export function isStewardDeclaration(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (v.kind === STEWARD_KIND &&
+        typeof v.name === "string" &&
+        Array.isArray(v.ops) &&
+        !!v.form &&
+        typeof v.form === "object" &&
+        typeof v.form.default === "string");
+}
+/** The Ops a steward runs beside its turns (#2861); none for a declaration without the field. */
+export function stewardBesideOf(steward) {
+    return Array.isArray(steward.beside) ? steward.beside : [];
+}
+/** The entry for `op` when the steward runs it beside its turns (#2861), or undefined. */
+export function stewardBesideFor(steward, op) {
+    return stewardBesideOf(steward).find((b) => b.op === op);
+}
+/** The Ops a steward runs as its turns, one at a time: `ops` without the beside ones. */
+export function stewardTurnOps(steward) {
+    const beside = new Set(stewardBesideOf(steward).map((b) => b.op));
+    return steward.ops.filter((op) => !beside.has(op.name));
+}
+/**
+ * What a `ready` step's result says (#2861): the work keys it names, or null
+ * when its result is not one of the shapes below. The value read is the
+ * result's `json` when it has one (a `shell` step with `json: true`), or the
+ * result itself.
+ *
+ * - an array: one key per entry (a string as is, anything else as its JSON);
+ *   empty means no work;
+ * - a non-empty string: one key; `""` means no work;
+ * - `true` means work, with no key; `false` and `null` mean none.
+ *
+ * The operator starts a run when a key is one it has not started a run for
+ * yet, so a run that ends with the same work still ready is not started
+ * again for it. `true` has no key, so it starts a run whenever none is in
+ * flight.
+ */
+export function readinessKeys(result) {
+    const value = result && typeof result === "object" && !Array.isArray(result) && "json" in result
+        ? result.json
+        : result;
+    if (value === true)
+        return { ready: true, keys: [] };
+    if (value === false || value === null || value === undefined)
+        return { ready: false, keys: [] };
+    if (typeof value === "string")
+        return value === "" ? { ready: false, keys: [] } : { ready: true, keys: [value] };
+    if (Array.isArray(value)) {
+        const keys = value.map((v) => (typeof v === "string" ? v : JSON.stringify(v)));
+        return { ready: keys.length > 0, keys };
+    }
+    return null;
+}
+/** The form a steward takes in `env` (`local` when none is named). */
+export function stewardFormFor(steward, env = DEFAULT_STEWARD_ENV) {
+    return steward.form.environments[env] ?? steward.form.default;
+}
+/**
+ * The lease a local steward holds for as long as it runs, so a second
+ * `chant operator --steward` for the same steward is refused. It sits under
+ * `refs/chant/lease/_stewards/`, beside the per-Op leases, which a leading
+ * `_` keeps out of any Op's name.
+ */
+export function stewardLeaseName(steward) {
+    return `_stewards/${steward}`;
+}
+/**
+ * The lease a local steward holds for as long as one of its Ops is actually
+ * running: one turn (#2750). Distinct from {@link stewardLeaseName}, which one
+ * `chant operator --steward` process holds for its whole life (renewed
+ * between ticks, released only when the process stops) — this one is taken
+ * right before a run starts and released right after it ends, whether the
+ * run is a round's scheduled tick or `chant run <op>` typed by hand. That is
+ * what makes an on-request run wait its turn behind a turn already in
+ * progress, and succeed again the moment that turn ends, rather than only
+ * once the whole steward process stops.
+ *
+ * `_turns/<name>`, not `_stewards/<name>/turn`: a git ref name is a path
+ * component in the loose-refs tree, and `refs/chant/lease/_stewards/<name>`
+ * (the lease {@link stewardLeaseName} names) already exists as a *leaf* —
+ * git refuses to also create anything *under* it (`fatal: ... exists;
+ * cannot create ...`), so nesting the turn lease inside the steward lease's
+ * own name is unusable the moment both are live at once. A sibling
+ * top-level segment sidesteps that entirely.
+ */
+export function stewardTurnLeaseName(steward) {
+    return `_turns/${steward}`;
+}
+/**
+ * Pick the steward `--steward [<name>]` names, or the project's only one.
+ * Returns the steward, or the message to refuse with.
+ */
+export function pickSteward(stewards, name) {
+    if (name) {
+        const found = stewards.get(name);
+        if (found)
+            return found.declaration;
+        const known = [...stewards.keys()].sort();
+        return `No steward "${name}" is declared` + (known.length ? ` (declared: ${known.join(", ")})` : " (no *.op.ts file exports one)");
+    }
+    if (stewards.size === 1)
+        return [...stewards.values()][0].declaration;
+    if (stewards.size === 0)
+        return "No steward is declared: export declareSteward({...}) (or the fountain Steward's declaration) from an *.op.ts file";
+    return `${stewards.size} stewards are declared (${[...stewards.keys()].sort().join(", ")}); name one with --steward <name>`;
+}

package/dist/op/types.js

@@ -0,0 +1,25 @@
+/**
+ * Op type definitions — the data model for a named, phased Op.
+ *
+ * These types are intentionally free of any runtime SDK's imports, so they can
+ * live in core without core depending on a runtime.
+ */
+/** The exit code `chant run` returns for a completed run that found drift, under `failOn: "drift"` or `--fail-on-drift` (#3675). */
+export const DRIFT_EXIT_CODE = 2;
+/**
+ * The id under which a run's work lease is published to its steps (#2748):
+ * `stepOutput(WORK_LEASE_STEP_ID, "token")`, or `workLeaseOutput("token")`
+ * from `./work-lease-run.ts`. No step of an Op with a `workLease` may use it.
+ */
+export const WORK_LEASE_STEP_ID = "workLease";
+/**
+ * {@link ActivityStep.outcomeAttribute} as a list, whichever form it was
+ * authored in. `[]` when the step publishes none, so every consumer can
+ * iterate without first asking which of the two shapes it is holding.
+ */
+export function outcomeAttributesOf(step) {
+    const declared = step.outcomeAttribute;
+    if (!declared)
+        return [];
+    return Array.isArray(declared) ? declared : [declared];
+}

package/dist/op/work-lease-decl.js

@@ -0,0 +1,81 @@
+/**
+ * The rules an Op's `workLease` and `changesCheckout` declaration keeps
+ * (#2748), with no imports beyond the Op model, so `Op()` and
+ * `declareSteward` can check them without loading the lease machinery in
+ * `./work-lease-run.ts`.
+ */
+import { isStepOutputRef } from "./step-output-ref.js";
+import { parseDuration } from "./duration.js";
+import { WORK_ITEM_ID_PATTERN, workItemIdProblem } from "../lifecycle/work-item-id.js";
+import { WORK_LEASE_STEP_ID } from "./types.js";
+/** A work item id a lease can be keyed by: the same pattern as `WORK_ITEM_ID_PATTERN` in `../lifecycle/work-lease.ts`. */
+export const WORK_LEASE_ITEM_PATTERN = WORK_ITEM_ID_PATTERN;
+/** The ids of the activity steps in an Op's main phases, in order. */
+function mainStepIds(phases) {
+    const ids = [];
+    for (const phase of phases) {
+        for (const step of phase.steps)
+            if (step.kind === "activity" && step.id)
+                ids.push(step.id);
+    }
+    return ids;
+}
+/**
+ * What is wrong with an Op's `workLease` and `changesCheckout`, or an empty
+ * list. The executor refuses to start a run with any of these, and
+ * `declareSteward` refuses to list the Op.
+ */
+export function workLeaseProblems(config) {
+    const problems = [];
+    const spec = config.workLease;
+    const name = config.name;
+    if (config.changesCheckout && !spec) {
+        problems.push(`Op "${name}" changes the checkout but declares no workLease. A change to the checkout happens under a work item's lease, ` +
+            `on a branch of its own: declare workLease on the Op.`);
+    }
+    if (!spec)
+        return problems;
+    const ids = mainStepIds(config.phases ?? []);
+    if (ids.includes(WORK_LEASE_STEP_ID)) {
+        problems.push(`Op "${name}": step id "${WORK_LEASE_STEP_ID}" is reserved for the run's work lease; rename the step`);
+    }
+    const checkId = (id) => {
+        const problem = workItemIdProblem(id);
+        if (problem)
+            problems.push(`Op "${name}": workLease.item ${problem}`);
+    };
+    const item = spec.item;
+    if (isStepOutputRef(item)) {
+        if (!ids.includes(item.step)) {
+            problems.push(`Op "${name}": workLease.item references step "${item.step}", which no activity step in the Op's phases declares`);
+        }
+    }
+    else if (Array.isArray(item)) {
+        if (item.length === 0)
+            problems.push(`Op "${name}": workLease.item is an empty list`);
+        item.forEach(checkId);
+    }
+    else if (item !== undefined) {
+        checkId(item);
+    }
+    if (spec.ttl !== undefined) {
+        try {
+            if (parseDuration(spec.ttl) < 3000)
+                problems.push(`Op "${name}": workLease.ttl "${spec.ttl}" is shorter than 3s`);
+        }
+        catch (err) {
+            problems.push(`Op "${name}": workLease.ttl: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (spec.outcome !== undefined && !isStepOutputRef(spec.outcome)) {
+        problems.push(`Op "${name}": workLease.outcome is a reference to a step's output`);
+    }
+    if (spec.kind !== undefined && (typeof spec.kind !== "string" || spec.kind.trim() === "")) {
+        problems.push(`Op "${name}": workLease.kind names a work kind file`);
+    }
+    return problems;
+}
+/** Whether a run of this Op has to be told its work item (`--work <id>`). */
+export function workLeaseNeedsRunItem(config) {
+    return config.workLease !== undefined && config.workLease.item === undefined;
+}