fix(journal): read-path non-mutation + CLI hardening + finite createServer defaults (#115)

## Summary
Follow-up polish to v1.14.1's journal OOM fix (#114). Three independent
improvements surfaced by CR:

1. **Read-path non-mutation bug fix.**
`Journal.getFixtureMatchCount(fixture, testId)` was a read method that
silently inserted an empty Map + triggered FIFO eviction for unknown
testIds. Reads could evict live testIds. Now split into a read-only
public `getFixtureMatchCountsForTest` (returns transient empty Map on
miss) and private `getOrCreateFixtureMatchCountsForTest` (insert+evict
write path used only by `incrementFixtureMatchCount`).

2. **CLI validation hardening.** `--journal-max -5` was silently treated
as unbounded; now rejected with a clear error. Same for the new
`--fixture-counts-max` flag.

3. **`createServer()` default flip.** `journalMaxEntries` (1000) and
`fixtureCountsMaxTestIds` (500) now default to finite caps for
programmatic callers — long-running embedders no longer inherit the
original leak. Tests using `new Journal()` directly remain unbounded by
default (back-compat). Opt in to unbounded via `journalMaxEntries: 0`.

## Test plan
- [x] 3 new tests: read-non-mutation, CLI negative rejection,
`fixtureCountsMaxTestIds` cap FIFO eviction
- [x] Full suite: 2461 tests pass
- [x] Lint + build + prettier clean
- [x] CR R2 on combined diff: 0 blocking bugs

## Breaking change note
The `createServer()` default flip is a behavioral change for
programmatic embedders that relied on unbounded journal retention. Opt
back in with `createServer({ journalMaxEntries: 0 })` if needed.
Documented in `types.ts` JSDoc.

Author: jpr5

CHANGELOG.md

@@ -1,5 +1,20 @@
 # @copilotkit/aimock
 
+## 1.14.2
+
+### Fixed
+
+- `Journal.getFixtureMatchCount()` is now read-only: calling it with an unknown testId no longer inserts an empty map or triggers FIFO eviction of a live testId. Reads never mutate cache state.
+- CLI rejects negative values for `--journal-max` and `--fixture-counts-max` with a clear error (previously silently treated as unbounded).
+
+### Changed
+
+- `createServer()` programmatic default: `journalMaxEntries` and `fixtureCountsMaxTestIds` now default to finite caps (1000 / 500) instead of unbounded. Long-running embedders that relied on unbounded retention must now opt in explicitly by passing `0`. Back-compat with test harnesses using `new Journal()` directly is preserved (they still default to unbounded).
+
+### Added
+
+- New `--fixture-counts-max <n>` CLI flag (default 500) to cap the fixture-match-counts map by testId.
+
 ## 1.14.1
 
 ### Patch Changes

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "description": "Mock infrastructure for AI application testing — LLM APIs, image generation, text-to-speech, transcription, video generation, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. One package, one port, zero dependencies.",
   "license": "MIT",
   "keywords": [

package.json

@@ -125,6 +125,32 @@ describe.skipIf(!CLI_AVAILABLE)("CLI: argument validation", () => {
     expect(stderr).toContain("Invalid chunk-size");
     expect(code).toBe(1);
   });
+
+  it("rejects --journal-max=-5 (negative)", async () => {
+    const { stderr, code } = await runCli(["--journal-max=-5"]);
+    expect(stderr).toContain("Invalid journal-max");
+    expect(stderr).toContain("non-negative");
+    expect(code).toBe(1);
+  });
+
+  it("rejects --journal-max=-1 (negative)", async () => {
+    const { stderr, code } = await runCli(["--journal-max=-1"]);
+    expect(stderr).toContain("Invalid journal-max");
+    expect(code).toBe(1);
+  });
+
+  it("rejects --journal-max 1.5 (non-integer)", async () => {
+    const { stderr, code } = await runCli(["--journal-max", "1.5"]);
+    expect(stderr).toContain("Invalid journal-max");
+    expect(code).toBe(1);
+  });
+
+  it("rejects --fixture-counts-max=-1 (negative)", async () => {
+    const { stderr, code } = await runCli(["--fixture-counts-max=-1"]);
+    expect(stderr).toContain("Invalid fixture-counts-max");
+    expect(stderr).toContain("non-negative");
+    expect(code).toBe(1);
+  });
 });
 
 describe.skipIf(!CLI_AVAILABLE)("CLI: fixture loading", () => {

src/__tests__/cli.test.ts

@@ -373,4 +373,88 @@ describe("Journal", () => {
       expect(journal.getAll()[0].path).toBe("/99500");
     });
   });
+
+  describe("fixtureCountsMaxTestIds (FIFO eviction on testId map)", () => {
+    // Minimal fixture shared by these tests — only the reference matters.
+    const fixture: Fixture = { match: { userMessage: "x" }, response: { content: "X" } };
+
+    it("does not cap when fixtureCountsMaxTestIds is unset (backwards compat)", () => {
+      const journal = new Journal();
+      for (let i = 0; i < 2000; i++) {
+        journal.incrementFixtureMatchCount(fixture, undefined, `test-${i}`);
+      }
+      // Every testId retained under unbounded default (historical behavior).
+      expect(journal.getFixtureMatchCount(fixture, "test-0")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "test-1999")).toBe(1);
+    });
+
+    it("treats fixtureCountsMaxTestIds = 0 or negative as uncapped", () => {
+      const j0 = new Journal({ fixtureCountsMaxTestIds: 0 });
+      const jNeg = new Journal({ fixtureCountsMaxTestIds: -1 });
+      for (let i = 0; i < 100; i++) {
+        j0.incrementFixtureMatchCount(fixture, undefined, `test-${i}`);
+        jNeg.incrementFixtureMatchCount(fixture, undefined, `test-${i}`);
+      }
+      expect(j0.getFixtureMatchCount(fixture, "test-0")).toBe(1);
+      expect(jNeg.getFixtureMatchCount(fixture, "test-0")).toBe(1);
+    });
+
+    it("evicts the oldest testId when size exceeds the cap (FIFO)", () => {
+      const journal = new Journal({ fixtureCountsMaxTestIds: 3 });
+
+      journal.incrementFixtureMatchCount(fixture, undefined, "t1");
+      journal.incrementFixtureMatchCount(fixture, undefined, "t2");
+      journal.incrementFixtureMatchCount(fixture, undefined, "t3");
+      // At cap (3). All three retained.
+      expect(journal.getFixtureMatchCount(fixture, "t1")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t2")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t3")).toBe(1);
+
+      // Fourth unique testId triggers eviction of the oldest (t1).
+      journal.incrementFixtureMatchCount(fixture, undefined, "t4");
+
+      // After eviction, t1's prior count is gone. Reads are non-mutating,
+      // so looking up t1 returns 0 without re-inserting.
+      expect(journal.getFixtureMatchCount(fixture, "t1")).toBe(0);
+      expect(journal.getFixtureMatchCount(fixture, "t2")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t3")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t4")).toBe(1);
+    });
+
+    it("getFixtureMatchCount does NOT mutate cache on unknown testId", () => {
+      const journal = new Journal({ fixtureCountsMaxTestIds: 3 });
+
+      journal.incrementFixtureMatchCount(fixture, undefined, "t1");
+      journal.incrementFixtureMatchCount(fixture, undefined, "t2");
+      journal.incrementFixtureMatchCount(fixture, undefined, "t3");
+      // Snapshot the internal size via a retained-testId probe: t1 is still
+      // present (count=1). Reading an unknown testId must not evict it.
+      expect(journal.getFixtureMatchCount(fixture, "t1")).toBe(1);
+
+      // Read many unknown testIds — each would have triggered insert+evict
+      // under the old behavior, evicting t1/t2/t3 one by one.
+      for (let i = 0; i < 50; i++) {
+        expect(journal.getFixtureMatchCount(fixture, `unknown-${i}`)).toBe(0);
+      }
+
+      // All original testIds must still be intact.
+      expect(journal.getFixtureMatchCount(fixture, "t1")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t2")).toBe(1);
+      expect(journal.getFixtureMatchCount(fixture, "t3")).toBe(1);
+    });
+
+    it("holds steady at the cap under sustained load with many unique testIds", () => {
+      // Red-green anchor: 10k unique testIds with cap=100 must stay at 100.
+      const journal = new Journal({ fixtureCountsMaxTestIds: 100 });
+      for (let i = 0; i < 10_000; i++) {
+        journal.incrementFixtureMatchCount(fixture, undefined, `t-${i}`);
+      }
+      // Only the last 100 testIds should have counts > 0 retained.
+      // Access an early one — since it was evicted, getFixtureMatchCount
+      // returns 0 (the read path is non-mutating on miss).
+      expect(journal.getFixtureMatchCount(fixture, "t-0")).toBe(0);
+      // Most recently added testIds retained.
+      expect(journal.getFixtureMatchCount(fixture, "t-9999")).toBe(1);
+    });
+  });
 });

src/__tests__/journal.test.ts

@@ -793,6 +793,51 @@ describe("journal", () => {
   });
 });
 
+describe("createServer journal caps (defaults)", () => {
+  it("applies a finite default journalMaxEntries (1000) when not specified", async () => {
+    // Red-green anchor: programmatic embedders must inherit a finite cap.
+    instance = await createServer(allFixtures);
+    // Seed 1500 synthetic entries via the journal add() API (much faster
+    // than 1500 HTTP requests; the cap lives on the Journal itself).
+    for (let i = 0; i < 1500; i++) {
+      instance.journal.add({
+        method: "POST",
+        path: "/v1/chat/completions",
+        headers: {},
+        body: { model: "gpt-4", messages: [{ role: "user", content: `msg-${i}` }] },
+        response: { status: 200, fixture: null },
+      });
+    }
+    expect(instance.journal.size).toBe(1000);
+  });
+
+  it("honors explicit journalMaxEntries: 0 (opt-in to unbounded)", async () => {
+    instance = await createServer(allFixtures, { journalMaxEntries: 0 });
+    for (let i = 0; i < 1500; i++) {
+      instance.journal.add({
+        method: "POST",
+        path: "/v1/chat/completions",
+        headers: {},
+        body: { model: "gpt-4", messages: [{ role: "user", content: `msg-${i}` }] },
+        response: { status: 200, fixture: null },
+      });
+    }
+    expect(instance.journal.size).toBe(1500);
+  });
+
+  it("applies a finite default fixtureCountsMaxTestIds (500) when not specified", async () => {
+    instance = await createServer(allFixtures);
+    const fixture: Fixture = { match: { userMessage: "x" }, response: { content: "X" } };
+    for (let i = 0; i < 1000; i++) {
+      instance.journal.incrementFixtureMatchCount(fixture, undefined, `test-${i}`);
+    }
+    // Oldest testId (test-0) should be evicted under the default cap.
+    expect(instance.journal.getFixtureMatchCount(fixture, "test-0")).toBe(0);
+    // Most-recently-added testId retained.
+    expect(instance.journal.getFixtureMatchCount(fixture, "test-999")).toBe(1);
+  });
+});
+
 describe("readBody error path", () => {
   it("returns 500 when the request body stream is destroyed mid-read", async () => {
     instance = await createServer(allFixtures);

src/__tests__/server.test.ts

@@ -11,12 +11,15 @@ describe("Journal per-testId match counting", () => {
       response: { content: "Hi" },
     };
 
-    const mapA = journal.getFixtureMatchCountsForTest("test-A");
-    const mapB = journal.getFixtureMatchCountsForTest("test-B");
-
     journal.incrementFixtureMatchCount(f, [f], "test-A");
     journal.incrementFixtureMatchCount(f, [f], "test-A");
 
+    // Reads are non-mutating: fetch the maps AFTER writes so we observe
+    // the live backing maps for known testIds. Unknown testIds return
+    // a transient empty map (does not insert into the cache).
+    const mapA = journal.getFixtureMatchCountsForTest("test-A");
+    const mapB = journal.getFixtureMatchCountsForTest("test-B");
+
     expect(mapA.get(f)).toBe(2);
     expect(mapB.get(f)).toBeUndefined();
   });
@@ -28,8 +31,8 @@ describe("Journal per-testId match counting", () => {
       response: { content: "Hi" },
     };
 
-    const defaultMap = journal.getFixtureMatchCountsForTest(DEFAULT_TEST_ID);
     journal.incrementFixtureMatchCount(f, [f]);
+    const defaultMap = journal.getFixtureMatchCountsForTest(DEFAULT_TEST_ID);
 
     expect(defaultMap.get(f)).toBe(1);
   });

src/__tests__/test-id-isolation.test.ts

@@ -26,6 +26,7 @@ Options:
       --proxy-only          Proxy mode: forward unmatched requests without saving
       --strict              Strict mode: fail on unmatched requests
       --journal-max <n>     Max request entries retained in memory (default: 1000, 0 = unbounded)
+      --fixture-counts-max <n>  Max unique testIds retained in fixture match-count map (default: 500, 0 = unbounded)
       --provider-openai <url>     Upstream URL for OpenAI (used with --record)
       --provider-anthropic <url>  Upstream URL for Anthropic
       --provider-gemini <url>     Upstream URL for Gemini
@@ -72,6 +73,7 @@ const { values } = parseArgs({
     "chaos-malformed": { type: "string" },
     "chaos-disconnect": { type: "string" },
     "journal-max": { type: "string", default: "1000" },
+    "fixture-counts-max": { type: "string", default: "500" },
     help: { type: "boolean", default: false },
   },
   strict: true,
@@ -113,8 +115,19 @@ if (Number.isNaN(chunkSize) || chunkSize < 1) {
 }
 
 const journalMax = Number(values["journal-max"]);
-if (Number.isNaN(journalMax) || !Number.isInteger(journalMax)) {
-  console.error(`Invalid journal-max: ${values["journal-max"]} (must be an integer)`);
+if (Number.isNaN(journalMax) || !Number.isInteger(journalMax) || journalMax < 0) {
+  console.error(
+    `Invalid journal-max: ${values["journal-max"]} (must be a non-negative integer; 0 or omitted = unbounded)`,
+  );
+  process.exit(1);
+}
+
+const fixtureCountsMaxStr = values["fixture-counts-max"];
+const fixtureCountsMax = Number(fixtureCountsMaxStr);
+if (Number.isNaN(fixtureCountsMax) || !Number.isInteger(fixtureCountsMax) || fixtureCountsMax < 0) {
+  console.error(
+    `Invalid fixture-counts-max: ${fixtureCountsMaxStr} (must be a non-negative integer; 0 = unbounded)`,
+  );
   process.exit(1);
 }
 
@@ -265,6 +278,7 @@ async function main() {
       record,
       strict: values.strict,
       journalMaxEntries: journalMax,
+      fixtureCountsMaxTestIds: fixtureCountsMax,
     },
     mounts,
   );