@vellumai/assistant 0.11.3 → 0.11.4-staging.2

package/src/plugins/defaults/memory/__tests__/memory-retrospective-provider-path.test.ts

@@ -96,7 +96,10 @@ mock.module("../find-most-recent-retrospective-for.js", () => ({
 }));
 
 mock.module("../../../../persistence/conversation-crud.js", () => ({
-  getMessagesAfter: (_id: string, _afterId: string | null) => newMessages,
+  // Real rows always carry `finalized` (NOT NULL, default 1); the slice
+  // filter drops unfinalized rows, so mock rows default to finalized.
+  getMessagesAfter: (_id: string, _afterId: string | null) =>
+    newMessages.map((row) => ({ finalized: 1, ...row })),
   getMessages: (id: string) => messageStores[id] ?? [],
   // `defaultResolveTarget` in the REAL wake reads the FORK id's row for the
   // archived check, so both rows carry archivedAt/createdAt. The fork's

package/src/plugins/defaults/memory/buffer-format.ts

@@ -0,0 +1,165 @@
+// ---------------------------------------------------------------------------
+// Memory buffer entry format: the single owner
+// ---------------------------------------------------------------------------
+//
+// `memory/buffer.md` is the append-only staging log that `remember()` writes
+// and consolidation drains. Its line format is written here and recognized
+// here, by one matcher, so the writer and every reader agree by construction.
+//
+// This module deliberately sits at the plugin root (shared infra, not a tier)
+// and imports nothing. `substrate/` is the bottom tier and may not import a
+// tier, but plugin-root infra is fair game, so all readers can reach this one
+// without inverting the layering.
+//
+// A second matcher for this format anywhere in the tree is a bug. Two copies
+// disagree on the shapes nobody thinks to test (indentation, spacing after the
+// bullet dash, spacing inside the date), and each disagreement splits or merges
+// somebody's fact.
+
+/**
+ * A parsed buffer entry opening line.
+ */
+export interface BufferEntryStart {
+  /**
+   * The bracketed timestamp, verbatim. Returned unparsed so it can serve
+   * directly as a consolidation cutoff: both sides of the agent's
+   * "timestamp >= cutoff" comparison then share this exact shape.
+   */
+  timestamp: string;
+  /** Everything after the timestamp bracket, trimmed. */
+  text: string;
+}
+
+/**
+ * Matches an entry opening line: `- [Mon D, h:mm AM/PM] fact`, the shape
+ * {@link formatRememberEntry} writes.
+ *
+ * Anchored at column 0, requiring a space after the dash, and spelling the
+ * timestamp with the single spaces {@link formatBufferTimestamp} emits.
+ * Everything else in the file is a continuation line belonging to the entry
+ * above it, which is how a multiline fact keeps its body: `remember()` writes
+ * only the opening line at column 0 and nests the body beneath it. That rule
+ * is what makes a bullet carrying other bracketed text (a `- [ ]` checklist
+ * item, a `- [[wikilink]]` bullet) read as continuation rather than as a new
+ * fact, and it is why a body line can never imitate an opening.
+ *
+ * Matching the writer's exact shape is the conservative choice in both
+ * directions: a line the writer could not have produced stays body text, so an
+ * odd hand-edit merges into the fact around it instead of splitting that fact
+ * or supplying a malformed timestamp to a caller that treats one as a cutoff.
+ *
+ * Group 1 is the timestamp, group 2 the fact text.
+ */
+const BUFFER_ENTRY_REGEX =
+  /^- \[([A-Z][a-z]{2} \d{1,2}, \d{1,2}:\d{2} [AP]M)\]\s*(.*)$/;
+
+/**
+ * Parse `line` as an entry opening, or `null` if it is a continuation line.
+ *
+ * Pass the raw line. Callers must not trim it first: leading whitespace is
+ * exactly what distinguishes an indented body line from a real entry, so a
+ * trimmed line reads an indented body bullet as a fresh fact and splits one
+ * entry into two.
+ */
+export function matchBufferEntryStart(line: string): BufferEntryStart | null {
+  const match = BUFFER_ENTRY_REGEX.exec(line.trimEnd());
+  if (match === null) {
+    return null;
+  }
+  return { timestamp: match[1]!, text: match[2]!.trim() };
+}
+
+/** Whether `line` opens a buffer entry. See {@link matchBufferEntryStart}. */
+export function isBufferEntryStart(line: string): boolean {
+  return BUFFER_ENTRY_REGEX.test(line.trimEnd());
+}
+
+/**
+ * Format `now` as a buffer-entry timestamp (`Mon D, h:mm AM/PM`). Exported so
+ * the consolidation job can present its cutoff in the same shape the buffer
+ * entries use, making the agent's "timestamp >= cutoff" comparison
+ * unambiguous at minute precision.
+ */
+export function formatBufferTimestamp(now: Date): string {
+  const month = now.toLocaleString("en-US", { month: "short" });
+  const day = now.getDate();
+  const hours = now.getHours();
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const ampm = hours >= 12 ? "PM" : "AM";
+  const displayHour = hours % 12 || 12;
+  return `${month} ${day}, ${displayHour}:${minutes} ${ampm}`;
+}
+
+/**
+ * Indent applied to a fact's continuation lines. Two spaces is the markdown
+ * convention for content nested under a `- ` bullet, so an entry stays
+ * readable as a list item.
+ */
+const CONTINUATION_INDENT = "  ";
+
+/**
+ * Build a timestamped bullet entry for `buffer.md` / `archive/<date>.md`.
+ *
+ * Format mirrors the long-standing v1 PKB layout so buffers stay
+ * human-readable and downstream consumers (sweep, consolidation, the graph
+ * view) can parse the same shape regardless of which path produced the entry.
+ *
+ * A fact's body is indented, which is what makes the format round-trip. The
+ * buffer is line-delimited and the delimiter is "canonical entry shape at
+ * column 0", so a body line carrying that exact shape would otherwise be
+ * indistinguishable from the start of the next fact and split one entry into
+ * two. Indenting moves every body line off column 0, so no fact content can
+ * imitate a delimiter no matter what the user dictated. Blank lines stay
+ * genuinely blank rather than becoming whitespace.
+ *
+ * Readers strip the indent: {@link matchBufferEntryStart} classifies on the
+ * raw line while `parseBufferEntries` trims continuation lines, so the fact
+ * text a caller gets back is unchanged by this.
+ *
+ * Exported so memory sweep / extractor jobs format their auto-remembered
+ * entries identically to user-facing `remember()` calls.
+ */
+export function formatRememberEntry(content: string, now: Date): string {
+  const [opening = "", ...body] = content.split("\n");
+  const nested = body.map((line) =>
+    line.trim().length === 0 ? "" : `${CONTINUATION_INDENT}${line}`,
+  );
+  return `- [${formatBufferTimestamp(now)}] ${[opening, ...nested].join("\n")}\n`;
+}
+
+/**
+ * Split buffer content into entries, each keeping its lines verbatim.
+ *
+ * The unit callers almost always want. Counting or trimming a buffer by raw
+ * lines conflates a five-line fact with five facts, and cuts a fact in half
+ * wherever the count runs out.
+ *
+ * Leading lines that precede the first entry opening (a hand-written buffer,
+ * or stray prose) are returned as a headless first group with
+ * `start === null`, so callers can decide what to do with them rather than
+ * silently dropping content.
+ */
+export function splitBufferEntries(
+  lines: readonly string[],
+): BufferEntryLines[] {
+  const groups: BufferEntryLines[] = [];
+  for (const [index, line] of lines.entries()) {
+    const start = matchBufferEntryStart(line);
+    if (start !== null || groups.length === 0) {
+      groups.push({ start, firstLine: index, lines: [line] });
+      continue;
+    }
+    groups[groups.length - 1]!.lines.push(line);
+  }
+  return groups;
+}
+
+/** One entry's verbatim lines, as returned by {@link splitBufferEntries}. */
+export interface BufferEntryLines {
+  /** `null` for the headless group before the first entry opening. */
+  start: BufferEntryStart | null;
+  /** Index of this group's first line in the input array. */
+  firstLine: number;
+  /** The group's lines, verbatim and in order. */
+  lines: string[];
+}

package/src/plugins/defaults/memory/context-search/sources/conversations.ts

@@ -224,6 +224,12 @@ async function gatherCandidateRowsFromQdrant(
  * the source/type/excluded-conversation predicates in SQL (Qdrant has no
  * visibility filtering). The app-side scorer determines final ordering, so
  * the SQL tie-break falls back to recency.
+ *
+ * No `finalized = 1` predicate, deliberately: every id in `messageIds` comes
+ * from the lexical or vector index, and indexing filters `finalized = 1` at
+ * index time (`message-lexical.ts`), so an unfinalized row can never be a
+ * candidate here. Do not copy this query shape to a reader whose id set has a
+ * different provenance; those need the filter themselves.
  */
 function searchByIds(
   messageIds: readonly string[],

package/src/plugins/defaults/memory/graph/image-ref-utils.ts

@@ -17,6 +17,9 @@ export async function loadImageRefData(
   const msg = db
     .select({ content: messages.content })
     .from(messages)
+    // No completeness predicate: refs come from the extracted memory graph,
+    // and extraction reads finalized rows only, so an unfinalized id cannot
+    // reach here. Do not copy this shape for ids with other provenance.
     .where(eq(messages.id, ref.messageId))
     .get();
   if (!msg) {

package/src/plugins/defaults/memory/graph/tool-handlers.ts

@@ -15,6 +15,7 @@ import {
 } from "../../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../../config/types.js";
 import { enqueueMemoryJob } from "../../../../persistence/jobs-store.js";
+import { formatRememberEntry } from "../buffer-format.js";
 import { getWorkspaceDir } from "../paths.js";
 import type { GraphStats } from "./store.js";
 import {
@@ -98,36 +99,6 @@ export function handleRemember(
   return { success: true, message };
 }
 
-/**
- * Format `now` as a buffer-entry timestamp (`Mon D, h:mm AM/PM`). Exported so
- * the memory v2 consolidation job can present its cutoff in the same shape
- * the buffer entries use, making the agent's "timestamp ≥ cutoff" comparison
- * unambiguous at minute precision.
- */
-export function formatBufferTimestamp(now: Date): string {
-  const month = now.toLocaleString("en-US", { month: "short" });
-  const day = now.getDate();
-  const hours = now.getHours();
-  const minutes = String(now.getMinutes()).padStart(2, "0");
-  const ampm = hours >= 12 ? "PM" : "AM";
-  const displayHour = hours % 12 || 12;
-  return `${month} ${day}, ${displayHour}:${minutes} ${ampm}`;
-}
-
-/**
- * Build a timestamped bullet entry for `buffer.md` / `archive/<date>.md`.
- *
- * Format mirrors the long-standing v1 PKB layout so v2 buffers stay
- * human-readable and downstream consumers (sweep, consolidation) can parse
- * the same shape regardless of which path produced the entry.
- *
- * Exported so memory v2 sweep / extractor jobs format their auto-remembered
- * entries identically to user-facing `remember()` calls.
- */
-export function formatRememberEntry(content: string, now: Date): string {
-  return `- [${formatBufferTimestamp(now)}] ${content}\n`;
-}
-
 /**
  * Append `entry` to `<rootDir>/buffer.md` and `<rootDir>/archive/<today>.md`,
  * creating the archive directory and seeding the archive header if missing.

package/src/plugins/defaults/memory/graph-topology/pending-buffer.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { formatRememberEntry } from "../buffer-format.js";
 import {
   buildPendingGraph,
   findPendingEntryForContent,
@@ -42,6 +43,39 @@ describe("parseBufferEntries", () => {
     expect(entries[1]!.text).toBe("separate fact");
   });
 
+  test("a written fact stays one node even when its body is entry-shaped at column 0", () => {
+    // Round trip through the real writer. A user can dictate a fact whose body
+    // is itself a dated bullet, and without the writer nesting the body those
+    // lines are byte-identical to the start of the next fact, so one memory
+    // renders as several pending nodes in the Memory tab.
+    const entries = parseBufferEntries(
+      formatRememberEntry(
+        "Rollout plan:\n- [Jul 21, 9:00 AM] cutover window opens\n- [Jul 22, 9:00 AM] rollback deadline",
+        new Date(2026, 6, 20, 15, 15),
+      ),
+    );
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.text).toBe(
+      "Rollout plan:\n- [Jul 21, 9:00 AM] cutover window opens\n- [Jul 22, 9:00 AM] rollback deadline",
+    );
+  });
+
+  test("an indented entry-shaped line stays inside the fact above it", () => {
+    // Only an entry's opening line sits at column 0, so an indented bullet
+    // that happens to carry a timestamp is body text the user wrote. Reading
+    // it as an entry splits one fact into two nodes in the Memory tab.
+    const entries = parseBufferEntries(
+      "- [Jul 20, 3:15 PM] Timeline for the migration:\n" +
+        "  - [Jul 21, 9:00 AM] cutover window opens\n" +
+        "  - [Jul 22, 9:00 AM] rollback deadline\n",
+    );
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.text).toBe(
+      "Timeline for the migration:\n- [Jul 21, 9:00 AM] cutover window opens\n- [Jul 22, 9:00 AM] rollback deadline",
+    );
+  });
+
   test("keeps interior blank lines inside a multiline fact", () => {
     const entries = parseBufferEntries(
       "- [Jul 20, 3:15 PM] first paragraph\n\nsecond paragraph\n- [Jul 20, 3:16 PM] next\n",

package/src/plugins/defaults/memory/graph-topology/pending-buffer.ts

@@ -18,7 +18,10 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { formatRememberEntry } from "../graph/tool-handlers.js";
+import {
+  formatRememberEntry,
+  matchBufferEntryStart,
+} from "../buffer-format.js";
 import type { MemoryGraphEdge, MemoryGraphNode } from "./types.js";
 
 /** Node id prefix marking a pending buffer entry (id = prefix + text hash). */
@@ -36,15 +39,6 @@ const MAX_PENDING_NODES = 200;
 
 const PENDING_LABEL_MAX_CHARS = 60;
 
-/**
- * Matches a real entry start: `- [Mon D, h:mm AM/PM] fact`, the exact shape
- * `formatRememberEntry` writes. The timestamp must be present and
- * timestamp-shaped — a bullet with other bracketed text (e.g. a `- [ ]`
- * checklist item inside a multiline fact) is a continuation, not an entry.
- */
-const BUFFER_ENTRY_REGEX =
-  /^-\s+\[[A-Z][a-z]{2}\s+\d{1,2},\s+\d{1,2}:\d{2}\s+[AP]M\]\s*(.*)$/;
-
 /** Lenient fallback for hand-written buffers: a plain bullet with no
  * timestamped entry seen yet still counts as an entry of its own. */
 const PLAIN_BULLET_REGEX = /^-\s+(.+)$/;
@@ -102,10 +96,12 @@ export function parseBufferEntries(content: string): PendingBufferEntry[] {
 
   for (const rawLine of content.split("\n")) {
     const line = rawLine.trimEnd();
-    const entryStart = BUFFER_ENTRY_REGEX.exec(line.trim());
+    // Matched against the untrimmed line: an indented entry-shaped bullet is
+    // body text inside the fact above it, not a fact of its own.
+    const entryStart = matchBufferEntryStart(line);
     if (entryStart) {
       flush();
-      current = [entryStart[1]!.trim()];
+      current = [entryStart.text];
       continue;
     }
     if (current !== null) {

package/src/plugins/defaults/memory/hooks/post-compact.ts

@@ -70,10 +70,7 @@ const postCompact: HookFunction<PostCompactContext> = async (ctx) => {
   // concurrent request's actor and the contact/member registry the actor
   // context derives from can be mutated by contact tools. The snapshots are the
   // values the turn's initial assembly resolved.
-  const trust =
-    conversation?.currentTurnTrustContext ??
-    conversation?.trustContext ??
-    FALLBACK_TURN_TRUST;
+  const trust = conversation?.getTurnOrRestingTrust() ?? FALLBACK_TURN_TRUST;
   const actorContext = conversation?.currentTurnInboundActorContext ?? null;
   // Render the `model_profile:` label from the turn-start notice key, using
   // the call site self-resolved from the live conversation — the same

package/src/plugins/defaults/memory/indexer.ts

@@ -123,7 +123,9 @@ export async function indexMessageNow(
   // memory_segments has no cross-file FK to messages, so this call must not
   // leave pieces for a message with no row. Skip early when the source
   // row is already gone, the common case of a backfill job running after the
-  // message was deleted. A post-write re-check below closes the narrower window
+  // message was deleted. Any-state existence check, deliberately: a
+  // streaming row exists, and orphan prevention is about deletion, not
+  // completeness. A post-write re-check below closes the narrower window
   // where the delete lands mid-transaction.
   const sourceMessage = getDb()
     .select({ id: messages.id })

package/src/plugins/defaults/memory/memory-retrospective-accounting.ts

@@ -52,18 +52,30 @@ export function isSkillCardMessage(row: { metadata: string | null }): boolean {
 }
 
 /**
- * `getMessagesAfter` minus skill-card rows. The retrospective job's
- * new-message slice: a card-only tail yields an empty slice (the job's
- * `no_new_messages` early return), and a mixed tail's cutoff lands on the
- * last real message rather than the card.
+ * `getMessagesAfter` truncated at the first unfinalized row, minus skill-card
+ * rows. The retrospective job's new-message slice: a card-only tail yields an
+ * empty slice (the job's `no_new_messages` early return), and a mixed tail's
+ * cutoff lands on the last real message rather than the card.
+ *
+ * The slice STOPS BEFORE the first unfinalized row rather than filtering it
+ * out. The job's cutoff (and therefore `lastProcessedMessageId` on success)
+ * is chosen from this slice, while the fork the job reviews skips unfinalized
+ * rows, so the cursor must never move past one: filtering through a stale
+ * mid-slice `finalized = 0` row would advance the cursor beyond it, and once
+ * the row later finalizes its `(createdAt, id)` sits behind the cursor,
+ * unreviewed forever. Truncating parks the cursor before the unfinalized row;
+ * the rows behind it are reviewed by the retrospective that runs after the
+ * row resolves (finalizes, or is repaired away by crash recovery).
  */
 export function getRetrospectiveMessagesAfter(
   conversationId: string,
   afterMessageId: string | null,
 ): MessageRow[] {
-  return getMessagesAfter(conversationId, afterMessageId).filter(
-    (row) => !isSkillCardMessage(row),
-  );
+  const rows = getMessagesAfter(conversationId, afterMessageId);
+  const firstUnfinalized = rows.findIndex((row) => row.finalized !== 1);
+  const bounded =
+    firstUnfinalized === -1 ? rows : rows.slice(0, firstUnfinalized);
+  return bounded.filter((row) => !isSkillCardMessage(row));
 }
 
 /**

package/src/plugins/defaults/memory/src/__tests__/memory-v3-gate-stats.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for `handleMemoryV3GateStats` in `memory-v3-routes.ts`.
+ *
+ * The handler aggregates gate telemetry from the telemetry DB and buckets it
+ * by concept page count. These tests cover:
+ *   - empty DB → zero counts, all buckets present, scoredPassRate null
+ *   - mixed rows land in the correct buckets by real_concept_page_count
+ *   - scored vs unscored runs are counted separately
+ *   - rows with no real_concept_page_count go to unknownPageCount
+ *   - lookbackDays is clamped to [1, 90]
+ *   - malformed JSON rows are skipped
+ *   - null/absent DB returns a zero response
+ */
+
+import type { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { handleMemoryV3GateStats } from "../memory-v3-routes.js";
+
+// ---------------------------------------------------------------------------
+// Minimal fake SQLite DB that returns pre-set rows
+// ---------------------------------------------------------------------------
+
+type FakeRow = { payload: string };
+
+function makePayload(detail: Record<string, unknown>): string {
+  return JSON.stringify({
+    type: "watchdog",
+    daemon_event_id: "test-id",
+    recorded_at: Date.now(),
+    check_name: "memory_v3_injection_gate",
+    value: 1,
+    detail,
+  });
+}
+
+function fakeDb(rows: FakeRow[]): Database {
+  return {
+    query: (_sql: string) => ({
+      all: (..._args: unknown[]) => rows,
+    }),
+  } as unknown as Database;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("handleMemoryV3GateStats", () => {
+  test("returns zero counts with all buckets when DB is null", () => {
+    const result = handleMemoryV3GateStats(30, null);
+    expect(result.totalRuns).toBe(0);
+    expect(result.buckets).toHaveLength(4);
+    for (const bucket of result.buckets) {
+      expect(bucket.total).toBe(0);
+      expect(bucket.scored).toBe(0);
+      expect(bucket.passed).toBe(0);
+      expect(bucket.scoredPassRate).toBeNull();
+      expect(bucket.reasons).toEqual({});
+    }
+    expect(result.unknownPageCount).toEqual({
+      total: 0,
+      passed: 0,
+      reasons: {},
+    });
+  });
+
+  test("returns zero counts with all buckets when DB returns no rows", () => {
+    const result = handleMemoryV3GateStats(30, fakeDb([]));
+    expect(result.totalRuns).toBe(0);
+    expect(result.buckets[0]!.pageCountRange).toBe("0–9");
+    expect(result.buckets[3]!.pageCountRange).toBe("200+");
+    for (const b of result.buckets) {
+      expect(b.scoredPassRate).toBeNull();
+    }
+  });
+
+  test("buckets a dense_pass row into 10–49 bucket", () => {
+    const rows = [
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_pass",
+          scored: true,
+          real_concept_page_count: 25,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    expect(result.totalRuns).toBe(1);
+    const bucket = result.buckets.find((b) => b.pageCountRange === "10–49")!;
+    expect(bucket.total).toBe(1);
+    expect(bucket.scored).toBe(1);
+    expect(bucket.passed).toBe(1);
+    expect(bucket.scoredPassRate).toBe(1);
+    expect(bucket.reasons).toEqual({ dense_pass: 1 });
+  });
+
+  test("buckets a fail row into 200+ bucket", () => {
+    const rows = [
+      {
+        payload: makePayload({
+          pass: false,
+          reason: "fail_no_signal",
+          scored: true,
+          real_concept_page_count: 350,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    const bucket = result.buckets.find((b) => b.pageCountRange === "200+")!;
+    expect(bucket.total).toBe(1);
+    expect(bucket.passed).toBe(0);
+    expect(bucket.scoredPassRate).toBe(0);
+    expect(bucket.reasons).toEqual({ fail_no_signal: 1 });
+  });
+
+  test("unscored pass-open rows count in total but not scored", () => {
+    const rows = [
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_unavailable",
+          scored: false,
+          real_concept_page_count: 5,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    const bucket = result.buckets.find((b) => b.pageCountRange === "0–9")!;
+    expect(bucket.total).toBe(1);
+    expect(bucket.scored).toBe(0);
+    expect(bucket.passed).toBe(1);
+    // No scored runs → scoredPassRate is null (unscored pass does not count)
+    expect(bucket.scoredPassRate).toBeNull();
+  });
+
+  test("unscored pass mixed with scored fail does not inflate scoredPassRate", () => {
+    // Regression: before fix, pass-open + scored-fail in same bucket gave 100%
+    const rows = [
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_unavailable",
+          scored: false,
+          real_concept_page_count: 30,
+        }),
+      },
+      {
+        payload: makePayload({
+          pass: false,
+          reason: "fail_no_signal",
+          scored: true,
+          real_concept_page_count: 40,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    const bucket = result.buckets.find((b) => b.pageCountRange === "10–49")!;
+    expect(bucket.total).toBe(2);
+    expect(bucket.scored).toBe(1);
+    expect(bucket.passed).toBe(1); // total passes (scored + unscored)
+    // Only the scored fail counts toward the rate — no scored passes
+    expect(bucket.scoredPassRate).toBe(0);
+  });
+
+  test("rows with no real_concept_page_count go to unknownPageCount", () => {
+    const rows = [
+      {
+        payload: makePayload({
+          pass: false,
+          reason: "fail_no_signal",
+          scored: true,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    expect(result.unknownPageCount.total).toBe(1);
+    expect(result.unknownPageCount.passed).toBe(0);
+    expect(result.unknownPageCount.reasons).toEqual({ fail_no_signal: 1 });
+    for (const b of result.buckets) {
+      expect(b.total).toBe(0);
+    }
+  });
+
+  test("mixed rows across multiple buckets are aggregated correctly", () => {
+    const rows: FakeRow[] = [
+      // 0–9 bucket: 1 unscored pass
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_disabled",
+          scored: false,
+          real_concept_page_count: 3,
+        }),
+      },
+      // 10–49 bucket: 1 pass, 1 fail (both scored)
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_pass",
+          scored: true,
+          real_concept_page_count: 20,
+        }),
+      },
+      {
+        payload: makePayload({
+          pass: false,
+          reason: "fail_no_signal",
+          scored: true,
+          real_concept_page_count: 45,
+        }),
+      },
+      // 50–199 bucket: 2 passes
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "sparse_only_strong",
+          scored: true,
+          real_concept_page_count: 100,
+        }),
+      },
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_pass",
+          scored: true,
+          real_concept_page_count: 150,
+        }),
+      },
+    ];
+
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    expect(result.totalRuns).toBe(5);
+
+    const b09 = result.buckets.find((b) => b.pageCountRange === "0–9")!;
+    expect(b09.total).toBe(1);
+    expect(b09.scored).toBe(0);
+    expect(b09.scoredPassRate).toBeNull();
+
+    const b1049 = result.buckets.find((b) => b.pageCountRange === "10–49")!;
+    expect(b1049.total).toBe(2);
+    expect(b1049.scored).toBe(2);
+    expect(b1049.passed).toBe(1);
+    expect(b1049.scoredPassRate).toBe(0.5);
+    expect(b1049.reasons).toEqual({ dense_pass: 1, fail_no_signal: 1 });
+
+    const b50199 = result.buckets.find((b) => b.pageCountRange === "50–199")!;
+    expect(b50199.scored).toBe(2);
+    expect(b50199.passed).toBe(2);
+    expect(b50199.scoredPassRate).toBe(1);
+  });
+
+  test("lookbackDays is clamped to 1–90", () => {
+    const r1 = handleMemoryV3GateStats(0, fakeDb([]));
+    expect(r1.lookbackDays).toBe(1);
+    const r2 = handleMemoryV3GateStats(999, fakeDb([]));
+    expect(r2.lookbackDays).toBe(90);
+    const r3 = handleMemoryV3GateStats(30, fakeDb([]));
+    expect(r3.lookbackDays).toBe(30);
+  });
+
+  test("malformed JSON payload rows are skipped", () => {
+    const rows: FakeRow[] = [
+      { payload: "not-valid-json" },
+      {
+        payload: makePayload({
+          pass: true,
+          reason: "dense_pass",
+          scored: true,
+          real_concept_page_count: 25,
+        }),
+      },
+    ];
+    const result = handleMemoryV3GateStats(30, fakeDb(rows));
+    // Only the valid row is counted
+    expect(result.totalRuns).toBe(2); // totalRuns counts raw rows before parse
+    const bucket = result.buckets.find((b) => b.pageCountRange === "10–49")!;
+    expect(bucket.total).toBe(1);
+  });
+});