@intentius/chant 0.90.0 → 0.91.0

package/src/op/operator.ts

@@ -39,6 +39,9 @@ import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { discoverOps, type DiscoveredOp } from "./discover";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { acquireLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
+import { runEnvOf } from "../lifecycle/run-ledger";
+import { stewardLeaseName, type StewardDeclaration } from "./steward";
+import { stewardWorkHolder } from "./work-lease-run";
 import { StaleLockError } from "../lifecycle/git";
 import { cronMatches, cronDueBetween } from "./cron";
 import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS, type WakeReason } from "./change-signal";
@@ -94,7 +97,14 @@ export type OperatorTickEvent =
    * back off silently forever instead of surfacing the fix. One op's lease
    * error never aborts the round for every other op.
    */
-  | { kind: "lease-error"; op: string; env: string; error: string };
+  | { kind: "lease-error"; op: string; env: string; error: string }
+  /**
+   * A local steward's round (#2731) found the steward's own lease held by
+   * another live holder: another `chant operator --steward` for the same
+   * steward. Nothing ticked. `op` is the steward's lease name and `env` is
+   * `-`, so a log line keyed on either still reads.
+   */
+  | { kind: "steward-busy"; op: string; env: string; steward: string; heldBy?: string };
 
 export interface OperatorRoundOptions {
   cwd?: string;
@@ -119,6 +129,30 @@ export interface OperatorRoundOptions {
    * round makes up exactly one tick rather than a backlog.
    */
   scheduleState?: Map<string, Date>;
+  /**
+   * Run a local steward's Ops instead of every discovered ConvergeOp (#2731).
+   * Only its scheduled Ops tick, each on its own cron, because that is what
+   * the same steward does on Fountain: an Op with no schedule runs when
+   * someone asks for it. The round first takes (or renews) the steward's own
+   * lease, and ticks nothing when another holder has it.
+   */
+  steward?: StewardDeclaration;
+}
+
+/** Take or renew a local steward's own lease (#2731). */
+export async function acquireStewardLease(
+  steward: string,
+  holder: string,
+  opts: { cwd?: string; ttlMs?: number; now?: () => Date } = {},
+): Promise<AcquireLeaseResult> {
+  return acquireLease(stewardLeaseName(steward), holder, { ...opts, ttlMs: opts.ttlMs ?? DEFAULT_LEASE_TTL_MS });
+}
+
+/** The Ops one round considers: a steward's scheduled ones, or every ConvergeOp. */
+async function roundOps(opts: OperatorRoundOptions): Promise<DiscoveredOp["config"][]> {
+  if (opts.steward) return opts.steward.ops.filter((op) => op.schedule !== undefined);
+  const { ops } = await discoverConvergeOps({ cwd: opts.cwd, env: opts.env });
+  return ops.map((d) => d.config);
 }
 
 /**
@@ -129,11 +163,42 @@ export interface OperatorRoundOptions {
  */
 export async function runOperatorRound(opts: OperatorRoundOptions): Promise<OperatorTickEvent[]> {
   const holder = opts.holder ?? currentHolderId();
-  const { ops } = await discoverConvergeOps({ cwd: opts.cwd, env: opts.env });
   const events: OperatorTickEvent[] = [];
+  const steward = opts.steward;
+  const leaseOpts = { cwd: opts.cwd, ttlMs: opts.leaseTtlMs, now: opts.now };
+
+  // A local steward is one writer (#2731): its round runs only while it holds
+  // its own lease, renewed here and again after every tick, so a turn longer
+  // than the lease's TTL still keeps it.
+  const holdSteward = async (): Promise<boolean> => {
+    if (!steward) return true;
+    let acquired: AcquireLeaseResult;
+    try {
+      acquired = await acquireStewardLease(steward.name, holder, leaseOpts);
+    } catch (err) {
+      events.push({
+        kind: "lease-error",
+        op: stewardLeaseName(steward.name),
+        env: "-",
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return false;
+    }
+    if (acquired.acquired) return true;
+    events.push({
+      kind: "steward-busy",
+      op: stewardLeaseName(steward.name),
+      env: "-",
+      steward: steward.name,
+      ...(acquired.heldBy?.holder ? { heldBy: acquired.heldBy.holder } : {}),
+    });
+    return false;
+  };
+
+  if (!(await holdSteward())) return events;
 
-  for (const { config } of ops) {
-    const env = envOf(config) ?? "unknown";
+  for (const config of await roundOps(opts)) {
+    const env = steward ? runEnvOf(config) : (envOf(config) ?? "unknown");
 
     // An Op that declares its own cadence (#2120) is ticked on that cron
     // rather than on every round. Level-triggered: the question is whether a
@@ -180,6 +245,9 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
     try {
       const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
         ledger: { cwd: opts.cwd },
+        // A steward's turn claims work leases as `<steward>/<op>@<holder>`
+        // (#2748), which is how `workspace status` finds the lease it holds.
+        ...(steward ? { work: { holder: stewardWorkHolder(steward.name, config.name, holder) } } : {}),
         // #2301: without a sink, `settle` catches a failed ledger append and
         // drops it. That is the failure this tick can least afford to lose —
         // the message below points the reader at the ledger record, which is
@@ -210,6 +278,7 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
             : String(err);
       events.push({ kind: "tick-failed", op: config.name, env, error: message });
     }
+    if (!(await holdSteward())) break;
   }
 
   return events;
@@ -430,5 +499,7 @@ export function formatRoundLine(event: OperatorTickEvent): string {
       return `operator: ${event.op}@${event.env} fenced=1(lease lost mid-tick — ledger record still written)`;
     case "lease-error":
       return `operator: ${event.op}@${event.env} error=1(lease acquire failed — ${event.error})`;
+    case "steward-busy":
+      return `operator: steward ${event.steward} skipped=1(steward-lease-held${event.heldBy ? `:${event.heldBy}` : ""})`;
   }
 }

package/src/op/runtime.ts

@@ -156,6 +156,12 @@ export interface OpRunStartOptions {
   progress?: (record: StepRecord) => void;
   /** Aborts in-flight work (Ctrl-C). */
   signal?: AbortSignal;
+  /**
+   * For an Op that declares `workLease` (#2748): the work item this run is
+   * for (`--work <id>`) and who holds its lease (`--holder`). Only the local
+   * runtime takes it; a hosted run's lease is taken where the run executes.
+   */
+  work?: { item?: string; holder?: string };
 }
 
 /**

package/src/op/runtimes/local.ts

@@ -166,6 +166,9 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
                     `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
                 ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+              ...(startOpts.work ? { work: startOpts.work } : {}),
+              onWorkLeaseWarning: (message) =>
+                process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
             },
           );
           const status = statusFrom(op.name, runId, startedAt, result);

package/src/op/step-output-ref.ts

@@ -87,6 +87,7 @@
 
 import { z } from "zod";
 import type { ActivityStep, OpConfig, PhaseDefinition } from "./types";
+import { WORK_LEASE_STEP_ID } from "./types";
 import { pathExistsInSchema, schemaAtPath, primitiveKindOf, type ActivityContract, type ActivityContractIssue } from "./activity-contract";
 
 const STEP_OUTPUT_REF_BRAND = Symbol.for("chant.op.stepOutputRef");
@@ -308,7 +309,7 @@ function indexById(locations: StepLocation[]): { byId: Map<string, StepLocation>
  *    the same parallel phase).
  */
 export function validateStepOutputRefScope(
-  config: Pick<OpConfig, "name" | "phases" | "onFailure">,
+  config: Pick<OpConfig, "name" | "phases" | "onFailure"> & Partial<Pick<OpConfig, "workLease">>,
 ): ActivityContractIssue[] {
   const issues: ActivityContractIssue[] = [];
 
@@ -339,6 +340,9 @@ export function validateStepOutputRefScope(
   for (const consumer of locations) {
     const refs = collectStepOutputRefs(consumer.step.args);
     for (const ref of refs) {
+      // The run's work lease (#2748) is published under a reserved id once it
+      // is claimed; an Op that declares one may reference it from any step.
+      if (config.workLease && ref.step === WORK_LEASE_STEP_ID) continue;
       if (duplicateIds.has(ref.step)) {
         issues.push({
           opName: config.name,
@@ -395,7 +399,7 @@ export function validateStepOutputRefScope(
  *    schema (an empty `path` — the whole return value — is always valid).
  */
 export function validateStepOutputRefs(
-  config: Pick<OpConfig, "name" | "phases" | "onFailure">,
+  config: Pick<OpConfig, "name" | "phases" | "onFailure"> & Partial<Pick<OpConfig, "workLease">>,
   contracts: ReadonlyMap<string, ActivityContract>,
 ): ActivityContractIssue[] {
   const issues = validateStepOutputRefScope(config);

package/src/op/steward.test.ts

@@ -0,0 +1,212 @@
+/**
+ * A steward's declaration and its local form (#2731): `declareSteward`'s
+ * refusals, discovery beside the Ops, a local round that runs the steward's
+ * scheduled Ops under its own lease, and the rule that a steward turn and a
+ * coding agent share one checkout without colliding.
+ */
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { declareSteward, isStewardDeclaration, pickSteward, stewardFormFor, stewardLeaseName } from "./steward";
+import { discoverOps, discoverStewards } from "./discover";
+import { runOperatorRound, acquireStewardLease, formatRoundLine } from "./operator";
+import { readLease } from "../lifecycle/lease";
+import { readRunLedger } from "../lifecycle/run-ledger";
+
+const PROFILES: Record<string, ActivityProfile> = {};
+
+function op(name: string, cron?: string, fn = "fakeTurn"): OpConfig {
+  return {
+    name,
+    overview: `${name} fixture`,
+    phases: [{ name: "Run", steps: [{ kind: "activity", fn, args: {} }] }],
+    ...(cron ? { schedule: { cron, overlap: "skip" as const } } : {}),
+  };
+}
+
+function git(args: string[], cwd: string): { stdout: string; status: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", status: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  mkdirSync(join(dir, "app"), { recursive: true });
+  writeFileSync(join(dir, "app", "index.ts"), "export const hello = 1;\n");
+  git(["add", "app/index.ts"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+/** An `*.op.ts` file exporting a steward as a literal: the shape `declareSteward` returns, no imports. */
+function writeStewardFile(dir: string, file: string, name: string, ops: OpConfig[], form: unknown = { default: "local", environments: {} }): void {
+  mkdirSync(join(dir, "ops"), { recursive: true });
+  writeFileSync(
+    join(dir, "ops", file),
+    `export const steward = ${JSON.stringify({ kind: "Chant::Steward", name, ops, form })};\n`,
+  );
+}
+
+function turns(log: string[]): Map<string, ActivityFn> {
+  return new Map<string, ActivityFn>([
+    ["fakeTurn", async () => { log.push("turn"); return { ok: true }; }],
+  ]);
+}
+
+describe("declareSteward", () => {
+  test("normalises the form, local by default", () => {
+    const s = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+    expect(isStewardDeclaration(s)).toBe(true);
+    expect(s.form).toEqual({ default: "local", environments: {} });
+    expect(stewardFormFor(s)).toBe("local");
+  });
+
+  test("chooses the form per environment", () => {
+    const s = declareSteward({
+      name: "box-steward",
+      ops: [],
+      form: { default: "local", environments: { "fountain-k3d": "fountain" } },
+    });
+    expect(stewardFormFor(s, "minimal")).toBe("local");
+    expect(stewardFormFor(s, "fountain-k3d")).toBe("fountain");
+  });
+
+  test("reads an Op declaration through its props", () => {
+    const s = declareSteward({ name: "box-steward", ops: [{ props: op("box-release") }] });
+    expect(s.ops.map((o) => o.name)).toEqual(["box-release"]);
+  });
+
+  test("a brokered steward names its capabilities and holds no vault (#2726)", () => {
+    const s = declareSteward({ name: "a", ops: [], capabilities: ["fountain", "inference", "fountain"] });
+    expect(s.capabilities).toEqual(["fountain", "inference"]);
+    expect(s.vault).toBeNull();
+    expect(declareSteward({ name: "b", ops: [], vault: "creds" }).vault).toBe("creds");
+    expect(() => declareSteward({ name: "c", ops: [], capabilities: ["fountain"], vault: "creds" })).toThrow(/holds no credential/);
+  });
+
+  test("refuses what would make two writers or a promise it can't keep", () => {
+    expect(() => declareSteward({ name: "a", ops: [op("x"), op("x")] })).toThrow(/listed twice/);
+    expect(() => declareSteward({ name: "a", ops: [{ ...op("x"), schedule: { cron: "* * * * *", overlap: "buffer" as never } }] })).toThrow(/overlap "buffer"/);
+    expect(() => declareSteward({ name: "a", ops: [op("x", "not a cron")] })).toThrow(/Steward "a": op "x"/);
+    expect(() => declareSteward({ name: "../a", ops: [] })).toThrow(/steward's name/);
+    expect(() => declareSteward({ name: "a", ops: [], form: "cloud" as never })).toThrow(/"local" or "fountain"/);
+    expect(() => declareSteward({ name: "a", ops: [], form: { default: "local", environments: { "a/b": "fountain" } } })).toThrow(/can't be an environment/);
+  });
+});
+
+describe("discoverStewards", () => {
+  test("finds a steward in an *.op.ts file, and discoverOps doesn't call that file an error", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeStewardFile(dir, "steward.op.ts", "box-steward", [op("box-converge", "* * * * *")]);
+      const { stewards, errors } = await discoverStewards({ cwd: dir });
+      expect(errors).toEqual([]);
+      expect([...stewards.keys()]).toEqual(["box-steward"]);
+      expect(stewards.get("box-steward")!.exportName).toBe("steward");
+      expect((await discoverOps({ cwd: dir })).errors).toEqual([]);
+    });
+  });
+
+  test("refuses one Op listed by two stewards", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeStewardFile(dir, "a.op.ts", "first", [op("box-converge", "* * * * *")]);
+      writeStewardFile(dir, "b.op.ts", "second", [op("box-converge", "* * * * *")]);
+      const { stewards, errors, conflicts } = await discoverStewards({ cwd: dir });
+      expect([...stewards.keys()]).toEqual(["first"]);
+      expect(errors).toEqual([]);
+      expect(conflicts).toHaveLength(1);
+      expect(conflicts[0]).toMatch(/steward "second" lists op "box-converge", which steward "first" already runs/);
+    });
+  });
+
+  test("pickSteward takes the only steward, or the named one, and refuses otherwise", () => {
+    const one = new Map([["box-steward", { declaration: declareSteward({ name: "box-steward", ops: [] }) }]]);
+    expect(pickSteward(one, "")).toMatchObject({ name: "box-steward" });
+    expect(pickSteward(one, "other")).toMatch(/No steward "other"/);
+    expect(pickSteward(new Map(), "")).toMatch(/No steward is declared/);
+    const two = new Map([...one, ["b", { declaration: declareSteward({ name: "b", ops: [] }) }]]);
+    expect(pickSteward(two, "")).toMatch(/2 stewards are declared/);
+  });
+});
+
+describe("a local steward round", () => {
+  test("runs only the scheduled Ops, each on its cron, and records each run", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({
+        name: "box-steward",
+        ops: [op("box-converge", "* * * * *"), op("box-dispatch", "*/5 * * * *"), op("box-release")],
+      });
+      const log: string[] = [];
+      // 10:01 fires every minute, not every five.
+      const now = () => new Date(2026, 8, 25, 10, 1, 0);
+      const events = await runOperatorRound({ cwd: dir, holder: "h1", steward, activities: turns(log), profiles: PROFILES, now });
+      expect(events.map((e) => [e.kind, e.op])).toEqual([
+        ["ticked", "box-converge"],
+        ["skipped-not-due", "box-dispatch"],
+      ]);
+      // box-release has no schedule: it runs when asked, never on a round.
+      expect(log).toEqual(["turn"]);
+      expect((await readRunLedger("local", "box-converge", { cwd: dir })).records).toHaveLength(1);
+      expect((await readLease(stewardLeaseName("box-steward"), { cwd: dir })).record?.holder).toBe("h1");
+    });
+  });
+
+  test("a second holder of the same steward ticks nothing", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *")] });
+      expect((await acquireStewardLease("box-steward", "h1", { cwd: dir })).acquired).toBe(true);
+      const log: string[] = [];
+      const events = await runOperatorRound({ cwd: dir, holder: "h2", steward, activities: turns(log), profiles: PROFILES });
+      expect(events).toEqual([{ kind: "steward-busy", op: "_stewards/box-steward", env: "-", steward: "box-steward", heldBy: "h1" }]);
+      expect(formatRoundLine(events[0])).toBe("operator: steward box-steward skipped=1(steward-lease-held:h1)");
+      expect(log).toEqual([]);
+    });
+  });
+
+  test("a coding agent edits app/ and holds the index lock during a steward turn, and neither collides", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = git(["rev-parse", "HEAD"], dir).stdout.trim();
+      const steward = declareSteward({ name: "box-steward", ops: [op("box-converge", "* * * * *", "agentEditsMidTurn")] });
+      const edited = "export const hello = 2; // the coding agent's edit\n";
+      const lock = join(dir, ".git", "index.lock");
+      const activities = new Map<string, ActivityFn>([
+        [
+          "agentEditsMidTurn",
+          async () => {
+            // The coding agent, mid-turn: an edit to the app, and a commit in
+            // progress that holds git's index lock.
+            writeFileSync(join(dir, "app", "index.ts"), edited);
+            writeFileSync(lock, "");
+            return { ok: true };
+          },
+        ],
+      ]);
+
+      const events = await runOperatorRound({ cwd: dir, holder: "h1", steward, activities, profiles: PROFILES });
+      expect(events.map((e) => e.kind)).toEqual(["ticked"]);
+
+      // The steward's writes landed where chant writes: the run ledger and the lease refs.
+      expect((await readRunLedger("local", "box-converge", { cwd: dir })).records).toHaveLength(1);
+      expect(git(["rev-parse", "--verify", "refs/heads/chant/lifecycle"], dir).status).toBe(0);
+
+      // And none of them touched the checkout: the agent's edit is intact, its
+      // lock is still its own, and HEAD and the index are where they were.
+      expect(readFileSync(join(dir, "app", "index.ts"), "utf-8")).toBe(edited);
+      expect(existsSync(lock)).toBe(true);
+      rmSync(lock); // the agent's commit finishes; git status needs the lock gone
+
+      expect(git(["rev-parse", "HEAD"], dir).stdout.trim()).toBe(head);
+      expect(git(["status", "--porcelain"], dir).stdout).toBe(" M app/index.ts\n");
+      expect(git(["diff", "--cached", "--name-only"], dir).stdout).toBe("");
+    });
+  });
+});

package/src/op/steward.ts

@@ -0,0 +1,253 @@
+/**
+ * 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 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}`;
+}
+
+/**
+ * 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>`;
+}