@cad0p/pi-steering 0.1.0

package/src/testing/index.ts

@@ -0,0 +1,1472 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Testing primitives for rule and plugin authors.
+ *
+ * Subpath export: `@cad0p/pi-steering/testing`. Also re-exported
+ * at the package root for discoverability.
+ *
+ * Phase 5a ships four low-level primitives that wrap the engine's
+ * internals without forcing authors to stand up a pi runtime stub:
+ *
+ *   - {@link loadHarness}         — build an evaluator + dispatcher
+ *                                    pair from a static
+ *                                    {@link SteeringConfig}. No walk-up
+ *                                    loading — tests pass explicit
+ *                                    config.
+ *   - {@link mockContext}         — build a {@link PredicateContext}
+ *                                    for unit-testing predicate
+ *                                    handlers in isolation.
+ *   - {@link mockObserverContext} — same for {@link ObserverContext}.
+ *   - {@link getAppendedEntries}  — read back `appendEntry` writes
+ *                                    captured by either mock context.
+ *
+ * The convenience wrappers (`testPredicate`, `expectBlocks`,
+ * `runMatrix`, …) that build on these live in a Phase 5b follow-up.
+ *
+ * Design notes:
+ *
+ *   - `exec` is deliberately stub-required. The defaults reject with a
+ *     clear error so a test forgetting to stub fails loudly instead of
+ *     silently evaluating predicates against an always-empty exec
+ *     result.
+ *   - `appendEntry` captures are tracked in a module-level WeakMap
+ *     keyed by the context object, so {@link getAppendedEntries}
+ *     accesses cleanly without leaking state across tests and without
+ *     requiring users to pass capture buffers around.
+ *   - `findEntries` draws from an entries array passed in at context
+ *     build time; it does NOT pick up entries written via the
+ *     context's own `appendEntry`. That mirrors the production
+ *     evaluator's per-call snapshot semantics — appends are visible
+ *     on the NEXT evaluation, not the current one.
+ */
+
+import type {
+  ExtensionContext,
+  ExecResult as PiExecResult,
+  ToolCallEvent,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { DEFAULT_PLUGINS, DEFAULT_RULES } from "../defaults.ts";
+import {
+  buildEvaluator,
+  EVALUATOR_BUILTIN_TRACKERS,
+  type EvaluatorHost,
+  type EvaluatorRuntime,
+} from "../evaluator.ts";
+import {
+  AGENT_LOOP_INDEX_KEY,
+  createAppendEntry,
+  isPlainObject,
+} from "../evaluator-internals/context.ts";
+import type { SyntheticEntry } from "../evaluator-internals/speculative-synthesis.ts";
+import { finalizePluginState } from "../internal/finalize-plugin-state.ts";
+import { runMergerPipeline } from "../internal/session-runtime.ts";
+import {
+  buildObserverDispatcher,
+  matchesWatch,
+  type ObserverDispatcher,
+} from "../observer-dispatcher.ts";
+import type { ResolvedPluginState } from "../plugin-merger.ts";
+import type {
+  ExecOpts,
+  ExecResult,
+  Observer,
+  ObserverContext,
+  PredicateContext,
+  PredicateHandler,
+  PredicateToolInput,
+  PredicateVerdict,
+  ToolResultEvent as SchemaToolResultEvent,
+  SteeringConfig,
+  SteeringDiagnostic,
+  WhenWalkerState,
+} from "../schema.ts";
+
+// ---------------------------------------------------------------------------
+// Capture tracking
+// ---------------------------------------------------------------------------
+
+/**
+ * Entry shape recorded by a mock context's `appendEntry`. Mirrors the
+ * call signature `appendEntry<T>(customType, data?)`; `data` is
+ * optional because pi's API accepts a bare customType.
+ */
+interface CapturedEntry {
+  readonly customType: string;
+  readonly data?: unknown;
+}
+
+/**
+ * Global, per-context append buffers. Weak so dropped contexts free
+ * the buffer. Never holds a reference to the test's context object
+ * itself beyond the weak slot.
+ */
+const appendBuffers = new WeakMap<object, CapturedEntry[]>();
+
+/**
+ * Minimal {@link EvaluatorHost} whose `appendEntry` pushes into the
+ * given capture buffer. Used by {@link mockContext} /
+ * {@link mockObserverContext} to share the production
+ * `createAppendEntry` wrapper: the wrapper expects an
+ * `EvaluatorHost`, and wiring a buffering host here lets the mocks
+ * auto-tag writes with `_agentLoopIndex` in the exact same shape the
+ * real engine and dispatcher produce.
+ *
+ * `exec` is stubbed to reject — it's never touched on this path
+ * (`createAppendEntry` only calls `host.appendEntry`) but has to be
+ * present to satisfy the {@link EvaluatorHost} shape.
+ */
+function bufferingAppendHost(buffer: CapturedEntry[]): EvaluatorHost {
+  return {
+    exec: () =>
+      Promise.reject(
+        new Error(
+          "[@cad0p/pi-steering/testing] internal: bufferingAppendHost.exec " +
+            "should never be called",
+        ),
+      ),
+    appendEntry: (customType: string, data?: unknown) => {
+      buffer.push({
+        customType,
+        ...(data !== undefined ? { data } : {}),
+      });
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+/**
+ * Build-once, invoke-many handle a test uses to drive the engine
+ * against a scenario. `evaluate` and `dispatch` have identical
+ * signatures to {@link EvaluatorRuntime.evaluate} and
+ * {@link ObserverDispatcher.dispatch} so production call sites can be
+ * ported verbatim.
+ */
+export interface Harness {
+  /** See {@link EvaluatorRuntime.evaluate}. */
+  evaluate: EvaluatorRuntime["evaluate"];
+  /** See {@link ObserverDispatcher.dispatch}. */
+  dispatch: ObserverDispatcher["dispatch"];
+  /**
+   * The effective config the harness was built from (after default
+   * injection and `disable` filtering).
+   *
+   * No-op short-circuit caveat: when `harness.diagnostics` has an
+   * error-class entry, treat `harness.config` as the post-merge,
+   * post-disabledRules-filter snapshot pi-steering would have
+   * handed to `buildEvaluator` if the diagnostics had been clean —
+   * provided as a debugging artifact, NOT an executable config
+   * production would accept (production would have thrown).
+   * Inspect `harness.diagnostics` first to learn which surface
+   * flagged a problem, then fix the source config and re-load
+   * before reading `config` for any "production would have run on
+   * this shape" interpretation.
+   */
+  readonly config: SteeringConfig;
+  /**
+   * The plugin merger's resolved state, for introspection /
+   * assertions.
+   *
+   * No-op short-circuit caveat: when an error-class diagnostic fires
+   * and the harness returns the no-op evaluator/dispatcher pair,
+   * `resolved.diagnostics` carries the FULL diagnostic list (merge-
+   * side + user-config-name + resolve-side) to mirror
+   * `harness.diagnostics`. In the regular path, `resolved.diagnostics`
+   * carries only the resolve-side stream — see
+   * {@link SteeringDiagnosticKind} for the per-kind
+   * loader-vs-merger split. Consumers should prefer
+   * `harness.diagnostics` for the canonical full list.
+   */
+  readonly resolved: ResolvedPluginState;
+  /**
+   * Every {@link SteeringDiagnostic} produced while building the
+   * harness — merge-side (within-layer collisions, cross-config
+   * collisions when {@link LoadHarnessOptions.includeDefaults} is
+   * `true`) and plugin-merger-side (predicate / observer / rule /
+   * extension-orphan / reserved-name / invalid-name diagnostics,
+   * plus user-config rule and observer name validation).
+   *
+   * Unlike production, `loadHarness` does NOT throw on error-class
+   * diagnostics. Plugin-author tests assert directly on this array
+   * (e.g. `harness.diagnostics.some(d => d.kind === "reserved-tracker-name")`)
+   * so the failure surface is observable in test output rather than
+   * a thrown error that hides which other diagnostics fired. Both
+   * plugin-shipped and user-config malformed names route through the
+   * same `kind: "invalid-name"` diagnostic stream — plugin-author
+   * tests can use a uniform matrix of malformed-name cases without
+   * worrying about which surface raised the issue.
+   *
+   * Production-strictness divergence: `loadHarness` does NOT honor
+   * the merged config's `failOnWarnings` flag. Production's
+   * `buildSessionRuntime` throws when `failOnWarnings !== false`
+   * (default `true`) AND any warning-class diagnostic is present;
+   * the harness ignores `failOnWarnings` and returns a real
+   * evaluator/dispatcher running on the post-collision merged
+   * state. Tests intending to use the harness as a "production
+   * prediction" should check this array against the strict-mode
+   * rule themselves, e.g.
+   * `harness.diagnostics.some(d => d.type === "error" || (config.failOnWarnings !== false && d.type === "warning"))`
+   * before treating the harness's verdict as production-faithful.
+   */
+  readonly diagnostics: readonly SteeringDiagnostic[];
+}
+
+/**
+ * Options for {@link loadHarness}.
+ */
+export interface LoadHarnessOptions {
+  /** The config under test. */
+  readonly config: SteeringConfig;
+
+  /**
+   * Prepend {@link DEFAULT_PLUGINS} to `config.plugins` and
+   * {@link DEFAULT_RULES} to `config.rules` at the innermost
+   * position. Mirrors the production flag via
+   * `!config.disableDefaults`, but kept explicit here so tests can
+   * exercise default rules without editing the config under test.
+   *
+   * Default: `false`.
+   */
+  readonly includeDefaults?: boolean;
+
+  /**
+   * Host to drive `exec` / `appendEntry` off. Defaults to an
+   * in-memory stub whose `exec` rejects with a clear error (tests
+   * needing exec must stub it explicitly) and whose `appendEntry`
+   * is a silent sink.
+   */
+  readonly host?: EvaluatorHost;
+}
+
+/**
+ * Build an evaluator + observer dispatcher pair from a static
+ * {@link SteeringConfig}. Tests drive rules through the same pipeline
+ * production uses, without needing a pi runtime stub or walk-up
+ * loading.
+ */
+export function loadHarness(options: LoadHarnessOptions): Harness {
+  const inputConfig = options.config;
+  const includeDefaults = options.includeDefaults ?? false;
+
+  // Run the same merge that production does (single layer here, since
+  // loadHarness operates on an in-memory config rather than a walk-up
+  // chain). The shared helper short-circuits between buildConfig and
+  // resolvePlugins on error-class merge diagnostics so a
+  // `tracker-name-collision` flagged by `buildConfig` is not also
+  // re-flagged by `resolvePlugins`. The diagnostics surface within-
+  // layer rule-name and observer-name collisions, plus tracker-name
+  // collisions and the cross-config plugin-name collisions that
+  // `includeDefaults: true` can introduce against DEFAULT_PLUGINS.
+  const defaults: SteeringConfig | undefined = includeDefaults
+    ? { rules: DEFAULT_RULES, plugins: DEFAULT_PLUGINS }
+    : undefined;
+  const {
+    merged: mergedConfig,
+    resolved,
+    diagnostics,
+  } = runMergerPipeline([inputConfig], defaults, EVALUATOR_BUILTIN_TRACKERS);
+
+  // Apply `config.disabledRules` to user + default rules. Plugin-shipped
+  // rules are filtered inside `resolvePlugins`. Mirrors
+  // `buildSessionRuntime`.
+  const disabled = new Set(mergedConfig.disabledRules ?? []);
+  const filteredConfig: SteeringConfig = { ...mergedConfig };
+  if (mergedConfig.rules !== undefined) {
+    const kept = mergedConfig.rules.filter((r) => !disabled.has(r.name));
+    if (kept.length > 0) filteredConfig.rules = kept;
+    else delete filteredConfig.rules;
+  }
+
+  // Aggregate every diagnostic produced during construction. Unlike
+  // `buildSessionRuntime`, loadHarness does NOT throw on error-class
+  // diagnostics — plugin-author tests assert on the array directly so
+  // they can see every diagnostic that fired in one read.
+  //
+  // Short-circuit on ANY error-class diagnostic — from the cross-
+  // layer merge (`buildConfig`'s `detectTrackerNameCollisions`) or
+  // from the plugin merger (`reserved-tracker-name`,
+  // `reserved-predicate-key`, `invalid-name`, `tracker-name-collision`).
+  // All error-class diagnostics produce the same no-op harness so
+  // plugin-author tests see uniform behavior regardless of which
+  // surface flagged the problem. Mirrors production's bridge-disabled
+  // state under the same conditions.
+  if (resolved === null || diagnostics.some((d) => d.type === "error")) {
+    return buildNoopHarness(filteredConfig, diagnostics);
+  }
+
+  // Mirror session-runtime's unused-observer drop so loadHarness
+  // tests produce the same verdicts as production for rules that
+  // rely on observer writes.
+  const { pluginKept, userKept } = finalizePluginState(
+    filteredConfig.rules ?? [],
+    resolved.rules,
+    filteredConfig.observers ?? [],
+    resolved.observers,
+  );
+  const filteredResolved = { ...resolved, observers: [...pluginKept] };
+
+  const host = options.host ?? defaultHarnessHost();
+  const evaluator = buildEvaluator(filteredConfig, filteredResolved, host);
+  const dispatcher = buildObserverDispatcher(filteredResolved, userKept, host);
+
+  return {
+    evaluate: evaluator.evaluate,
+    dispatch: dispatcher.dispatch,
+    config: filteredConfig,
+    resolved: filteredResolved,
+    diagnostics,
+  };
+}
+
+/**
+ * Build a no-op {@link Harness} that surfaces the given diagnostics
+ * but doesn't drive the evaluator / dispatcher. Used when an
+ * error-class loader diagnostic prevents safe construction of the
+ * runtime; mirrors production's bridge-disabled state under the same
+ * conditions.
+ */
+function buildNoopHarness(
+  config: SteeringConfig,
+  diagnostics: readonly SteeringDiagnostic[],
+): Harness {
+  const emptyResolved: ResolvedPluginState = {
+    predicates: {},
+    observers: [],
+    trackers: {},
+    trackerModifiers: {},
+    composedTrackers: {},
+    rules: [],
+    rulePluginOwners: {},
+    // Mirror harness.diagnostics so consumers reading either surface
+    // (harness.resolved.diagnostics or harness.diagnostics) see the
+    // same list. Otherwise harness.resolved.diagnostics would be
+    // silently empty in the no-op short-circuit branch while the
+    // outer harness.diagnostics carries the real entries.
+    diagnostics: [...diagnostics],
+  };
+  return {
+    evaluate: async () => {},
+    dispatch: async () => {},
+    config,
+    resolved: emptyResolved,
+    diagnostics: [...diagnostics],
+  };
+}
+
+/**
+ * Default in-memory host for {@link loadHarness}. `exec` rejects
+ * explicitly — authors needing a stub pass their own host. `appendEntry`
+ * is a silent sink (writes into a throwaway array not exposed on the
+ * return).
+ */
+function defaultHarnessHost(): EvaluatorHost {
+  return {
+    exec: () =>
+      Promise.reject(
+        new Error(
+          "loadHarness: exec not stubbed — pass options.host with an exec implementation",
+        ),
+      ),
+    appendEntry: () => {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// mockContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of an entry fed into {@link mockContext} / {@link
+ * mockObserverContext} to back `findEntries`. Mirrors the subset of
+ * pi's `CustomEntry` the evaluator + dispatcher actually read.
+ */
+export interface MockEntry {
+  readonly type: "custom";
+  readonly customType: string;
+  readonly data: unknown;
+  readonly timestamp: string;
+}
+
+/**
+ * Options for {@link priorEntry}.
+ */
+export interface PriorEntryOptions {
+  /**
+   * Agent-loop index to stamp on the payload. The engine's live
+   * `appendEntry` wrapper stamps this automatically on every write;
+   * fixture entries must reproduce the same shape so `when.happened:
+   * { in: "agent_loop" }` scope filtering works identically whether
+   * the entry was written at runtime or seeded into the mock.
+   *
+   * Defaults to `0`. Set to the value of {@link MockContextOptions.agentLoopIndex}
+   * to place the entry in the current agent loop; set to a lower
+   * value (or 0 with `agentLoopIndex: 1+` on the context) to place
+   * it in a prior agent loop.
+   */
+  readonly agentLoopIndex?: number;
+
+  /**
+   * ISO-8601 timestamp string. Defaults to `"2026-01-01T00:00:00.000Z"`.
+   * Use distinct, monotonically-increasing timestamps when seeding
+   * multiple entries the `since` invalidation sentinel needs to
+   * order.
+   */
+  readonly timestamp?: string;
+}
+
+/**
+ * Build a {@link MockEntry} for {@link MockContextOptions.entries}
+ * (and the observer-context equivalent) with the reserved
+ * `_agentLoopIndex` tag stamped on the payload exactly as the live
+ * engine's `appendEntry` wrapper would.
+ *
+ * The reserved-key name is kept as an internal detail of the engine
+ * so plugin / fixture authors don't have to remember the underscore
+ * prefix. A typo on the `agentLoopIndex` field of {@link PriorEntryOptions}
+ * is a TypeScript compile error; the equivalent typo on a hand-rolled
+ * `data: { agentLoopIndex: 5 }` literal is silent — the entry passes
+ * through `findEntries` but then fails to match the current
+ * agent-loop scope, and the rule under test appears to misbehave.
+ *
+ * Payload shaping mirrors the live `createAppendEntry`:
+ *   - Plain-object `data`: merged as `{ ...data, _agentLoopIndex }`.
+ *   - Anything else (arrays, Date, Map, Set, Error, primitives,
+ *     null, undefined): wrapped as `{ value: data, _agentLoopIndex }`.
+ *
+ * @example
+ *   const ctx = mockContext({
+ *     agentLoopIndex: 5,
+ *     entries: [
+ *       priorEntry("ws-sync-done", {}, { agentLoopIndex: 5 }),
+ *     ],
+ *   });
+ *   // `when.happened: { event: "ws-sync-done", in: "agent_loop" }`
+ *   // now sees the entry as "happened in the current loop".
+ */
+export function priorEntry(
+  customType: string,
+  data?: unknown,
+  opts?: PriorEntryOptions,
+): MockEntry {
+  const agentLoopIndex = opts?.agentLoopIndex ?? 0;
+  const tagged = isPlainObject(data)
+    ? { ...data, [AGENT_LOOP_INDEX_KEY]: agentLoopIndex }
+    : { value: data, [AGENT_LOOP_INDEX_KEY]: agentLoopIndex };
+  return {
+    type: "custom",
+    customType,
+    timestamp: opts?.timestamp ?? "2026-01-01T00:00:00.000Z",
+    data: tagged,
+  };
+}
+
+/**
+ * Re-exported for plugin authors constructing `toolCallEvents`
+ * fixtures on {@link MockContextOptions}. Structurally `{ data,
+ * timestamp, speculative: true }` — the same shape the walker-level
+ * speculative-entry synthesis pass produces in production. Plugin
+ * predicates that filter out speculative entries check
+ * `entry.speculative === true`.
+ */
+export type { SyntheticEntry } from "../evaluator-internals/speculative-synthesis.ts";
+
+/**
+ * Options for {@link mockContext}.
+ */
+export interface MockContextOptions {
+  /** Defaults to `"/tmp/test"`. */
+  readonly cwd?: string;
+
+  /** Engine agent-loop counter. Defaults to `0`. */
+  readonly agentLoopIndex?: number;
+
+  /**
+   * Which tool this predicate is evaluating under. Defaults to
+   * `"bash"`. Drives the default shape of {@link input} when the
+   * caller doesn't supply one.
+   */
+  readonly tool?: "bash" | "write" | "edit";
+
+  /**
+   * Tool input. Omitted: derived from {@link tool} as the empty
+   * shape for that tool (bash: `{ command: "" }`, write:
+   * `{ path: "", content: "" }`, edit: `{ path: "", edits: [] }`).
+   */
+  readonly input?: PredicateToolInput;
+
+  /**
+   * Walker-state snapshot the predicate sees via
+   * {@link PredicateContext.walkerState}.
+   *
+   * Defaults to `{ cwd: options.cwd, env: new Map() }` so the
+   * built-in `when.cwd` predicate and any plugin reading
+   * `walkerState.env` work without wiring up a full walker. Callers
+   * who want a specific env map or branch tracker state pass it in
+   * via this option.
+   *
+   * The typed shape is {@link WhenWalkerState} with every field
+   * optional (partial) so tests that only care about one dimension
+   * don't have to fill in the others. The engine's production path
+   * always populates `cwd` + `env`; the mock's default matches.
+   *
+   * Partial override: fields you pass merge over the defaults, so
+   * `mockContext({ walkerState: { cwd: "/x" } })` keeps the default
+   * empty env Map (same shape as production). Pass `env` explicitly
+   * only when you need a seeded map.
+   */
+  readonly walkerState?: Partial<WhenWalkerState> & Record<string, unknown>;
+
+  /**
+   * Stub for `ctx.exec`. Defaults to rejecting with a clear error
+   * message — tests that call out to exec must stub explicitly
+   * (silent `undefined` would make predicate logic hard to reason
+   * about).
+   */
+  readonly exec?: (
+    cmd: string,
+    args: readonly string[],
+    opts?: ExecOpts,
+  ) => ExecResult | Promise<ExecResult>;
+
+  /**
+   * Prior session entries `findEntries` reads from. Filtered by
+   * customType; timestamps parsed from the ISO string to epoch-ms,
+   * matching the production shape.
+   *
+   * For rules that use `when.happened: { in: "agent_loop" }` (or
+   * `in: "session"` with the same-loop filter), construct entries
+   * via {@link priorEntry} so the engine's reserved
+   * `_agentLoopIndex` tag is stamped correctly — hand-rolled
+   * literals with a typo (`agentLoopIndex` instead of the underscore
+   * form) silently fail to match the current agent-loop scope and
+   * the rule appears to misbehave.
+   */
+  readonly entries?: ReadonlyArray<MockEntry>;
+
+  /**
+   * Per-ref speculative events the built-in `when.happened` predicate
+   * reads from `ctx.walkerState.events` (see
+   * {@link PredicateContext.walkerState}'s reserved `events` key).
+   * Keys are the `customType` event literals; values are the
+   * synthetic entries for that type. When provided, overwrites any
+   * `events` entry on the caller's {@link walkerState}.
+   *
+   * Use this to drive `when.happened` with `in: "tool_call"` (or any plugin
+   * predicate that introspects `walkerState.events`) in isolation
+   * without wiring up `loadHarness` + a full bash event. The shape
+   * matches what the walker-level synthesis pass produces in
+   * production — `{ data, timestamp, speculative: true }` per entry.
+   */
+  readonly toolCallEvents?: Readonly<Record<string, readonly SyntheticEntry[]>>;
+}
+
+/**
+ * Build a {@link PredicateContext} for unit-testing predicates in
+ * isolation. See {@link MockContextOptions} for defaults. The returned
+ * context's `appendEntry` captures into a buffer accessible via
+ * {@link getAppendedEntries}.
+ */
+export function mockContext(
+  options: MockContextOptions = {},
+): PredicateContext {
+  const cwd = options.cwd ?? "/tmp/test";
+  const tool = options.tool ?? "bash";
+  const input = options.input ?? defaultInputFor(tool);
+  // Default walker state satisfies the required `cwd` + `env` fields
+  // of {@link WhenWalkerState}. Callers supplying their own
+  // walkerState get a shallow merge: defaults first, override last,
+  // so `mockContext({ walkerState: { cwd: "/x" } })` keeps the
+  // default env Map instead of dropping it (which would crash any
+  // predicate that reads `ctx.walkerState.env.get(...)`). This
+  // matches the production evaluator, which always populates both
+  // cwd and env.
+  const baseWalkerState: Record<string, unknown> = {
+    cwd,
+    env: new Map<string, string>(),
+    ...(options.walkerState as Record<string, unknown> | undefined),
+  };
+  // Fold `toolCallEvents` (option) into `walkerState.events` (ctx
+  // shape) the same way the evaluator's `prepareBashState` does —
+  // the caller doesn't have to know the reserved-key convention.
+  // Explicit option wins over any `events` entry the caller placed
+  // directly on `walkerState`.
+  const walkerState: Record<string, unknown> =
+    options.toolCallEvents !== undefined
+      ? { ...baseWalkerState, events: options.toolCallEvents }
+      : baseWalkerState;
+  const agentLoopIndex = options.agentLoopIndex ?? 0;
+  const buffer: CapturedEntry[] = [];
+
+  // Route through the production `createAppendEntry` wrapper so mock
+  // and real engine stay in lockstep: plain-object payloads get
+  // `_agentLoopIndex` merged in, everything else wraps as
+  // `{ value, _agentLoopIndex }`. Without this, a rule author testing
+  // their self-mark pattern via `mockContext` would see un-tagged
+  // entries that would never have been written that way in
+  // production, and a follow-up `when.happened: { in: "agent_loop" }`
+  // simulation would disagree with the real engine.
+  const bufferingHost = bufferingAppendHost(buffer);
+
+  const ctx: PredicateContext = {
+    cwd,
+    tool,
+    input,
+    agentLoopIndex,
+    exec: buildExec(options.exec, "mockContext"),
+    appendEntry: createAppendEntry(bufferingHost, agentLoopIndex),
+    findEntries: buildFindEntries(options.entries ?? []),
+    // Cast: mockContext's walkerState may be a user-supplied `Partial<
+    // WhenWalkerState>`. The default path above fills in cwd + env;
+    // explicit-override callers might omit them intentionally (testing
+    // plugin predicates that don't read cwd / env). The production
+    // evaluator always populates both, so tests that care match that
+    // via the default. The Partial<> option shape signals "bring what
+    // you need"; this cast acknowledges the resulting schema-strict
+    // shape is the mock's responsibility.
+    walkerState: walkerState as Readonly<WhenWalkerState>,
+  };
+
+  appendBuffers.set(ctx, buffer);
+  return ctx;
+}
+
+/**
+ * Shape-of-`input` default per tool. Kept narrow — just the shape
+ * required by `PredicateToolInput` so unit tests don't have to invent
+ * placeholder values.
+ */
+function defaultInputFor(tool: "bash" | "write" | "edit"): PredicateToolInput {
+  switch (tool) {
+    case "bash":
+      return { tool: "bash", command: "" };
+    case "write":
+      return { tool: "write", path: "", content: "" };
+    case "edit":
+      return { tool: "edit", path: "", edits: [] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// mockObserverContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for {@link mockObserverContext}. Observers don't see
+ * `tool`, `input`, or `walkerState` — those are predicate-side
+ * concepts — so those fields are omitted here.
+ */
+export type MockObserverContextOptions = Omit<
+  MockContextOptions,
+  "tool" | "input" | "walkerState" | "toolCallEvents"
+>;
+
+/**
+ * Build an {@link ObserverContext} for unit-testing observer
+ * `onResult` handlers. Same capture + `findEntries` pattern as
+ * {@link mockContext}.
+ *
+ * Note: production `ObserverContext` does NOT expose `exec` — but the
+ * mock does (as an `exec`-like stub on a different property name is
+ * more confusing than forbidding it outright). Observer authors that
+ * reach for `exec` are probably using the wrong hook; rules / plugins
+ * carrying that logic belong in a predicate. The mock still accepts
+ * the stub so tests composing an observer + predicate through a shared
+ * options object don't have to strip the field.
+ *
+ * We DO NOT attach `exec` to the returned ObserverContext — the
+ * schema doesn't expose it. The stub is accepted but silently unused
+ * at this phase; the follow-up `testObserver` wrapper (Phase 5b) will
+ * surface a warning when the stub is set but can never fire.
+ */
+export function mockObserverContext(
+  options: MockObserverContextOptions = {},
+): ObserverContext {
+  const cwd = options.cwd ?? "/tmp/test";
+  const agentLoopIndex = options.agentLoopIndex ?? 0;
+  const buffer: CapturedEntry[] = [];
+
+  // Same wrapper as mockContext: keeps the mock observer context
+  // writing entries in the auto-tagged shape the real dispatcher
+  // produces.
+  const bufferingHost = bufferingAppendHost(buffer);
+
+  const ctx: ObserverContext = {
+    cwd,
+    agentLoopIndex,
+    appendEntry: createAppendEntry(bufferingHost, agentLoopIndex),
+    findEntries: buildFindEntries(options.entries ?? []),
+  };
+
+  appendBuffers.set(ctx, buffer);
+  return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// createRecordingHost + mockExtensionContext
+// ---------------------------------------------------------------------------
+//
+// Low-level factories for tests that drive `harness.evaluate` /
+// `harness.dispatch` directly and need to inspect what the engine
+// wrote. Most plugin authors should reach for {@link loadHarness} +
+// {@link expectBlocks} / {@link expectAllows} first — those cover the
+// common rule-gating assertions without exposing the host/ctx surface.
+//
+// The factories here are the escape hatch for the 10% of tests that:
+//
+//   - Drive a multi-call sequence where earlier `appendEntry` writes
+//     must be visible to later `findEntries` reads (self-marking rules,
+//     `when.happened` gating, observer → rule handoff).
+//   - Assert the exact shape of `appendEntry` writes (audit entries,
+//     tracker state) without going through a shorthand expectation.
+//   - Compose a custom {@link EvaluatorHost} for an existing
+//     {@link loadHarness} call while still getting typed access to
+//     recorded exec / appendEntry calls.
+//
+// Use {@link createRecordingHost} with {@link loadHarness} as follows:
+//
+// ```ts
+// const host = createRecordingHost();
+// const ctx = mockExtensionContext("/tmp/test", host.entries);
+// const harness = loadHarness({ config: {...}, host });
+// await harness.evaluate(event, ctx, 1);
+// assert.ok(host.entries.some((e) => e.customType === "my-mark"));
+// ```
+//
+// Prior art: these graduate the `makeTrackedHost` + `makeCtx` helpers
+// previously private to `src/__test-helpers__.ts`. Kept as a separate
+// pair (not merged into {@link loadHarness}) so authors can wire the
+// host and ctx to their own production-runtime facsimile when the
+// default harness plumbing doesn't fit.
+
+/**
+ * Shape of a session-entry produced by {@link createRecordingHost}'s
+ * `appendEntry`, readable by an {@link ExtensionContext} built from
+ * {@link mockExtensionContext}. Mirrors the subset of pi's
+ * `CustomEntry` the engine reads — `id` and `parentId` exist on real
+ * pi entries, so we populate them too to keep type-shape drift from
+ * masking silent divergence.
+ */
+export interface RecordedSessionEntry {
+  readonly type: "custom";
+  readonly customType: string;
+  readonly data: unknown;
+  readonly timestamp: string;
+  readonly id: string;
+  readonly parentId: string | null;
+}
+
+/**
+ * Exec-call record captured by {@link createRecordingHost}. One entry
+ * per invocation, in registration order. `args` is defensively copied
+
+ * so later mutation of the caller's argv array doesn't corrupt the
+ * record.
+ */
+export interface RecordedExecCall {
+  readonly cmd: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+}
+
+/**
+ * Options for {@link createRecordingHost}.
+ */
+export interface CreateRecordingHostOptions {
+  /**
+   * Stub for `host.exec`. Receives the normalized `cwd` (either the
+   * caller's `opts.cwd` or `"/"`). Defaults to resolving with an
+   * empty successful result — override when tests need to assert
+   * behavior against a specific stdout / exit code.
+   */
+  readonly exec?: (
+    cmd: string,
+    args: readonly string[],
+    cwd: string,
+  ) => Promise<PiExecResult>;
+}
+
+/**
+ * Recording {@link EvaluatorHost}. Every `exec` and `appendEntry`
+ * call is captured into readable accumulators; `entries` mirrors the
+ * `appendEntry` writes in the shape pi's `sessionManager.getEntries()`
+ * returns, so feeding `host.entries` into {@link mockExtensionContext}
+ * makes the engine's writes visible to its subsequent reads in the
+ * same test.
+ *
+ * Note: `entries` and `execCalls` / `appendedEntries` are returned as
+ * mutable arrays so asserts can use `.some`, `.find`, etc. directly
+ * without a copy. They are owned by the host; don't splice or reassign
+ * them out from under it.
+ */
+export interface RecordingHost extends EvaluatorHost {
+  /**
+   * Session-entry log backing {@link mockExtensionContext}. Mutated
+   * in-place on every `appendEntry` call. Pass this array to
+   * `mockExtensionContext(cwd, host.entries)` so the host and the
+   * ctx share the same store.
+   */
+  readonly entries: RecordedSessionEntry[];
+
+  /** Every `exec` invocation, in call order. */
+  readonly execCalls: RecordedExecCall[];
+
+  /**
+   * Every `appendEntry(type, data)` invocation, in call order. The
+   * `data` field is stored verbatim — NOT the auto-tagged shape the
+   * engine produces (that's reflected in {@link entries} instead).
+   * This buffer is the raw host-level log; use it for assertions that
+   * care about exactly which calls the engine made.
+   */
+  readonly appendedEntries: Array<{ type: string; data: unknown }>;
+}
+
+/**
+ * Build a {@link RecordingHost}. Every `exec` call is recorded, and
+ * every `appendEntry` call appends both to {@link RecordingHost.
+ * appendedEntries} (raw host-level log) and to {@link RecordingHost.
+ * entries} (session-entry shape used by {@link mockExtensionContext}).
+ *
+ * Timestamps on the session-entry log are monotonically-incrementing
+ * ISO strings starting at `2026-01-01T00:00:00Z` (+ 1s per entry) so
+ * chronological-order asserts stay stable across test runs without a
+ * live clock dependency. Override with a wrapping host if your test
+ * needs real timestamps.
+ *
+ * The default `exec` stub resolves with an empty successful result —
+ * safer than rejecting by default because most tests don't exercise
+ * exec at all and a loud reject would swamp the signal. Opt in to
+ * rejection via `options.exec` when a test must assert "exec was NOT
+ * called".
+ */
+export function createRecordingHost(
+  options: CreateRecordingHostOptions = {},
+): RecordingHost {
+  const execCalls: RecordedExecCall[] = [];
+  const appendedEntries: Array<{ type: string; data: unknown }> = [];
+  const entries: RecordedSessionEntry[] = [];
+  let idCounter = 0;
+  return {
+    execCalls,
+    appendedEntries,
+    entries,
+    exec: async (cmd, args, opts) => {
+      const cwd = opts?.cwd ?? "/";
+      execCalls.push({ cmd, args: [...args], cwd });
+      if (options.exec) {
+        return options.exec(cmd, args, cwd);
+      }
+      return { stdout: "", stderr: "", code: 0, killed: false };
+    },
+    appendEntry: (type, data) => {
+      appendedEntries.push({ type, data });
+      entries.push({
+        type: "custom",
+        customType: type,
+        data,
+        timestamp: new Date(
+          Date.UTC(2026, 0, 1, 0, 0, idCounter++),
+        ).toISOString(),
+        id: `entry-${idCounter}`,
+        parentId: null,
+      });
+    },
+  };
+}
+
+/**
+ * Build a minimal {@link ExtensionContext} stub backed by a
+ * {@link RecordedSessionEntry} array. Used with {@link loadHarness}'s
+ * `harness.evaluate` / `harness.dispatch` when a test needs the engine
+ * to see entries a {@link RecordingHost} previously recorded.
+ *
+ * Only `cwd` and `sessionManager.getEntries()` are populated — the
+ * two fields the engine actually reads. Everything else on
+ * `ExtensionContext` throws on access (via an `unknown` cast) so an
+ * accidental reliance on unsupported surface surfaces as a clear
+ * `TypeError` rather than silently passing.
+ *
+ * Pass `host.entries` from {@link createRecordingHost} to share the
+ * backing store between the engine's writes and its subsequent reads.
+ *
+ * Choosing between this and {@link loadHarness} alone:
+ *
+ *   - Use {@link loadHarness} + {@link expectBlocks}/{@link expectAllows}
+ *     when the test only asserts block vs allow on a single event.
+ *   - Use {@link createRecordingHost} + `mockExtensionContext` when the
+ *     test drives a multi-call sequence, asserts on session-entry
+ *     shape, or inspects exec calls.
+ */
+export function mockExtensionContext(
+  cwd: string,
+  entries: ReadonlyArray<RecordedSessionEntry> = [],
+): ExtensionContext {
+  return {
+    cwd,
+    sessionManager: {
+      getEntries: () => entries,
+      // Other SessionManager methods are stubbed to throw via the
+      // unknown-cast below; any accidental dependency surfaces as a
+      // clear TypeError rather than silently passing.
+    } as unknown as ExtensionContext["sessionManager"],
+  } as ExtensionContext;
+}
+
+// ---------------------------------------------------------------------------
+// getAppendedEntries
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the `appendEntry` capture buffer for a mock context.
+ *
+ * Returns an empty array when:
+ *   - nothing has been appended yet, OR
+ *   - the context wasn't built by {@link mockContext} /
+ *     {@link mockObserverContext} (safe lookup — no throw).
+ *
+ * The returned array is a snapshot (copy) so callers can iterate
+ * without worrying about concurrent appends racing the assertion.
+ */
+export function getAppendedEntries(
+  ctx: PredicateContext | ObserverContext,
+): ReadonlyArray<{ customType: string; data?: unknown }> {
+  const buf = appendBuffers.get(ctx);
+  if (buf === undefined) return [];
+  return [...buf];
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `exec` closure for a mock context. Wraps a user-supplied
+ * stub or returns a "not stubbed" rejecter. Normalizes the return
+ * type to `Promise<ExecResult>` so sync stubs work too.
+ */
+function buildExec(
+  stub: MockContextOptions["exec"],
+  who: "mockContext" | "mockObserverContext",
+): PredicateContext["exec"] {
+  if (stub === undefined) {
+    return () =>
+      Promise.reject(new Error(`${who}: exec not stubbed — pass options.exec`));
+  }
+  return async (cmd, args, opts) => stub(cmd, args, opts);
+}
+
+/**
+ * Build the `findEntries` closure backing mock contexts. Filters the
+ * entries array by customType and projects timestamps from ISO
+ * strings to epoch-ms — matches {@link createFindEntries} on the
+ * production path.
+ *
+ * No caching here: test-context entry lists are tiny and the cache
+ * would make it harder to reason about repeated reads during a test
+ * mutating the underlying array.
+ */
+function buildFindEntries(
+  entries: ReadonlyArray<MockEntry>,
+): PredicateContext["findEntries"] {
+  return <T>(customType: string) => {
+    const out: Array<{ data: T; timestamp: number }> = [];
+    for (const entry of entries) {
+      if (entry.type !== "custom") continue;
+      if (entry.customType !== customType) continue;
+      const ts = Date.parse(entry.timestamp);
+      out.push({
+        data: entry.data as T,
+        timestamp: Number.isNaN(ts) ? 0 : ts,
+      });
+    }
+    return out;
+  };
+}
+
+// ===========================================================================
+// Phase 5b — Convenience wrappers
+// ===========================================================================
+
+// ---------------------------------------------------------------------------
+// Shorthand input types
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience shape for a bash tool-call event. Accepted by
+ * {@link expectBlocks}, {@link expectAllows}, {@link expectRuleFires},
+ * and {@link runMatrix} in place of a full {@link ToolCallEvent}.
+ */
+export interface BashShorthand {
+  readonly command: string;
+  readonly cwd?: string;
+}
+
+/** Convenience shape for a write tool-call event. */
+export interface WriteShorthand {
+  readonly write: { readonly path: string; readonly content: string };
+  readonly cwd?: string;
+}
+
+/** Convenience shape for an edit tool-call event. */
+export interface EditShorthand {
+  readonly edit: {
+    readonly path: string;
+    readonly edits: ReadonlyArray<{
+      readonly oldText: string;
+      readonly newText: string;
+    }>;
+  };
+  readonly cwd?: string;
+}
+
+/** Union of the bash/write/edit shorthands. */
+export type ToolCallShorthand = BashShorthand | WriteShorthand | EditShorthand;
+
+/**
+ * Convenience shape for a tool-result event, accepted by
+ * {@link testObserver}. Mirrors the minimal {@link SchemaToolResultEvent}
+ * fields observers actually read.
+ */
+export interface ToolResultShorthand {
+  readonly toolName: string;
+  readonly input?: unknown;
+  readonly output?: unknown;
+  readonly exitCode?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Event + context resolution helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect a {@link ToolCallShorthand} by its tag field. Actual
+ * {@link ToolCallEvent} instances carry a `type: "tool_call"` marker
+ * that shorthands never have.
+ */
+function isShorthand(
+  input: ToolCallEvent | ToolCallShorthand,
+): input is ToolCallShorthand {
+  return !("type" in input && input.type === "tool_call");
+}
+
+/**
+ * Resolve a shorthand-or-event input into a concrete
+ * {@link ToolCallEvent} + a minimal {@link ExtensionContext} stub.
+ * The stub carries only `cwd` and a `sessionManager.getEntries()`
+ * returning `[]` — enough for the evaluator to build its per-call
+ * closures without failing on undefined reads.
+ */
+function resolveToolCallEvent(
+  input: ToolCallEvent | ToolCallShorthand,
+  fallbackCwd: string,
+): { event: ToolCallEvent; ctx: ExtensionContext } {
+  const event = isShorthand(input) ? shorthandToEvent(input) : input;
+  const cwd = isShorthand(input) ? (input.cwd ?? fallbackCwd) : fallbackCwd;
+  const ctx = {
+    cwd,
+    sessionManager: { getEntries: () => [] },
+  } as unknown as ExtensionContext;
+  return { event, ctx };
+}
+
+/** Build a synthetic {@link ToolCallEvent} from a shorthand. */
+function shorthandToEvent(s: ToolCallShorthand): ToolCallEvent {
+  if ("command" in s) {
+    return {
+      type: "tool_call",
+      toolName: "bash",
+      input: { command: s.command },
+    } as unknown as ToolCallEvent;
+  }
+  if ("write" in s) {
+    return {
+      type: "tool_call",
+      toolName: "write",
+      input: { path: s.write.path, content: s.write.content },
+    } as unknown as ToolCallEvent;
+  }
+  return {
+    type: "tool_call",
+    toolName: "edit",
+    input: { path: s.edit.path, edits: s.edit.edits },
+  } as unknown as ToolCallEvent;
+}
+
+/** Short human-readable summary of an event for failure messages. */
+function describeEvent(event: ToolCallEvent): string {
+  const input = (event as unknown as { input: unknown }).input;
+  if (
+    event.toolName === "bash" &&
+    typeof input === "object" &&
+    input !== null &&
+    "command" in input
+  ) {
+    const cmd = (input as { command: unknown }).command;
+    return `bash \`${String(cmd)}\``;
+  }
+  if (typeof input === "object" && input !== null && "path" in input) {
+    const p = (input as { path: unknown }).path;
+    return `${event.toolName} ${String(p)}`;
+  }
+  return event.toolName;
+}
+
+/**
+ * Resolve a tool-result event or shorthand into a full
+ * {@link SchemaToolResultEvent}. Used by {@link testObserver} to drive
+ * observers without making the caller stand up a pi-shape result.
+ */
+function resolveToolResultEvent(
+  input: SchemaToolResultEvent | ToolResultShorthand,
+): SchemaToolResultEvent {
+  // Both shapes carry `toolName` + `input` + `output` + `exitCode?`.
+  // Accept either; project to the minimal schema shape.
+  return {
+    toolName: input.toolName,
+    input: (input as { input?: unknown }).input ?? {},
+    output: (input as { output?: unknown }).output ?? {},
+    ...(input.exitCode !== undefined ? { exitCode: input.exitCode } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// testPredicate
+// ---------------------------------------------------------------------------
+
+/**
+ * Drive a single {@link PredicateHandler} against a {@link mockContext}.
+ * Returns the boolean verdict.
+ *
+ * Usage:
+ * ```ts
+ * const fires = await testPredicate(branch, /^main$/, {
+ *   walkerState: { branch: "main" },
+ * });
+ * ```
+ *
+ * Chain-aware predicates (e.g. the built-in `happened` with its
+ * `&&`-chain speculative allow) read per-ref synthetic events from
+ * `ctx.walkerState.events`. Populate `toolCallEvents` (or set
+ * `walkerState` directly) in {@link MockContextOptions} to simulate
+ * that surface in isolation without wiring up `loadHarness` + a
+ * full bash event.
+ */
+export async function testPredicate<A = unknown>(
+  predicate: PredicateHandler<A>,
+  args: A,
+  options: MockContextOptions = {},
+): Promise<PredicateVerdict> {
+  const ctx = mockContext(options);
+  return predicate(args, ctx);
+}
+
+// ---------------------------------------------------------------------------
+// testObserver
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire an {@link Observer} at an event, returning the captured
+ * `appendEntry` writes plus whether the observer's `watch` filter
+ * accepted the event. Use the `entries` field to assert what the
+ * observer recorded; use `watchMatched` to assert the filter gated
+ * firing correctly.
+ *
+ * If the observer's `watch` did NOT match, `onResult` is NOT called
+ * (mirrors production dispatch).
+ *
+ * If `options.exec` is supplied, emits a `console.warn` — observers
+ * don't see `exec`, so the stub can never fire. Exists on the options
+ * shape only because {@link MockObserverContextOptions} is derived
+ * from {@link MockContextOptions} for ergonomic test composition.
+ */
+export async function testObserver(
+  observer: Observer,
+  event: SchemaToolResultEvent | ToolResultShorthand,
+  options: MockObserverContextOptions = {},
+): Promise<{
+  entries: ReadonlyArray<{ customType: string; data?: unknown }>;
+  watchMatched: boolean;
+}> {
+  if (options.exec !== undefined) {
+    console.warn(
+      "testObserver: exec option ignored — ObserverContext doesn't expose exec",
+    );
+  }
+
+  const ctx = mockObserverContext(options);
+  const resolvedEvent = resolveToolResultEvent(event);
+  const watchMatched = matchesWatch(observer.watch, resolvedEvent);
+
+  if (watchMatched) {
+    await Promise.resolve(observer.onResult(resolvedEvent, ctx));
+  }
+
+  return { entries: getAppendedEntries(ctx), watchMatched };
+}
+
+// ---------------------------------------------------------------------------
+// expectBlocks / expectAllows / expectRuleFires
+// ---------------------------------------------------------------------------
+
+/** Options for {@link expectBlocks}. */
+export interface ExpectBlocksOptions {
+  /**
+   * Expected rule name — matched against the `[steering:<name>@<source>]`
+   * prefix (source-tagged format per ADR §11). The source suffix is
+   * ignored for matching; pass the bare rule name.
+   */
+  readonly rule?: string;
+  /** Expected reason — exact string match (string) or pattern match (RegExp). */
+  readonly reason?: string | RegExp;
+}
+
+/**
+ * Extract the rule name from a block reason. Reasons are source-tagged
+ * as `[steering:<rule>@<source>] …`; we return the `<rule>` portion
+ * so callers can assert by name without caring which plugin shipped
+ * the rule.
+ */
+function extractRuleName(reason: string): string | null {
+  const m = reason.match(/^\[steering:([^@\]]+)(?:@[^\]]+)?\]/);
+  return m?.[1] ?? null;
+}
+
+/** Normalize the `ToolCallEventResult` to a concrete block payload or null. */
+// biome-ignore lint/suspicious/noConfusingVoidType: mirrors EvaluatorRuntime["evaluate"]'s return type (`void` when the event passes through unblocked); callers pass its result through unchanged.
+function interpretResult(result: ToolCallEventResult | void): {
+  blocked: boolean;
+  reason: string | null;
+} {
+  if (result === undefined || result === null) {
+    return { blocked: false, reason: null };
+  }
+  const r = result as { block?: boolean; reason?: unknown };
+  if (r.block !== true) return { blocked: false, reason: null };
+  return {
+    blocked: true,
+    reason: typeof r.reason === "string" ? r.reason : String(r.reason ?? ""),
+  };
+}
+
+/**
+ * Assert that the harness blocks the given event. Returns the block
+ * payload for further inspection. Throws on allow.
+ *
+ * Optional `expected.rule` / `expected.reason` narrow the assertion:
+ *   - `rule: "no-force-push"` — the fired rule's name must match.
+ *   - `reason: /force-push/` — the reason string must match (exact
+ *     string or regex).
+ */
+export async function expectBlocks(
+  harness: Harness,
+  event: ToolCallEvent | ToolCallShorthand,
+  expected: ExpectBlocksOptions = {},
+): Promise<ToolCallEventResult> {
+  const { event: resolvedEvent, ctx } = resolveToolCallEvent(
+    event,
+    "/tmp/test",
+  );
+  const result = await harness.evaluate(resolvedEvent, ctx, 0);
+  const { blocked, reason } = interpretResult(result);
+
+  if (!blocked) {
+    throw new Error(
+      `expectBlocks: expected block, got allow for ${describeEvent(resolvedEvent)} at ${ctx.cwd}`,
+    );
+  }
+
+  if (expected.rule !== undefined) {
+    const firedRule = extractRuleName(reason ?? "");
+    if (firedRule !== expected.rule) {
+      throw new Error(
+        `expectBlocks: expected rule "${expected.rule}" to fire, ` +
+          `got "${firedRule ?? "<none>"}" for ${describeEvent(resolvedEvent)}\n` +
+          `  reason: ${reason}`,
+      );
+    }
+  }
+
+  if (expected.reason !== undefined && reason !== null) {
+    const matches =
+      expected.reason instanceof RegExp
+        ? expected.reason.test(reason)
+        : expected.reason === reason;
+    if (!matches) {
+      throw new Error(
+        `expectBlocks: reason did not match expected pattern\n` +
+          `  expected: ${String(expected.reason)}\n` +
+          `  got:      ${reason}`,
+      );
+    }
+  }
+
+  return result as ToolCallEventResult;
+}
+
+/**
+ * Assert that the harness allows the given event (no rule fires).
+ * Throws with a rich message on block.
+ */
+export async function expectAllows(
+  harness: Harness,
+  event: ToolCallEvent | ToolCallShorthand,
+): Promise<void> {
+  const { event: resolvedEvent, ctx } = resolveToolCallEvent(
+    event,
+    "/tmp/test",
+  );
+  const result = await harness.evaluate(resolvedEvent, ctx, 0);
+  const { blocked, reason } = interpretResult(result);
+
+  if (blocked) {
+    const firedRule = extractRuleName(reason ?? "") ?? "<unknown>";
+    throw new Error(
+      `expectAllows: expected allow, got block for ${describeEvent(resolvedEvent)}\n` +
+        `  rule:   ${firedRule}\n` +
+        `  reason: ${reason}`,
+    );
+  }
+}
+
+/**
+ * Assert that a specific rule fires on the given event. Thin alias
+ * over {@link expectBlocks}; kept as a distinct helper for tests whose
+ * intent is "which rule fired" rather than "the tool was blocked".
+ */
+export async function expectRuleFires(
+  harness: Harness,
+  event: ToolCallEvent | ToolCallShorthand,
+  ruleName: string,
+): Promise<void> {
+  await expectBlocks(harness, event, { rule: ruleName });
+}
+
+// ---------------------------------------------------------------------------
+// runMatrix / formatMatrix
+// ---------------------------------------------------------------------------
+
+/** One row of a {@link runMatrix} input. */
+export interface MatrixCase {
+  readonly name: string;
+  readonly event: ToolCallEvent | ToolCallShorthand;
+  readonly expect:
+    | "block"
+    | "allow"
+    | { readonly block: true; readonly rule?: string };
+  readonly cwd?: string;
+}
+
+/** Per-case outcome. */
+export interface MatrixCaseResult {
+  readonly case: MatrixCase;
+  readonly passed: boolean;
+  readonly actual: "block" | "allow";
+  readonly reason?: string;
+  readonly errorMessage?: string;
+}
+
+/** Aggregate outcome of {@link runMatrix}. */
+export interface MatrixResult {
+  readonly total: number;
+  readonly passed: number;
+  readonly failed: number;
+  readonly cases: ReadonlyArray<MatrixCaseResult>;
+}
+
+/**
+ * Batch-evaluate a list of cases against a harness. Never throws —
+ * failures surface in `result.cases`. Pair with {@link formatMatrix}
+ * to render a human-readable report.
+ */
+export async function runMatrix(
+  harness: Harness,
+  cases: readonly MatrixCase[],
+): Promise<MatrixResult> {
+  const caseResults: MatrixCaseResult[] = [];
+
+  for (const c of cases) {
+    const fallback = c.cwd ?? "/tmp/test";
+    const { event, ctx } = resolveToolCallEvent(c.event, fallback);
+    const evalResult = await harness.evaluate(event, ctx, 0);
+    const { blocked, reason } = interpretResult(evalResult);
+    const actual: "block" | "allow" = blocked ? "block" : "allow";
+
+    let passed = false;
+    let errorMessage: string | undefined;
+
+    if (c.expect === "allow") {
+      passed = !blocked;
+      if (!passed) {
+        errorMessage = `expected allow; got block (${extractRuleName(reason ?? "") ?? "<unknown>"})`;
+      }
+    } else if (c.expect === "block") {
+      passed = blocked;
+      if (!passed) errorMessage = "expected block; got allow";
+    } else {
+      if (!blocked) {
+        passed = false;
+        errorMessage = "expected block; got allow";
+      } else if (c.expect.rule !== undefined) {
+        const firedRule = extractRuleName(reason ?? "");
+        passed = firedRule === c.expect.rule;
+        if (!passed) {
+          errorMessage = `expected rule "${c.expect.rule}"; got "${firedRule ?? "<unknown>"}"`;
+        }
+      } else {
+        passed = true;
+      }
+    }
+
+    caseResults.push({
+      case: c,
+      passed,
+      actual,
+      ...(reason !== null ? { reason } : {}),
+      ...(errorMessage !== undefined ? { errorMessage } : {}),
+    });
+  }
+
+  const passed = caseResults.filter((r) => r.passed).length;
+  return {
+    total: caseResults.length,
+    passed,
+    failed: caseResults.length - passed,
+    cases: caseResults,
+  };
+}
+
+/**
+ * Pretty-print a {@link MatrixResult}. ASCII-friendly for CI log
+ * aggregators; structure mirrors the adversarial-matrix report style.
+ */
+export function formatMatrix(result: MatrixResult): string {
+  const lines: string[] = [];
+  lines.push(
+    `MATRIX — ${result.total} cases. ${result.passed} pass, ${result.failed} fail.`,
+  );
+  lines.push("=".repeat(64));
+  for (const r of result.cases) {
+    const expect =
+      typeof r.case.expect === "string"
+        ? r.case.expect
+        : `block:${r.case.expect.rule ?? "*"}`;
+    const actualLabel =
+      r.actual === "block"
+        ? `BLOCK (${extractRuleName(r.reason ?? "") ?? "?"})`
+        : "allow";
+    const status = r.passed ? "" : "  FAIL";
+    lines.push(
+      `[${r.case.name}]  expect:${expect}  actual:${actualLabel}${status}`,
+    );
+    if (!r.passed && r.errorMessage) {
+      lines.push(`  ↳ ${r.errorMessage}`);
+    }
+  }
+  lines.push("=".repeat(64));
+  lines.push(`PASS: ${result.passed}/${result.total}`);
+  return lines.join("\n");
+}