@intentius/chant 0.49.0 → 0.51.0

package/src/cli/handlers/components.ts

@@ -26,20 +26,23 @@
  * `componentBom` fall back to `null` exactly as before — no regression for
  * ledgers with no persisted manifests at all.
  */
-import { resolve } from "node:path";
+import { resolve, join, dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
 import {
   appendReleaseRecord,
   readReleaseLedger,
   listReleaseEnvironments,
+  latestPerComponent,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
 import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
-import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-store";
+import { findBuildManifestByArtifactDigest, readBuildManifest } from "../../lifecycle/build-ledger-store";
 import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
+import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -51,6 +54,7 @@ import type { LexiconPlugin } from "../../lexicon";
 import { normalizeObservation, mergeObservations, unobservedAll, type NormalizedObservation } from "../../observation";
 import type { Phase, Component } from "../../components/component";
 import { deployUnits } from "../../components/deploy-units";
+import { sortedJsonReplacer } from "../../utils";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -147,6 +151,159 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   }
 }
 
+/** One entry of `chant components export`'s per-entry result (text and `--json` output). */
+interface ExportEntryResult {
+  kind: string;
+  path: string;
+  digest: string;
+  status: "materialized" | "missing";
+  /** Set only when `status` is "missing" — why the source file couldn't be read. */
+  reason?: string;
+}
+
+/**
+ * chant components export <env> --component <name> [--digest <manifestDigest>]
+ *   -o <dir> [--json]
+ *
+ * Materializes a persisted `BuildArchiveManifest` (#609,
+ * ../../lifecycle/build-ledger-store.ts) to a portable directory: every
+ * `image`/`template`/`asset`/`sbom` entry is copied byte-for-byte from where
+ * the build that produced it left it on disk (its `path`, resolved against
+ * the current working directory — the same directory a component's
+ * `docker-build`/`addArchiveTemplate`/etc. step wrote it into) under that
+ * same archive-relative path in `-o <dir>`, plus a `manifest.json` so the
+ * directory is self-describing without chant. No re-synthesis: this reads
+ * bytes a prior `chant build`/`run --components` already produced, never
+ * regenerates them (#929) — the "byte-identical, promote-by-digest" contract
+ * the build archive is built on (see ../../components/verbs/build-archive.ts).
+ *
+ * Manifest resolution:
+ *  - `--digest <manifestDigest>` reads it directly (`readBuildManifest`),
+ *    independent of any environment/release record.
+ *  - Otherwise resolves "the manifest behind this component's most recent
+ *    successful run" in `<env>`: the latest release record's own
+ *    `manifestDigest` when it was recorded, else a reverse lookup by its
+ *    promoted artifact digest (`findBuildManifestByArtifactDigest`) — the
+ *    same join `chant components status` already performs.
+ *
+ * A source file missing on disk (the build that produced the manifest ran
+ * somewhere else, or its output was since cleaned) is reported per entry
+ * rather than silently dropped; the command exits non-zero so an incomplete
+ * export is never mistaken for a complete one.
+ */
+export async function runComponentsExport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const environment = args.extraPositional;
+  const component = args.component;
+  const outDir = args.output;
+  const usage = "chant components export <env> --component <name> [--digest <manifestDigest>] -o <dir>";
+
+  if (!outDir) {
+    console.error(formatError({ message: "-o/--output <dir> is required", hint: usage }));
+    return 1;
+  }
+
+  await fetchLifecycle();
+
+  let manifest: BuildArchiveManifest;
+
+  if (args.digest) {
+    const resolved = await readBuildManifest(args.digest);
+    if (!resolved) {
+      console.error(formatError({ message: `No persisted build manifest found for digest ${args.digest}` }));
+      return 1;
+    }
+    if (component && resolved.component !== component) {
+      console.error(formatWarning({
+        message: `--component ${component} does not match the resolved manifest's component (${resolved.component}) — exporting the manifest at --digest ${args.digest} anyway`,
+      }));
+    }
+    manifest = resolved;
+  } else {
+    if (!environment || !component) {
+      console.error(formatError({
+        message: "Environment and --component are required unless --digest <manifestDigest> is given",
+        hint: usage,
+      }));
+      return 1;
+    }
+    const ledger = await readReleaseLedger(environment);
+    const latest = latestPerComponent(ledger.records).get(component);
+    if (!latest) {
+      console.error(formatError({
+        message: `No release record for component "${component}" in environment "${environment}"`,
+      }));
+      return 1;
+    }
+    const resolved = latest.manifestDigest
+      ? await readBuildManifest(latest.manifestDigest)
+      : await findBuildManifestByArtifactDigest(latest.digest);
+    if (!resolved) {
+      console.error(formatError({
+        message: `No persisted build manifest found for ${component}@${environment}'s recorded digest ${latest.digest}`,
+        hint: "The build predates #609, or was recorded via `chant components release` alone with no corresponding `chant build`/`run --components`.",
+      }));
+      return 1;
+    }
+    manifest = resolved;
+  }
+
+  const targetDir = resolve(outDir);
+  const sourceRoot = resolve(".");
+  await mkdir(targetDir, { recursive: true });
+
+  const entries = [...manifest.contents].sort((a, b) => a.path.localeCompare(b.path));
+  const results: ExportEntryResult[] = [];
+  for (const entry of entries) {
+    try {
+      const bytes = await readFile(resolve(sourceRoot, entry.path));
+      const target = join(targetDir, entry.path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, bytes);
+      results.push({ kind: entry.kind, path: entry.path, digest: entry.digest, status: "materialized" });
+    } catch (err) {
+      results.push({
+        kind: entry.kind,
+        path: entry.path,
+        digest: entry.digest,
+        status: "missing",
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(manifest, sortedJsonReplacer, 2));
+
+  const missing = results.filter((r) => r.status === "missing");
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      component: manifest.component,
+      manifestDigest: manifest.manifestDigest,
+      outDir: targetDir,
+      entries: results,
+    }, null, 2));
+  } else {
+    console.log(formatBold(`${manifest.component} (${manifest.manifestDigest}) -> ${targetDir}`));
+    for (const r of results) {
+      const status = r.status === "materialized" ? formatSuccess("ok") : formatError({ message: r.reason ?? "missing" });
+      console.log(`  ${r.kind.padEnd(10)}${r.path.padEnd(40)}${status}`);
+    }
+    console.log(`  ${"manifest".padEnd(10)}${"manifest.json".padEnd(40)}${formatSuccess("ok")}`);
+  }
+
+  if (missing.length > 0) {
+    console.error(formatError({
+      message: `${missing.length} of ${results.length} archive entr${missing.length === 1 ? "y" : "ies"} not found on disk — export incomplete`,
+      hint: `Run this from the checkout where the build that produced ${manifest.manifestDigest} still has its output on disk.`,
+    }));
+    return 1;
+  }
+
+  console.error(formatSuccess(`Exported ${results.length} entr${results.length === 1 ? "y" : "ies"} + manifest.json to ${targetDir}`));
+  return 0;
+}
+
 /** One row of `chant components status` JSON output. */
 interface StatusJsonRow {
   component: string;
@@ -595,7 +752,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
 export async function runComponentsUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown components subcommand: ${ctx.args.path}`,
-    hint: "Available: chant components status [env], chant components release <env>",
+    hint: "Available: chant components status [env], chant components release <env>, chant components export <env>",
   }));
   return 1;
 }

package/src/cli/handlers/graph.test.ts

@@ -431,6 +431,26 @@ describe("runGraph", () => {
       expect(discoverMock).not.toHaveBeenCalled();
     });
 
+    test("--components --format ir carries declared composites (#1492); undeclared components have no composites attr", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphMock.mockResolvedValue({
+        success: true,
+        order: ["shared-foundation", "loom-backend"],
+        waves: [["shared-foundation"], ["loom-backend"]],
+        edges: [{ from: "loom-backend", to: "shared-foundation" }],
+        files: {},
+        composites: { "shared-foundation": ["ArtifactBucket", "OperatorRole"] },
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.find((n: { id: string }) => n.id === "shared-foundation").attrs.composites).toEqual([
+        "ArtifactBucket",
+        "OperatorRole",
+      ]);
+      expect("composites" in ir.nodes.find((n: { id: string }) => n.id === "loom-backend").attrs).toBe(false);
+    });
+
     test("--components --format mermaid lanes the components by wave", async () => {
       lintMock.mockResolvedValue({ success: true });
       componentGraphClean();

package/src/cli/handlers/graph.ts

@@ -580,7 +580,16 @@ async function runComponentGraphView(
       // `liveNames` (#1491): the resources this component owns — declared, or
       // the contract's `[name]` identity fallback — so a consumer can join
       // the component DAG to the resource graph instead of guessing at kinds.
-      attrs: { wave: waveOf.get(name) ?? null, liveNames: graph.liveNames?.[name] ?? [name] },
+      // `composites` (#1492): the composite kind(s) this component's
+      // resources come from, when the component declared them explicitly —
+      // omitted from attrs (not defaulted) when it didn't, so a consumer
+      // knows to fall back to its own naming-convention guess rather than
+      // reading "no composites" from an empty array.
+      attrs: {
+        wave: waveOf.get(name) ?? null,
+        liveNames: graph.liveNames?.[name] ?? [name],
+        ...(graph.composites?.[name] ? { composites: graph.composites[name] } : {}),
+      },
       // Deep-link the node to its `*.component.ts` (behold's inspect panel).
       ...(graph.files?.[name] ? { sourceLoc: { file: graph.files[name] } } : {}),
     })),

package/src/cli/handlers/lifecycle.test.ts

@@ -821,6 +821,96 @@ describe("runLifecyclePlan", () => {
     expect(byName["sg-0abc123"].name).toBe("sg-0abc123");
   });
 
+  // #1665 — per-change disruption. Core defines the contract and reports it;
+  // the lexicon that owns the spec answers, and every degradation is `unknown`.
+  describe("disruption classification (#1665)", () => {
+    const drifted = (lexicon: string, type: string) => {
+      readSnapshotMock.mockResolvedValue(JSON.stringify({
+        lexicon,
+        environment: "prod",
+        commit: "abc",
+        timestamp: "2026-04-01T00:00:00Z",
+        resources: { db: meta({ type, attributes: { Engine: "postgres" } }) },
+      }));
+      return staticDescribeResources({ db: meta({ type, attributes: { Engine: "mysql" } }) });
+    };
+
+    test("a lexicon's verdict reaches --json and the stderr warning", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ aws: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: drifted("aws", "AWS::RDS::DBInstance"),
+          classifyDisruption: ({ changes }) =>
+            Object.fromEntries(
+              changes.map((c) => [
+                c.name,
+                { disruption: "destroy" as const, because: c.deltas.map((d) => d.path), detail: "Engine is create-only" },
+              ]),
+            ),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const db = plan.entries.find((e: { name: string }) => e.name === "db");
+      expect(db).toMatchObject({
+        action: "update",
+        disruption: "destroy",
+        disruptionDetail: "Engine is create-only",
+      });
+      expect(db.disruptionBecause).toContain("attributes.Engine");
+      // The --json shape has no column for it, so the warning is what a CI
+      // consumer hears.
+      expect(stderrBuf.join("\n")).toContain("replace the resource rather than mutating it in place");
+    });
+
+    test("a lexicon with no classifier leaves every update unknown, never in-place", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ k8s: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({ name: "k8s", describeResources: drifted("k8s", "K8s::Apps::Deployment") }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const db = plan.entries.find((e: { name: string }) => e.name === "db");
+      expect(db.disruption).toBe("unknown");
+      expect(db.disruptionDetail).toContain("k8s lexicon does not classify disruption");
+      expect(stderrBuf.join("\n")).toContain("could not be classified");
+    });
+
+    test("the human render carries the verdict", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ aws: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: drifted("aws", "AWS::RDS::DBInstance"),
+          classifyDisruption: () => ({ db: { disruption: "in-place" as const, detail: "no create-only property changed" } }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const out = stdoutBuf.join("\n");
+      expect(out).toContain("Disruption: 1 in-place");
+      expect(out).toContain("— in-place: no create-only property changed");
+      expect(stderrBuf.join("\n")).not.toContain("could not be classified");
+    });
+  });
+
   // #1832 — effect receipts are declared, diffed, and observed like any
   // resource, but observe-only to the generic apply path: the plan compares
   // live value to resolved expectation and proposes the fire, never a create.

package/src/cli/handlers/lifecycle.ts

@@ -3,8 +3,9 @@ import { commandBuildParams } from "../build-params-cli";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
-import { deepDiffForLexicon } from "../../lifecycle/deep-observe";
+import { deepDiffForLexicon, type DeclaredEntities } from "../../lifecycle/deep-observe";
 import { countPropertyDrift, type DeepDiffResult } from "../../lifecycle/deep-diff";
+import { describePathOrigin, getPathProvenance } from "../../provenance";
 import {
   acceptDeviations,
   baselineForLexicon,
@@ -19,6 +20,7 @@ import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
+import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption";
 import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
 import {
   formatUnobserved,
@@ -55,7 +57,7 @@ import type { ChantConfig } from "../../config";
  * then `config.sourceDir`, then "." (the root). Snapshot/diff/plan all use this
  * so their build digests stay consistent.
  */
-function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
+export function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
   return resolve(args.src ?? config.sourceDir ?? ".");
 }
 
@@ -803,13 +805,17 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
     // declared name the reader can never resolve reads as missing (see
     // lifecycle/observe.ts).
     const declared = new Set<string>();
-    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    const entities: DeclaredEntities = new Map();
     for (const [name, entity] of args.buildResult.entities) {
       if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
         declared.add(name);
+        // Path origins are carried across explicitly (#1443): this map is plain
+        // objects, and the symbol-keyed provenance channel does not survive it.
+        const pathOrigins = getPathProvenance(entity);
         entities.set(name, {
           entityType: entity.entityType,
           props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+          ...(pathOrigins ? { pathOrigins } : {}),
         });
       }
     }
@@ -964,7 +970,10 @@ function renderDeepDiff(lexiconName: string, deep: DeepDiffResult): void {
         const declared = "declared" in change ? formatValue(change.declared) : "<undeclared>";
         const live = "live" in change ? formatValue(change.live) : "<absent>";
         const baseline = "baseline" in change ? ` [accepted: ${formatValue(change.baseline)}]` : "";
-        console.log(`      ${change.path}: ${declared} → ${live}${baseline}`);
+        // Both sides of the attribution, where each is known (#1443/#1189).
+        const from = change.origin ? ` [from: ${describePathOrigin(change.origin)}]` : "";
+        const owner = change.owner ? ` [owner: ${change.owner}]` : "";
+        console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}`);
       }
     }
   }
@@ -1256,7 +1265,17 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         // Attribution survives the flat merge below (#1674).
         lexicon: lexiconName,
       });
-      merged.entries.push(...cs.entries);
+
+      // Disruption (#1665) is asked of THIS lexicon, before the merge: the
+      // deltas are paths into its own observation shape, and the replacement
+      // rules are in the spec it compiled. A lexicon that answers nothing
+      // leaves every update `unknown` — never `in-place`.
+      const classified = await annotateDisruption(
+        cs,
+        environment,
+        plugin.classifyDisruption ? (o) => plugin.classifyDisruption!(o) : undefined,
+      );
+      merged.entries.push(...classified.entries);
       checked++;
     }
   } finally {
@@ -1291,6 +1310,12 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     }));
   }
 
+  // Same reason as above (#1665): the `--json` and `--report gitlab-mr` shapes
+  // have no column for how much an update hurts.
+  for (const notice of disruptionNotices(merged)) {
+    console.error(formatWarning({ message: notice }));
+  }
+
   // `--report gitlab-mr` emits the GitLab MR plan-widget artifact instead of the
   // human render. Write it to a file (`tfplan.json`) in CI and declare it as
   // `artifacts:reports:terraform` to light up the merge-request widget.

package/src/cli/handlers/op-progress.test.ts

@@ -0,0 +1,202 @@
+import { describe, test, expect } from "vitest";
+import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
+import type { OpConfig } from "../../op/types";
+import type { EffectReceiptRef } from "../../op/receipt-store";
+import type { WorkflowHistoryRaw, HistoryEvent } from "./run-client";
+
+// Minimal history-event builders. Field shapes match what `fetchNormalizedHistory`
+// produces: short PascalCase `eventType`, decimal-string `eventId`/`scheduledEventId`.
+function scheduled(eventId: string, fn: string, at: Date): HistoryEvent {
+  return {
+    eventId,
+    eventType: "ActivityTaskScheduled",
+    eventTime: at,
+    activityTaskScheduledEventAttributes: { activityId: eventId, activityType: { name: fn } },
+  };
+}
+function completed(scheduledEventId: string, at: Date): HistoryEvent {
+  return {
+    eventType: "ActivityTaskCompleted",
+    eventTime: at,
+    activityTaskCompletedEventAttributes: { scheduledEventId },
+  };
+}
+function failed(scheduledEventId: string, at: Date, message = "boom"): HistoryEvent {
+  return {
+    eventType: "ActivityTaskFailed",
+    eventTime: at,
+    activityTaskFailedEventAttributes: { scheduledEventId, failure: { message } },
+  };
+}
+
+const T0 = new Date("2026-05-01T00:00:00Z");
+const sec = (n: number) => new Date(T0.getTime() + n * 1000);
+
+describe("extractStepRecords", () => {
+  test("joins two phases' activities to their declared phase, in order", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [
+        { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "build", sec(0)),
+        completed("1", sec(1)),
+        scheduled("2", "deploy", sec(2)),
+        completed("2", sec(4)),
+      ],
+    };
+    const records = extractStepRecords(config, history);
+    expect(records).toEqual([
+      { phase: "Build", fn: "build", status: "ok", durationMs: 1000 },
+      { phase: "Deploy", fn: "deploy", status: "ok", durationMs: 2000 },
+    ]);
+  });
+
+  test("two steps calling the same activity each get their own scheduled event (no last-wins collision)", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "dup" }, { kind: "activity", fn: "dup" }] }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "dup", sec(0)),
+        completed("1", sec(1)), // first "dup": 1000ms, ok
+        scheduled("2", "dup", sec(1)),
+        failed("2", sec(1.5), "second dup failed"), // second "dup": fails
+      ],
+    };
+    const records = extractStepRecords(config, history);
+    expect(records).toEqual([
+      { phase: "P1", fn: "dup", status: "ok", durationMs: 1000 },
+      { phase: "P1", fn: "dup", status: "fail", durationMs: 500, error: "second dup failed" },
+    ]);
+  });
+
+  test("a step not yet scheduled produces no record unless final", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [
+        { name: "P1", steps: [{ kind: "activity", fn: "a" }] },
+        { name: "P2", steps: [{ kind: "activity", fn: "b" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = { events: [scheduled("1", "a", sec(0)), completed("1", sec(1))] };
+
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "P1", fn: "a", status: "ok", durationMs: 1000 },
+    ]);
+    expect(extractStepRecords(config, history, { final: true })).toEqual([
+      { phase: "P1", fn: "a", status: "ok", durationMs: 1000 },
+      { phase: "P2", fn: "b", status: "skipped", durationMs: 0 },
+    ]);
+  });
+
+  test("a scheduled-but-not-yet-settled step produces no record", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "a" }] }],
+    };
+    const history: WorkflowHistoryRaw = { events: [scheduled("1", "a", sec(0))] };
+    expect(extractStepRecords(config, history)).toEqual([]);
+  });
+
+  test("a retried activity resolves to its last outcome (Failed attempt then eventual Completed)", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "flaky" }] }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "flaky", sec(0)),
+        failed("1", sec(1), "attempt 1 failed"),
+        completed("1", sec(3)), // eventual success
+      ],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "P1", fn: "flaky", status: "ok", durationMs: 3000 },
+    ]);
+  });
+
+  test("effect step: matched receipt — only receiptRead settles; nested + receiptWrite are skipped only when final", () => {
+    const receipt: EffectReceiptRef = { name: "r", effect: "e", flavor: "existence", inputs: {} };
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{
+        name: "Effect",
+        steps: [{ kind: "effect", receipt, steps: [{ kind: "activity", fn: "applyIt" }] }],
+      }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [scheduled("1", "receiptRead", sec(0)), completed("1", sec(1))],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "Effect", fn: "receiptRead", status: "ok", durationMs: 1000 },
+    ]);
+    expect(extractStepRecords(config, history, { final: true })).toEqual([
+      { phase: "Effect", fn: "receiptRead", status: "ok", durationMs: 1000 },
+      { phase: "Effect", fn: "applyIt", status: "skipped", durationMs: 0 },
+      { phase: "Effect", fn: "receiptWrite", status: "skipped", durationMs: 0 },
+    ]);
+  });
+
+  test("onFailure phases are matched in reverse declared order, matching how the workflow actually runs them", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "Main", steps: [{ kind: "activity", fn: "boom" }] }],
+      onFailure: [
+        { name: "C1", steps: [{ kind: "activity", fn: "comp1" }] },
+        { name: "C2", steps: [{ kind: "activity", fn: "comp2" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "boom", sec(0)),
+        failed("1", sec(1), "boom"),
+        // Compensation runs C2 then C1 (reverse of declared order).
+        scheduled("2", "comp2", sec(2)),
+        completed("2", sec(3)),
+        scheduled("3", "comp1", sec(3)),
+        completed("3", sec(4)),
+      ],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "Main", fn: "boom", status: "fail", durationMs: 1000, error: "boom" },
+      { phase: "C2", fn: "comp2", status: "ok", durationMs: 1000 },
+      { phase: "C1", fn: "comp1", status: "ok", durationMs: 1000 },
+    ]);
+  });
+});
+
+describe("countActivities", () => {
+  test("counts scheduled and completed events", () => {
+    const history: WorkflowHistoryRaw = {
+      events: [scheduled("1", "a", sec(0)), scheduled("2", "b", sec(0)), completed("1", sec(1))],
+    };
+    expect(countActivities(history)).toEqual({ completed: 1, scheduled: 2 });
+  });
+
+  test("empty history", () => {
+    expect(countActivities({})).toEqual({ completed: 0, scheduled: 0 });
+  });
+});
+
+describe("queryGateState", () => {
+  test("returns the query result when the handle supports it", async () => {
+    const handle = { query: async () => ({ signalName: "g", since: "t" }) } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toEqual({ signalName: "g", since: "t" });
+  });
+
+  test("returns null when the workflow reports no pending gate", async () => {
+    const handle = { query: async () => null } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toBeNull();
+  });
+
+  test("returns undefined (not an error) when the query isn't registered — e.g. an Op with no gates", async () => {
+    const handle = { query: async () => { throw new Error("unregistered query"); } } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toBeUndefined();
+  });
+});