@cad0p/pi-steering 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,747 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+import { DEFAULT_PLUGINS, DEFAULT_RULES } from "../defaults.js";
+import { buildEvaluator, EVALUATOR_BUILTIN_TRACKERS, } from "../evaluator.js";
+import { AGENT_LOOP_INDEX_KEY, createAppendEntry, isPlainObject, } from "../evaluator-internals/context.js";
+import { finalizePluginState } from "../internal/finalize-plugin-state.js";
+import { runMergerPipeline } from "../internal/session-runtime.js";
+import { buildObserverDispatcher, matchesWatch, } from "../observer-dispatcher.js";
+/**
+ * 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();
+/**
+ * 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) {
+    return {
+        exec: () => Promise.reject(new Error("[@cad0p/pi-steering/testing] internal: bufferingAppendHost.exec " +
+            "should never be called")),
+        appendEntry: (customType, data) => {
+            buffer.push({
+                customType,
+                ...(data !== undefined ? { data } : {}),
+            });
+        },
+    };
+}
+/**
+ * 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) {
+    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 = 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 = { ...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, diagnostics) {
+    const emptyResolved = {
+        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() {
+    return {
+        exec: () => Promise.reject(new Error("loadHarness: exec not stubbed — pass options.host with an exec implementation")),
+        appendEntry: () => { },
+    };
+}
+/**
+ * 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, data, opts) {
+    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,
+    };
+}
+/**
+ * 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 = {}) {
+    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 = {
+        cwd,
+        env: new Map(),
+        ...options.walkerState,
+    };
+    // 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 = options.toolCallEvents !== undefined
+        ? { ...baseWalkerState, events: options.toolCallEvents }
+        : baseWalkerState;
+    const agentLoopIndex = options.agentLoopIndex ?? 0;
+    const buffer = [];
+    // 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 = {
+        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,
+    };
+    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) {
+    switch (tool) {
+        case "bash":
+            return { tool: "bash", command: "" };
+        case "write":
+            return { tool: "write", path: "", content: "" };
+        case "edit":
+            return { tool: "edit", path: "", edits: [] };
+    }
+}
+/**
+ * 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 = {}) {
+    const cwd = options.cwd ?? "/tmp/test";
+    const agentLoopIndex = options.agentLoopIndex ?? 0;
+    const buffer = [];
+    // 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 = {
+        cwd,
+        agentLoopIndex,
+        appendEntry: createAppendEntry(bufferingHost, agentLoopIndex),
+        findEntries: buildFindEntries(options.entries ?? []),
+    };
+    appendBuffers.set(ctx, buffer);
+    return ctx;
+}
+/**
+ * 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 = {}) {
+    const execCalls = [];
+    const appendedEntries = [];
+    const entries = [];
+    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, entries = []) {
+    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.
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 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) {
+    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, who) {
+    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) {
+    return (customType) => {
+        const out = [];
+        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,
+                timestamp: Number.isNaN(ts) ? 0 : ts,
+            });
+        }
+        return out;
+    };
+}
+// ---------------------------------------------------------------------------
+// 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) {
+    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, fallbackCwd) {
+    const event = isShorthand(input) ? shorthandToEvent(input) : input;
+    const cwd = isShorthand(input) ? (input.cwd ?? fallbackCwd) : fallbackCwd;
+    const ctx = {
+        cwd,
+        sessionManager: { getEntries: () => [] },
+    };
+    return { event, ctx };
+}
+/** Build a synthetic {@link ToolCallEvent} from a shorthand. */
+function shorthandToEvent(s) {
+    if ("command" in s) {
+        return {
+            type: "tool_call",
+            toolName: "bash",
+            input: { command: s.command },
+        };
+    }
+    if ("write" in s) {
+        return {
+            type: "tool_call",
+            toolName: "write",
+            input: { path: s.write.path, content: s.write.content },
+        };
+    }
+    return {
+        type: "tool_call",
+        toolName: "edit",
+        input: { path: s.edit.path, edits: s.edit.edits },
+    };
+}
+/** Short human-readable summary of an event for failure messages. */
+function describeEvent(event) {
+    const input = event.input;
+    if (event.toolName === "bash" &&
+        typeof input === "object" &&
+        input !== null &&
+        "command" in input) {
+        const cmd = input.command;
+        return `bash \`${String(cmd)}\``;
+    }
+    if (typeof input === "object" && input !== null && "path" in input) {
+        const p = input.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) {
+    // Both shapes carry `toolName` + `input` + `output` + `exitCode?`.
+    // Accept either; project to the minimal schema shape.
+    return {
+        toolName: input.toolName,
+        input: input.input ?? {},
+        output: input.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(predicate, args, options = {}) {
+    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, event, options = {}) {
+    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 };
+}
+/**
+ * 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) {
+    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) {
+    if (result === undefined || result === null) {
+        return { blocked: false, reason: null };
+    }
+    const r = result;
+    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, event, expected = {}) {
+    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;
+}
+/**
+ * Assert that the harness allows the given event (no rule fires).
+ * Throws with a rich message on block.
+ */
+export async function expectAllows(harness, event) {
+    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, event, ruleName) {
+    await expectBlocks(harness, event, { rule: ruleName });
+}
+/**
+ * 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, cases) {
+    const caseResults = [];
+    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 = blocked ? "block" : "allow";
+        let passed = false;
+        let errorMessage;
+        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) {
+    const lines = [];
+    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");
+}
+//# sourceMappingURL=index.js.map