@openagentsinc/conformance-kit 0.2.0-rc.2

package/src/event-log-laws.ts

@@ -0,0 +1,273 @@
+import { Deferred, Effect, Fiber, Ref, Stream } from "effect";
+import {
+  buildTextDelta,
+  buildTurnFinished,
+  buildTurnStarted,
+  type HarnessEventLogStore,
+  makeHarnessEventLog,
+} from "@openagentsinc/agent-harness-contract";
+import type { KhalaRuntimeSource } from "@openagentsinc/agent-runtime-schema";
+import { describe, expect, test } from "vite-plus/test";
+
+import { scriptTurn, sequencesOf, TEST_SOURCE } from "./fixtures.ts";
+
+/**
+ * Configuration for {@link runEventLogLaws}. The implementation under test is a
+ * factory that produces a fresh {@link HarnessEventLogStore} — the persistence
+ * port a real backend (the desktop local-turn journal, the managed-sandbox
+ * event store, or a third party's store) implements. The kit builds the
+ * {@link makeHarnessEventLog} runtime over the store, so a store that satisfies
+ * the port passes both the store-level and the live-attach laws.
+ */
+export interface EventLogLawsConfig {
+  /** A short label naming the implementation under test, used in test titles. */
+  readonly label: string;
+  /** Produce a fresh, empty store. Called once per law so laws never share state. */
+  readonly makeStore: () => Effect.Effect<HarnessEventLogStore>;
+  /** The event source label. Defaults to the shared `test_fixture` source. */
+  readonly source?: KhalaRuntimeSource;
+}
+
+/**
+ * The durable event-log laws, parameterized over any store.
+ *
+ * Promoted, published form of `agent-harness-contract/src/event-log.test.ts`:
+ *
+ * - **Append monotonicity / dup-free.** A non-increasing sequence for a turn
+ *   (duplicate or out-of-order) is rejected with a typed error — this is what
+ *   makes replay duplicate-free.
+ * - **Gap-free, dup-free replay from a cursor.** `read` / `replay` return
+ *   exactly the events after the cursor, ascending, no gap and no duplicate.
+ * - **Durable replay after process death.** A fresh log runtime over the SAME
+ *   store replays everything a dead producer persisted.
+ * - **Rerun boundaries are recorded and reported** so a recomputed tail is
+ *   distinguishable from an exact attach.
+ * - **Live attach** replays the persisted tail then follows new events with no
+ *   gap or duplicate at the seam.
+ * - **Single-flight attach.** A newer attach for the same `(turn, class)`
+ *   supersedes the older so a reconnecting consumer never double-runs.
+ */
+export const runEventLogLaws = (config: EventLogLawsConfig): void => {
+  const { label, makeStore } = config;
+  const source = config.source ?? TEST_SOURCE;
+
+  const turn = (turnId: string, words: ReadonlyArray<string>, startSeq = 0) =>
+    scriptTurn({ turnId, threadId: "s1", words, startSeq, source });
+
+  describe(`[${label}] event log — durable replay`, () => {
+    test("rejects a duplicate or out-of-order sequence for a turn", async () => {
+      const exit = await Effect.runPromiseExit(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const [first] = turn("t1", []); // just turn.started at seq 0
+          yield* store.append(first!);
+          // Re-append the same sequence 0 — must be rejected.
+          yield* store.append(first!);
+        }),
+      );
+      expect(exit._tag).toBe("Failure");
+    });
+
+    test("read returns exactly the tail after a cursor, ascending, gap-free and dup-free", async () => {
+      const tail = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          yield* Effect.forEach(turn("t1", ["a", "b", "c"]), (event) => store.append(event));
+          return yield* store.read({ turnId: "t1", fromCursor: 1 });
+        }),
+      );
+      expect(sequencesOf(tail)).toEqual([2, 3, 4]);
+      expect(new Set(sequencesOf(tail)).size).toBe(tail.length);
+    });
+
+    test("lastCursor is -1 when empty and the greatest stored sequence otherwise", async () => {
+      const cursors = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const empty = yield* store.lastCursor({ turnId: "t1" });
+          yield* Effect.forEach(turn("t1", ["a", "b"]), (event) => store.append(event));
+          const filled = yield* store.lastCursor({ turnId: "t1" });
+          return { empty, filled };
+        }),
+      );
+      expect(cursors.empty).toBe(-1);
+      expect(cursors.filled).toBe(3);
+    });
+
+    test("replays the tail from a cursor after process death (fresh runtime, same store)", async () => {
+      const outcome = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const script = turn("t1", ["a", "b", "c"]); // sequences 0..4
+
+          // Producer runtime appends the whole turn, then "dies".
+          const producer = yield* makeHarnessEventLog(store);
+          yield* Effect.forEach(script, (event) => producer.appendEvent(event));
+
+          // A different runtime rehydrates over the SAME store and replays from 1.
+          const recovered = yield* makeHarnessEventLog(store);
+          const tail = yield* Stream.runCollect(recovered.replay({ turnId: "t1", fromCursor: 1 }));
+          const last = yield* recovered.lastCursor({ turnId: "t1" });
+          const all = yield* Stream.runCollect(recovered.replay({ turnId: "t1", fromCursor: -1 }));
+          return { tail, last, all };
+        }),
+      );
+      expect(sequencesOf(outcome.tail)).toEqual([2, 3, 4]);
+      expect(new Set(sequencesOf(outcome.tail)).size).toBe(outcome.tail.length);
+      expect(outcome.last).toBe(4);
+      // A full replay from -1 returns the entire turn exactly once.
+      expect(sequencesOf(outcome.all)).toEqual([0, 1, 2, 3, 4]);
+    });
+  });
+
+  describe(`[${label}] event log — rerun boundary visibility`, () => {
+    test("records and reports a rerun boundary so a recomputed tail is distinguishable", async () => {
+      const boundaries = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const log = yield* makeHarnessEventLog(store);
+          yield* Effect.forEach(turn("t1", ["a"]), (event) => log.appendEvent(event));
+          yield* log.markRerunBoundary({ turnId: "t1", atCursor: 1 });
+          return yield* log.rerunBoundaries({ turnId: "t1" });
+        }),
+      );
+      expect(boundaries).toEqual([1]);
+    });
+  });
+
+  describe(`[${label}] event log — live attach`, () => {
+    test("attach replays the persisted tail then follows new events with no gap or duplicate", async () => {
+      const collected = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const log = yield* makeHarnessEventLog(store);
+
+          // Persist the first two events (seq 0, 1).
+          yield* log.appendEvent(
+            buildTurnStarted({ turnId: "t1", threadId: "s1", sequence: 0, source }),
+          );
+          yield* log.appendEvent(
+            buildTextDelta({
+              turnId: "t1",
+              threadId: "s1",
+              sequence: 1,
+              source,
+              messageId: "m",
+              text: "a",
+            }),
+          );
+
+          // Attach from cursor 0 (want seq 1 onward): replay 1, then live 2..3.
+          const sink = yield* Ref.make<ReadonlyArray<number>>([]);
+          const wantCount = 3; // seq 1, 2, 3
+          const done = yield* Deferred.make<void>();
+          const fiber = yield* Effect.forkChild(
+            log.attach({ turnId: "t1", fromCursor: 0, consumerClass: "renderer" }).pipe(
+              Stream.runForEach((event) =>
+                Effect.gen(function* () {
+                  const next = yield* Ref.updateAndGet(sink, (xs) => [...xs, event.sequence]);
+                  if (next.length >= wantCount) {
+                    yield* Deferred.succeed(done, undefined);
+                  }
+                }),
+              ),
+            ),
+          );
+
+          // Append two more live events after the attach is running.
+          yield* log.appendEvent(
+            buildTextDelta({
+              turnId: "t1",
+              threadId: "s1",
+              sequence: 2,
+              source,
+              messageId: "m",
+              text: "b",
+            }),
+          );
+          yield* log.appendEvent(
+            buildTurnFinished({
+              turnId: "t1",
+              threadId: "s1",
+              sequence: 3,
+              source,
+              finishReason: "stop",
+            }),
+          );
+
+          yield* Deferred.await(done);
+          yield* Fiber.interrupt(fiber);
+          return yield* Ref.get(sink);
+        }),
+      );
+
+      expect(collected).toEqual([1, 2, 3]);
+      expect(new Set(collected).size).toBe(collected.length);
+    });
+
+    test("single-flight: a newer attach for the same (turn, class) supersedes the older", async () => {
+      const result = await Effect.runPromise(
+        Effect.gen(function* () {
+          const store = yield* makeStore();
+          const log = yield* makeHarnessEventLog(store);
+          yield* log.appendEvent(
+            buildTurnStarted({ turnId: "t1", threadId: "s1", sequence: 0, source }),
+          );
+
+          const sinkA = yield* Ref.make<ReadonlyArray<number>>([]);
+          const sinkB = yield* Ref.make<ReadonlyArray<number>>([]);
+          const bGot = yield* Deferred.make<void>();
+          const aReplayed = yield* Deferred.make<void>();
+
+          // Attach A replays seq 0 then follows. Receiving seq 0 proves A is the
+          // active subscriber — deterministic, no sleep needed.
+          const fiberA = yield* Effect.forkChild(
+            log.attach({ turnId: "t1", fromCursor: -1, consumerClass: "renderer" }).pipe(
+              Stream.runForEach((event) =>
+                Effect.gen(function* () {
+                  yield* Ref.update(sinkA, (xs) => [...xs, event.sequence]);
+                  yield* Deferred.succeed(aReplayed, undefined);
+                }),
+              ),
+            ),
+          );
+          yield* Deferred.await(aReplayed);
+
+          // Attach B for the SAME (turn, class) — supersedes A.
+          const fiberB = yield* Effect.forkChild(
+            log.attach({ turnId: "t1", fromCursor: 0, consumerClass: "renderer" }).pipe(
+              Stream.runForEach((event) =>
+                Effect.gen(function* () {
+                  yield* Ref.update(sinkB, (xs) => [...xs, event.sequence]);
+                  yield* Deferred.succeed(bGot, undefined);
+                }),
+              ),
+            ),
+          );
+
+          // A should be interrupted by the supersede; await its fiber.
+          yield* Fiber.await(fiberA);
+
+          // Publish a new event; only B (the live subscriber) should receive it.
+          yield* log.appendEvent(
+            buildTextDelta({
+              turnId: "t1",
+              threadId: "s1",
+              sequence: 1,
+              source,
+              messageId: "m",
+              text: "b",
+            }),
+          );
+          yield* Deferred.await(bGot);
+          yield* Fiber.interrupt(fiberB);
+
+          return { a: yield* Ref.get(sinkA), b: yield* Ref.get(sinkB) };
+        }),
+      );
+
+      expect(result.a).toEqual([0]);
+      expect(result.b).toContain(1);
+    });
+  });
+};

package/src/fixtures.ts

@@ -0,0 +1,106 @@
+import { Effect, Stream } from "effect";
+import {
+  buildTextDelta,
+  buildTurnFinished,
+  buildTurnStarted,
+  type HarnessStreamEvent,
+} from "@openagentsinc/agent-harness-contract";
+import type { KhalaRuntimeSource } from "@openagentsinc/agent-runtime-schema";
+
+/**
+ * Shared, deterministic fixtures for the conformance kit's law suites. Every
+ * builder here is pure and clock-free: identical inputs give identical events,
+ * so a law suite is reproducible against any implementation under test.
+ */
+
+/** The canonical source label the kit stamps on every fixture event. */
+export const TEST_SOURCE: KhalaRuntimeSource = { lane: "test_fixture" };
+
+/** The `sequence` list of a run of events — the shape most laws assert over. */
+export const sequencesOf = (events: ReadonlyArray<HarnessStreamEvent>): ReadonlyArray<number> =>
+  events.map((event) => event.sequence);
+
+/**
+ * A full scripted turn: `turn.started`, one `text.delta` per word, then
+ * `turn.finished`. Sequences are contiguous from `startSeq`. This is the same
+ * scripted turn shape the in-repo reference suites use, hoisted so a consumer
+ * building its own store/log fixtures reuses the exact event vocabulary.
+ */
+export const scriptTurn = (params: {
+  readonly turnId: string;
+  readonly threadId: string;
+  readonly words: ReadonlyArray<string>;
+  readonly startSeq?: number;
+  readonly source?: KhalaRuntimeSource;
+}): ReadonlyArray<HarnessStreamEvent> => {
+  const source = params.source ?? TEST_SOURCE;
+  const events: Array<HarnessStreamEvent> = [];
+  let seq = params.startSeq ?? 0;
+  events.push(
+    buildTurnStarted({ turnId: params.turnId, threadId: params.threadId, sequence: seq++, source }),
+  );
+  for (const word of params.words) {
+    events.push(
+      buildTextDelta({
+        turnId: params.turnId,
+        threadId: params.threadId,
+        sequence: seq++,
+        source,
+        messageId: `msg.${params.turnId}`,
+        text: word,
+      }),
+    );
+  }
+  events.push(
+    buildTurnFinished({
+      turnId: params.turnId,
+      threadId: params.threadId,
+      sequence: seq++,
+      source,
+      finishReason: "stop",
+    }),
+  );
+  return events;
+};
+
+/** Collect a finite harness stream into an array. */
+export const collect = <E>(
+  stream: Stream.Stream<HarnessStreamEvent, E>,
+): Effect.Effect<ReadonlyArray<HarnessStreamEvent>, E> => Stream.runCollect(stream);
+
+/**
+ * Run an effect and report whether it succeeded or failed, without letting the
+ * typed failure escape. Law suites use this to probe optional behavior: a
+ * refused capability must fail with a specific typed error, and the suite must
+ * be able to observe that failure and assert on it rather than aborting.
+ */
+export type Attempt<A, E> =
+  | { readonly _tag: "ok"; readonly value: A }
+  | { readonly _tag: "failed"; readonly error: E };
+
+export const attempt = <A, E>(effect: Effect.Effect<A, E>): Effect.Effect<Attempt<A, E>> =>
+  effect.pipe(
+    Effect.map((value): Attempt<A, E> => ({ _tag: "ok", value })),
+    Effect.catch((error: E) => Effect.succeed<Attempt<A, E>>({ _tag: "failed", error })),
+  );
+
+/**
+ * Assert a run of events is a contiguous, gap-free, duplicate-free ascending
+ * sequence. Returns the sequence list so a caller can chain further checks.
+ */
+export const assertContiguous = (
+  events: ReadonlyArray<HarnessStreamEvent>,
+  params: { readonly from: number },
+): ReadonlyArray<number> => {
+  const seqs = sequencesOf(events);
+  const expected = seqs.map((_, index) => params.from + index);
+  if (JSON.stringify(seqs) !== JSON.stringify(expected)) {
+    throw new Error(
+      `expected contiguous sequences from ${params.from}: got ${JSON.stringify(seqs)}`,
+    );
+  }
+  if (new Set(seqs).size !== seqs.length) {
+    throw new Error(`expected no duplicate sequences: got ${JSON.stringify(seqs)}`);
+  }
+  return seqs;
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @openagentsinc/conformance-kit — published law suites for the
+ * `@openagentsinc/ai` contracts.
+ *
+ * Each law suite is a runner a consumer calls in their own test file,
+ * parameterized over the implementation under test. Point one at your adapter,
+ * store, reducer, recall source, or RLM engine and it either passes the kit or
+ * it is not conformant. The kit's own tests run every suite against the in-repo
+ * reference implementations, so the kit is proven to work.
+ */
+export { runAdapterLaws, type AdapterLawsConfig } from "./adapter-laws.ts";
+export { runEventLogLaws, type EventLogLawsConfig } from "./event-log-laws.ts";
+export { runReducerLaws, type ReducerLawsConfig } from "./reducer-laws.ts";
+export { runRecallLaws, type RecallLawsConfig, type RecallSource } from "./recall-laws.ts";
+export { runRlmCapLaws, type RlmCapLawsConfig } from "./rlm-cap-laws.ts";
+export {
+  assertContiguous,
+  attempt,
+  type Attempt,
+  collect,
+  scriptTurn,
+  sequencesOf,
+  TEST_SOURCE,
+} from "./fixtures.ts";

package/src/recall-laws.test.ts

@@ -0,0 +1,10 @@
+import { recallTierD } from "@openagentsinc/history-corpus";
+
+import { runRecallLaws } from "./recall-laws.ts";
+
+// The kit run against the in-repo reference recall backend (Tier D) proves the
+// kit itself works.
+runRecallLaws({
+  label: "recall-tier-d",
+  recall: (params) => recallTierD(params),
+});

package/src/recall-laws.ts

@@ -0,0 +1,270 @@
+import { Effect } from "effect";
+import {
+  buildTextDelta,
+  buildTurnFinished,
+  buildTurnStarted,
+  type HarnessStreamEvent,
+  makeInMemoryEventLogStore,
+} from "@openagentsinc/agent-harness-contract";
+import {
+  buildHistoryCorpus,
+  type HistoryCorpusEntry,
+  type HistoryCorpusPolicy,
+  HistoryRecallError,
+  historyRecallDefaultCaps,
+  type HistoryRecallCaps,
+  type HistoryRecallQuestion,
+  type HistoryRecallResponse,
+} from "@openagentsinc/history-corpus";
+import type { KhalaRuntimeSource } from "@openagentsinc/agent-runtime-schema";
+import { describe, expect, test } from "vite-plus/test";
+
+const SOURCE: KhalaRuntimeSource = { lane: "test_fixture" };
+const BUILT_AT = "2026-07-21T12:00:00.000Z";
+const THREAD_ID = "t1";
+const TURN_COUNT = 120;
+const PLANTED_TURN = 80;
+const LONG_TURN = 100;
+const PLANTED_TEXT = "DECISION: adopt the blue protocol";
+const LONG_TEXT = `LONGSPAN ${"x".repeat(600)}`;
+
+const ownerPolicy: HistoryCorpusPolicy = {
+  includeVisibilities: ["public", "operator", "private"],
+  includeRedactionClasses: ["public_ref", "redacted_summary", "operator_summary", "private_ref"],
+};
+
+const turnIdOf = (turn: number): string => `t1.turn-${String(turn).padStart(3, "0")}`;
+
+const scriptTurn = (turn: number, words: ReadonlyArray<string>): Array<HarnessStreamEvent> => {
+  const turnId = turnIdOf(turn);
+  const events: Array<HarnessStreamEvent> = [];
+  let seq = 0;
+  events.push(buildTurnStarted({ turnId, threadId: THREAD_ID, sequence: seq++, source: SOURCE }));
+  for (const word of words) {
+    events.push(
+      buildTextDelta({
+        turnId,
+        threadId: THREAD_ID,
+        sequence: seq++,
+        source: SOURCE,
+        messageId: `msg.${turnId}`,
+        text: word,
+      }),
+    );
+  }
+  events.push(
+    buildTurnFinished({
+      turnId,
+      threadId: THREAD_ID,
+      sequence: seq++,
+      source: SOURCE,
+      finishReason: "stop",
+    }),
+  );
+  return events;
+};
+
+interface RecallFixture {
+  readonly entries: ReadonlyArray<HistoryCorpusEntry>;
+  readonly coverageNote: string;
+}
+
+/**
+ * A deep, deterministic corpus: many turns on one thread, with a decision
+ * planted hundreds of sequences in, and a 600-plus-character text that
+ * overflows the default per-span character cap.
+ */
+const buildRecallFixture = async (): Promise<RecallFixture> => {
+  const store = makeInMemoryEventLogStore();
+  const turnIds: Array<string> = [];
+  const events: Array<HarnessStreamEvent> = [];
+  for (let turn = 0; turn < TURN_COUNT; turn++) {
+    turnIds.push(turnIdOf(turn));
+    if (turn === PLANTED_TURN) {
+      events.push(...scriptTurn(turn, ["alpha", PLANTED_TEXT, "beta"]));
+    } else if (turn === LONG_TURN) {
+      events.push(...scriptTurn(turn, [LONG_TEXT]));
+    } else {
+      events.push(...scriptTurn(turn, ["alpha", "beta"]));
+    }
+  }
+  await Effect.runPromise(Effect.forEach(events, (event) => store.append(event)));
+  const corpus = await Effect.runPromise(
+    buildHistoryCorpus({
+      scope: { _tag: "Thread", threadId: THREAD_ID },
+      eventLog: store,
+      turnIds,
+      policy: ownerPolicy,
+      builtAt: BUILT_AT,
+    }),
+  );
+  return { entries: corpus.entries, coverageNote: corpus.manifest.coverage.note };
+};
+
+let cachedFixture: Promise<RecallFixture> | undefined;
+const recallFixture = (): Promise<RecallFixture> => (cachedFixture ??= buildRecallFixture());
+
+/** The recall query surface under test — matches the Tier D input signature. */
+export interface RecallSource {
+  readonly recall: (params: {
+    readonly entries: ReadonlyArray<HistoryCorpusEntry>;
+    readonly coverageNote: string;
+    readonly question: HistoryRecallQuestion;
+    readonly caps?: HistoryRecallCaps | undefined;
+  }) => Effect.Effect<HistoryRecallResponse, HistoryRecallError>;
+}
+
+/** Configuration for {@link runRecallLaws}. */
+export interface RecallLawsConfig extends RecallSource {
+  /** A short label naming the implementation under test, used in test titles. */
+  readonly label: string;
+}
+
+/**
+ * The recall honesty laws, parameterized over any recall source.
+ *
+ * Promoted, published form of `history-corpus/src/recall.test.ts`. Recall is a
+ * deterministic query over a durable corpus; the laws hold the source to the
+ * honesty contract: caps TRUNCATE (they never fail), and the response must
+ * state exactly what it scanned, which caps it hit, and the corpus coverage
+ * bound. A source that answers correctly but lies about coverage — or that
+ * fabricates a model call behind a "deterministic" answer — is not conformant.
+ *
+ * - **Correctness anchor.** A decision planted deep is found with its exact
+ *   cursor span and zero model calls.
+ * - **Caps truncate and report.** `maxEntriesScanned`, `maxSpans`, and
+ *   `maxCharsPerSpan` each truncate; `truncated` is true exactly when `capsHit`
+ *   is non-empty, and `capsHit` names the cap.
+ * - **`cost.modelCalls` is always 0** for every deterministic question kind.
+ * - **Coverage note carry-through.** The corpus coverage bound rides on every
+ *   response's `honesty.coverageNote`.
+ * - **Invalid input fails typed.** An uncompilable grep pattern is a typed
+ *   `invalid_pattern` error, never a crash.
+ */
+export const runRecallLaws = (config: RecallLawsConfig): void => {
+  const { label, recall } = config;
+
+  const ask = async (question: HistoryRecallQuestion, caps?: HistoryRecallCaps) => {
+    const { entries, coverageNote } = await recallFixture();
+    return Effect.runPromise(recall({ entries, coverageNote, question, caps }));
+  };
+
+  describe(`[${label}] recall — correctness and cost`, () => {
+    test("finds a decision planted deep with its exact cursor span and zero model calls", async () => {
+      const { entries } = await recallFixture();
+      const response = await ask({ _tag: "Grep", pattern: "DECISION: adopt" });
+      expect(response.answers.length).toBe(1);
+      expect(response.answers[0]).toMatchObject({
+        turnId: turnIdOf(PLANTED_TURN),
+        sequenceStart: 2,
+        sequenceEnd: 2,
+        excerpt: PLANTED_TEXT,
+      });
+      expect(response.honesty.tier).toBe("deterministic");
+      expect(response.honesty.entriesScanned).toBe(entries.length);
+      expect(response.honesty.entriesTotal).toBe(entries.length);
+      expect(response.honesty.truncated).toBe(false);
+      expect(response.honesty.capsHit).toEqual([]);
+      expect(response.cost.modelCalls).toBe(0);
+    });
+
+    test("every question kind answers with zero model calls", async () => {
+      const questions: ReadonlyArray<HistoryRecallQuestion> = [
+        { _tag: "Grep", pattern: "alpha" },
+        { _tag: "CursorSlice", fromSequence: 0, toSequence: 1 },
+        { _tag: "KeyTurns", limit: 2 },
+        { _tag: "TurnSummary", turnId: turnIdOf(0) },
+      ];
+      for (const question of questions) {
+        const response = await ask(question, { maxSpans: 3 });
+        expect(response.cost.modelCalls).toBe(0);
+        expect(response.honesty.tier).toBe("deterministic");
+      }
+    });
+  });
+
+  describe(`[${label}] recall — caps truncate and report honestly`, () => {
+    test("maxEntriesScanned stops the scan and honesty names the cap, across cap values", async () => {
+      const { entries } = await recallFixture();
+      const total = entries.length;
+      for (const cap of [1, 5, 137, total, total + 1000]) {
+        const response = await ask(
+          { _tag: "Grep", pattern: "zzz-no-such-text" },
+          {
+            maxEntriesScanned: cap,
+          },
+        );
+        expect(response.honesty.entriesScanned).toBe(Math.min(cap, total));
+        expect(response.honesty.entriesTotal).toBe(total);
+        const expectTruncated = cap < total;
+        expect(response.honesty.truncated).toBe(expectTruncated);
+        expect(response.honesty.capsHit).toEqual(expectTruncated ? ["maxEntriesScanned"] : []);
+      }
+    });
+
+    test("maxSpans caps the answers and honesty names the cap", async () => {
+      // Every turn matches sequence 0, so there are TURN_COUNT candidate spans.
+      const question: HistoryRecallQuestion = {
+        _tag: "CursorSlice",
+        fromSequence: 0,
+        toSequence: 0,
+      };
+      const capped = await ask(question, { maxSpans: 7 });
+      expect(capped.answers.length).toBe(7);
+      expect(capped.honesty.truncated).toBe(true);
+      expect(capped.honesty.capsHit).toEqual(["maxSpans"]);
+
+      const defaulted = await ask(question);
+      expect(defaulted.answers.length).toBe(historyRecallDefaultCaps.maxSpans);
+      expect(defaulted.honesty.capsHit).toEqual(["maxSpans"]);
+    });
+
+    test("maxCharsPerSpan truncates the excerpt and honesty names the cap", async () => {
+      const defaulted = await ask({ _tag: "Grep", pattern: "LONGSPAN" });
+      expect(defaulted.answers.length).toBe(1);
+      expect(defaulted.answers[0]!.excerpt.length).toBe(historyRecallDefaultCaps.maxCharsPerSpan);
+      expect(defaulted.honesty.truncated).toBe(true);
+      expect(defaulted.honesty.capsHit).toEqual(["maxCharsPerSpan"]);
+
+      const tight = await ask({ _tag: "Grep", pattern: "LONGSPAN" }, { maxCharsPerSpan: 100 });
+      expect(tight.answers[0]!.excerpt.length).toBe(100);
+      expect(tight.honesty.capsHit).toEqual(["maxCharsPerSpan"]);
+    });
+
+    test("truncated is true exactly when capsHit is non-empty", async () => {
+      const complete = await ask({ _tag: "Grep", pattern: "DECISION: adopt" });
+      expect(complete.honesty.capsHit).toEqual([]);
+      expect(complete.honesty.truncated).toBe(false);
+
+      const truncated = await ask(
+        { _tag: "CursorSlice", fromSequence: 0, toSequence: 0 },
+        {
+          maxSpans: 2,
+        },
+      );
+      expect(truncated.honesty.capsHit.length).toBeGreaterThan(0);
+      expect(truncated.honesty.truncated).toBe(true);
+    });
+  });
+
+  describe(`[${label}] recall — coverage and typed failure`, () => {
+    test("honesty carries the corpus coverage note through every response", async () => {
+      const { coverageNote } = await recallFixture();
+      const response = await ask({ _tag: "Grep", pattern: "alpha" }, { maxSpans: 1 });
+      expect(response.honesty.coverageNote).toBe(coverageNote);
+    });
+
+    test("an invalid grep pattern is a typed invalid_pattern error, never a crash", async () => {
+      const { entries, coverageNote } = await recallFixture();
+      const error = await Effect.runPromise(
+        recall({
+          entries,
+          coverageNote,
+          question: { _tag: "Grep", pattern: "(unclosed" },
+        }).pipe(Effect.flip),
+      );
+      expect(error).toBeInstanceOf(HistoryRecallError);
+      expect(error.reason).toBe("invalid_pattern");
+    });
+  });
+};