@intentius/chant 0.57.0 → 0.58.0

package/src/op/runtimes/local.test.ts

@@ -0,0 +1,181 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { OpConfig } from "../types";
+import type { OpRunRecord, OpRunRecordInput } from "../runtime";
+
+const loadActivitiesMock = vi.fn();
+const loadProfilesMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+
+vi.mock("../activity-registry", async () => {
+  const actual = await vi.importActual<typeof import("../activity-registry")>("../activity-registry");
+  return {
+    ...actual,
+    loadActivities: (...args: unknown[]) => loadActivitiesMock(...args),
+    loadProfiles: (...args: unknown[]) => loadProfilesMock(...args),
+  };
+});
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+
+// The gate ledger a local run consults (#2119) is the `chant/lifecycle` orphan
+// branch by default. Point it at memory here so a unit test never writes a
+// fact to the real repo.
+vi.mock("../gate", async () => {
+  const actual = await vi.importActual<typeof import("../gate")>("../gate");
+  return { ...actual, gitGateLedgerPort: () => actual.memoryGateLedgerPort() };
+});
+
+/** The run ledger, in memory — see the mock below. Cleared before each test. */
+const runLedger: OpRunRecord[] = [];
+
+// The run ledger this runtime appends to and answers from (#2118) is that same
+// orphan branch. In memory here for the same reason the gate ledger is: a unit
+// test must never leave a fact in the real repo. Everything else about the
+// ledger path stays real, so these tests exercise the actual read-back.
+vi.mock("../../lifecycle/run-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/run-ledger")>("../../lifecycle/run-ledger");
+  return {
+    ...actual,
+    appendRunRecord: async (input: OpRunRecordInput) => {
+      const record: OpRunRecord = { version: 1, ...input, id: input.id ?? `run-${runLedger.length}` };
+      runLedger.push(record);
+      return { commit: "0".repeat(40), record };
+    },
+    readRunLedger: async (_env: string, op: string) => ({
+      records: runLedger.filter((r) => r.op === op),
+      malformed: 0,
+    }),
+  };
+});
+
+const { createLocalOpRuntime } = await import("./local");
+
+function op(name: string, steps: unknown[]): OpConfig {
+  return {
+    name,
+    overview: `${name} overview`,
+    phases: [{ name: "main", steps }],
+  } as unknown as OpConfig;
+}
+
+describe("the local op runtime", () => {
+  beforeEach(() => {
+    loadActivitiesMock.mockReset();
+    loadProfilesMock.mockReset().mockResolvedValue({ fastIdempotent: { timeout: "1m" } });
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: { lexicons: ["aws"] } });
+    runLedger.length = 0;
+  });
+
+  test("start runs the Op and reports it completed, with the executor's own result", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({ done: true }))]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), {});
+    const status = await handle.result();
+
+    expect(runtime.name).toBe("local");
+    expect(status.state).toBe("completed");
+    expect(status.result?.status).toBe("ok");
+    expect(status.records?.map((r) => r.fn)).toEqual(["ok"]);
+  });
+
+  test("the project's configured lexicons decide which appliers load", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    await (await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), {})).result();
+    expect(loadActivitiesMock).toHaveBeenCalledWith(["aws"]);
+  });
+
+  test("a failing step settles as failed rather than throwing out of result()", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["boom", vi.fn(async () => { throw new Error("nope"); })]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(op("bad", [{ kind: "activity", fn: "boom", args: {} }]), {});
+    const status = await handle.result();
+
+    expect(status.state).toBe("failed");
+    expect(status.result?.status).toBe("fail");
+  });
+
+  test("progress is called once per settled step", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    const seen: string[] = [];
+
+    const handle = await runtime.start(
+      op("hello", [
+        { kind: "activity", fn: "ok", args: {} },
+        { kind: "activity", fn: "ok", args: {} },
+      ]),
+      { progress: (record) => seen.push(record.fn) },
+    );
+    await handle.result();
+
+    expect(seen).toEqual(["ok", "ok"]);
+  });
+
+  test("a gated Op settles as gated, naming the gate, and runs nothing after it (#2119)", async () => {
+    const after = vi.fn(async () => ({}));
+    loadActivitiesMock.mockResolvedValue(new Map([["after", after]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(
+      op("gated", [
+        { kind: "gate", signalName: "approve-prod" },
+        { kind: "activity", fn: "after", args: {} },
+      ]),
+      {},
+    );
+    const status = await handle.result();
+
+    expect(status.state).toBe("gated");
+    expect(status.gate?.name).toBe("approve-prod");
+    expect(status.result?.status).toBe("gated");
+    expect(after).not.toHaveBeenCalled();
+  });
+
+  test("status, log and list answer from the run ledger (#2118)", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    const config = op("hello", [{ kind: "activity", fn: "ok", args: {} }]);
+
+    expect(await runtime.status("hello")).toBeUndefined();
+    expect(await runtime.log("hello")).toEqual([]);
+
+    await (await runtime.start(config, {})).result();
+    await (await runtime.start(config, {})).result();
+
+    // Two records on the ledger, not two entries in a process-local map.
+    expect(runLedger.map((r) => r.op)).toEqual(["hello", "hello"]);
+    expect((await runtime.status("hello"))?.state).toBe("completed");
+    expect(await runtime.log("hello")).toHaveLength(2);
+    expect(await runtime.log("hello", { limit: 1 })).toHaveLength(1);
+    expect((await runtime.list([config])).get("hello")?.state).toBe("completed");
+
+    // Newest first, and the ledger's own id is the run id a reader sees.
+    const [newest] = await runtime.log("hello");
+    expect(newest.id).toBe(runLedger[1].id);
+    expect((await runtime.status("hello"))?.runId).toBe(runLedger[1].id);
+  });
+
+  test("a run the ledger could not record still answers from this process", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    const config = op("hello", [{ kind: "activity", fn: "ok", args: {} }]);
+
+    await (await runtime.start(config, {})).result();
+    // Whatever the ledger holds is lost (an unwritable branch, a project that
+    // is not a checkout); the in-memory history is the fallback.
+    runLedger.length = 0;
+
+    expect((await runtime.status("hello"))?.state).toBe("completed");
+    expect((await runtime.list([config])).get("hello")?.state).toBe("completed");
+  });
+
+  test("cancel says why a foreground run has nothing to cancel", async () => {
+    const runtime = createLocalOpRuntime();
+    await expect(runtime.cancel("hello", { force: true })).rejects.toThrow(/foreground/);
+  });
+});

package/src/op/runtimes/local.ts

@@ -0,0 +1,212 @@
+/**
+ * The built-in `local` op runtime (#2121, epic #2114).
+ *
+ * Wraps `runOpLocally` (../local-executor.ts) in the {@link OpRuntimeProvider}
+ * contract so `chant run <op>` has one dispatch path whether the run is hosted
+ * here or by a lexicon's `opRuntime`. Behaviour is the executor's, unchanged:
+ * activities and profiles come from the project's configured lexicons, a gate
+ * is decided against the gate ledger and ends the run `gated` (#2119), and
+ * Ctrl-C aborts through the caller's `AbortSignal`.
+ *
+ * Status, log and list read the run ledger (#2118): every run this provider
+ * starts appends one `OpRunRecord` to `<env>/runs__<op>.jsonl` on the
+ * lifecycle branch, so an answer here outlives the process that produced it
+ * and a run started by cron, CI or another machine is visible too. The
+ * in-memory history stays as the fallback for the case the ledger cannot cover
+ * — a project that is not a checkout, or a run whose append failed — so a
+ * `chant run` followed by `chant run status` in the same process still
+ * answers.
+ */
+
+import { loadChantConfig } from "../../config";
+import { loadActivities, loadProfiles } from "../activity-registry";
+import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
+import { runComponents } from "../../components/cli-support";
+import { discoverOps } from "../discover";
+import { readRunLedger, runEnvOf, DEFAULT_RUN_ENV } from "../../lifecycle/run-ledger";
+import type { OpConfig } from "../types";
+import {
+  runStateOf,
+  type OpRunHandle,
+  type OpRunRecord,
+  type OpRunStartOptions,
+  type OpRunStatus,
+  type OpRuntimeProvider,
+} from "../runtime";
+
+/** Every run this process has started, newest last, keyed by op name. */
+type RunLog = Map<string, OpRunStatus[]>;
+
+function statusFrom(
+  op: string,
+  runId: string,
+  startedAt: string,
+  result: OpRunResult,
+): OpRunStatus {
+  return {
+    op,
+    runId,
+    state: runStateOf(result.status),
+    startedAt,
+    endedAt: new Date().toISOString(),
+    records: result.records,
+    result,
+    ...(result.gate ? { gate: { name: result.gate.gate, since: result.gate.timestamp } } : {}),
+  };
+}
+
+/**
+ * A ledger record read back as a runtime status. `records` and `result` are
+ * absent on purpose: the ledger keeps each step's verdict, not the activity
+ * return values a live `OpRunResult` carries, and inventing them would make a
+ * replayed answer look like a live one.
+ */
+function statusFromRecord(record: OpRunRecord): OpRunStatus {
+  return {
+    op: record.op,
+    runId: record.id,
+    state: runStateOf(record.status),
+    startedAt: record.started,
+    endedAt: record.ended,
+    ...(record.gate ? { gate: record.gate } : {}),
+  };
+}
+
+/**
+ * Build the local provider. `projectPath` is where `chant.config.ts` is read
+ * from to decide which cloud appliers to load — the same best-effort read the
+ * CLI did inline before the seam existed.
+ */
+export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRuntimeProvider {
+  const runs: RunLog = new Map();
+  const projectPath = opts.projectPath ?? process.cwd();
+
+  const record = (status: OpRunStatus): void => {
+    const existing = runs.get(status.op);
+    if (existing) existing.push(status);
+    else runs.set(status.op, [status]);
+  };
+
+  // A run ledger is keyed `<env>/runs__<op>.jsonl`, and `status`/`log` are
+  // handed a name rather than a config. `start` and `list` know the config and
+  // seed this; otherwise the same `*.op.ts` scan that found the Op in the
+  // first place resolves its `labels.Env`.
+  const envs = new Map<string, string>();
+  const noteEnv = (op: OpConfig): string => {
+    const env = runEnvOf(op);
+    envs.set(op.name, env);
+    return env;
+  };
+
+  const envFor = async (op: string): Promise<string> => {
+    const known = envs.get(op);
+    if (known) return known;
+    try {
+      const { ops } = await discoverOps({ cwd: projectPath });
+      for (const discovered of ops.values()) noteEnv(discovered.config);
+    } catch {
+      // Not a checkout — nothing to scan; fall through to the default env.
+    }
+    return envs.get(op) ?? DEFAULT_RUN_ENV;
+  };
+
+  /** This op's ledger history, oldest first. Empty when there is no ledger to read. */
+  const ledgerFor = async (op: string, env?: string): Promise<OpRunRecord[]> => {
+    try {
+      const { records } = await readRunLedger(env ?? (await envFor(op)), op, { cwd: projectPath });
+      return records;
+    } catch {
+      return [];
+    }
+  };
+
+  return {
+    name: "local",
+
+    async start(op: OpConfig, startOpts: OpRunStartOptions): Promise<OpRunHandle> {
+      // The project's configured lexicons decide which cloud appliers to load
+      // (aws -> floci, gcp -> gcpApply, azure -> az group). Best-effort: an
+      // unreadable config just yields the base activities.
+      let lexicons: string[] = [];
+      try {
+        lexicons = (await loadChantConfig(projectPath)).config.lexicons ?? [];
+      } catch {
+        // No/invalid chant.config — base activities only.
+      }
+
+      const [activities, profiles] = await Promise.all([loadActivities(lexicons), loadProfiles()]);
+
+      const runId = `local-${Date.now()}`;
+      const startedAt = new Date().toISOString();
+      noteEnv(op);
+
+      const settled = (async (): Promise<OpRunStatus> => {
+        try {
+          const result = await runOpLocally(
+            op,
+            activities,
+            profiles,
+            startOpts.signal,
+            {
+              runId,
+              // The run's outcome is a durable fact (#2118): the executor
+              // appends it here, at the one seam every local run passes
+              // through, rather than in the CLI handler above it.
+              ledger: { cwd: projectPath },
+              ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+            },
+          );
+          const status = statusFrom(op.name, runId, startedAt, result);
+          record(status);
+          return status;
+        } catch (err) {
+          if (err instanceof OpRunFailure) {
+            const status = statusFrom(op.name, runId, startedAt, err.result);
+            record(status);
+            return status;
+          }
+          throw err;
+        }
+      })();
+
+      return { op: op.name, runId, result: () => settled };
+    },
+
+    async status(op: string): Promise<OpRunStatus | undefined> {
+      const newest = (await ledgerFor(op)).at(-1);
+      if (newest) return statusFromRecord(newest);
+      const history = runs.get(op);
+      return history?.[history.length - 1];
+    },
+
+    async log(op: string, logOpts?: { limit?: number }): Promise<OpRunRecord[]> {
+      const history = (await ledgerFor(op)).reverse();
+      return logOpts?.limit === undefined ? history : history.slice(0, logOpts.limit);
+    },
+
+    async list(ops: OpConfig[]): Promise<Map<string, OpRunStatus | undefined>> {
+      const out = new Map<string, OpRunStatus | undefined>();
+      for (const op of ops) {
+        const newest = (await ledgerFor(op.name, noteEnv(op))).at(-1);
+        if (newest) {
+          out.set(op.name, statusFromRecord(newest));
+          continue;
+        }
+        const history = runs.get(op.name);
+        out.set(op.name, history?.[history.length - 1]);
+      }
+      return out;
+    },
+
+    async cancel(op: string): Promise<void> {
+      throw new Error(
+        `the local runtime runs "${op}" in the foreground — there is no detached run to cancel. ` +
+          `Press Ctrl-C in the terminal running it, or pass --on <lexicon> for a hosted run.`,
+      );
+    },
+
+    runComponents(path, selector, options) {
+      return runComponents(path, selector, options);
+    },
+  };
+}

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

@@ -5,14 +5,16 @@
  * An Op's steps run in a fixed sequence chant already knows: phases in
  * order, and (within a non-parallel phase) steps in order. Today the only
  * way a value escapes a step is `outcomeAttribute`, which stringifies it
- * into a Temporal search attribute — a UI filter, not something a later
- * step can consume. `StepOutputRef` is the mechanism that lets a later
+ * into a named run outcome — something to read a run back by, not something a
+ * later step can consume. `StepOutputRef` is the mechanism that lets a later
  * step's `args` hold a *reference* to an earlier step's declared return
  * value instead.
  *
  * Deliberately a reference, not an expression: `diff.out.driftedStacks` is
- * a value placeholder the build resolves and the serializer compiles into a
- * real local variable in the generated workflow — never `diff.out.count >
+ * a value placeholder that stays inert in the Op's data until the executor
+ * substitutes the producing step's recorded result for it, just before the
+ * consuming activity is called (`../op/local-executor.ts`'s
+ * `resolveStepOutputRefs` over `resultsById`) — never `diff.out.count >
  * 0` or a `.map()` over a reference. That property (an Op is data you can
  * read and know what it does, not a program) is exactly what makes it safe
  * to add this without Ops becoming programs; see the issue's "line not to
@@ -42,10 +44,10 @@
  * Cross-contract type compatibility (chant #1950 pre-merge review, finding
  * 3): `validateStepOutputRefs` checks the producer side (a registered
  * contract with a `returns` schema, and — when `path` is set — that the path
- * resolves on it) and, separately, `validateActivitySteps`/TMP012 checks a
+ * resolves on it) and, separately, `validateActivitySteps`/OPS012 checks a
  * step's `args` against its own contract's `args` schema — but a
  * {@link StepOutputRef} sitting in `args` is a placeholder object at build
- * time, not the value it resolves to, so TMP012 skips it (see
+ * time, not the value it resolves to, so OPS012 skips it (see
  * `activity-contract.ts`'s `isStepOutputRefValue` guard) rather than
  * false-positive on it. Nothing before this compared the *consumer's*
  * declared type at that position against the *producer's* declared type at
@@ -93,8 +95,8 @@ const STEP_OUTPUT_REF_BRAND = Symbol.for("chant.op.stepOutputRef");
  * A typed reference to a prior step's declared return value. Inert by
  * construction — it carries a producer step id and an optional dot-path
  * into that producer's return schema, resolved by `chant build`
- * (`validateStepOutputRefs`) and compiled by the temporal serializer into a
- * local variable holding the awaited activity result.
+ * (`validateStepOutputRefs`) and compiled by a hosting lexicon's serializer
+ * into a local variable holding the awaited activity result.
  */
 export interface StepOutputRef {
   readonly [STEP_OUTPUT_REF_BRAND]: true;
@@ -268,11 +270,11 @@ function indexById(locations: StepLocation[]): { byId: Map<string, StepLocation>
  * validateStepOutputRefs}'s checks that don't depend on a contract map, kept
  * as its own export so a caller with no contracts on hand (or that wants to
  * defend against exactly this class of bug regardless of what contracts are
- * registered) can still refuse a scope-invalid reference. The temporal
- * lexicon's serializer (`serializeOps`) is exactly this caller: TMP013 (which
- * calls the fuller {@link validateStepOutputRefs}) protects `chant build`,
- * but `serializeOps` is a public export a caller can invoke directly,
- * bypassing that lint pass — this is its own defense-in-depth.
+ * registered) can still refuse a scope-invalid reference. A hosting lexicon's
+ * own Op serializer is exactly this caller: OPS013 (which calls the fuller
+ * {@link validateStepOutputRefs}) protects `chant build`, but a serializer is
+ * a public export a caller can invoke directly, bypassing that lint pass —
+ * this is its own defense-in-depth.
  *
  * Flags:
  *  - a reference authored inside `onFailure`, or inside an `EffectStep`'s

package/src/op/types.ts

@@ -1,33 +1,66 @@
 /**
- * Op type definitions — the data model for a named, phased Temporal workflow.
+ * Op type definitions — the data model for a named, phased Op.
  *
- * These types are intentionally free of Temporal SDK imports so they can live
- * in core without pulling in @temporalio/* as a dependency.
+ * These types are intentionally free of any runtime SDK's imports, so they can
+ * live in core without core depending on a runtime.
  */
 
 import type { EffectReceiptRef } from "./receipt-store";
+import type { ActivityProfileName } from "./activity-profiles";
 
 export interface OpConfig {
-  /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
+  /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
   name: string;
   /** Human-readable description shown in `chant run list` and deployment reports. */
   overview: string;
-  /** Temporal task queue. Defaults to `name`. */
-  taskQueue?: string;
-  /** Temporal namespace. Defaults to chant.config.ts defaultProfile's namespace. */
-  namespace?: string;
   /** Ordered list of execution phases. */
   phases: PhaseDefinition[];
   /** Other Op names that must be complete before this Op can run. */
   depends?: string[];
   /** Compensation phases executed on terminal failure (run in reverse order). */
   onFailure?: PhaseDefinition[];
-  /** Search attributes to upsert at workflow start. */
-  searchAttributes?: Record<string, string>;
+  /**
+   * Discovery keys for this Op — free-form `name: value` pairs a reader
+   * filters on. `ConvergeOp` sets `Converge: "true"` and `Env`, `WatchOp`
+   * sets `Watch`, and `discoverConvergeOps` (`./operator.ts`) reads both;
+   * `chant run list` prints whatever is here.
+   *
+   * These are the discovery half of what `searchAttributes` used to carry
+   * (#2118). The other half — a run's own outcome (`Phase`, `Drift`,
+   * `Approver`, `RollbackFailed`) — is not a property of the declaration at
+   * all and now lands on the run ledger as a fact
+   * (`../lifecycle/run-ledger.ts`), written per run rather than declared once.
+   */
+  labels?: Record<string, string>;
+  /**
+   * The cadence this Op runs on, when it has one (#2120). Runtime-neutral
+   * data, not a scheduler: the github/gitlab/forgejo lexicons render it as a
+   * CI cron ({@link ScheduledOpSpec}), `chant operator` reads it as this Op's
+   * tick cadence, a hosting lexicon hands it to its own scheduler, and the
+   * local one-shot executor ignores it.
+   */
+  schedule?: OpSchedule;
+}
+
+/**
+ * An Op's cadence (#2120). The cron is validated at `Op()` construction by
+ * the permissive 5-/6-field parser in `./cron.ts`, the same one a lexicon's
+ * own post-synth cron check imports.
+ */
+export interface OpSchedule {
+  /** 5- or 6-field cron expression, read in the running host's local time. */
+  cron: string;
+  /**
+   * What a fire does while the previous run is still going. `"skip"` is the
+   * only value — and the default — because that is what a level-triggered
+   * tick wants: the next fire re-observes everything anyway, so queueing a
+   * backlog buys nothing a single later tick does not.
+   */
+  overlap?: "skip";
 }
 
 export interface PhaseDefinition {
-  /** Display name shown in progress output and Temporal UI. */
+  /** Display name shown in progress output. */
   name: string;
   /** Ordered steps within the phase. */
   steps: StepDefinition[];
@@ -61,23 +94,50 @@ export interface ActivityStep {
    */
   args?: Record<string, unknown>;
   /**
-   * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
+   * Key from {@link ACTIVITY_PROFILES} controlling timeout + retry.
    * Default: "fastIdempotent"
    */
-  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate" | "argoSync" | "policyCheck";
+  profile?: ActivityProfileName;
   /**
-   * Surface this activity's return value as a workflow search attribute.
+   * Surface this activity's return value as a named run outcome.
+   *
+   * The local executor captures it into the step's record and folds it into
+   * the run ledger's `outcomes` (`../lifecycle/run-ledger.ts`); a hosting
+   * lexicon's serializer may additionally publish it to whatever index that
+   * runtime queries by. Useful for reading back a run by outcome (e.g. `Drift:
+   * "true"/"false"` from a lifecycleDiff activity).
    *
-   * The serializer captures the awaited result into a temporary, then emits
-   * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
-   * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
-   * from a lifecycleDiff activity).
+   * An array publishes several attributes off the same result in one upsert
+   * (#2105): one activity can answer more than one question about a run, and
+   * `choudoufuLivePlan`'s drift boolean plus its unowned and adoptable counts
+   * are three attributes over a single live read that nothing would be gained
+   * by splitting into three steps. A single object is the same thing with one
+   * entry, and stays the authored form everywhere one attribute is enough.
    *
    * `from` is a dot-path into the return value (e.g. `"drifted"` for
    * `{ drifted: boolean }`); when omitted, the whole return value is
-   * stringified.
+   * recorded.
    */
-  outcomeAttribute?: { name: string; from?: string };
+  outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[];
+}
+
+/** One named run outcome published off a step's return value. */
+export interface OutcomeAttribute {
+  /** The outcome's name, as it appears in the run ledger's `outcomes`. */
+  name: string;
+  /** Dot-path into the activity's return value; the whole value when omitted. */
+  from?: string;
+}
+
+/**
+ * {@link ActivityStep.outcomeAttribute} as a list, whichever form it was
+ * authored in. `[]` when the step publishes none, so every consumer can
+ * iterate without first asking which of the two shapes it is holding.
+ */
+export function outcomeAttributesOf(step: { outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[] }): OutcomeAttribute[] {
+  const declared = step.outcomeAttribute;
+  if (!declared) return [];
+  return Array.isArray(declared) ? declared : [declared];
 }
 
 /**
@@ -102,19 +162,19 @@ export interface EffectStep {
   expectation?: string;
   /**
    * Steps run when the live receipt does not match, in authored order. A gate
-   * authored here pauses only when the effect will fire. Effect steps do not
+   * authored here is reached only when the effect will fire. Effect steps do not
    * nest.
    */
   steps: Array<ActivityStep | GateStep>;
-  /** Annotation carried into the generated workflow as a comment. */
+  /** Annotation carried into the Op's build output as a comment. */
   description?: string;
 }
 
 export interface GateStep {
   kind: "gate";
-  /** Signal name. The generated workflow waits for this signal before continuing. */
+  /** The gate's name — what `chant approve <op> <gate>` resolves. */
   signalName: string;
-  /** Temporal duration string. Default: "48h". */
+  /** How long a recorded pending gate stays valid, as a duration string. Default: "48h". */
   timeout?: string;
   /** Human-readable description of the action required to unblock this gate. */
   description?: string;

package/src/ownership.ts

@@ -44,7 +44,7 @@ export interface ChannelKeys {
 /**
  * The label-based ownership convention (`app.kubernetes.io/managed-by` +
  * `chant.intentius.io/{stack,env}`) — the default, shared by every label-based
- * lexicon (k8s, gcp, helm, and the Temporal apply activity's `kubectl --prune`
+ * lexicon (k8s, gcp, helm, and the `k8sApply` activity's `kubectl --prune`
  * selector). AWS and Azure tag keys are defined in their own lexicons.
  */
 export const LABEL_OWNERSHIP_KEYS: ChannelKeys = {

package/src/provenance.test.ts

@@ -155,6 +155,12 @@ describe("describePathOrigin", () => {
       "composite WebService (web)",
     );
     expect(describePathOrigin({ kind: "build-param", params: ["region", "tier"] })).toBe("param region, tier");
+    expect(
+      describePathOrigin({ kind: "composite-parameter", composite: "WebService", parameters: ["name", "tier"] }),
+    ).toBe("composite WebService parameter name, tier");
+    expect(describePathOrigin({ kind: "composite-literal", composite: "WebService" })).toBe(
+      "composite WebService literal",
+    );
   });
 });