@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/src/tests/memory-rater-implicit-citation.test.ts

@@ -0,0 +1,304 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, createSessionLogs, getDb, initDb } from "../be/db";
+import { SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
+import { ImplicitCitationRater } from "../be/memory/raters/implicit-citation";
+import {
+  getRaterWeightMultiplier,
+  getRegisteredRaters,
+  SERVER_RATERS,
+} from "../be/memory/raters/registry";
+import { getRetrievalsForTask, recordRetrievals } from "../be/memory/raters/retrieval";
+import { applyRating } from "../be/memory/raters/store";
+import type { RatingEvent } from "../be/memory/raters/types";
+
+const TEST_DB_PATH = "./test-memory-rater-implicit-citation.sqlite";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure-function unit tests — no DB required for these. Plan §7.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("ImplicitCitationRater (pure)", () => {
+  const rater = new ImplicitCitationRater();
+
+  test("name is 'implicit-citation'", () => {
+    expect(rater.name).toBe("implicit-citation");
+  });
+
+  test("hit + miss: emits +1 weight=0.5 for cited memory, -1 weight=0.25 for uncited", async () => {
+    const events = await rater.rate({
+      agentId: "agent-x",
+      taskId: "task-y",
+      retrievedMemoryIds: ["mem-A", "mem-B"],
+      evidence: "I used mem-A here when solving the task.",
+    });
+    expect(events).toHaveLength(2);
+    const a = events.find((e) => e.memoryId === "mem-A")!;
+    const b = events.find((e) => e.memoryId === "mem-B")!;
+    expect(a).toEqual({ memoryId: "mem-A", signal: 1, weight: 0.5, source: "" });
+    expect(b).toEqual({ memoryId: "mem-B", signal: -1, weight: 0.25, source: "" });
+  });
+
+  test("rater leaves source empty — framework stamps it (anti-spoof)", async () => {
+    const events = await rater.rate({
+      agentId: "agent-x",
+      retrievedMemoryIds: ["mem-X"],
+      evidence: "mem-X cited",
+    });
+    expect(events[0]!.source).toBe("");
+  });
+
+  test("empty evidence → all misses (negative)", async () => {
+    const events = await rater.rate({
+      agentId: "agent-x",
+      retrievedMemoryIds: ["mem-A", "mem-B", "mem-C"],
+      evidence: "",
+    });
+    expect(events).toHaveLength(3);
+    for (const e of events) {
+      expect(e.signal).toBe(-1);
+      expect(e.weight).toBe(0.25);
+    }
+  });
+
+  test("null evidence → all misses (negative)", async () => {
+    const events = await rater.rate({
+      agentId: "agent-x",
+      retrievedMemoryIds: ["mem-A"],
+      evidence: null,
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0]!.signal).toBe(-1);
+  });
+
+  test("empty retrievedMemoryIds → no events", async () => {
+    const events = await rater.rate({
+      agentId: "agent-x",
+      retrievedMemoryIds: [],
+      evidence: "anything",
+    });
+    expect(events).toEqual([]);
+  });
+
+  test("substring-prefix collision: citing 'mem-AB' counts as a hit for 'mem-A'", async () => {
+    // Documented behaviour: literal substring match. UUID call sites never
+    // collide; this test locks the rule for synthetic IDs so a future change
+    // (e.g. word-boundary regex) is intentional.
+    const events = await rater.rate({
+      agentId: "agent-x",
+      retrievedMemoryIds: ["mem-A", "mem-AB"],
+      evidence: "mem-AB only",
+    });
+    const a = events.find((e) => e.memoryId === "mem-A")!;
+    const ab = events.find((e) => e.memoryId === "mem-AB")!;
+    expect(a.signal).toBe(1);
+    expect(ab.signal).toBe(1);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Integration tests — DB-backed end-to-end through the same path as
+// store-progress.ts §5 fires.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("retrieval → ImplicitCitationRater → posterior shift", () => {
+  const agentId = "aaaa0000-0000-4000-8000-000000000ic1";
+  const taskId = "00000000-0000-4000-8000-0000000ic001";
+  const taskIdMiss = "00000000-0000-4000-8000-0000000ic002";
+  let store: SqliteMemoryStore;
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    createAgent({ id: agentId, name: "Citation Test Agent", isLead: false, status: "idle" });
+    const insertTask = getDb().prepare(
+      `INSERT INTO agent_tasks (id, agentId, task, status, source, createdAt, lastUpdatedAt)
+       VALUES (?, ?, ?, 'in_progress', 'mcp', ?, ?)`,
+    );
+    const nowIso = new Date().toISOString();
+    insertTask.run(taskId, agentId, "test task with citation", nowIso, nowIso);
+    insertTask.run(taskIdMiss, agentId, "test task without citation", nowIso, nowIso);
+    store = new SqliteMemoryStore();
+  });
+
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(TEST_DB_PATH + suffix);
+      } catch {}
+    }
+  });
+
+  beforeEach(() => {
+    getDb().run("DELETE FROM memory_rating");
+    getDb().run("DELETE FROM memory_retrieval");
+    getDb().run("DELETE FROM session_logs");
+    getDb().run("UPDATE agent_memory SET alpha = 1.0, beta = 1.0");
+  });
+
+  function makeMemory(name: string): { id: string } {
+    const memory = store.store({
+      agentId,
+      scope: "agent",
+      name,
+      content: `${name} content`,
+      source: "manual",
+    });
+    return { id: memory.id };
+  }
+
+  function readPosterior(id: string): { alpha: number; beta: number } {
+    const row = getDb()
+      .prepare<{ alpha: number; beta: number }, [string]>(
+        "SELECT alpha, beta FROM agent_memory WHERE id = ?",
+      )
+      .get(id);
+    if (!row) throw new Error(`memory ${id} not found`);
+    return { alpha: row.alpha, beta: row.beta };
+  }
+
+  function getRatings(taskId: string) {
+    return getDb()
+      .prepare<
+        {
+          memoryId: string;
+          source: string;
+          signal: number;
+          weight: number;
+        },
+        [string]
+      >("SELECT memoryId, source, signal, weight FROM memory_rating WHERE taskId = ?")
+      .all(taskId);
+  }
+
+  test("recordRetrievals writes one row per result for the task", () => {
+    const m1 = makeMemory("retrieval-target-1");
+    const m2 = makeMemory("retrieval-target-2");
+    recordRetrievals(taskId, agentId, [
+      { memoryId: m1.id, similarity: 0.9 },
+      { memoryId: m2.id, similarity: 0.7 },
+    ]);
+    const rows = getRetrievalsForTask(taskId);
+    expect(rows).toHaveLength(2);
+    expect(rows.map((r) => r.memoryId).sort()).toEqual([m1.id, m2.id].sort());
+  });
+
+  test("recordRetrievals is a no-op when taskId is undefined", () => {
+    const m = makeMemory("no-task");
+    recordRetrievals(undefined, agentId, [{ memoryId: m.id, similarity: 0.9 }]);
+    const rows = getDb().prepare("SELECT COUNT(*) as n FROM memory_retrieval").get() as {
+      n: number;
+    };
+    expect(rows.n).toBe(0);
+  });
+
+  test("recordRetrievals is a no-op when results is empty", () => {
+    recordRetrievals(taskId, agentId, []);
+    const rows = getDb().prepare("SELECT COUNT(*) as n FROM memory_retrieval").get() as {
+      n: number;
+    };
+    expect(rows.n).toBe(0);
+  });
+
+  test("end-to-end: cited memory shifts alpha by 0.5; uncited memory shifts beta by 0.25", async () => {
+    const cited = makeMemory("cited");
+    const uncited = makeMemory("uncited");
+
+    // 1. Search-time: log the retrievals.
+    recordRetrievals(taskId, agentId, [
+      { memoryId: cited.id, similarity: 0.9 },
+      { memoryId: uncited.id, similarity: 0.85 },
+    ]);
+
+    // 2. During the task: session_logs accumulate text mentioning ONE of them.
+    createSessionLogs({
+      taskId,
+      sessionId: "session-1",
+      iteration: 1,
+      cli: "claude",
+      lines: [`Looking up memory ${cited.id} for context.`, "Doing the work."],
+    });
+
+    // 3. Task completion: simulate the store-progress server-rater fire.
+    const retrievals = getRetrievalsForTask(taskId);
+    const retrievedMemoryIds = retrievals.map((r) => r.memoryId);
+    const evidence = getDb()
+      .prepare<{ content: string }, [string]>(
+        "SELECT content FROM session_logs WHERE taskId = ? ORDER BY iteration, lineNumber",
+      )
+      .all(taskId)
+      .map((row) => row.content)
+      .join("\n");
+
+    const rater = new ImplicitCitationRater();
+    const events = await rater.rate({
+      taskId,
+      agentId,
+      retrievedMemoryIds,
+      evidence,
+    });
+    const stamped: RatingEvent[] = events.map((e) => ({ ...e, source: rater.name }));
+    const result = applyRating(stamped, { taskId });
+    expect(result.applied).toBe(2);
+
+    // 4. Posteriors moved as documented.
+    expect(readPosterior(cited.id)).toEqual({ alpha: 1.5, beta: 1.0 });
+    expect(readPosterior(uncited.id)).toEqual({ alpha: 1.0, beta: 1.25 });
+
+    // 5. Audit rows written with `source = 'implicit-citation'`.
+    const ratings = getRatings(taskId);
+    expect(ratings).toHaveLength(2);
+    for (const r of ratings) {
+      expect(r.source).toBe("implicit-citation");
+    }
+    const citedRow = ratings.find((r) => r.memoryId === cited.id)!;
+    const uncitedRow = ratings.find((r) => r.memoryId === uncited.id)!;
+    expect(citedRow).toMatchObject({ signal: 1, weight: 0.5 });
+    expect(uncitedRow).toMatchObject({ signal: -1, weight: 0.25 });
+  });
+
+  test("negative path: no citation in session_logs → only beta moves", async () => {
+    const m = makeMemory("never-cited");
+    recordRetrievals(taskIdMiss, agentId, [{ memoryId: m.id, similarity: 0.9 }]);
+    createSessionLogs({
+      taskId: taskIdMiss,
+      sessionId: "session-2",
+      iteration: 1,
+      cli: "claude",
+      lines: ["completely unrelated content"],
+    });
+
+    const rater = new ImplicitCitationRater();
+    const events = await rater.rate({
+      taskId: taskIdMiss,
+      agentId,
+      retrievedMemoryIds: [m.id],
+      evidence: "completely unrelated content",
+    });
+    const stamped: RatingEvent[] = events.map((e) => ({ ...e, source: rater.name }));
+    applyRating(stamped, { taskId: taskIdMiss });
+
+    expect(readPosterior(m.id)).toEqual({ alpha: 1.0, beta: 1.25 });
+  });
+
+  test("registry: implicit-citation is in SERVER_RATERS and instantiable via MEMORY_RATERS", () => {
+    expect(SERVER_RATERS.has("implicit-citation")).toBe(true);
+
+    const previous = process.env.MEMORY_RATERS;
+    process.env.MEMORY_RATERS = "implicit-citation";
+    try {
+      const raters = getRegisteredRaters();
+      expect(raters.map((r) => r.name)).toContain("implicit-citation");
+      // Multiplier defaults to 1.0 when MEMORY_RATER_WEIGHTS is unset.
+      expect(getRaterWeightMultiplier("implicit-citation")).toBe(1.0);
+    } finally {
+      if (previous === undefined) delete process.env.MEMORY_RATERS;
+      else process.env.MEMORY_RATERS = previous;
+    }
+  });
+});

package/src/tests/memory-rater-llm-summarizer.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Unit tests for the `runMemoryRater` helper extracted from `src/hooks/hook.ts`
+ * in the PR #450 review-feedback amendment. The helper owns the OpenRouter
+ * direct-HTTP path: request shape (model, `response_format: json_object`,
+ * Authorization header), tolerant JSON parse on the assistant content, schema
+ * validation, and the env-driven model override.
+ *
+ * All tests stub `fetch` — no network calls.
+ */
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_MEMORY_RATER_MODEL,
+  getMemoryRaterModel,
+  MEMORY_RATER_JSON_SCHEMA,
+  MEMORY_RATER_SCHEMA_NAME,
+  runMemoryRater,
+  tryParseLooseJson,
+} from "../be/memory/raters/llm-summarizer";
+
+function makeOpenRouterResponse(content: string, init: ResponseInit = { status: 200 }): Response {
+  return new Response(
+    JSON.stringify({
+      choices: [{ message: { role: "assistant", content } }],
+    }),
+    {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+      ...init,
+    },
+  );
+}
+
+describe("getMemoryRaterModel", () => {
+  test("returns the default when MEMORY_RATER_MODEL is unset", () => {
+    expect(getMemoryRaterModel({})).toBe(DEFAULT_MEMORY_RATER_MODEL);
+    expect(DEFAULT_MEMORY_RATER_MODEL).toBe("google/gemini-3-flash-preview");
+  });
+
+  test("returns the env override when set", () => {
+    expect(getMemoryRaterModel({ MEMORY_RATER_MODEL: "anthropic/claude-haiku-4.5" })).toBe(
+      "anthropic/claude-haiku-4.5",
+    );
+  });
+
+  test("trims whitespace in the env override", () => {
+    expect(getMemoryRaterModel({ MEMORY_RATER_MODEL: "   openai/gpt-5-mini   " })).toBe(
+      "openai/gpt-5-mini",
+    );
+  });
+
+  test("falls back to the default when env var is empty / whitespace-only", () => {
+    expect(getMemoryRaterModel({ MEMORY_RATER_MODEL: "" })).toBe(DEFAULT_MEMORY_RATER_MODEL);
+    expect(getMemoryRaterModel({ MEMORY_RATER_MODEL: "   " })).toBe(DEFAULT_MEMORY_RATER_MODEL);
+  });
+
+  test("respects process.env when no env arg is provided", () => {
+    const prev = process.env.MEMORY_RATER_MODEL;
+    process.env.MEMORY_RATER_MODEL = "fake/model-from-process-env";
+    try {
+      expect(getMemoryRaterModel()).toBe("fake/model-from-process-env");
+    } finally {
+      if (prev === undefined) delete process.env.MEMORY_RATER_MODEL;
+      else process.env.MEMORY_RATER_MODEL = prev;
+    }
+  });
+});
+
+describe("tryParseLooseJson", () => {
+  test("strict JSON parses unchanged", () => {
+    expect(tryParseLooseJson('{"a":1}')).toEqual({ a: 1 });
+  });
+
+  test("strips ```json fences", () => {
+    expect(tryParseLooseJson('```json\n{"a":1}\n```')).toEqual({ a: 1 });
+  });
+
+  test("strips plain ``` fences", () => {
+    expect(tryParseLooseJson('```\n{"a":1}\n```')).toEqual({ a: 1 });
+  });
+
+  test("recovers from prose preamble via brace-slice", () => {
+    expect(tryParseLooseJson('Here you go: {"a":1}')).toEqual({ a: 1 });
+  });
+
+  test("recovers from preamble + trailing chatter via brace-slice", () => {
+    expect(tryParseLooseJson('preamble\n{"a":1}\nthanks')).toEqual({ a: 1 });
+  });
+
+  test("returns null on genuine garbage", () => {
+    expect(tryParseLooseJson("not json at all")).toBeNull();
+  });
+
+  test("returns null on broken JSON inside fences", () => {
+    expect(tryParseLooseJson("```json\n{broken,}\n```")).toBeNull();
+  });
+
+  test("never throws — even on adversarial input", () => {
+    expect(() => tryParseLooseJson("{[}}}}")).not.toThrow();
+    expect(() => tryParseLooseJson("```")).not.toThrow();
+    expect(() => tryParseLooseJson("")).not.toThrow();
+  });
+});
+
+describe("runMemoryRater — request shape", () => {
+  test("POSTs to OpenRouter chat-completions with the right model, strict json_schema response_format, and Authorization header", async () => {
+    let capturedUrl: string | URL | Request | undefined;
+    let capturedInit: RequestInit | undefined;
+    const fakeFetch: typeof fetch = async (url, init) => {
+      capturedUrl = url;
+      capturedInit = init;
+      return makeOpenRouterResponse(JSON.stringify({ summary: "ok", ratings: [] }));
+    };
+
+    const result = await runMemoryRater({
+      prompt: "test prompt",
+      apiKey: "test-api-key-123",
+      fetchImpl: fakeFetch,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(String(capturedUrl)).toBe("https://openrouter.ai/api/v1/chat/completions");
+    expect(capturedInit?.method).toBe("POST");
+
+    const headers = capturedInit?.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(headers.Authorization).toBe("Bearer test-api-key-123");
+
+    const body = JSON.parse(String(capturedInit?.body));
+    expect(body.model).toBe(DEFAULT_MEMORY_RATER_MODEL);
+    expect(body.messages).toEqual([{ role: "user", content: "test prompt" }]);
+
+    // OpenRouter strict json_schema mode — assert the wrapper shape.
+    expect(body.response_format.type).toBe("json_schema");
+    expect(body.response_format.json_schema.name).toBe(MEMORY_RATER_SCHEMA_NAME);
+    expect(body.response_format.json_schema.strict).toBe(true);
+    // Schema is the canonical one derived from SummaryWithRatingsSchema.
+    expect(body.response_format.json_schema.schema).toEqual(MEMORY_RATER_JSON_SCHEMA);
+  });
+
+  test("MEMORY_RATER_JSON_SCHEMA reflects SummaryWithRatingsSchema (key shape only)", () => {
+    // Don't assert exact JSON Schema bytes — Zod's emitter can change with
+    // version bumps. Lock down the contract that matters for the OpenRouter
+    // call: top-level keys, required fields, additionalProperties: false,
+    // and the per-rating shape.
+    expect(MEMORY_RATER_JSON_SCHEMA.type).toBe("object");
+    expect(MEMORY_RATER_JSON_SCHEMA.additionalProperties).toBe(false);
+    expect(Array.isArray(MEMORY_RATER_JSON_SCHEMA.required)).toBe(true);
+    expect(MEMORY_RATER_JSON_SCHEMA.required as string[]).toEqual(
+      expect.arrayContaining(["summary", "ratings"]),
+    );
+    const props = MEMORY_RATER_JSON_SCHEMA.properties as Record<string, Record<string, unknown>>;
+    expect(props.summary.type).toBe("string");
+    expect(props.ratings.type).toBe("array");
+    const items = props.ratings.items as Record<string, unknown>;
+    expect(items.type).toBe("object");
+    expect(items.additionalProperties).toBe(false);
+    const itemProps = items.properties as Record<string, Record<string, unknown>>;
+    expect(itemProps.id.type).toBe("string");
+    expect(itemProps.score.type).toBe("number");
+    expect(itemProps.score.minimum).toBe(0);
+    expect(itemProps.score.maximum).toBe(1);
+    expect(itemProps.reasoning.type).toBe("string");
+    // referencesSource is optional → present in properties but not required.
+    expect(itemProps.referencesSource.type).toBe("string");
+    expect(items.required as string[]).toEqual(
+      expect.arrayContaining(["id", "score", "reasoning"]),
+    );
+    expect((items.required as string[]).includes("referencesSource")).toBe(false);
+  });
+
+  test("schema does NOT carry a $schema metadata key (OpenRouter rejects extras at the root)", () => {
+    expect("$schema" in MEMORY_RATER_JSON_SCHEMA).toBe(false);
+  });
+
+  test("explicit `model` opt overrides the env default", async () => {
+    let capturedBody: { model?: string } = {};
+    const fakeFetch: typeof fetch = async (_url, init) => {
+      capturedBody = JSON.parse(String(init?.body));
+      return makeOpenRouterResponse(JSON.stringify({ summary: "x", ratings: [] }));
+    };
+
+    const result = await runMemoryRater({
+      prompt: "p",
+      apiKey: "k",
+      model: "anthropic/claude-haiku-4.5",
+      fetchImpl: fakeFetch,
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.model).toBe("anthropic/claude-haiku-4.5");
+    expect(capturedBody.model).toBe("anthropic/claude-haiku-4.5");
+  });
+
+  test("MEMORY_RATER_MODEL env var changes the model when no opt is passed", async () => {
+    const prev = process.env.MEMORY_RATER_MODEL;
+    process.env.MEMORY_RATER_MODEL = "openai/gpt-5-mini";
+    try {
+      let capturedBody: { model?: string } = {};
+      const fakeFetch: typeof fetch = async (_url, init) => {
+        capturedBody = JSON.parse(String(init?.body));
+        return makeOpenRouterResponse(JSON.stringify({ summary: "x", ratings: [] }));
+      };
+      const result = await runMemoryRater({
+        prompt: "p",
+        apiKey: "k",
+        fetchImpl: fakeFetch,
+      });
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.model).toBe("openai/gpt-5-mini");
+      expect(capturedBody.model).toBe("openai/gpt-5-mini");
+    } finally {
+      if (prev === undefined) delete process.env.MEMORY_RATER_MODEL;
+      else process.env.MEMORY_RATER_MODEL = prev;
+    }
+  });
+});
+
+describe("runMemoryRater — response handling", () => {
+  test("happy path — strict JSON content parses + validates", async () => {
+    const fakeFetch: typeof fetch = async () =>
+      makeOpenRouterResponse(
+        JSON.stringify({
+          summary: "found two patterns",
+          ratings: [{ id: "mem-A", score: 0.9, reasoning: "directly answered" }],
+        }),
+      );
+
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.summary).toBe("found two patterns");
+    expect(result.data.ratings).toHaveLength(1);
+    expect(result.data.ratings[0]!.score).toBeCloseTo(0.9, 6);
+  });
+
+  test("tolerant parser recovers from ```json fences (PR #447 regression)", async () => {
+    const inner = JSON.stringify({
+      summary: "fenced summary",
+      ratings: [{ id: "m", score: 0.7, reasoning: "useful" }],
+    });
+    const fakeFetch: typeof fetch = async () =>
+      makeOpenRouterResponse(`\`\`\`json\n${inner}\n\`\`\``);
+
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.summary).toBe("fenced summary");
+    expect(result.data.ratings[0]!.score).toBeCloseTo(0.7, 6);
+  });
+
+  test("tolerant parser recovers from prose preamble (PR #447 regression)", async () => {
+    const inner = JSON.stringify({
+      summary: "preambled summary",
+      ratings: [{ id: "m", score: 0, reasoning: "irrelevant" }],
+    });
+    const fakeFetch: typeof fetch = async () =>
+      makeOpenRouterResponse(`Here is the JSON:\n\n${inner}`);
+
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.summary).toBe("preambled summary");
+  });
+
+  test("schema-invalid content returns ok:false / reason:'schema'", async () => {
+    // score = 5 violates the [0, 1] range in SummaryWithRatingsSchema.
+    const fakeFetch: typeof fetch = async () =>
+      makeOpenRouterResponse(
+        JSON.stringify({
+          summary: "x",
+          ratings: [{ id: "m", score: 5, reasoning: "bogus" }],
+        }),
+      );
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("schema");
+  });
+
+  test("genuinely garbage content returns ok:false / reason:'parse'", async () => {
+    const fakeFetch: typeof fetch = async () =>
+      makeOpenRouterResponse("totally not JSON at all, just words");
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("parse");
+  });
+
+  test("HTTP 5xx returns ok:false / reason:'http_error' with status", async () => {
+    const fakeFetch: typeof fetch = async () => new Response("upstream blew up", { status: 502 });
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("http_error");
+      expect(result.status).toBe(502);
+    }
+  });
+
+  test("transport failure returns ok:false / reason:'transport'", async () => {
+    const fakeFetch: typeof fetch = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("transport");
+  });
+
+  test("missing choices[0].message.content returns ok:false / reason:'empty_content'", async () => {
+    const fakeFetch: typeof fetch = async () =>
+      new Response(JSON.stringify({ choices: [] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    const result = await runMemoryRater({ prompt: "p", apiKey: "k", fetchImpl: fakeFetch });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("empty_content");
+  });
+});