@intentius/chant 0.50.0 → 0.52.0

package/src/cli/build-options.ts

@@ -0,0 +1,109 @@
+/**
+ * The one place chant assembles `build()`'s options for a project directory.
+ *
+ * chant #2002 — `chant build` (./commands/build.ts) and the `policyGate` Op
+ * step (../lint/policy.ts's `evaluateProjectPolicies`) both build the same
+ * directory, and each used to assemble that option object itself. The two lists
+ * drifted to nine options against two: the gate built with fold off (the path
+ * `chant build` retired as its default in #1134), without the project's config
+ * (so serializers lost their lexicon-scoped dialect settings and a policy
+ * reading `ctx.docs` inspected different documents), and without `buildRoots`
+ * (so config-declared roots contributed no entities at all). A gate can only
+ * decide on a build `chant build` would produce if the two are assembled from
+ * one place, so they are.
+ *
+ * Two functions rather than one because the *modes* are needed earlier than the
+ * rest: `chant build` arms sandboxed policy execution from the resolved
+ * `sandbox` before it loads any policy module, which happens before build-time
+ * parameters and the ownership marker exist. {@link resolveBuildModes} is that
+ * early half; {@link resolveProjectBuildOptions} takes its result and assembles
+ * everything `build()` is given.
+ */
+import { resolveFoldEnabled, resolveSandboxEnabled, type ChantConfig } from "../config";
+import { collectBuildRootContributors, resolveLexiconVersions } from "./plugins";
+import type { LexiconPlugin } from "../lexicon";
+import type { BuildOptions } from "../build";
+import type { OwnershipMarker } from "../ownership";
+import type { BuildParamProvenance } from "../provenance";
+
+/** The resolved fold/sandbox execution modes for one build. */
+export interface BuildModes {
+  /** #1022/#1134 — fold source modules statically; the default build path. */
+  fold: boolean;
+  /** #1045 Phase 2 — execute run-fallback files in a sandboxed child. */
+  sandbox: boolean;
+}
+
+/**
+ * Resolve this build's execution modes: an explicit CLI flag wins over
+ * `chant.config.ts`'s `build.fold`/`build.sandbox`, which wins over the default
+ * (fold on, sandbox off). Callers with no flags to offer (the `policyGate` step)
+ * pass no overrides and get the project's own answer.
+ */
+export function resolveBuildModes(
+  config: ChantConfig,
+  overrides?: { fold?: boolean; sandbox?: boolean },
+): BuildModes {
+  return {
+    fold: resolveFoldEnabled(config, overrides?.fold),
+    sandbox: resolveSandboxEnabled(config, overrides?.sandbox),
+  };
+}
+
+/** Inputs {@link resolveProjectBuildOptions} needs to assemble a build. */
+export interface ProjectBuildOptionsInput {
+  /** The project's resolved config, from `loadChantConfigUpward`. */
+  config: ChantConfig;
+  /** Directory the config was found in — build roots are rooted here, not at a (possibly sourceDir-scoped) build path. */
+  configDir: string;
+  /** The lexicon plugins loaded for this build. */
+  plugins?: readonly LexiconPlugin[];
+  /** Resolved execution modes, from {@link resolveBuildModes}. */
+  modes: BuildModes;
+  /** The resolved ownership marker, when marking is on. */
+  ownership?: OwnershipMarker;
+  /** This build's resolved build-time parameters (#1064). */
+  buildParams?: BuildParamProvenance[];
+}
+
+/**
+ * Assemble the option object `build()` takes for a project directory.
+ *
+ * Every option here is derived from the project (its config, its plugins, its
+ * resolved parameters) rather than from the command that asked, so two callers
+ * handing in the same project get byte-identical builds. A new option belongs
+ * in this function, never at a call site.
+ */
+export function resolveProjectBuildOptions(input: ProjectBuildOptionsInput): BuildOptions {
+  const { config, configDir, plugins, modes, ownership, buildParams } = input;
+
+  // #1039 — each loaded plugin's registered intrinsics (e.g. AWS's `Sub`), so
+  // a file using a registered intrinsic tagged template folds instead of
+  // unconditionally falling back to run. `intrinsics` is an optional plugin
+  // extension, hence the guard.
+  const intrinsics = plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
+
+  // #1063 — the same loaded plugins, by NAME, are this build's allowlist for
+  // following a bare import specifier into a lexicon package (so `Azure`,
+  // `GCP`, `S3Actions`, `CI` fold as values).
+  const lexicons = plugins?.map((plugin) => plugin.name) ?? [];
+
+  return {
+    ownership,
+    config: config as unknown as Record<string, unknown>,
+    fold: modes.fold,
+    sandbox: modes.sandbox,
+    intrinsics,
+    lexicons,
+    // chant #1442 — which lexicon VERSION interpreted each declaration.
+    lexiconVersions: resolveLexiconVersions(lexicons),
+    buildParams,
+    // #1548 piece 3 — config-declared build roots (kustomize dirs, committed
+    // ciphertext), rendered into entities by the owning lexicon's hook.
+    buildRoots: collectBuildRootContributors(
+      plugins,
+      config as unknown as Record<string, unknown>,
+      configDir,
+    ),
+  };
+}

package/src/cli/commands/build.ts

@@ -5,17 +5,15 @@ import {
   resolveOwnershipEnv,
   ownershipEnvDisagreement,
   isOwnershipParamRef,
-  resolveFoldEnabled,
-  resolveSandboxEnabled,
   resolveKnowledgeDir,
 } from "../../config";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
 import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
-import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import { coreReceiptChecks } from "../../lint/receipt-checks";
 import { coreOutputChecks } from "../../lint/output-checks";
@@ -182,15 +180,14 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
   const policies = config.lint?.policies ?? [];
 
-  // #1022/#1134 — fold is the default build path: an explicit CLI flag
-  // (--fold/--no-fold) wins over `chant.config.ts`'s `build.fold`, which
-  // wins over the default of `true`.
-  const fold = resolveFoldEnabled(config, options.fold);
-
-  // #1045 Phase 2 — opt-in sandboxed execution of run-fallback files (or,
-  // without --fold, every file). Same CLI-flag-wins-over-config precedence
-  // as fold, resolved independently.
-  const sandbox = resolveSandboxEnabled(config, options.sandbox);
+  // #1022/#1134 (fold) and #1045 Phase 2 (sandbox) — an explicit CLI flag
+  // (--fold/--no-fold, --sandbox) wins over `chant.config.ts`'s
+  // `build.fold`/`build.sandbox`, which wins over the defaults (fold on,
+  // sandbox off). Resolved here rather than with the rest of the build
+  // options below because arming sandboxed policy execution has to happen
+  // before any policy module could be loaded — see #2002 in ../build-options.ts.
+  const modes = resolveBuildModes(config, { fold: options.fold, sandbox: options.sandbox });
+  const { fold, sandbox } = modes;
 
   // #1131 — arm sandboxed policy execution from the RESOLVED value, before any
   // policy module could be loaded. Resolved, not `options.sandbox`, because
@@ -301,48 +298,22 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     }
   }
 
-  // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
-  // `Sub`) through to the fold path, so a file using a registered intrinsic
-  // tagged template folds instead of unconditionally falling back to run.
-  // `intrinsics` is an optional plugin extension (not every lexicon defines
-  // any), hence the guard.
-  const intrinsics = options.plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
-
-  // #1063 — the same loaded plugins, by NAME, are this build's allowlist for
-  // following a bare import specifier into a lexicon package (so `Azure`,
-  // `GCP`, `S3Actions`, `CI` fold as values). A plugin's `name` is the
-  // lexicon name `loadPlugin()` was called with, which is exactly what
-  // `@intentius/chant-lexicon-<name>` was imported from — see
-  // ../plugins.ts and fold-import.ts's `lexiconPackageName`.
-  const lexicons = options.plugins?.map((plugin) => plugin.name) ?? [];
-
-  // chant #1442 — which lexicon VERSION interpreted each declaration. The
-  // declaration is fingerprinted by `hashProps`; the thing that turned it into
-  // output was not recorded at all, so a lexicon bump that changed emitted
-  // output left the build digest identical. Captured here because this is the
-  // layer that knows which lexicons were loaded — `build()` is given only
-  // their names.
-  const lexiconVersions = resolveLexiconVersions(lexicons);
-
-  // Run the build
-  const result = await build(infraPath, options.serializers, undefined, {
-    ownership,
-    config: config as unknown as Record<string, unknown>,
-    fold,
-    sandbox,
-    intrinsics,
-    lexicons,
-    lexiconVersions,
-    buildParams: paramsResolution.provenance,
-    // #1548 piece 3 — config-declared build roots (kustomize dirs), rendered
-    // into entities by the owning lexicon's hook. Rooted at the config dir,
-    // not the (possibly sourceDir-scoped) infra path.
-    buildRoots: collectBuildRootContributors(
-      options.plugins,
-      config as unknown as Record<string, unknown>,
+  // Run the build. #2002 — every option comes from the shared assembler
+  // (../build-options.ts), which `evaluateProjectPolicies` calls too, so the
+  // `policyGate` step decides on the same project this command builds.
+  const result = await build(
+    infraPath,
+    options.serializers,
+    undefined,
+    resolveProjectBuildOptions({
+      config,
       configDir,
-    ),
-  });
+      plugins: options.plugins,
+      modes,
+      ownership,
+      buildParams: paramsResolution.provenance,
+    }),
+  );
 
   // #1022 — report per-file fold vs run so it's visible what still runs.
   // #1424 — one line by default; the per-file lines and their reasons are

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

@@ -753,6 +753,25 @@ describe("runLifecyclePlan", () => {
     expect(stdoutBuf.join("\n")).toContain("bucket");
   });
 
+  // #1983 — `--report markdown` emits the reviewer-facing projection instead
+  // of the human render, same as `--report gitlab-mr` swaps in the widget JSON.
+  test("--report markdown emits the markdown projection instead of the human render", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", reportFile: "markdown" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("## Plan for `prod`");
+    expect(out).toContain("### CREATE");
+    expect(out).toContain("- `bucket`");
+  });
+
   // #1620 — the resolved read address rides plan entries the same way it rides
   // the live diff. Regression: the plan path dropped the observation's queried
   // map, so only unobserved rows ever carried an address while the docs
@@ -821,6 +840,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

@@ -18,8 +18,9 @@ import {
 } from "../../lifecycle/observation-baseline";
 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 { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice, 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,
@@ -1264,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,12 +1302,17 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
-  // shapes have no room for it) still learn the plan has a hole (#1089).
-  const unobservedCount = summarize(merged).unobserved;
-  if (unobservedCount > 0) {
-    console.error(formatWarning({
-      message: `${unobservedCount} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
-    }));
+  // shapes have no room for it) still learn the plan has a hole (#1089). The
+  // `markdown` report carries the same wording in its own body instead — a
+  // reviewer reading a comment never sees this stderr.
+  for (const notice of unobservedPlanNotice(merged)) {
+    console.error(formatWarning({ message: notice }));
+  }
+
+  // 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
@@ -1307,6 +1323,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  // `--report markdown` emits the reviewer-facing projection (#1983) — a
+  // counts header, entries grouped and attributed to their lexicon, holes and
+  // disruption both carried in the body rather than left to stderr.
+  if (args.reportFile === "markdown") {
+    console.log(renderChangeSetMarkdown(merged));
+    return 0;
+  }
+
   if (args.json) {
     console.log(JSON.stringify(merged, null, 2));
   } else {

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