@vellumai/assistant 0.8.5 → 0.8.6

package/src/memory/v2/harness/trace.ts

@@ -41,6 +41,12 @@ export interface GateDecision {
   decision: "ready" | "more";
   /** When "more", the generated follow-up queries seeding the next pass. */
   questions?: string[];
+  /**
+   * The gate's one-line rationale for this verdict, when it supplied one.
+   * Surfaced in the descent trace and the live-shadow telemetry so a run can be
+   * analyzed after the fact ("why did the gate keep this set?").
+   */
+  reasoning?: string;
 }
 
 /** Everything that happened on one pass of the loop. */

package/src/memory/v3/__tests__/consolidation-job.test.ts

@@ -38,11 +38,9 @@ import {
 
 import { eq } from "drizzle-orm";
 
-import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
+import { createMockLoggerModule } from "../../../__tests__/helpers/mock-logger.js";
 
-mock.module("../../../util/logger.js", () => ({
-  getLogger: () => makeMockLogger(),
-}));
+mock.module("../../../util/logger.js", () => createMockLoggerModule());
 
 // ── runBackgroundJob mock ───────────────────────────────────────────
 //

package/src/memory/v3/__tests__/coretrieval-seed.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Tests for `assistant/src/memory/v3/coretrieval-seed.ts`.
+ *
+ *   - `buildCoretrievalGraph` (pure): co-occurrence counting, the min-count
+ *     floor, the always-on frequency exclusion, NPMI ranking, and the top-K cap.
+ *   - `seedCoretrievalEdges` (driver): reads router selections from
+ *     `memory_v2_activation_logs`, persists the graph into `memory_v3_auto_edges`
+ *     in the shape `aboveThreshold` reads back, and is idempotent.
+ *
+ * Generic slugs only (page-a, topic-x, …) — no real content.
+ */
+
+import { Database } from "bun:sqlite";
+import { describe, expect, mock, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+import type { DrizzleDb } from "../../db-connection.js";
+import {
+  buildCoretrievalGraph,
+  seedCoretrievalEdges,
+} from "../coretrieval-seed.js";
+
+describe("buildCoretrievalGraph", () => {
+  const opts = { minCount: 2, maxNeighborFreqRatio: 1, topK: 10 };
+
+  test("ignores turns with fewer than two distinct slugs", () => {
+    const graph = buildCoretrievalGraph(
+      [["page-a"], ["page-b"], ["page-a", "page-a"]],
+      opts,
+    );
+    expect(graph.size).toBe(0);
+  });
+
+  test("ranks a surprising association above a high-frequency one (NPMI)", () => {
+    // page-b appears only ever alongside page-a (perfectly associated); topic-c
+    // is high-frequency (appears all over), so its co-occurrence with page-a is
+    // unsurprising. NPMI must rank page-b above topic-c for source page-a.
+    const turns = [
+      ["page-a", "page-b"],
+      ["page-a", "page-b"],
+      ["page-a", "page-b"],
+      ["page-a", "page-b"],
+      ["page-a", "topic-c"],
+      ["page-a", "topic-c"],
+      ["page-a", "topic-c"],
+      ["page-a", "topic-c"],
+      ["topic-c", "page-d"],
+      ["topic-c", "page-d"],
+      ["topic-c", "page-d"],
+      ["topic-c", "page-d"],
+      ["topic-c", "page-d"],
+      ["topic-c", "page-d"],
+    ];
+    const graph = buildCoretrievalGraph(turns, opts);
+    const neighbors = graph.get("page-a")!;
+    expect(neighbors[0].target).toBe("page-b");
+    const bScore = neighbors.find((n) => n.target === "page-b")!.score;
+    const cScore = neighbors.find((n) => n.target === "topic-c")?.score ?? -1;
+    expect(bScore).toBeGreaterThan(cScore);
+  });
+
+  test("drops pairs below the min-count floor", () => {
+    const turns = [
+      ["page-a", "page-b"],
+      ["page-a", "page-b"], // page-a↔page-b co-occur twice
+      ["page-a", "page-c"], // page-a↔page-c co-occur once
+    ];
+    const strict = buildCoretrievalGraph(turns, { ...opts, minCount: 2 });
+    const targets = (strict.get("page-a") ?? []).map((n) => n.target);
+    expect(targets).toContain("page-b");
+    expect(targets).not.toContain("page-c");
+  });
+
+  test("excludes always-on neighbors above the frequency ratio", () => {
+    // topic-hub appears on every turn (always-on); page-b appears on few. With a
+    // 0.5 ratio cap, topic-hub is excluded as a neighbor even though it co-occurs.
+    const turns = [
+      ["page-a", "page-b", "topic-hub"],
+      ["page-a", "page-b", "topic-hub"],
+      ["page-x", "topic-hub"],
+      ["page-y", "topic-hub"],
+    ];
+    const graph = buildCoretrievalGraph(turns, {
+      minCount: 2,
+      maxNeighborFreqRatio: 0.5,
+      topK: 10,
+    });
+    const targets = (graph.get("page-a") ?? []).map((n) => n.target);
+    expect(targets).toContain("page-b");
+    expect(targets).not.toContain("topic-hub");
+  });
+
+  test("caps neighbors at top-K", () => {
+    const turns = [
+      ["src", "n1", "n2", "n3", "n4"],
+      ["src", "n1", "n2", "n3", "n4"],
+    ];
+    const graph = buildCoretrievalGraph(turns, { ...opts, topK: 2 });
+    expect(graph.get("src")!.length).toBe(2);
+  });
+});
+
+describe("seedCoretrievalEdges", () => {
+  function freshDb(): { db: DrizzleDb; sqlite: Database } {
+    const sqlite = new Database(":memory:");
+    sqlite.run(
+      `CREATE TABLE memory_v2_activation_logs (
+         id TEXT PRIMARY KEY, mode TEXT NOT NULL, concepts_json TEXT NOT NULL
+       )`,
+    );
+    sqlite.run(
+      `CREATE TABLE memory_v3_auto_edges (
+         source_slug TEXT NOT NULL, target_slug TEXT NOT NULL,
+         weight REAL NOT NULL, last_reinforced_at INTEGER NOT NULL,
+         PRIMARY KEY (source_slug, target_slug)
+       )`,
+    );
+    return { db: drizzle(sqlite) as unknown as DrizzleDb, sqlite };
+  }
+
+  function insertRouterTurn(
+    sqlite: Database,
+    id: string,
+    slugs: string[],
+  ): void {
+    const concepts = slugs.map((slug) => ({ slug, status: "injected" }));
+    sqlite.run(
+      `INSERT INTO memory_v2_activation_logs (id, mode, concepts_json) VALUES (?, 'router', ?)`,
+      [id, JSON.stringify(concepts)],
+    );
+  }
+
+  test("persists the co-retrieval graph in the shape aboveThreshold reads", () => {
+    const { db, sqlite } = freshDb();
+    for (let i = 0; i < 4; i++) {
+      insertRouterTurn(sqlite, `t${i}`, ["page-a", "page-b"]);
+    }
+    // A non-router row must be ignored.
+    sqlite.run(
+      `INSERT INTO memory_v2_activation_logs (id, mode, concepts_json) VALUES ('x', 'v3_shadow', ?)`,
+      [JSON.stringify([{ slug: "noise-a", status: "injected" }])],
+    );
+
+    const result = seedCoretrievalEdges(db, {
+      minCount: 2,
+      maxNeighborFreqRatio: 1,
+      topK: 10,
+      seedWeight: 2,
+    });
+
+    expect(result.turnsScanned).toBe(4);
+    expect(result.edgesWritten).toBeGreaterThan(0);
+
+    // Assert via a direct table read (not auto-edges' aboveThreshold, which a
+    // sibling test file mocks) so the seed's persistence is verified in
+    // isolation. The edge is symmetric: both directions are written.
+    const pairs = (
+      sqlite
+        .query(
+          `SELECT source_slug, target_slug FROM memory_v3_auto_edges WHERE weight >= 1`,
+        )
+        .all() as Array<{ source_slug: string; target_slug: string }>
+    ).map((r) => `${r.source_slug}->${r.target_slug}`);
+    expect(pairs).toContain("page-a->page-b");
+    expect(pairs).toContain("page-b->page-a");
+  });
+
+  test("is idempotent — re-running does not inflate weights", () => {
+    const { db, sqlite } = freshDb();
+    for (let i = 0; i < 4; i++) {
+      insertRouterTurn(sqlite, `t${i}`, ["page-a", "page-b"]);
+    }
+    const seedOpts = {
+      minCount: 2,
+      maxNeighborFreqRatio: 1,
+      topK: 10,
+      seedWeight: 2,
+    };
+    seedCoretrievalEdges(db, seedOpts);
+    seedCoretrievalEdges(db, seedOpts);
+
+    const row = sqlite
+      .query(
+        `SELECT weight FROM memory_v3_auto_edges WHERE source_slug = 'page-a' AND target_slug = 'page-b'`,
+      )
+      .get() as { weight: number };
+    expect(row.weight).toBe(2);
+  });
+
+  test("weights edges by NPMI — a stronger association gets a higher weight", () => {
+    const { db, sqlite } = freshDb();
+    // page-b co-occurs with page-a more than page-c does (both exclusive to
+    // page-a), so NPMI(a,b) > NPMI(a,c) > 0; the filler turns lower base rates.
+    for (let i = 0; i < 3; i++)
+      insertRouterTurn(sqlite, `ab${i}`, ["page-a", "page-b"]);
+    for (let i = 0; i < 2; i++)
+      insertRouterTurn(sqlite, `ac${i}`, ["page-a", "page-c"]);
+    for (let i = 0; i < 5; i++)
+      insertRouterTurn(sqlite, `de${i}`, ["topic-d", "topic-e"]);
+
+    seedCoretrievalEdges(db, {
+      minCount: 2,
+      maxNeighborFreqRatio: 1,
+      topK: 10,
+      seedWeight: 2,
+    });
+
+    const weightOf = (s: string, t: string) =>
+      (
+        sqlite
+          .query(
+            `SELECT weight FROM memory_v3_auto_edges WHERE source_slug = ? AND target_slug = ?`,
+          )
+          .get(s, t) as { weight: number } | null
+      )?.weight;
+    const wAB = weightOf("page-a", "page-b");
+    const wAC = weightOf("page-a", "page-c");
+    expect(wAC).toBeGreaterThan(0);
+    expect(wAB!).toBeGreaterThan(wAC!);
+    // NPMI < 1 for a non-exclusive pair, so weight stays below the perfect-
+    // association seedWeight.
+    expect(wAB!).toBeLessThan(2);
+  });
+
+  test("skips edges with non-positive NPMI (co-occur at or below chance)", () => {
+    const { db, sqlite } = freshDb();
+    // page-a and page-b are each frequent but seldom together (below chance) =>
+    // negative NPMI => skipped. page-a/topic-x co-occur above chance => kept.
+    for (let i = 0; i < 4; i++)
+      insertRouterTurn(sqlite, `ax${i}`, ["page-a", "topic-x"]);
+    for (let i = 0; i < 4; i++)
+      insertRouterTurn(sqlite, `by${i}`, ["page-b", "topic-y"]);
+    for (let i = 0; i < 2; i++)
+      insertRouterTurn(sqlite, `ab${i}`, ["page-a", "page-b"]);
+
+    seedCoretrievalEdges(db, {
+      minCount: 2,
+      maxNeighborFreqRatio: 1,
+      topK: 10,
+      seedWeight: 2,
+    });
+
+    const has = (s: string, t: string) =>
+      sqlite
+        .query(
+          `SELECT 1 FROM memory_v3_auto_edges WHERE source_slug = ? AND target_slug = ?`,
+        )
+        .get(s, t) !== null;
+    expect(has("page-a", "topic-x")).toBe(true);
+    expect(has("page-a", "page-b")).toBe(false);
+  });
+
+  test("returns an empty summary when there are no router turns", () => {
+    const { db } = freshDb();
+    const result = seedCoretrievalEdges(db);
+    expect(result).toEqual({
+      turnsScanned: 0,
+      nodes: 0,
+      edgesWritten: 0,
+      avgDegree: 0,
+    });
+  });
+});

package/src/memory/v3/__tests__/edges.test.ts

@@ -5,9 +5,12 @@
  * Coverage matrix:
  *   - 1-hop and 2-hop outgoing expansion from a single seed.
  *   - Default hops (2) when omitted.
- *   - Seed excluded from its own `pulled`.
+ *   - Seed excluded from its own `pulled`, and from another seed's `pulled`
+ *     when one seed is reachable from another (seeds-excluded contract).
  *   - Multiple seeds: top-level `pulled` is the union; per-seed expansions
  *     attribute correctly; duplicate seeds collapse.
+ *   - Per-seed cap spends slots on unique neighbors, not duplicates an earlier
+ *     seed already pulled (recall at the cap).
  *   - `extraAdjacency` merges with the curated graph during traversal.
  *   - `extraAdjacency` bridges across hops (curated → extra → curated).
  *   - Cycles in the curated graph (and via extraAdjacency) terminate, bounded
@@ -463,6 +466,46 @@ describe("expandEdges — bounds", () => {
     }
   });
 
+  test("maxTotalPulls overrides the default union ceiling", async () => {
+    // 20 seeds × 32 disjoint targets = 640 reachable, far past any cap. A low
+    // per-call maxTotalPulls must bound the union to that value, not the 400
+    // default; an omitted or invalid value falls back to the default.
+    const seedCount = 20;
+    const graph: Record<string, string[]> = {};
+    const seeds: string[] = [];
+    for (let s = 0; s < seedCount; s++) {
+      const seed = topicSlug("people", s);
+      const targets: string[] = [];
+      for (let t = 0; t < MAX_PULLS_PER_SEED; t++) {
+        const target = topicSlug("targets", s * MAX_PULLS_PER_SEED + t);
+        targets.push(target);
+        graph[target] = [];
+      }
+      graph[seed] = targets;
+      seeds.push(seed);
+    }
+    await writeGraph(graph);
+
+    const capped = await expandEdges({
+      workspaceDir,
+      seeds,
+      hops: 1,
+      maxTotalPulls: 40,
+    });
+    expect(capped.pulled.size).toBeLessThanOrEqual(40);
+
+    // Omitted → the 400 default; an invalid (negative) value also falls back.
+    const dflt = await expandEdges({ workspaceDir, seeds, hops: 1 });
+    expect(dflt.pulled.size).toBe(MAX_TOTAL_PULLS);
+    const invalid = await expandEdges({
+      workspaceDir,
+      seeds,
+      hops: 1,
+      maxTotalPulls: -5,
+    });
+    expect(invalid.pulled.size).toBe(MAX_TOTAL_PULLS);
+  });
+
   test("duplicate slugs across seeds don't waste the total budget", async () => {
     // Two seeds, both pointing at the same shared target plus one private each.
     // The shared slug is counted once, so the union is 3 — well under the cap,
@@ -492,6 +535,106 @@ describe("expandEdges — bounds", () => {
       { from: "people/bob", pulled: ["topics/bob-only", "topics/shared"] },
     ]);
   });
+
+  test("a seed reachable from another seed is excluded from pulled", async () => {
+    // alice -> bob, and bob is itself a seed. bob is a confident hit in its own
+    // right, not a neighbor, so it must never appear in the pulled union — even
+    // though alice's outgoing walk reaches it. bob's own private neighbor is
+    // still pulled.
+    await writeGraph({
+      alice: ["bob"],
+      bob: ["carol"],
+      carol: [],
+    });
+
+    const { pulled, expansions } = await expandEdges({
+      workspaceDir,
+      seeds: ["alice", "bob"],
+      hops: 1,
+    });
+
+    expect(pulled.has("bob")).toBe(false);
+    expect([...pulled].sort()).toEqual(["carol"]);
+    // alice reaches only bob, which is a seed, so alice contributes nothing.
+    expect(expansions).toEqual([
+      { from: "alice", pulled: [] },
+      { from: "bob", pulled: ["carol"] },
+    ]);
+  });
+
+  test("a seed two hops from another seed is still excluded from pulled", async () => {
+    // alice -> mid -> bob. With a 2-hop walk alice reaches bob, but bob is a
+    // seed and must not leak into pulled; the intermediate `mid` is a genuine
+    // neighbor and is kept.
+    await writeGraph({
+      alice: ["mid"],
+      mid: ["bob"],
+      bob: [],
+    });
+
+    const { pulled } = await expandEdges({
+      workspaceDir,
+      seeds: ["alice", "bob"],
+      hops: 2,
+    });
+
+    expect(pulled.has("bob")).toBe(false);
+    expect([...pulled].sort()).toEqual(["mid"]);
+  });
+
+  test("per-seed cap is spent on unique neighbors, not duplicates", async () => {
+    // alice pulls 16 shared `dup/*` neighbors. bob reaches those same 16 dups
+    // plus 32 unique `fresh/*` neighbors. bob's per-seed budget is
+    // MAX_PULLS_PER_SEED (32) because the union is nowhere near the total cap.
+    //
+    // The old slice took bob's lexicographically-first 32 reached slugs — the
+    // 16 already-pulled dups plus only the first 16 fresh — wasting 16 budget
+    // slots on duplicates and dropping the other 16 unique neighbors. Filtering
+    // already-pulled slugs before the slice spends all 32 slots on fresh
+    // neighbors, so every unique one is retained (recall north star).
+    const dupCount = 16;
+    const freshCount = MAX_PULLS_PER_SEED; // 32, so old code drops 16 unique.
+    const dups: string[] = [];
+    const fresh: string[] = [];
+    const graph: Record<string, string[]> = {};
+    for (let i = 0; i < dupCount; i++) {
+      const slug = topicSlug("dup", i);
+      dups.push(slug);
+      graph[slug] = [];
+    }
+    for (let i = 0; i < freshCount; i++) {
+      const slug = topicSlug("fresh", i);
+      fresh.push(slug);
+      graph[slug] = [];
+    }
+    // "dup/*" sorts before "fresh/*", so the old front-of-list slice is exactly
+    // the 16 dups + first 16 fresh.
+    graph["alice"] = [...dups];
+    graph["bob"] = [...dups, ...fresh];
+    await writeGraph(graph);
+
+    const { pulled, expansions } = await expandEdges({
+      workspaceDir,
+      seeds: ["alice", "bob"],
+      hops: 1,
+    });
+
+    // All 32 unique fresh neighbors survive — none dropped to a duplicate slot.
+    for (const slug of fresh) expect(pulled.has(slug)).toBe(true);
+    // A unique neighbor the old code would have dropped (past the first 16) is
+    // now retained.
+    expect(pulled.has(topicSlug("fresh", freshCount - 1))).toBe(true);
+    // Union is the 16 dups + 32 fresh, all distinct.
+    expect(pulled.size).toBe(dupCount + freshCount);
+
+    // bob's budget (32 fresh slots) is fully spent on unique neighbors; the
+    // dups it also reaches stay in its trace for faithful attribution but did
+    // not consume the budget.
+    const bobExpansion = expansions.find((e) => e.from === "bob")!;
+    expect(bobExpansion.pulled).toEqual([...dups, ...fresh].sort());
+    // Every trace slug is genuinely in the union.
+    for (const slug of bobExpansion.pulled) expect(pulled.has(slug)).toBe(true);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/memory/v3/__tests__/filter.test.ts

@@ -171,6 +171,36 @@ describe("filterDenseHits — judged keep/drop", () => {
     expect(userText).not.toContain("x");
   });
 
+  test("excludes the full sticky set from judgment, not just bypass", async () => {
+    const calls: ProviderCall[] = [];
+    // Dense surfaces a, b, plus sticky-but-not-bypass slug `s`. `s` must not be
+    // judged (the gate force-injects every sticky slug regardless), so the model
+    // only sees a, b. Model keeps a.
+    const provider = makeProvider(
+      filterToolResponse({ keep_slugs: ["a"] }),
+      calls,
+    );
+
+    const result = await filterDenseHits({
+      input: makeInput(),
+      dense: denseResult(["a", "b", "s"]),
+      // sticky is a strict superset of bypass here: `s` is sticky but not bypass.
+      sticky: new Set(["s"]),
+      bypass: new Set(),
+      provider,
+    });
+
+    // `s` is excluded from the judged set even though it is not in bypass.
+    expect(result.trace.judged).toEqual(["a", "b"]);
+    expect(result.trace.dropped).toEqual(["b"]);
+    // The sticky slug `s` was never shown to the model.
+    const slugLines = calls[0].messages[0].content
+      .map((b) => (b.type === "text" ? b.text : ""))
+      .join("\n")
+      .split("\n");
+    expect(slugLines).not.toContain("s");
+  });
+
   test("forces tool_choice on filter_dense_hits and surfaces judged candidates", async () => {
     const calls: ProviderCall[] = [];
     const provider = makeProvider(
@@ -306,6 +336,24 @@ describe("filterDenseHits — no LLM call", () => {
     expect([...result.kept].sort()).toEqual(["x", "y"]);
     expect(result.trace).toEqual({ judged: [], dropped: [] });
   });
+
+  test("dense fully covered by sticky (not bypass) → no call", async () => {
+    const provider = makeNeverCalledProvider();
+
+    // Every dense slug is sticky but none is bypass: there is nothing to judge,
+    // so no LLM round-trip happens. kept is the (empty) bypass set — the sticky
+    // slugs are force-selected downstream by the gate, not via the filter.
+    const result = await filterDenseHits({
+      input: makeInput(),
+      dense: denseResult(["x", "y"]),
+      sticky: new Set(["x", "y"]),
+      bypass: new Set(),
+      provider,
+    });
+
+    expect(result.kept).toEqual([]);
+    expect(result.trace).toEqual({ judged: [], dropped: [] });
+  });
 });
 
 describe("filterDenseHits — system prompt", () => {