@intentius/chant 0.90.0 → 0.93.0

package/src/op/steward.ts

@@ -0,0 +1,277 @@
+/**
+ * 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.
+ */
+
+import type { OpConfig } from "./types";
+import { isValidCronExpression, cronSyntaxMessage } from "./cron";
+import { workLeaseNeedsRunItem, workLeaseProblems } from "./work-lease-decl";
+
+/** The entity marker a steward declaration carries. */
+export const STEWARD_KIND = "Chant::Steward";
+
+/** Where a steward runs. */
+export const STEWARD_FORMS = ["local", "fountain"] as const;
+export type StewardForm = (typeof STEWARD_FORMS)[number];
+
+/** The form a declaration asks for, as given: one form, or a default with per-environment exceptions. */
+export type StewardFormSpec = StewardForm | { default: StewardForm; environments?: Record<string, StewardForm> };
+
+/** 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}$/;
+
+/**
+ * An Op a steward runs, however the project holds it: the `Op()` declaration
+ * (config behind `.props`), or the bare config.
+ */
+export type StewardOpInput = OpConfig | { props: unknown };
+
+export interface StewardDeclarationConfig {
+  /** The steward's name. On Fountain, the Agent's and the Teammate's. */
+  name: string;
+  /** The Ops it runs. A scheduled one runs on its cron; any other runs when asked. */
+  ops: StewardOpInput[];
+  /** Where it runs. Default `local`. */
+  form?: StewardFormSpec;
+  /**
+   * The box capabilities its Ops reach through the box's broker (#2726), by
+   * the names the member's `box` block in the workspace declaration gives
+   * them, such as `fountain` or `inference`. A steward that names any holds no
+   * credential of its own, so it takes no `vault`.
+   */
+  capabilities?: string[];
+  /** The vault the steward holds on Fountain, by name, for a steward that isn't behind a broker. */
+  vault?: string;
+}
+
+/** A steward's declaration, normalised. Plain data: see the module doc. */
+export interface StewardDeclaration {
+  readonly kind: typeof STEWARD_KIND;
+  readonly name: string;
+  readonly ops: readonly OpConfig[];
+  readonly form: { readonly default: StewardForm; readonly environments: Readonly<Record<string, StewardForm>> };
+  /** Brokered box capabilities its Ops use (#2726). Empty when it names none. */
+  readonly capabilities: readonly string[];
+  /** The vault it holds, by name, or null. Never set together with `capabilities`. */
+  readonly vault: string | null;
+}
+
+/** The config inside an op, whether it arrived as a declaration or as itself. */
+export function stewardOpConfig(op: StewardOpInput): OpConfig {
+  const declared = (op as { props?: unknown }).props;
+  return (declared && typeof declared === "object" ? declared : op) as OpConfig;
+}
+
+function checkForm(steward: string, form: unknown, where: string): StewardForm {
+  if (!STEWARD_FORMS.includes(form as StewardForm)) {
+    throw new Error(`Steward "${steward}": ${where} is ${JSON.stringify(form)}; a steward's form is "local" or "fountain"`);
+  }
+  return form as StewardForm;
+}
+
+/** Normalise a form spec, refusing an unknown form or an environment name no ledger could hold. */
+export function normaliseStewardForm(steward: string, spec: StewardFormSpec | undefined): StewardDeclaration["form"] {
+  if (spec === undefined) return { default: "local", environments: {} };
+  if (typeof spec === "string") return { default: checkForm(steward, spec, "form"), environments: {} };
+  const environments: Record<string, StewardForm> = {};
+  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 };
+}
+
+/**
+ * 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.
+ */
+export function declareSteward(config: StewardDeclarationConfig): StewardDeclaration {
+  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 ops = config.ops.map(stewardOpConfig);
+  const seen = new Set<string>();
+  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 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]),
+    form: normaliseStewardForm(name, config.form),
+    capabilities: Object.freeze(capabilities),
+    vault,
+  });
+}
+
+/** Is this value a steward declaration? Duck-typed, like `isOpEntity`. */
+export function isStewardDeclaration(value: unknown): value is StewardDeclaration {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Partial<StewardDeclaration>;
+  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 form a steward takes in `env` (`local` when none is named). */
+export function stewardFormFor(steward: StewardDeclaration, env: string = DEFAULT_STEWARD_ENV): StewardForm {
+  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: string): string {
+  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: string): string {
+  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: Map<string, { declaration: StewardDeclaration }>,
+  name: string,
+): StewardDeclaration | string {
+  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/src/op/types.ts

@@ -42,6 +42,59 @@ export interface OpConfig {
    * local one-shot executor ignores it.
    */
   schedule?: OpSchedule;
+  /**
+   * The work item this Op runs under (#2748, ws-055). The executor claims the
+   * item's work lease (`../lifecycle/work-lease.ts`) before the steps that run
+   * under it, renews it as a heartbeat while they run, stops the run when the
+   * lease is lost, and gives it back when the run ends. See
+   * {@link OpWorkLease} and `./work-lease-run.ts`.
+   */
+  workLease?: OpWorkLease;
+  /**
+   * The Op changes the checkout: it applies a build, or upgrades the
+   * workspace (#2748). Such an Op must declare {@link OpConfig.workLease}: the
+   * executor refuses to run it otherwise, and `declareSteward` refuses to list
+   * it. Its leased steps get a git worktree of their own, on the branch
+   * `chant/work/<item>`, so the change never lands in the working tree a
+   * coding agent is editing.
+   */
+  changesCheckout?: boolean;
+}
+
+/**
+ * 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";
+
+/**
+ * Which work item an Op runs under, and how (#2748).
+ *
+ * `item` is an id, a list of candidate ids (the first one nobody holds is
+ * claimed, as chud's dispatcher took the first ready contract nobody held), a
+ * reference to an earlier step's output that resolves to either, or omitted,
+ * in which case the run names it (`chant run <op> --work <id>`). A literal or
+ * run-time item is claimed before the first step; a referenced one right
+ * after the step that produces it. A run that finds nothing to claim (the
+ * reference resolved to nothing, or every candidate is held) ends `ok` with
+ * the rest of its steps skipped, and the claim's record says why.
+ */
+export interface OpWorkLease {
+  item?: string | string[] | StepOutputRef;
+  /**
+   * The work kind file whose member owns the lease (#2524 D7), relative to
+   * the project directory. Omitted, the lease is in the project's own ledger.
+   */
+  kind?: string;
+  /** How long a claim lasts unless renewed, as a duration ("10m"). Renewed every third of it. Default 10m. */
+  ttl?: string;
+  /**
+   * How the release records a run that ended `ok`: a reference to a step
+   * output holding a short string (`done`, `not_done`, ...). Default `done`;
+   * a failed run releases `not_done` and a gated one `gated`.
+   */
+  outcome?: StepOutputRef;
 }
 
 /**
@@ -100,6 +153,13 @@ export interface ActivityStep {
    * Default: "fastIdempotent"
    */
   profile?: ActivityProfileName;
+  /**
+   * How long one attempt may run, such as `"45m"`, in place of the
+   * profile's timeout (#2787). The profile's retry policy is kept, so a
+   * `shell` step stays one attempt. At most `MAX_STEP_TIMEOUT` (six hours); a longer
+   * wait is a gate, not a step.
+   */
+  timeout?: string;
   /**
    * Surface this activity's return value as a named run outcome.
    *

package/src/op/work-lease-decl.ts

@@ -0,0 +1,80 @@
+/**
+ * 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";
+import { parseDuration } from "./duration";
+import { WORK_LEASE_STEP_ID, type OpConfig, type PhaseDefinition } from "./types";
+
+/** 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 = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+/** The ids of the activity steps in an Op's main phases, in order. */
+function mainStepIds(phases: readonly PhaseDefinition[]): string[] {
+  const ids: string[] = [];
+  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: Pick<OpConfig, "name" | "phases" | "workLease" | "changesCheckout">): string[] {
+  const problems: string[] = [];
+  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: unknown) => {
+    if (typeof id !== "string" || !WORK_LEASE_ITEM_PATTERN.test(id) || id.includes("..")) {
+      problems.push(`Op "${name}": workLease.item ${JSON.stringify(id)} can't key a work lease (letters, digits, ".", "_" and "-")`);
+    }
+  };
+  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) < 3_000) 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: Pick<OpConfig, "workLease">): boolean {
+  return config.workLease !== undefined && config.workLease.item === undefined;
+}
+