@intentius/chant 0.90.0 → 0.93.0

package/src/op/decide-config.test.ts

@@ -0,0 +1,52 @@
+/**
+ * The `decide` block in chant.config, the activity's contract, and the step
+ * builder (#2828: the systemone lexicon's plugin tests, re-homed in core).
+ */
+
+import { describe, expect, it } from "vitest";
+import { ChantConfigSchema } from "../config";
+import { decideContract } from "./activities/activity-contracts";
+import * as activities from "./activities";
+import { decide } from "./builders";
+
+describe("decide.backends in chant.config", () => {
+  const valid = (config: Record<string, unknown>) => ChantConfigSchema.safeParse(config).success;
+
+  it("accepts env and brokered keys, and a keyless local backend", () => {
+    expect(
+      valid({
+        decide: {
+          backends: {
+            systemone: { url: "https://api.typesafe.ai", key: { env: "TYPESAFE_API_KEY" } },
+            studio: { url: "http://127.0.0.1:7071", key: { capability: "inference", member: "box" }, timeoutMs: 5000 },
+            local: { url: "http://127.0.0.1:8080" },
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("refuses a literal key, an unknown field, and an unknown key in the block", () => {
+    expect(valid({ decide: { backends: { s: { url: "https://x", key: "sk-literal" } } } })).toBe(false);
+    expect(valid({ decide: { backends: { s: { url: "https://x", token: { env: "K" } } } } })).toBe(false);
+    expect(valid({ decide: { backend: {} } })).toBe(false);
+  });
+});
+
+describe("the decide activity and its contract", () => {
+  it("is one of core's activities, with a contract of the same name", () => {
+    expect(typeof (activities as Record<string, unknown>).decide).toBe("function");
+    expect(decideContract.name).toBe("decide");
+  });
+
+  it("the contract refuses a literal key and an unknown arg", () => {
+    expect(decideContract.args.safeParse({ point: "p", backends: { s: { url: "https://x", key: { env: "K" } } } }).success).toBe(true);
+    expect(decideContract.args.safeParse({ point: "p", backends: { s: { url: "https://x", key: "sk-literal" } } }).success).toBe(false);
+    expect(decideContract.args.safeParse({ point: "p", pont: "typo" }).success).toBe(false);
+  });
+
+  it("the builder makes a fastIdempotent decide step with the point first", () => {
+    const step = decide("slice-tier", { read: { "work-item": "W-002" }, subject: "W-002", id: "tier" });
+    expect(step).toMatchObject({ kind: "activity", fn: "decide", args: { point: "slice-tier", read: { "work-item": "W-002" }, subject: "W-002" }, profile: "fastIdempotent", id: "tier" });
+  });
+});

package/src/op/decide-config.ts

@@ -0,0 +1,80 @@
+/**
+ * The `decide` block in `chant.config.ts`: the backends a decision point's
+ * model decider names, which the `decide` Op activity calls (#2828).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ *
+ * export default {
+ *   decide: {
+ *     backends: {
+ *       systemone: { url: "https://api.typesafe.ai", key: { env: "TYPESAFE_API_KEY" } },
+ *       local: { url: "http://127.0.0.1:8080" },
+ *       studio: { url: "http://127.0.0.1:7071", key: { capability: "inference", member: "box" } },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A point's model decider says `"backend": "systemone"`, and that name is the
+ * key here. A backend is an endpoint that speaks the `POST /v1/systemone` wire
+ * format (TypeSafe's, or any server that implements it, #2491) and where its
+ * key comes from.
+ *
+ * The key is never a literal. It is either an environment variable's name, or
+ * a capability the workspace declares as brokered on a box member (#2726).
+ * With a brokered capability the broker holds the credential: it either sets
+ * the variable `env` names for this process, or it is itself the endpoint and
+ * adds the key on the way through, in which case no key is sent from here.
+ * SYS001 refuses a string literal where a key goes.
+ *
+ * This module holds only the schemas, so `../config.ts` can validate the
+ * block without loading the client or anything under `workspace/`.
+ */
+
+import { z } from "zod";
+
+/** A key read from an environment variable at call time. */
+export const envKeySchema = z.strictObject({
+  /** The variable's name. */
+  env: z.string().min(1),
+});
+
+/**
+ * A key reached through a capability a box member declares as brokered
+ * (`box.capabilities` in `chant.workspace.json`, #2726). The capability must be
+ * declared and name a broker, or the call is refused.
+ */
+export const brokeredKeySchema = z.strictObject({
+  /** The capability's name in the box block, such as `inference`. */
+  capability: z.string().min(1),
+  /** The member whose box declares it. Without it, the one member that declares the capability. */
+  member: z.string().min(1).optional(),
+  /**
+   * The environment variable the broker sets with the scoped key. Without it,
+   * the broker is the endpoint and adds the key itself, so none is sent.
+   */
+  env: z.string().min(1).optional(),
+});
+
+export const keySchema = z.union([envKeySchema, brokeredKeySchema]);
+
+export const backendSchema = z.strictObject({
+  /** The server's base URL. `/v1/systemone` is appended. */
+  url: z.string().min(1),
+  /** Where the bearer key comes from. Omitted for a server that takes none, such as a local one. */
+  key: keySchema.optional(),
+  /** How long to wait for an answer before the backend counts as unreachable, in milliseconds. Default 30000. */
+  timeoutMs: z.number().int().positive().optional(),
+});
+
+export const decideConfigSchema = z.strictObject({
+  /** Backend name, as a point's model decider names it, to the backend. */
+  backends: z.record(z.string(), backendSchema).optional(),
+});
+
+export type EnvKey = z.infer<typeof envKeySchema>;
+export type BrokeredKey = z.infer<typeof brokeredKeySchema>;
+export type BackendKey = z.infer<typeof keySchema>;
+export type DecideBackend = z.infer<typeof backendSchema>;
+export type DecideConfig = z.infer<typeof decideConfigSchema>;

package/src/op/decide-read-inputs.ts

@@ -0,0 +1,117 @@
+/**
+ * A point's inputs, read through the read contract.
+ *
+ * A point names each input as a read-contract output, optionally with a
+ * dotted field: `work-item.criteria` is the `criteria` field of a work item as
+ * `records --json` lists it (#2738). The decide activity takes, for each
+ * output, what to read (`read: { "work-item": "W-002" }`), reads it the way
+ * the read contract does, and gives each input its field. Values passed in
+ * `inputs` are taken as given and win over read ones.
+ *
+ * Read by id or name here:
+ *
+ *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`)
+ *   member                        a member, by name (`ls --json`)
+ *
+ * The other outputs a point may name (finding, region, commit, gate, release,
+ * environment, component) are passed in `inputs`, as the output printed them.
+ * These reads never call a model, and never write. The module loads code
+ * under `workspace/`, so the `decide` activity imports it on first call.
+ */
+
+import { declaredKindFiles, queryDeclaredRecords } from "../workspace/records-cli";
+import { listWorkspace } from "../workspace/ls";
+import { inputOutput } from "../workspace/points";
+
+/** The outputs {@link readInputs} reads by id or name. */
+export const READABLE_OUTPUTS = ["record", "decision", "work-item", "member"] as const;
+
+/** One output a decide step asked to read that could not be read. */
+export class InputReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InputReadError";
+  }
+}
+
+/** A field of `value` by dotted path, or undefined. */
+export function fieldOf(value: unknown, path: string): unknown {
+  let at: unknown = value;
+  for (const part of path.split(".")) {
+    if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part)) return undefined;
+    at = (at as Record<string, unknown>)[part];
+  }
+  return at;
+}
+
+async function readRecord(id: string, cwd: string, output: string): Promise<Record<string, unknown>> {
+  const set = await queryDeclaredRecords(declaredKindFiles(cwd), { cwd });
+  const unread: string[] = [];
+  for (const doc of set.kinds) {
+    if ("error" in doc) {
+      unread.push(`${doc.declared.path}: ${doc.error.code}`);
+      continue;
+    }
+    const found = doc.records.find((r) => r.id === id);
+    if (found) return found as unknown as Record<string, unknown>;
+  }
+  throw new InputReadError(`no declared record kind holds a record with id ${id} (read for ${output})${unread.length ? `; not read: ${unread.join(", ")}` : ""}`);
+}
+
+function readMember(name: string, cwd: string): Record<string, unknown> {
+  const doc = listWorkspace({ cwd });
+  if ("error" in doc) throw new InputReadError(`the workspace can't be listed: ${doc.error.code}: ${doc.error.message}`);
+  const found = doc.members.find((m) => m.name === name);
+  if (!found) throw new InputReadError(`the workspace has no member named ${name}`);
+  return found as unknown as Record<string, unknown>;
+}
+
+/**
+ * The value of one declared input from what was read for its output. A
+ * record's field is looked up in its front matter first, then in the record
+ * as `records --json` lists it (`state`, `valid`, `path`...). An input with no
+ * field is the whole value.
+ */
+function inputValue(input: string, output: string, read: Record<string, unknown>): unknown {
+  const field = input.length > output.length ? input.slice(output.length + 1) : "";
+  if (field === "") return read;
+  if (output === "member") return fieldOf(read, field);
+  const fromData = fieldOf(read.data, field);
+  return fromData !== undefined ? fromData : fieldOf(read, field);
+}
+
+export interface ReadInputsResult {
+  inputs: Record<string, unknown>;
+  /** Declared inputs of a read output that the value read does not have. Left out, so no table row matches on them. */
+  missing: string[];
+}
+
+/**
+ * Read each output `read` names, and give the point's inputs that name it
+ * their values. Throws an {@link InputReadError} for an output this does not
+ * read, one the point does not name, or an id that is not there.
+ */
+export async function readInputs(declared: string[], read: Record<string, string>, cwd: string): Promise<ReadInputsResult> {
+  const named = new Set(declared.map(inputOutput));
+  for (const output of Object.keys(read)) {
+    if (!(READABLE_OUTPUTS as readonly string[]).includes(output)) {
+      throw new InputReadError(`${output} is not read by id here; pass its values in inputs, as the read contract printed them (read takes ${READABLE_OUTPUTS.join(", ")})`);
+    }
+    if (!named.has(output)) throw new InputReadError(`the point reads no ${output} input (its inputs are ${declared.join(", ")})`);
+  }
+  const values = new Map<string, Record<string, unknown>>();
+  for (const [output, id] of Object.entries(read)) {
+    values.set(output, output === "member" ? readMember(id, cwd) : await readRecord(id, cwd, output));
+  }
+  const inputs: Record<string, unknown> = {};
+  const missing: string[] = [];
+  for (const input of declared) {
+    const output = inputOutput(input);
+    const value = values.get(output);
+    if (value === undefined) continue;
+    const v = inputValue(input, output, value);
+    if (v === undefined) missing.push(input);
+    else inputs[input] = v;
+  }
+  return { inputs, missing };
+}

package/src/op/discover.ts

@@ -5,6 +5,7 @@ import type { OpConfig } from "./types";
 import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
 import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
+import { isStewardDeclaration, type StewardDeclaration } from "./steward";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -152,6 +153,9 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
       const mod = (await import(filePath)) as Record<string, unknown>;
       const exported = opsExportedBy(mod);
 
+      // A file may hold a steward and no Op (#2731): the steward sits beside
+      // the Ops it runs, and `discoverStewards` reads it from here.
+      if (exported.length === 0 && Object.values(mod).some(isStewardDeclaration)) continue;
       if (exported.length === 0) {
         errors.push(
           `${filePath}: exports no Op. Expected \`export default Op({...})\` or a named export such as \`export const deploy = Op({...})\``,
@@ -180,3 +184,70 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   return { ops, errors };
 }
+
+export interface DiscoveredSteward {
+  declaration: StewardDeclaration;
+  filePath: string;
+  exportName: string;
+}
+
+export interface StewardDiscoveryResult {
+  stewards: Map<string, DiscoveredSteward>;
+  /** Files that could not be imported. */
+  errors: string[];
+  /** Stewards dropped because they would be a second writer: a name or an Op another steward already has. */
+  conflicts: string[];
+}
+
+/**
+ * Every steward declared in the project's `*.op.ts` files (#2731), found the
+ * way {@link discoverOps} finds Ops, keyed by the steward's name.
+ *
+ * Refuses, as errors, the two ways a project could end up with two writers:
+ * two stewards of one name, and one Op listed by two stewards. The steward
+ * declared first (in file walk order) keeps its entry; the other is dropped
+ * and reported in `conflicts`.
+ */
+export async function discoverStewards(opts?: { cwd?: string }): Promise<StewardDiscoveryResult> {
+  const errors: string[] = [];
+  const conflicts: string[] = [];
+  const stewards = new Map<string, DiscoveredSteward>();
+  const opOwner = new Map<string, string>();
+
+  const root = await findDiscoveryRoot(opts?.cwd);
+  const files = await collectOpFiles(root);
+
+  for (const filePath of files) {
+    let mod: Record<string, unknown>;
+    try {
+      mod = (await import(filePath)) as Record<string, unknown>;
+    } catch (err) {
+      errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    const seen = new Set<unknown>();
+    const exportNames = ["default", ...Object.keys(mod).filter((k) => k !== "default")];
+    for (const exportName of exportNames) {
+      const value = mod[exportName];
+      if (!isStewardDeclaration(value) || seen.has(value)) continue;
+      seen.add(value);
+      const prior = stewards.get(value.name);
+      if (prior) {
+        conflicts.push(`Duplicate steward "${value.name}" in ${filePath} and ${prior.filePath}`);
+        continue;
+      }
+      const claimed = value.ops.find((op) => opOwner.has(op.name));
+      if (claimed) {
+        conflicts.push(
+          `${filePath}: steward "${value.name}" lists op "${claimed.name}", which steward "${opOwner.get(claimed.name)}" already runs. ` +
+            `Two stewards running one Op are two writers; list it on one of them.`,
+        );
+        continue;
+      }
+      for (const op of value.ops) opOwner.set(op.name, value.name);
+      stewards.set(value.name, { declaration: value, filePath, exportName });
+    }
+  }
+
+  return { stewards, errors, conflicts };
+}

package/src/op/gate-approval.ts

@@ -32,7 +32,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { lexiconModulePath } from "../lexicon-module";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
 
 /** What a policy's decision does to the gate. */
@@ -226,7 +226,7 @@ export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePoli
   const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
   let mod: Partial<GatePolicyEvaluator>;
   try {
-    mod = (await import(spec)) as Partial<GatePolicyEvaluator>;
+    mod = (await importLexiconPackage(spec)) as Partial<GatePolicyEvaluator>;
   } catch (err) {
     throw new Error(
       `the gate's policy is evaluated by ${spec}, which could not be loaded: ` +

package/src/op/gate-wait.ts

@@ -0,0 +1,57 @@
+/**
+ * A step whose command stopped at a gate of its own (#2779).
+ *
+ * Some chant commands decide a gate themselves rather than through a `gate`
+ * step: `chant workspace upgrade` stages its patch, records
+ * `workspace-upgrade` / `<scope>` pending on the gate ledger, and exits 3.
+ * An Op step that runs such a command stops its run at that gate by throwing
+ * {@link GateWait} with the pending fact the command recorded. The executor
+ * ends the run there with status `gated`, as it does at a pending `gate`
+ * step: no later step runs, no `onFailure` phase runs, a work lease is
+ * released `gated`, and the run ledger names the gate, with the op it is
+ * recorded under when that isn't the run's own.
+ *
+ * Nothing waits. After `chant approve <op> <gate>` the next run runs the
+ * command again, the command finds the approval, and the step goes on. A
+ * local steward re-runs its own gated run on the first round after the
+ * approval (`./operator.ts`).
+ *
+ * `shell()` throws it for an exit code named in `gatedExit`
+ * (`./activities/shell.ts`); an activity of a lexicon can throw it too.
+ */
+
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+
+/** The marker {@link GateWait} carries, so a copy of core linked twice still recognises it. */
+const GATE_WAIT = Symbol.for("chant.op.GateWait");
+
+/**
+ * Thrown by an activity whose command stopped at a gate. Not a failure: the
+ * executor ends the run with status `gated` (see the module doc).
+ */
+export class GateWait extends Error {
+  readonly [GATE_WAIT] = true;
+  constructor(readonly pending: PendingGateRecord) {
+    super(`stopped at gate ${pending.op} / ${pending.gate}: approve it with \`chant approve ${pending.op} ${pending.gate}\` and run again`);
+    this.name = "GateWait";
+  }
+}
+
+/** Is this a {@link GateWait}? Duck-typed on the shared symbol. */
+export function isGateWait(err: unknown): err is GateWait {
+  return !!err && typeof err === "object" && (err as Record<symbol, unknown>)[GATE_WAIT] === true && "pending" in err;
+}
+
+/**
+ * `value` as a pending gate fact, or undefined when it isn't one: it needs
+ * the `op`, `gate`, `timestamp` and `expiresAt` every pending line on the
+ * gate ledger carries.
+ */
+export function asPendingGate(value: unknown): PendingGateRecord | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const v = value as Record<string, unknown>;
+  for (const key of ["op", "gate", "timestamp", "expiresAt"]) {
+    if (typeof v[key] !== "string" || v[key] === "") return undefined;
+  }
+  return { ...(v as unknown as PendingGateRecord), version: 1, kind: "pending" };
+}

package/src/op/gate.ts

@@ -481,8 +481,13 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
 /**
  * The line every renderer prints to say how a pending gate is cleared. A
  * component gate names its environment (#2574), so the approval picks that
- * environment's pending fact when others stand beside it.
+ * environment's pending fact when others stand beside it. A gate bound to a
+ * plan (#2300) gets `--plan <digest>` too (#2832), so the line approves the
+ * plan the reader was shown and not whatever is pending by the time they run
+ * it.
  */
-export function approveCommand(op: string, gate: string, environment?: string): string {
-  return environment === undefined ? `chant approve ${op} ${gate}` : `chant approve ${op} ${gate} --env ${environment}`;
+export function approveCommand(op: string, gate: string, environment?: string, planDigest?: string): string {
+  return `chant approve ${op} ${gate}` +
+    (environment === undefined ? "" : ` --env ${environment}`) +
+    (planDigest === undefined ? "" : ` --plan ${planDigest}`);
 }

package/src/op/generate-pipeline.ts

@@ -17,7 +17,7 @@
  */
 
 import { discoverOps, type DiscoveredOp } from "./discover";
-import { lexiconModulePath } from "../lexicon-module";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -37,7 +37,7 @@ import {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await importLexiconPackage(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

package/src/op/index.ts

@@ -1,9 +1,9 @@
 export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
-         guardValidate,
+         guardValidate, workEvidence,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
          spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove,
          spriteApplyNetworkPolicy, spriteApplyServices,
@@ -15,8 +15,12 @@ export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-life
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, OpSchedule, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
-export { outcomeAttributesOf } from "./types";
+export type { OpConfig, OpSchedule, OpWorkLease, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
+export { outcomeAttributesOf, WORK_LEASE_STEP_ID } from "./types";
+export {
+  RunWorkLease, workLeaseOutput, stewardWorkHolder, workLeaseProblems, workLeaseNeedsRunItem, LEASE_LOST, WORK_BRANCH_PREFIX,
+} from "./work-lease-run";
+export type { WorkLeaseOutput, WorkLeaseRunResult, WorkClaimOutcome, RunWorkLeaseOptions } from "./work-lease-run";
 export { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron";
 export {
   WatchOp, ReconcileOp, ApplyOp, ConvergeOp,
@@ -33,6 +37,10 @@ export type {
   LexiconUpgradeOpConfig, LexiconUpgradeOpResources,
   BehaviourOpConfig, BehaviourOpResources,
 } from "./composites";
+export type {
+  ConvergeSymptom, ResourceSymptom, ResourceObservation, ObservedResource, ResourceStatus,
+} from "../lifecycle/symptoms";
+export { parseResourceObservation, CONVERGE_RESOURCE_ENV } from "../lifecycle/symptoms";
 export { receiptActivities, receiptCheckInput } from "./receipt-store";
 export type {
   ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
@@ -47,7 +55,7 @@ export { loadActivities, loadProfiles, resolveActivity } from "./activity-regist
 export type { ActivityFn } from "./activity-registry";
 export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
 export type { LexiconActivityContractContributor } from "./activity-contract-registry";
-export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES } from "./activity-profiles";
+export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES, MAX_STEP_TIMEOUT } from "./activity-profiles";
 export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
@@ -100,8 +108,28 @@ export type {
 } from "./converge-rule";
 export {
   discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
-  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS,
+  formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease,
+  acquireStewardTurn, STEWARD_TURN_WAIT_MS,
 } from "./operator";
+export {
+  declareSteward, isStewardDeclaration, stewardFormFor, stewardOpConfig, normaliseStewardForm, stewardLeaseName,
+  stewardTurnLeaseName,
+  STEWARD_KIND, STEWARD_FORMS, STEWARD_NAME_PATTERN, DEFAULT_STEWARD_ENV,
+} from "./steward";
+export type {
+  StewardDeclaration, StewardDeclarationConfig, StewardForm, StewardFormSpec, StewardOpInput,
+} from "./steward";
+export { discoverStewards } from "./discover";
+export {
+  askPointInRun, brokeredModelAsk, isPointWait, PointWait, DEFAULT_INFERENCE_CAPABILITY,
+} from "./steward-points";
+export type { AskPointInRunOptions, BrokeredModelAsk, WaitingPoint } from "./steward-points";
+export { GateWait, isGateWait } from "./gate-wait";
+export {
+  currentStewardTurn, enterStewardTurn, setStewardTurn, resetStewardTurn, STEWARD_ENV,
+} from "./steward-turn";
+export type { StewardTurn } from "./steward-turn";
+export type { DiscoveredSteward, StewardDiscoveryResult } from "./discover";
 export type {
   OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions,
   ChangeSubscriber, OperatorSignalEvent,

package/src/op/lifecycle-receipt-store.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { lifecycleReceiptFile, lifecycleReceiptStore } from "./lifecycle-receipt-store";
+import { receiptActivities, type EffectReceiptRef } from "./receipt-store";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+function initRepo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+const RECEIPT: EffectReceiptRef = { name: "fly-migration:shop/001_init.sql", effect: "fly-migrate", flavor: "hash", inputs: {} };
+
+describe("lifecycleReceiptStore", () => {
+  test("a receipt is absent, then written under <env>/receipts on chant/lifecycle", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const store = lifecycleReceiptStore({ environment: "prod", cwd: dir });
+      expect(await store.read(RECEIPT)).toBeUndefined();
+      await store.write(RECEIPT, "sha256:abc");
+      expect(await store.read(RECEIPT)).toBe("sha256:abc");
+      const shown = git(["show", `chant/lifecycle:prod/${lifecycleReceiptFile(RECEIPT.name)}`], dir);
+      expect(shown.exitCode).toBe(0);
+      expect(shown.stdout.trim()).toBe("sha256:abc");
+      // Another environment has its own receipts.
+      expect(await lifecycleReceiptStore({ environment: "dev", cwd: dir }).read(RECEIPT)).toBeUndefined();
+    });
+  });
+
+  test("bound to core's receipt activities, the effect step's read-compare-write goes through it", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const acts = receiptActivities(lifecycleReceiptStore({ environment: "prod", cwd: dir }));
+      const first = await acts.receiptRead({ receipt: RECEIPT, expectation: "sha256:1" });
+      expect(first).toEqual({ current: null, expectation: "sha256:1", applied: false });
+      await acts.receiptWrite({ receipt: RECEIPT, expectation: "sha256:1" });
+      expect((await acts.receiptRead({ receipt: RECEIPT, expectation: "sha256:1" })).applied).toBe(true);
+    });
+  });
+
+  test("with no environment and no CHANT_ENV it refuses rather than guessing", async () => {
+    const store = lifecycleReceiptStore({ env: {} });
+    await expect(store.read(RECEIPT)).rejects.toThrow(/no environment/);
+  });
+
+  test("receipt names become safe file names", () => {
+    expect(lifecycleReceiptFile("fly-migration:app/002 add.sql")).toBe("receipts/fly-migration_app_002_add.sql.receipt");
+  });
+});

package/src/op/lifecycle-receipt-store.ts

@@ -0,0 +1,61 @@
+/**
+ * A receipt store on the `chant/lifecycle` branch (#2736, ws-056).
+ *
+ * The aws and k8s rows keep receipts in the cloud they deploy to (an SSM
+ * parameter, a ConfigMap). A target with no store of its own, such as a Fly
+ * Machine, keeps them next to the release ledger instead: one file per receipt
+ * at `<env>/receipts/<name>.receipt` on the lifecycle branch, written through
+ * the same plumbing as the release and build ledgers (../lifecycle/git.ts), so
+ * a workspace member's receipts land under its own `_members/<member>/` prefix.
+ *
+ * The receipt is per environment, not per checkout: every checkout that
+ * fetches the branch sees which effects have fired there. Writing is local;
+ * the ledger push that follows a recorded release (or `chant lifecycle push`)
+ * carries it to the remote.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "../lifecycle/git";
+import type { EffectReceiptRef, ReceiptStore } from "./receipt-store";
+
+/** Options for {@link lifecycleReceiptStore}. */
+export interface LifecycleReceiptStoreOptions {
+  /** The environment whose ledger directory holds the receipts. Omitted, `CHANT_ENV` answers. */
+  environment?: string;
+  /** The checkout whose lifecycle branch is written. Defaults to the working directory. */
+  cwd?: string;
+  /** Environment record the `CHANT_ENV` fallback reads. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+}
+
+/** The file name a receipt is kept under: its name with anything outside `[A-Za-z0-9_.-]` replaced. */
+export function lifecycleReceiptFile(name: string): string {
+  return `receipts/${name.replace(/[^a-zA-Z0-9_.-]/g, "_")}.receipt`;
+}
+
+/**
+ * A {@link ReceiptStore} over the lifecycle branch. The environment is resolved
+ * at first use, so constructing the store reads nothing; with none given and no
+ * `CHANT_ENV`, a read or write fails rather than guessing a directory.
+ */
+export function lifecycleReceiptStore(options: LifecycleReceiptStoreOptions = {}): ReceiptStore {
+  const environment = (): string => {
+    const env = options.environment ?? (options.env ?? process.env).CHANT_ENV;
+    if (!env) {
+      throw new Error(
+        "lifecycle receipt store: no environment. Receipts are kept per environment on chant/lifecycle; " +
+          "run with --env <name>, set CHANT_ENV, or pass the environment explicitly.",
+      );
+    }
+    return env;
+  };
+  const opts = options.cwd ? { cwd: options.cwd } : undefined;
+  return {
+    async read(receipt: EffectReceiptRef): Promise<string | undefined> {
+      const content = await readBlobFromPath(environment(), lifecycleReceiptFile(receipt.name), opts);
+      return content === null ? undefined : content.trim();
+    },
+    async write(receipt: EffectReceiptRef, expectation: string): Promise<void> {
+      await writeBlobToPath(environment(), lifecycleReceiptFile(receipt.name), `${expectation}\n`, `Receipt ${receipt.name}`, opts);
+    },
+  };
+}