@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -28,8 +28,15 @@ import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { migrateAddMemoryV3Selections } from "../../../../memory/migrations/268-add-memory-v3-selections.js";
+import { migrateAddMemoryV3EverInjected } from "../../../../memory/migrations/277-add-memory-v3-ever-injected.js";
 import * as schema from "../../../../memory/schema.js";
-import type { CandidateLane, SectionIndex, SelectionSource } from "../types.js";
+import type { HotSetEntry, HotSetOptions } from "../hot-set.js";
+import type { OrchestrateResult } from "../orchestrate.js";
+import {
+  MEMORY_V3_COMMIT_META_KEY,
+  type SectionIndex,
+  type SelectionSource,
+} from "../types.js";
 
 // `mock.module` is process-global and, in Bun, neither `mock.restore()` nor a
 // re-mock in `afterAll` reverts it for files that load LATER in the same
@@ -62,6 +69,8 @@ const realSkillStore = {
 const realCliCommandStore = {
   ...(await import("../../../../memory/v2/cli-command-store.js")),
 };
+const realCoreSet = { ...(await import("../core-set.js")) };
+const realHotSet = { ...(await import("../hot-set.js")) };
 
 let shadowMockActive = false;
 
@@ -69,6 +78,7 @@ let shadowMockActive = false;
 
 let liveEnabled = false;
 let shadowEnabled = false;
+let memoryEnabled = true;
 let messages: Array<{ role: string; content: string }> = [];
 
 // A synthetic skill capability slug the page index carries. Its rendered
@@ -77,30 +87,36 @@ let messages: Array<{ role: string; content: string }> = [];
 const CAPABILITY_SLUG = "skills/example";
 const CAPABILITY_CONTENT = "use the kumquat skill to do the thing";
 
-// The orchestrate result the spy returns. `laneBySlug` records the lane that
-// surfaced each pooled slug: page-1 → "needle", page-2 → "dense", page-3 →
-// "edge"; `attributeSelections` reads it directly. `carried` is a carry-forward
-// slug not re-selected this turn. `sectionBySlug` carries the matched section
-// for the slugs that had one (page-1/page-2) — consumed by the live injector's
-// progressive disclosure, independent of source attribution.
-const orchestrateSpy = mock(async () => ({
-  currentSelections: [
-    { slug: "page-1", pinned: true },
-    { slug: "page-2", pinned: false },
-    { slug: "page-3", pinned: false },
-  ],
-  workingSetUnion: new Set<string>(["page-1", "page-2", "page-3"]),
-  finalInjection: ["page-1", "page-2", "page-3", "carried"],
-  sectionBySlug: new Map([
-    ["page-1", { article: "page-1", title: "", text: "x", ordinal: 0 }],
-    ["page-2", { article: "page-2", title: "", text: "y", ordinal: 0 }],
-  ]),
-  laneBySlug: new Map<string, CandidateLane>([
-    ["page-1", "needle"],
-    ["page-2", "dense"],
-    ["page-3", "edge"],
-  ]),
-}));
+// The orchestrate result the spy returns. `lanes` records where each pooled
+// slug lived: page-core in the core lane, page-hot in the hot lane, and the
+// finder entries page-1 → "needle", page-2 → "dense", page-3 → "edge";
+// `attributeSelections` reads it directly. `matchedSections` carries the
+// matched section for the slugs that had one (page-1/page-2) — consumed by the
+// live injector's progressive disclosure, independent of source attribution.
+const orchestrateSpy = mock(
+  async (): Promise<OrchestrateResult> => ({
+    selections: [
+      { slug: "page-core", pinned: false },
+      { slug: "page-hot", pinned: false },
+      { slug: "page-1", pinned: true },
+      { slug: "page-2", pinned: false },
+      { slug: "page-3", pinned: false },
+    ],
+    matchedSections: new Map([
+      ["page-1", { article: "page-1", title: "", text: "x", ordinal: 0 }],
+      ["page-2", { article: "page-2", title: "", text: "y", ordinal: 0 }],
+    ]),
+    lanes: {
+      core: ["page-core"],
+      hot: ["page-hot"],
+      finder: [
+        { slug: "page-1", descriptor: "", lane: "needle" },
+        { slug: "page-2", descriptor: "", lane: "dense" },
+        { slug: "page-3", descriptor: "", lane: "edge" },
+      ],
+    },
+  }),
+);
 
 let sectionBuilds = 0;
 let needleBuilds = 0;
@@ -108,6 +124,14 @@ let edgeBuilds = 0;
 let ensureCollectionCalls = 0;
 let ensureCollectionThrows = false;
 
+// Stable-prefix lane inputs, driven per test: what the curated core file
+// yields and what the frecency hot set computes. `hotSetOpts` captures the
+// options `initLanes` passed so the test can assert the core exclusion and the
+// config plumbing.
+let coreSetSlugs: string[] = [];
+let hotSetResult: HotSetEntry[] = [];
+let hotSetOpts: HotSetOptions | null = null;
+
 // The `pageBody` resolver `initLanes` passes to `buildSectionIndex` (its second
 // arg), captured by the stub below so a test can drive it directly: a capability
 // slug must resolve to its rendered capability content, an on-disk slug to its
@@ -122,12 +146,21 @@ function makeDb() {
   testSqlite.exec("PRAGMA journal_mode=WAL");
   const db = drizzle(testSqlite, { schema });
   migrateAddMemoryV3Selections(db);
+  // The live injector's net-new dedup reads/writes the everInjected store.
+  migrateAddMemoryV3EverInjected(db);
   return db;
 }
 
+// The fake index lists the LIVE pages — `initLanes` filters the core and hot
+// lanes against `byArticle`, so membership here is what "the page exists"
+// means to the stable-prefix lanes.
 const FAKE_SECTION_INDEX: SectionIndex = {
   sections: [],
-  byArticle: new Map(),
+  byArticle: new Map([
+    ["page-1", []],
+    ["page-2", []],
+    [CAPABILITY_SLUG, []],
+  ]),
 };
 
 // ─── module mocks (installed before the plugin import) ──────────────────────
@@ -144,8 +177,10 @@ mock.module("../../../../config/assistant-feature-flags.js", () => ({
 mock.module("../../../../config/loader.js", () => ({
   getConfig: () => ({
     memory: {
+      enabled: memoryEnabled,
       v3: {
-        workingSet: { maxPages: 150, evictWindow: 5 },
+        hotSet: { k: 40, halfLifeDays: 14 },
+        spotlight: { n: 6, windowTurns: 2 },
         needleK: 100,
         denseK: 100,
         edge: { hubDegree: 30, seedCount: 18, perSeed: 6, cap: 45 },
@@ -155,6 +190,26 @@ mock.module("../../../../config/loader.js", () => ({
   }),
 }));
 
+// Stable-prefix lanes: the curated core loader and the frecency hot set are
+// stubbed to controllable values; `initLanes` owns the existence filtering and
+// the core exclusion these tests assert.
+mock.module("../core-set.js", () => ({
+  ...realCoreSet,
+  loadCoreSet: (...args: Parameters<typeof realCoreSet.loadCoreSet>) =>
+    shadowMockActive ? coreSetSlugs : realCoreSet.loadCoreSet(...args),
+}));
+
+mock.module("../hot-set.js", () => ({
+  ...realHotSet,
+  computeHotSet: (
+    ...args: Parameters<typeof realHotSet.computeHotSet>
+  ): HotSetEntry[] => {
+    if (!shadowMockActive) return realHotSet.computeHotSet(...args);
+    hotSetOpts = args[1];
+    return hotSetResult;
+  },
+}));
+
 // Spread the real module so every export the live path transitively imports
 // stays present; only `getMessages` is overridden.
 mock.module("../../../../memory/conversation-crud.js", () => ({
@@ -305,9 +360,14 @@ mock.module("../orchestrate.js", () => ({
 }));
 
 // Import AFTER mocks so the plugin binds to them.
-const { runShadowObservation, resetShadowLanesForTests, invalidateLanes } =
-  await import("../shadow-plugin.js");
-const { memoryV3Injector } = await import("../injector.js");
+const {
+  runShadowObservation,
+  resetShadowLanesForTests,
+  invalidateLanes,
+  attributeSelections,
+} = await import("../shadow-plugin.js");
+const { memoryV3Injector, resetMemoryV3InjectorStateForTests } =
+  await import("../injector.js");
 
 afterAll(() => {
   shadowMockActive = false;
@@ -325,6 +385,7 @@ beforeEach(() => {
   shadowMockActive = true;
   liveEnabled = false;
   shadowEnabled = false;
+  memoryEnabled = true;
   messages = [
     {
       role: "user",
@@ -338,21 +399,45 @@ beforeEach(() => {
   ensureCollectionCalls = 0;
   ensureCollectionThrows = false;
   capturedPageBody = null;
+  coreSetSlugs = [];
+  hotSetResult = [];
+  hotSetOpts = null;
   testDb = makeDb();
   resetShadowLanesForTests();
+  // The injector memoizes one orchestration per (conversation, turn); clear it
+  // so tests reusing the same ids observe fresh orchestrations.
+  resetMemoryV3InjectorStateForTests();
 });
 
-/** Invoke the memory-v3 injector's `produce()` for a turn. */
-function produce(conversationId: string, turnIndex: number) {
-  return memoryV3Injector.produce({
+/** Invoke the memory-v3 injector's `produce()` for a turn and, when a block
+ *  is produced, invoke its attachment-commit callback — simulating runtime
+ *  assembly's user-tail commit point, where the everInjected-store write now
+ *  happens. */
+async function produce(conversationId: string, turnIndex: number) {
+  const block = await memoryV3Injector.produce({
     requestId: "r1",
     conversationId,
     turnIndex,
     trust: {} as never,
   });
+  const commit = block?.meta?.[MEMORY_V3_COMMIT_META_KEY];
+  if (typeof commit === "function") (commit as () => void)();
+  return block;
 }
 
 describe("memory-v3 shadow plugin", () => {
+  test("global memory disabled → observation is skipped even when v3 flags are on", async () => {
+    shadowEnabled = true;
+    liveEnabled = true;
+    memoryEnabled = false;
+
+    await runShadowObservation("conv-1", 0);
+
+    expect(orchestrateSpy).not.toHaveBeenCalled();
+    expect(sectionBuilds).toBe(0);
+    expect(readRows()).toHaveLength(0);
+  });
+
   test("shadow flag OFF → orchestrate not called, no DB writes", async () => {
     shadowEnabled = false;
     await runShadowObservation("conv-1", 0);
@@ -367,20 +452,38 @@ describe("memory-v3 shadow plugin", () => {
 
     expect(orchestrateSpy).toHaveBeenCalledTimes(1);
     const rows = readRows();
-    // Each selection is attributed to the lane that surfaced it
-    // (`result.laneBySlug`), not re-derived from section presence — so the
-    // dense-only page-2 logs "dense", not "needle".
+    // Each selection is attributed to the lane that pooled it
+    // (`result.lanes`), not re-derived from section presence — so the
+    // dense-only page-2 logs "dense", not "needle". The result is
+    // current-turn selections only.
     expect(rows).toEqual([
-      { slug: "carried", source: "carry-forward", pinned: 0 },
       // page-1 was surfaced by the needle lane → "needle", pinned.
       { slug: "page-1", source: "needle", pinned: 1 },
       // page-2 was surfaced by the dense lane → "dense".
       { slug: "page-2", source: "dense", pinned: 0 },
       // page-3 was surfaced by the edge lane → "edge".
       { slug: "page-3", source: "edge", pinned: 0 },
+      // page-core / page-hot sit in the stable prefix → "core" / "hot".
+      { slug: "page-core", source: "core", pinned: 0 },
+      { slug: "page-hot", source: "hot", pinned: 0 },
     ]);
   });
 
+  test("a selection of a core page a finder also hit attributes to core (pool position wins)", () => {
+    const rows = attributeSelections({
+      selections: [{ slug: "page-core", pinned: false }],
+      matchedSections: new Map(),
+      lanes: {
+        core: ["page-core"],
+        hot: [],
+        // The needle also hit the core page this turn — the row still logs
+        // "core" because that is where the candidate lived in the pool.
+        finder: [{ slug: "page-core", descriptor: "", lane: "needle" }],
+      },
+    });
+    expect(rows).toEqual([{ slug: "page-core", source: "core", pinned: 0 }]);
+  });
+
   test("the turn passed to orchestrate carries the latest user message", async () => {
     shadowEnabled = true;
     await runShadowObservation("conv-1", 0);
@@ -405,12 +508,38 @@ describe("memory-v3 shadow plugin", () => {
       sectionIndex?: unknown;
       needle?: unknown;
       edgeGraph?: unknown;
-      workingSet?: unknown;
+      coreSlugs?: unknown;
+      hotSlugs?: unknown;
     };
     expect(deps.sectionIndex).toBeDefined();
     expect(deps.needle).toBeDefined();
     expect(deps.edgeGraph).toBeDefined();
-    expect(deps.workingSet).toBeDefined();
+    expect(deps.coreSlugs).toEqual([]);
+    expect(deps.hotSlugs).toEqual([]);
+  });
+
+  test("initLanes filters core to existing pages and excludes core from the hot set", async () => {
+    shadowEnabled = true;
+    // The core file lists a live page and a dangling slug; the hot set returns
+    // a live page and a deleted one (selection rows can outlive their pages).
+    coreSetSlugs = ["page-1", "missing-page"];
+    hotSetResult = [
+      { slug: "page-2", score: 2 },
+      { slug: "gone-page", score: 1 },
+    ];
+    await runShadowObservation("conv-1", 0);
+
+    const deps = (
+      orchestrateSpy.mock.calls as unknown as unknown[][]
+    )[0]![1] as { coreSlugs: string[]; hotSlugs: string[] };
+    // Dangling core entries and deleted hot pages never reach the pool.
+    expect(deps.coreSlugs).toEqual(["page-1"]);
+    expect(deps.hotSlugs).toEqual(["page-2"]);
+    // The hot set was computed with the (filtered) core excluded and the
+    // configured k / half-life (14 days, in ms).
+    expect(hotSetOpts?.excludeSlugs).toEqual(new Set(["page-1"]));
+    expect(hotSetOpts?.k).toBe(40);
+    expect(hotSetOpts?.halfLifeMs).toBe(14 * 24 * 60 * 60 * 1000);
   });
 
   test("both flags OFF → produce returns null, no orchestrate, no writes", async () => {
@@ -431,7 +560,7 @@ describe("memory-v3 shadow plugin", () => {
     expect(readRows().length).toBeGreaterThan(0);
   });
 
-  test("live on → produce returns the rendered <memory> block and logs", async () => {
+  test("live on → produce returns the net-new CARD block and logs", async () => {
     liveEnabled = true;
     shadowEnabled = false;
     const block = await produce("conv-1", 0);
@@ -439,25 +568,37 @@ describe("memory-v3 shadow plugin", () => {
     expect(block!.placement).toBe("after-memory-prefix");
     expect(block!.text.startsWith("<memory>\n")).toBe(true);
     expect(block!.text.endsWith("\n</memory>")).toBe(true);
-    // Progressive disclosure: a slug with a matched section renders that
-    // section's text (page-1 → "x"), NOT the full page body.
-    expect(block!.text).toContain("# memory/concepts/page-1.md\nx");
-    expect(block!.text).not.toContain("body for page-1");
-    // A slug with no matched section (carry-forward) falls back to the full body.
-    expect(block!.text).toContain("body for carried");
+    // Turn 1: every selection is net-new and renders as a compact card —
+    // the page header plus the page's head section (the fixture body has no
+    // `## ` headings, so the whole body is the head and no TOC line renders).
+    for (const slug of ["page-core", "page-hot", "page-1", "page-2"]) {
+      expect(block!.text).toContain(
+        `# memory/concepts/${slug}.md\nbody for ${slug}`,
+      );
+    }
     // Selections are still logged in live mode.
     expect(readRows().length).toBeGreaterThan(0);
   });
 
+  test("live on → a later turn re-selecting the same pages renders an EMPTY block (net-new dedup)", async () => {
+    liveEnabled = true;
+    shadowEnabled = false;
+    const first = await produce("conv-1", 0);
+    expect(first!.text.length).toBeGreaterThan(0);
+    // Same orchestrate fixture on the next turn → zero net-new cards. The
+    // block is still produced (its presence keys v2 suppression downstream).
+    const repeat = await produce("conv-1", 1);
+    expect(repeat).not.toBeNull();
+    expect(repeat!.text).toBe("");
+  });
+
   test("live on but empty selection → produce returns null", async () => {
     liveEnabled = true;
     shadowEnabled = false;
     orchestrateSpy.mockImplementationOnce(async () => ({
-      currentSelections: [],
-      workingSetUnion: new Set<string>(),
-      finalInjection: [],
-      sectionBySlug: new Map(),
-      laneBySlug: new Map(),
+      selections: [],
+      matchedSections: new Map(),
+      lanes: { core: [], hot: [], finder: [] },
     }));
     const block = await produce("conv-1", 0);
     expect(block).toBeNull();

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

@@ -1,22 +1,10 @@
 import { expect, test } from "bun:test";
 
-import type {
-  MemoryRoutingTurn,
-  SelectionSource,
-  Slug,
-  WorkingSetEntry,
-} from "../types.js";
+import type { MemoryRoutingTurn, SelectionSource, Slug } from "../types.js";
 
 test("v3 core types instantiate", () => {
   const slug: Slug = "page-123";
 
-  const entry: WorkingSetEntry = {
-    slug,
-    selectedAtTurn: 1,
-    pinned: false,
-    lastSeenTurn: 2,
-  };
-
   const turnContext: MemoryRoutingTurn = {
     conversationId: "conv-xyz",
     turnNumber: 3,
@@ -24,9 +12,9 @@ test("v3 core types instantiate", () => {
     recentContext: "prior turns",
   };
 
-  const source: SelectionSource = "carry-forward";
+  const source: SelectionSource = "needle";
 
-  expect(entry.slug).toBe(slug);
+  expect(slug).toBe("page-123");
   expect(turnContext.turnNumber).toBe(3);
-  expect(source).toBe("carry-forward");
+  expect(source).toBe("needle");
 });

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

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+
+import { cardBytes, renderCard } from "./card.js";
+
+describe("renderCard", () => {
+  test("standard article renders head section + section TOC", () => {
+    const raw = [
+      "---",
+      "summary: A page about topic A.",
+      "---",
+      "# Topic A",
+      "",
+      "Lead paragraph one about topic A.",
+      "",
+      "Lead paragraph two with more detail.",
+      "",
+      "## History",
+      "history body",
+      "",
+      "## Design",
+      "design body",
+      "",
+      "## Open Questions",
+      "open questions body",
+    ].join("\n");
+
+    expect(renderCard("page-a", raw)).toBe(
+      [
+        "# memory/concepts/page-a.md",
+        "# Topic A",
+        "",
+        "Lead paragraph one about topic A.",
+        "",
+        "Lead paragraph two with more detail.",
+        "",
+        "[sections: §History · §Design · §Open Questions]",
+      ].join("\n"),
+    );
+  });
+
+  test("kind: index page renders its links: map instead of section names", () => {
+    const longNote = "x".repeat(100);
+    const raw = [
+      "---",
+      "kind: index",
+      "links:",
+      "  - page-a — short note about page a",
+      `  - page-b — ${longNote}`,
+      "  - page-c",
+      "---",
+      "# Index of Topics",
+      "",
+      "Lead line.",
+      "",
+      "## Pages",
+      "generic section body",
+    ].join("\n");
+
+    const card = renderCard("topics-index", raw);
+    expect(card).toBe(
+      [
+        "# memory/concepts/topics-index.md",
+        "# Index of Topics",
+        "",
+        "Lead line.",
+        "",
+        `[linked: page-a — short note about page a · page-b — ${"x".repeat(80)}… · page-c]`,
+      ].join("\n"),
+    );
+    // Section names never appear on an index card.
+    expect(card).not.toContain("§Pages");
+  });
+
+  test("kind: index without usable links falls back to section names", () => {
+    const raw = [
+      "---",
+      "kind: index",
+      "---",
+      "# Bare Index",
+      "",
+      "## Pages",
+      "body",
+    ].join("\n");
+
+    expect(renderCard("bare-index", raw)).toBe(
+      [
+        "# memory/concepts/bare-index.md",
+        "# Bare Index",
+        "",
+        "[sections: §Pages]",
+      ].join("\n"),
+    );
+  });
+
+  test("sectionless page omits the TOC line", () => {
+    const raw = [
+      "---",
+      "summary: s",
+      "---",
+      "# Sectionless",
+      "",
+      "Just a lead.",
+    ].join("\n");
+
+    expect(renderCard("page-b", raw)).toBe(
+      ["# memory/concepts/page-b.md", "# Sectionless", "", "Just a lead."].join(
+        "\n",
+      ),
+    );
+  });
+
+  test("frontmatter-less text renders head + TOC", () => {
+    const raw = [
+      "# No Frontmatter",
+      "",
+      "Lead.",
+      "",
+      "## Only Section",
+      "body",
+    ].join("\n");
+
+    expect(renderCard("page-c", raw)).toBe(
+      [
+        "# memory/concepts/page-c.md",
+        "# No Frontmatter",
+        "",
+        "Lead.",
+        "",
+        "[sections: §Only Section]",
+      ].join("\n"),
+    );
+  });
+
+  test("body starting at a ## heading renders header + TOC with no head block", () => {
+    const raw = ["## First", "body", "", "## Second", "body"].join("\n");
+
+    expect(renderCard("page-d", raw)).toBe(
+      ["# memory/concepts/page-d.md", "", "[sections: §First · §Second]"].join(
+        "\n",
+      ),
+    );
+  });
+
+  test("long lead injects whole (no length cap)", () => {
+    const longLead = `Long lead. ${"y".repeat(10_000)}`;
+    const raw = ["# Long", "", longLead, "", "## Section", "body"].join("\n");
+
+    expect(renderCard("page-e", raw)).toContain(longLead);
+  });
+
+  test("deterministic for the same input", () => {
+    const raw = ["# T", "", "Lead.", "", "## S", "b"].join("\n");
+    expect(renderCard("page-f", raw)).toBe(renderCard("page-f", raw));
+  });
+});
+
+describe("cardBytes", () => {
+  test("counts UTF-8 bytes, not characters", () => {
+    expect(cardBytes("abc")).toBe(3);
+    expect(cardBytes("§")).toBe(2); // U+00A7 is 2 bytes in UTF-8
+  });
+
+  test("accounts for a rendered card's full byte footprint", () => {
+    const card = renderCard(
+      "page-a",
+      ["# T", "", "Lead.", "", "## S", "b"].join("\n"),
+    );
+    // The card contains exactly one multibyte char (the TOC's "§"), so its
+    // byte footprint is one over its character length.
+    expect(card.match(/§/g)).toHaveLength(1);
+    expect(cardBytes(card)).toBe(card.length + 1);
+  });
+});