@intentius/chant 0.89.0 → 0.91.0

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>`;
+}

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;
 }
 
 /**

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;
+}
+