@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/plugins/defaults/memory/v3/__tests__/pool-log-store.test.ts

@@ -28,13 +28,17 @@ import { Database } from "bun:sqlite";
 import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { OrchestrateResult } from "../orchestrate.js";
-import { ensureMemoryV3PoolsSchema } from "../plugin-schema.js";
+import {
+  ensureMemoryV3PoolInputsSchema,
+  ensureMemoryV3PoolsSchema,
+} from "../plugin-schema.js";
 import type {
   PoolCandidateRecord,
   PoolLane,
   PoolRecord,
 } from "../pool-log-store.js";
-import type { Section, Slug } from "../types.js";
+import { renderFinderLine } from "../pool-select.js";
+import type { MemoryRoutingTurn, Section, Slug } from "../types.js";
 
 const realDb = {
   ...(await import("../../../../../persistence/db-connection.js")),
@@ -50,6 +54,7 @@ makeDb();
 function makeDb() {
   memorySqlite = new Database(":memory:");
   ensureMemoryV3PoolsSchema(memorySqlite);
+  ensureMemoryV3PoolInputsSchema(memorySqlite);
 }
 
 mock.module("../../../../../persistence/db-connection.js", () => ({
@@ -62,8 +67,17 @@ mock.module("../../../../../persistence/db-connection.js", () => ({
       : realDb.getMemorySqlite(),
 }));
 
-const { buildPoolRecord, readPoolForMessageIds, readPoolForTurn, writePool } =
-  await import("../pool-log-store.js");
+const {
+  buildPoolInput,
+  buildPoolRecord,
+  hashPoolText,
+  readPoolForMessageIds,
+  readPoolForTurn,
+  readPoolInputForTurn,
+  readPoolText,
+  writePool,
+  writePoolInput,
+} = await import("../pool-log-store.js");
 
 beforeEach(() => {
   storeMockActive = true;
@@ -115,6 +129,32 @@ function orchestrated(): OrchestrateResult {
   };
 }
 
+/** {@link orchestrated} with the pool the selector was given: a card per
+ *  stable-prefix slug and one finder candidate per finder line, in the
+ *  record's order, plus the gate and keep-all facts. */
+function orchestratedWithPool(): OrchestrateResult {
+  const result = orchestrated();
+  return {
+    ...result,
+    pool: {
+      stable: [
+        { slug: "core/page", card: "core card" },
+        { slug: "hot/page", card: "hot card" },
+        { slug: "fresh/page", card: "fresh card" },
+        { slug: "skills/example", card: "skill card" },
+      ],
+      finder: result.lanes.finder.map((line) => ({
+        slug: line.slug,
+        lane: line.lane,
+        section: line.section,
+        descriptor: line.descriptor || `${line.slug} lead`,
+      })),
+    },
+    keptAll: false,
+    gateReason: "dense_pass",
+  };
+}
+
 /**
  * A turn the injection gate hard-skipped: the selector was never consulted,
  * so there are no selections, but the result's lanes still carry the stable
@@ -447,3 +487,142 @@ describe("ensureMemoryV3PoolsSchema", () => {
     expect(column?.dflt_value).toBe("1");
   });
 });
+
+describe("pool input capture", () => {
+  const turn: MemoryRoutingTurn = {
+    conversationId: "conv-1",
+    turnNumber: 4,
+    currentMessage: "what did we decide about the garden?",
+    recentContext: "user: hi\nassistant: hello",
+    situationalContext: "Today is 2026-01-01.",
+    previousAssistantMessage: "hello",
+  };
+
+  test("buildPoolInput captures each candidate's rendered text in pool order, aligned with the pool record", () => {
+    const result = orchestratedWithPool();
+    const { input, texts } = buildPoolInput(result, turn, "select wisely");
+    const record = buildPoolRecord(result);
+
+    expect(input.candidate_text_hashes).toHaveLength(record.candidates.length);
+    const rendered = [
+      ...result.pool!.stable.map((candidate) => candidate.card),
+      ...result.pool!.finder.map((candidate) => renderFinderLine(candidate)),
+    ];
+    expect(input.candidate_text_hashes.map((hash) => texts.get(hash))).toEqual(
+      rendered,
+    );
+    expect(input.candidate_text_hashes[0]).toBe(hashPoolText("core card"));
+    expect(input).toMatchObject({
+      situational_context: "Today is 2026-01-01.",
+      recent_context: "user: hi\nassistant: hello",
+      current_message: "what did we decide about the garden?",
+      previous_assistant_message: "hello",
+      selector_prompt_hash: hashPoolText("select wisely"),
+      kept_all: false,
+      gate_reason: "dense_pass",
+    });
+  });
+
+  test("a turn whose selector never judged a pool captures the context and no candidate texts", () => {
+    const { input, texts } = buildPoolInput(
+      hardSkipped(),
+      {
+        ...turn,
+        situationalContext: undefined,
+        previousAssistantMessage: undefined,
+      },
+      "select wisely",
+    );
+
+    expect(input.candidate_text_hashes).toEqual([]);
+    expect(texts.size).toBe(0);
+    expect(input).toMatchObject({
+      situational_context: null,
+      previous_assistant_message: null,
+      selector_prompt_hash: null,
+      gate_reason: null,
+    });
+  });
+
+  test("a result without the selector's pool captures no candidate texts rather than misaligned ones", () => {
+    const { input, texts } = buildPoolInput(
+      orchestrated(),
+      turn,
+      "select wisely",
+    );
+
+    expect(input.candidate_text_hashes).toEqual([]);
+    expect(texts.size).toBe(0);
+  });
+
+  test("writePoolInput and readPoolInputForTurn round-trip; a re-observed turn replaces its row; texts are stored once", () => {
+    const capture = buildPoolInput(
+      orchestratedWithPool(),
+      turn,
+      "select wisely",
+    );
+    writePoolInput(memorySqlite, "conv-1", 4, capture);
+
+    expect(readPoolInputForTurn("conv-1", 4)).toEqual(capture.input);
+    expect(readPoolText(capture.input.candidate_text_hashes[0]!)).toBe(
+      "core card",
+    );
+
+    // The next turn pools the same candidates: its input row is its own, the
+    // texts are shared by hash.
+    writePoolInput(
+      memorySqlite,
+      "conv-1",
+      5,
+      buildPoolInput(
+        orchestratedWithPool(),
+        { ...turn, turnNumber: 5, currentMessage: "and the fence?" },
+        "select wisely",
+      ),
+    );
+    const textCount = () =>
+      (
+        memorySqlite
+          .query(`SELECT COUNT(*) AS n FROM memory_v3_pool_texts`)
+          .get() as { n: number }
+      ).n;
+    expect(textCount()).toBe(new Set(capture.input.candidate_text_hashes).size);
+    expect(readPoolInputForTurn("conv-1", 5)?.current_message).toBe(
+      "and the fence?",
+    );
+
+    writePoolInput(
+      memorySqlite,
+      "conv-1",
+      4,
+      buildPoolInput(
+        orchestratedWithPool(),
+        { ...turn, currentMessage: "again" },
+        "select wisely",
+      ),
+    );
+    expect(readPoolInputForTurn("conv-1", 4)?.current_message).toBe("again");
+    expect(
+      (
+        memorySqlite
+          .query(`SELECT COUNT(*) AS n FROM memory_v3_pool_inputs`)
+          .get() as { n: number }
+      ).n,
+    ).toBe(2);
+  });
+
+  test("an absent turn or text reads null, and reads degrade to null when the memory connection is unavailable", () => {
+    expect(readPoolInputForTurn("conv-1", 9)).toBeNull();
+    expect(readPoolText("missing")).toBeNull();
+
+    writePoolInput(
+      memorySqlite,
+      "conv-1",
+      4,
+      buildPoolInput(orchestratedWithPool(), turn, "select wisely"),
+    );
+    memoryDbAvailable = false;
+    expect(readPoolInputForTurn("conv-1", 4)).toBeNull();
+    expect(readPoolText(hashPoolText("core card"))).toBeNull();
+  });
+});

package/src/plugins/defaults/memory/v3/__tests__/shadow-plugin.test.ts

@@ -43,6 +43,7 @@ import type { HotSetEntry, HotSetOptions } from "../hot-set.js";
 import type { OrchestrateResult } from "../orchestrate.js";
 import {
   ensureMemoryV3InjectedSectionsSchema,
+  ensureMemoryV3PoolInputsSchema,
   ensureMemoryV3PoolsSchema,
 } from "../plugin-schema.js";
 import { MEMORY_V3_FULL_PROFILE_MIN_PAGES } from "../tuning-profile.js";
@@ -123,6 +124,9 @@ let gateEnabledCfg = true;
 // Mutable `memory.v3.rareTerm.enabled` switch carried by the mocked config
 // (default on, mirroring the schema default).
 let rareTermEnabledCfg = true;
+// Mutable `memory.v3.poolLog.captureInput` opt-in carried by the mocked
+// config (default off, mirroring the schema default).
+let captureInputCfg = false;
 let messages: Array<{
   role: string;
   content: string;
@@ -240,6 +244,7 @@ function makeDb() {
   ensureMemoryV3InjectedSectionsSchema(memorySqlite);
   // `observeTurn` records each turn's candidate pool next to its selections.
   ensureMemoryV3PoolsSchema(memorySqlite);
+  ensureMemoryV3PoolInputsSchema(memorySqlite);
   return db;
 }
 
@@ -298,6 +303,7 @@ function seedMemoryConfig(): void {
       // Gate tuning (schema defaults) with the mutable `enabled` kill-switch,
       // threaded through to orchestrate as-is.
       gate: { ...GATE_DEFAULTS, enabled: gateEnabledCfg },
+      poolLog: { captureInput: captureInputCfg },
     },
     qdrant: { vectorSize: 8, onDisk: false },
   });
@@ -586,8 +592,9 @@ const {
 } = await import("../shadow-plugin.js");
 const { memoryV3Injector, resetMemoryV3InjectorStateForTests } =
   await import("../injector.js");
-const { MemoryV3RetrievalUnavailableError } = await import("../pool-select.js");
-const { buildPoolRecord, readPoolForMessageIds } =
+const { MemoryV3RetrievalUnavailableError, renderFinderLine } =
+  await import("../pool-select.js");
+const { buildPoolRecord, readPoolForMessageIds, readPoolText } =
   await import("../pool-log-store.js");
 
 /** Seed the real config from the current mutable knobs, then run the real
@@ -626,6 +633,23 @@ function readPools() {
   }>;
 }
 
+function readPoolInputs() {
+  return memorySqlite
+    .query(
+      `SELECT conversation_id, turn, current_message, kept_all, gate_reason,
+              candidate_text_hashes_json
+       FROM memory_v3_pool_inputs ORDER BY turn`,
+    )
+    .all() as Array<{
+    conversation_id: string;
+    turn: number;
+    current_message: string;
+    kept_all: number;
+    gate_reason: string | null;
+    candidate_text_hashes_json: string;
+  }>;
+}
+
 /** The `chosen` verdict per pooled slug, read from the single pool row. */
 function chosenBySlug(): Record<string, boolean> {
   const pools = readPools();
@@ -668,6 +692,7 @@ beforeEach(() => {
   selectorEnabledCfg = false;
   gateEnabledCfg = true;
   rareTermEnabledCfg = true;
+  captureInputCfg = false;
   messages = [
     {
       role: "user",
@@ -975,6 +1000,61 @@ describe("memory-v3 engine", () => {
     expect(readPools().map((pool) => pool.message_id)).toEqual(["m-skipped"]);
   });
 
+  test("the selector's input is not captured unless memory.v3.poolLog.captureInput is on", async () => {
+    await observeTurn("conv-1", 2);
+
+    expect(readPools()).toHaveLength(1);
+    expect(readPoolInputs()).toHaveLength(0);
+  });
+
+  test("with memory.v3.poolLog.captureInput on, the turn log writes the selector's input and every pooled candidate's text", async () => {
+    captureInputCfg = true;
+    const finder = [
+      { slug: "page-1", descriptor: "the first page", lane: "needle" as const },
+      { slug: "page-2", descriptor: "", lane: "edge" as const },
+    ];
+    orchestrateSpy.mockImplementationOnce(async () => ({
+      selections: [
+        { slug: "page-core", sections: [] },
+        { slug: "page-1", sections: [] },
+      ],
+      lanes: { core: ["page-core"], hot: [], fresh: [], always: [], finder },
+      selectorRan: true,
+      keptAll: false,
+      gateReason: "dense_pass",
+      pool: {
+        stable: [{ slug: "page-core", card: "core card" }],
+        finder,
+      },
+    }));
+
+    await observeTurn("conv-1", 2);
+
+    const pools = readPools();
+    expect(pools).toHaveLength(1);
+    expect(pools[0]!.pool_size).toBe(3);
+    const inputs = readPoolInputs();
+    expect(inputs).toHaveLength(1);
+    expect(inputs[0]).toMatchObject({
+      conversation_id: "conv-1",
+      turn: 2,
+      current_message: "hello world",
+      kept_all: 0,
+      gate_reason: "dense_pass",
+    });
+
+    // One hash per pooled candidate in pool order: the card as pre-rendered,
+    // then each finder line exactly as the selector renders it.
+    const hashes = JSON.parse(
+      inputs[0]!.candidate_text_hashes_json,
+    ) as string[];
+    expect(hashes.map((hash) => readPoolText(hash))).toEqual([
+      "core card",
+      renderFinderLine(finder[0]!),
+      renderFinderLine(finder[1]!),
+    ]);
+  });
+
   test("a turn observed again replaces its selection rows in step with its pool", async () => {
     orchestrateSpy.mockImplementationOnce(async () =>
       poolOf(["page-1", "page-2"]),
@@ -1163,6 +1243,27 @@ describe("memory-v3 engine", () => {
     expect(sourceOf([])).toBe("needle");
   });
 
+  test("a turn whose selector could not run attributes no rows, so unjudged pages never feed frecency or learned edges", () => {
+    const rows = attributeSelections({
+      selections: [
+        { slug: "page-core", sections: [] },
+        { slug: "page-hot", sections: [] },
+      ],
+      lanes: {
+        core: ["page-core"],
+        hot: ["page-hot"],
+        fresh: [],
+        always: [],
+        finder: [{ slug: "page-two", descriptor: "", lane: "needle" }],
+      },
+      selectorRan: false,
+      selectorFailure: new MemoryV3RetrievalUnavailableError(
+        "selector unavailable",
+      ),
+    });
+    expect(rows).toEqual([]);
+  });
+
   test("a selection of a core page a finder also hit attributes to core (pool position wins)", () => {
     const rows = attributeSelections({
       selections: [{ slug: "page-core", sections: [] }],

package/src/plugins/defaults/memory/v3/card.ts

@@ -1,5 +1,6 @@
+import { safeStringSlice } from "@vellumai/plugin-api";
+
 import { FRONTMATTER_REGEX, parseFrontmatterFields } from "../frontmatter.js";
-import { safeStringSlice } from "../host-utils.js";
 import { injectedConceptHeader } from "../substrate/injected-block-slugs.js";
 import { LINK_SEPARATOR, parseLinkEntry } from "../substrate/page-links.js";
 import type { Slug } from "./types.js";