@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/api/responses/memory-v3-selection-log.ts

@@ -1,7 +1,7 @@
 /**
  * Wire contract for the memory v3 selection set surfaced in the inspector's
  * Memory tab. Mirrors the return value of `getMemoryV3SelectionForInspector`
- * in `assistant/src/memory/v3/selection-log-store.ts`.
+ * in `assistant/src/plugins/defaults/memory-v3-shadow/selection-log-store.ts`.
  *
  * Canonical wire-contract source. Assistant code imports the types directly
  * from this file via relative paths; external consumers (web client, gateway,
@@ -12,19 +12,27 @@
  * `live` / `shadow` reflect the CURRENT `memory-v3-live` / `memory-v3-shadow`
  * flag state, not the per-turn history (the selection rows don't record which
  * mode was active when they were written). When `live` is true the rendered
- * `injectedText` block was actually injected into the turn; when only `shadow`
- * is true it is the block that WOULD have been injected. For stable-flag
- * shadow validation these coincide; recording per-turn `injected` is a
- * documented follow-up.
+ * `injectedText` reflects the live selection; when only `shadow` is true it is
+ * the block that WOULD have been injected.
+ *
+ * `injectedText` is APPROXIMATE, not a verbatim record. It is re-rendered from
+ * the persisted selection rows, which store slug/source/pinned but NOT the
+ * matched-section identity. A page that live injection sent as a single matched
+ * section is re-rendered here as its FULL page (the section ordinal isn't
+ * persisted), so the text can differ from what was actually sent to the model.
+ * The selected slug set is exact — only the rendered text is full-page
+ * approximate. Persisting the per-turn injected section is a documented
+ * follow-up.
  */
 
 import { z } from "zod";
 
 /**
  * One selected page in the v3 set. `source` is the lane that surfaced it —
- * the daemon emits `l1+l2`, `core+l2`, `needle`, or `carry-forward` — but the
- * schema stays a permissive string so a new lane label doesn't break parsing
- * on the FE. `pinned` marks a slug carried forward across turns.
+ * the daemon emits `needle`, `dense`, `edge`, or `carry-forward` — but the
+ * schema stays a permissive string so a new lane label (or a historical
+ * pre-lane row) doesn't break parsing on the FE. `pinned` marks a slug carried
+ * forward across turns.
  */
 export const MemoryV3SelectionRowSchema = z.object({
   slug: z.string(),
@@ -36,8 +44,9 @@ export type MemoryV3SelectionRow = z.infer<typeof MemoryV3SelectionRowSchema>;
 
 /**
  * Memory v3 selection log shape. `injectedText` is the rendered
- * `<memory>…</memory>` block for the selection (actual when `live`, would-be
- * when `shadow`-only).
+ * `<memory>…</memory>` block for the selection — APPROXIMATE: re-rendered from
+ * the persisted rows, with full pages where live injection used a matched
+ * section (the section identity isn't persisted). See the file header.
  */
 export const MemoryV3SelectionLogSchema = z.object({
   turn: z.number(),

package/src/cli/commands/__tests__/memory-v3.test.ts

@@ -1,245 +1,226 @@
 /**
- * Tests for the `memory v3` CLI command group's daemon-side handlers.
+ * Tests for the `assistant memory v3` CLI subgroup (section-lane model).
  *
- * The CLI subcommands are thin IPC shells over the handlers in
- * `runtime/routes/memory-v3-routes.ts`; the logic worth testing lives there.
- * We exercise the handlers directly against a temp workspace + data dir
- * injected via their `deps` parameter. Generic taxonomy only
- * (domain-a/topic-x, etc.).
- *
- * Source-of-truth note: `health` and `set-core` build the leaf tree from each
- * concept page's `leaves:` frontmatter (via the page index) and union it over
- * `assignments.json`, matching the consolidation-injected health block. The
- * fixture below writes concept pages with `leaves:` frontmatter as the
- * authoritative membership and keeps a *stale* `assignments.json` to prove the
- * handlers read the frontmatter, not the stale assignments. The seeded
- * skill/CLI-command catalogs are mocked empty so `allSlugs` (derived from the
- * page index) is deterministic.
+ * Validates:
+ *   - Subcommand registration (rebuild-index, backfill-sections) under
+ *     `memory v3`.
+ *   - Each subcommand maps to the right `cliIpcCall` method.
+ *   - `backfill-sections` passes a long IPC timeout (the one-time full-corpus
+ *     embed easily outlasts the default 60s), while `rebuild-index` does not.
+ *   - IPC error paths return a non-zero exit code without throwing.
  */
 
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-
-import * as cliCommandStore from "../../../memory/v2/cli-command-store.js";
-import { invalidatePageIndex } from "../../../memory/v2/page-index.js";
-import * as skillStore from "../../../memory/v2/skill-store.js";
-import {
-  handleMemoryV3Health,
-  handleMemoryV3Reconcile,
-  handleMemoryV3SetCore,
-  UnknownLeafError,
-} from "../../../runtime/routes/memory-v3-routes.js";
-
-// ---------------------------------------------------------------------------
-// Temp data-dir fixture
-// ---------------------------------------------------------------------------
-
-let workspaceDir: string;
-let dataDir: string;
-
-/** Write a leaf markdown file with the given frontmatter under leaves/. */
-async function writeLeaf(
-  relPath: string,
-  frontmatter: { path: string; in_core: boolean; id?: string },
-  body = "description",
-): Promise<void> {
-  const file = join(dataDir, "leaves", `${relPath}.md`);
-  await mkdir(join(file, ".."), { recursive: true });
-  const fm = [
-    "---",
-    `path: ${frontmatter.path}`,
-    `in_core: ${frontmatter.in_core}`,
-    ...(frontmatter.id ? [`id: ${frontmatter.id}`] : []),
-    "---",
-    body,
-    "",
-  ].join("\n");
-  await writeFile(file, fm);
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { Command } from "commander";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+/** The last `cliIpcCall` invocation captured for assertions. */
+let lastIpcCall: {
+  method: string;
+
+  params?: any;
+  options?: { timeoutMs?: number; signal?: AbortSignal };
+} | null = null;
+
+/** The result that cliIpcCall will return. */
+let mockIpcResult: {
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+} = { ok: true, result: { articles: 3, sections: 12, failures: 0 } };
+
+/** Captured log output for assertion. */
+let logOutput: string[] = [];
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+mock.module("../../../ipc/cli-client.js", () => ({
+  cliIpcCall: async (
+    method: string,
+    params?: any,
+    options?: { timeoutMs?: number; signal?: AbortSignal },
+  ) => {
+    lastIpcCall = { method, params, options };
+    return mockIpcResult;
+  },
+}));
+
+const capture = (...args: unknown[]) => {
+  logOutput.push(args.map(String).join(" "));
+};
+const fakeLogger = {
+  info: capture,
+  warn: capture,
+  error: capture,
+  debug: () => {},
+};
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => fakeLogger,
+  getCliLogger: () => fakeLogger,
+}));
+
+// ---------------------------------------------------------------------------
+// Import modules under test (after mocks)
+// ---------------------------------------------------------------------------
+
+const { registerMemoryV3Command } = await import("../memory-v3.js");
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeErr: () => {},
+    writeOut: () => {},
+  });
+  registerMemoryV3Command(program);
+  return program;
 }
 
-/** Write a concept page with `leaves:` frontmatter under memory/concepts/. */
-async function writePage(slug: string, leaves: string[]): Promise<void> {
-  const file = join(workspaceDir, "memory", "concepts", `${slug}.md`);
-  await mkdir(join(file, ".."), { recursive: true });
-  const fm = [
-    "---",
-    `summary: ${slug} summary`,
-    "leaves:",
-    ...leaves.map((l) => `  - ${l}`),
-    "---",
-    `${slug} body`,
-    "",
-  ].join("\n");
-  await writeFile(file, fm);
+async function runCommand(
+  args: string[],
+): Promise<{ stdout: string; exitCode: number }> {
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+  const stdoutChunks: string[] = [];
+
+  process.stdout.write = ((chunk: unknown) => {
+    stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = (() => true) as typeof process.stderr.write;
+
+  process.exitCode = 0;
+
+  try {
+    const program = buildProgram();
+    await program.parseAsync(["node", "assistant", ...args]);
+  } catch {
+    if (process.exitCode === 0) process.exitCode = 1;
+  } finally {
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  const exitCode = process.exitCode ?? 0;
+  process.exitCode = 0;
+
+  return { exitCode, stdout: stdoutChunks.join("") };
 }
 
-beforeEach(async () => {
-  workspaceDir = await mkdtemp(join(tmpdir(), "mem-v3-cli-ws-"));
-  dataDir = join(workspaceDir, "memory", "v3", "data");
-  await mkdir(dataDir, { recursive: true });
-
-  // Keep the page index deterministic regardless of the on-disk seeded
-  // catalogs, and clear any module-cached index from a prior test.
-  spyOn(skillStore, "listSkillEntries").mockReturnValue([]);
-  spyOn(cliCommandStore, "listCliCommandEntries").mockReturnValue([]);
-  invalidatePageIndex();
-
-  // A small generic tree: two leaves under domain-a, one under domain-b.
-  await writeLeaf("domain-a/topic-x", {
-    path: "domain-a/topic-x",
-    in_core: true,
-    id: "leaf-x",
-  });
-  await writeLeaf("domain-a/topic-y", {
-    path: "domain-a/topic-y",
-    in_core: false,
-    id: "leaf-y",
-  });
-  await writeLeaf("domain-b/topic-z", {
-    path: "domain-b/topic-z",
-    in_core: false,
-    id: "leaf-z",
-  });
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
 
-  // Authoritative membership lives in each page's `leaves:` frontmatter.
-  await writePage("page-1", ["domain-a/topic-x"]);
-  await writePage("page-2", ["domain-a/topic-x", "domain-a/topic-y"]);
-  await writePage("page-3", ["domain-b/topic-z"]);
-
-  // STALE assignments.json: deliberately divergent from the frontmatter above.
-  // It re-maps the SAME slugs that already carry `leaves:` frontmatter to the
-  // WRONG leaves. `loadLeafTree`'s per-page precedence only lets frontmatter win
-  // when it is non-empty, so for these slugs the frontmatter wins and
-  // assignments.json contributes no membership — proving the handlers read the
-  // page index, not these stale assignments (the regression Defect A guards
-  // against). We deliberately avoid a slug that exists ONLY in assignments.json:
-  // such a slug has no frontmatter, falls back to its assignments entry, and
-  // would inflate the cost preview below with phantom membership.
-  await writeFile(
-    join(dataDir, "assignments.json"),
-    JSON.stringify({
-      "page-1": ["domain-a/bogus-leaf"],
-      "page-2": ["domain-b/topic-z"],
-    }),
-  );
-  await writeFile(
-    join(dataDir, "core.json"),
-    JSON.stringify({ alwaysOn: ["domain-a/topic-x"] }),
-  );
+beforeEach(() => {
+  lastIpcCall = null;
+  mockIpcResult = {
+    ok: true,
+    result: { articles: 3, sections: 12, failures: 0 },
+  };
+  logOutput = [];
+  process.exitCode = 0;
 });
 
-afterEach(async () => {
-  invalidatePageIndex();
-  await rm(workspaceDir, { recursive: true, force: true });
+// ---------------------------------------------------------------------------
+// Subcommand registration
+// ---------------------------------------------------------------------------
+
+describe("subcommand registration", () => {
+  test("registers v3 under memory with the expected subcommands", () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === "memory");
+    expect(memory).toBeDefined();
+    const v3 = memory!.commands.find((c) => c.name() === "v3");
+    expect(v3).toBeDefined();
+    const subcommandNames = v3!.commands.map((c) => c.name()).sort();
+    expect(subcommandNames).toEqual(["backfill-sections", "rebuild-index"]);
+  });
 });
 
 // ---------------------------------------------------------------------------
-// set-core
+// rebuild-index
 // ---------------------------------------------------------------------------
 
-describe("handleMemoryV3SetCore", () => {
-  test("rejects an unknown leaf and does not write", async () => {
-    const call = handleMemoryV3SetCore(
-      { add: ["domain-a/does-not-exist"], write: true },
-      { dataDir, workspaceDir },
-    );
-    await expect(call).rejects.toThrow(/domain-a\/does-not-exist/);
-    await expect(
-      handleMemoryV3SetCore(
-        { add: ["domain-a/does-not-exist"], write: true },
-        { dataDir, workspaceDir },
-      ),
-    ).rejects.toBeInstanceOf(UnknownLeafError);
+describe("memory v3 rebuild-index", () => {
+  test("sends memory_v3_rebuild_index with the default (no) timeout", async () => {
+    mockIpcResult = { ok: true, result: { invalidated: true } };
 
-    // core.json must be untouched (still just the original entry).
-    const core = JSON.parse(await readFile(join(dataDir, "core.json"), "utf8"));
-    expect(core.alwaysOn).toEqual(["domain-a/topic-x"]);
-  });
+    const { exitCode } = await runCommand(["memory", "v3", "rebuild-index"]);
 
-  test("previews the always-on page count from frontmatter membership", async () => {
-    // Adding topic-y to core: core = {topic-x, topic-y}. Membership comes from
-    // page `leaves:` frontmatter — topic-x → {page-1, page-2}, topic-y →
-    // {page-2} ⇒ unique always-on slugs {page-1, page-2} = 2. If the handler
-    // read the stale assignments.json instead (page-1 → bogus-leaf, page-2 →
-    // topic-z), topic-x/topic-y would have no members and this would be 0.
-    const result = await handleMemoryV3SetCore(
-      { add: ["domain-a/topic-y"] },
-      { dataDir, workspaceDir },
-    );
-    expect(result.written).toBe(false);
-    expect(result.nextCore).toEqual(["domain-a/topic-x", "domain-a/topic-y"]);
-    expect(result.alwaysOnPageCount).toBe(2);
-
-    // No write happened — core.json still holds only the original entry.
-    const core = JSON.parse(await readFile(join(dataDir, "core.json"), "utf8"));
-    expect(core.alwaysOn).toEqual(["domain-a/topic-x"]);
+    expect(exitCode).toBe(0);
+    expect(lastIpcCall!.method).toBe("memory_v3_rebuild_index");
+    expect(lastIpcCall!.params!.body).toEqual({});
+    // rebuild-index is fast; it relies on the default call timeout.
+    expect(lastIpcCall!.options).toBeUndefined();
   });
 
-  test("writes core.json on --yes (write: true)", async () => {
-    const result = await handleMemoryV3SetCore(
-      { add: ["domain-b/topic-z"], write: true },
-      { dataDir, workspaceDir },
-    );
-    expect(result.written).toBe(true);
-    expect(result.nextCore).toEqual(["domain-a/topic-x", "domain-b/topic-z"]);
+  test("exits with code 1 on IPC failure", async () => {
+    mockIpcResult = { ok: false, error: "Daemon down" };
 
-    const core = JSON.parse(await readFile(join(dataDir, "core.json"), "utf8"));
-    expect(core.alwaysOn).toEqual(["domain-a/topic-x", "domain-b/topic-z"]);
-  });
+    const { exitCode } = await runCommand(["memory", "v3", "rebuild-index"]);
 
-  test("remove is idempotent for an absent entry", async () => {
-    const result = await handleMemoryV3SetCore(
-      { remove: ["domain-a/topic-y"], write: true },
-      { dataDir, workspaceDir },
-    );
-    // topic-y was never in core; result is the original core unchanged.
-    expect(result.nextCore).toEqual(["domain-a/topic-x"]);
+    expect(exitCode).toBe(1);
   });
 });
 
 // ---------------------------------------------------------------------------
-// health
+// backfill-sections
 // ---------------------------------------------------------------------------
 
-describe("handleMemoryV3Health", () => {
-  test("computes the slug universe from page frontmatter, not assignments.json", async () => {
-    const result = await handleMemoryV3Health({ dataDir, workspaceDir });
-    // domain-b/topic-z has a single member ⇒ a tiny leaf, so the report is
-    // non-empty and renders the memory-v3 health header.
-    expect(result.rendered).toContain("memory-v3 health:");
-    expect(result.counts.tinyLeaves).toBeGreaterThanOrEqual(1);
-    // Every page leaf ref (from frontmatter) resolves to a real leaf file ⇒ no
-    // dangling refs. If assignments.json were the source, page-1's bogus-leaf
-    // would dangle.
-    expect(result.counts.danglingRefs).toBe(0);
-    // The slug universe is the page-index pages (page-1..3), all assigned via
-    // frontmatter, so nothing is unassigned.
-    expect(result.counts.unassigned).toBe(0);
+describe("memory v3 backfill-sections", () => {
+  test("sends memory_v3_backfill_sections with a long (30-min) IPC timeout", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: { articles: 50, sections: 400, failures: 0 },
+    };
+
+    const { exitCode } = await runCommand([
+      "memory",
+      "v3",
+      "backfill-sections",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(lastIpcCall!.method).toBe("memory_v3_backfill_sections");
+    expect(lastIpcCall!.params!.body).toEqual({});
+    // The one-time full-corpus embed is long-running, so the CLI must override
+    // the default 60s timeout with a generous ceiling (30 min).
+    expect(lastIpcCall!.options!.timeoutMs).toBe(30 * 60 * 1000);
   });
 
-  test("flags a page frontmatter ref with no backing leaf as dangling", async () => {
-    await writePage("page-4", ["domain-a/missing-leaf"]);
-    invalidatePageIndex();
-    const result = await handleMemoryV3Health({ dataDir, workspaceDir });
-    expect(result.counts.danglingRefs).toBeGreaterThanOrEqual(1);
+  test("summarizes embedded sections on success", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: { articles: 7, sections: 42, failures: 0 },
+    };
+
+    await runCommand(["memory", "v3", "backfill-sections"]);
+
+    expect(
+      logOutput.some((line) => line.includes("42") && line.includes("7")),
+    ).toBe(true);
   });
-});
 
-// ---------------------------------------------------------------------------
-// reconcile
-// ---------------------------------------------------------------------------
+  test("exits with code 1 on IPC failure", async () => {
+    mockIpcResult = { ok: false, error: "Memory v3 not enabled" };
+
+    const { exitCode } = await runCommand([
+      "memory",
+      "v3",
+      "backfill-sections",
+    ]);
 
-describe("handleMemoryV3Reconcile", () => {
-  test("no-op reconcile against an unchanged tree returns empty diffs", async () => {
-    // v1: prevLeaves is derived from the current tree, so diffing
-    // current-vs-current yields no renames/deletes — reconcile runs as a
-    // convergence/prune pass. This still drives the full reconcileTree path
-    // (snapshot → apply → validate → invalidate).
-    const result = await handleMemoryV3Reconcile({ dataDir, workspaceDir });
-    expect(result.renames).toEqual([]);
-    expect(result.deleted).toEqual([]);
-    expect(result.prunedCore).toEqual([]);
+    expect(exitCode).toBe(1);
   });
 });