@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/__tests__/daemon-assistant-events.test.ts

@@ -1,6 +1,6 @@
 /**
  * Tests that daemon outbound messages are mirrored into the
- * assistant-events hub as AssistantEvent objects.
+ * assistant-events hub as AssistantEventEnvelope objects.
  *
  * Tests:
  *   - send()      → one mirrored assistant event per message
@@ -8,9 +8,8 @@
  */
 import { describe, expect, test } from "bun:test";
 
+import type { AssistantEvent, AssistantEventEnvelope } from "../api/index.js";
 // ── Imports (after mocks) ────────────────────────────────────────────────────
-import type { ServerMessage } from "../daemon/message-protocol.js";
-import type { AssistantEvent } from "../runtime/assistant-event.js";
 import { buildAssistantEvent } from "../runtime/assistant-event.js";
 import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
 
@@ -20,7 +19,7 @@ import { AssistantEventHub } from "../runtime/assistant-event-hub.js";
 
 describe("buildAssistantEvent", () => {
   test("returns event with correct shape", () => {
-    const msg: ServerMessage = {
+    const msg: AssistantEvent = {
       type: "assistant_text_delta",
       conversationId: "sess_1",
       text: "hi",
@@ -36,14 +35,14 @@ describe("buildAssistantEvent", () => {
   });
 
   test("generates unique ids for each call", () => {
-    const msg: ServerMessage = { type: "message_complete" };
+    const msg: AssistantEvent = { type: "message_complete" };
     const a = buildAssistantEvent(msg);
     const b = buildAssistantEvent(msg);
     expect(a.id).not.toBe(b.id);
   });
 
   test("conversationId is undefined when omitted", () => {
-    const msg: ServerMessage = { type: "message_complete" };
+    const msg: AssistantEvent = { type: "message_complete" };
     const event = buildAssistantEvent(msg);
     expect(event.conversationId).toBeUndefined();
   });
@@ -54,7 +53,7 @@ describe("buildAssistantEvent", () => {
 describe("daemon send → one mirrored assistant event", () => {
   test("publishing a single event to the hub delivers exactly one event", async () => {
     const hub = new AssistantEventHub();
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
 
     hub.subscribe({
       type: "process",
@@ -63,7 +62,7 @@ describe("daemon send → one mirrored assistant event", () => {
       },
     });
 
-    const msg: ServerMessage = {
+    const msg: AssistantEvent = {
       type: "assistant_text_delta",
       conversationId: "sess_a",
       text: "hello",
@@ -78,7 +77,7 @@ describe("daemon send → one mirrored assistant event", () => {
 
   test("conversationId falls back to explicit parameter when message lacks it", async () => {
     const hub = new AssistantEventHub();
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
 
     hub.subscribe({
       type: "process",
@@ -87,7 +86,7 @@ describe("daemon send → one mirrored assistant event", () => {
       },
     });
 
-    const msg: ServerMessage = { type: "message_complete" }; // no conversationId field
+    const msg: AssistantEvent = { type: "message_complete" }; // no conversationId field
     const event = buildAssistantEvent(msg, "sess_explicit");
 
     await hub.publish(event);
@@ -100,7 +99,7 @@ describe("daemon send → one mirrored assistant event", () => {
 describe("daemon broadcast → one mirrored event per message (not per socket)", () => {
   test("one broadcast publish produces exactly one hub event regardless of subscriber count", async () => {
     const hub = new AssistantEventHub();
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
 
     // Two subscribers (simulating two wire clients)
     hub.subscribe({
@@ -117,7 +116,7 @@ describe("daemon broadcast → one mirrored event per message (not per socket)",
     });
 
     // Simulate broadcast: server calls publishAssistantEvent once
-    const msg: ServerMessage = {
+    const msg: AssistantEvent = {
       type: "message_complete",
       conversationId: "sess_b",
     };
@@ -130,7 +129,7 @@ describe("daemon broadcast → one mirrored event per message (not per socket)",
 
   test("broadcast publishes once; single send publishes once — not additive", async () => {
     const hub = new AssistantEventHub();
-    const publishedEvents: AssistantEvent[] = [];
+    const publishedEvents: AssistantEventEnvelope[] = [];
 
     hub.subscribe({
       type: "process",
@@ -139,12 +138,12 @@ describe("daemon broadcast → one mirrored event per message (not per socket)",
       },
     });
 
-    const msgA: ServerMessage = {
+    const msgA: AssistantEvent = {
       type: "assistant_text_delta",
       conversationId: "s1",
       text: "a",
     };
-    const msgB: ServerMessage = {
+    const msgB: AssistantEvent = {
       type: "message_complete",
       conversationId: "s1",
     };

package/src/__tests__/db-test-helpers.ts

@@ -7,43 +7,29 @@
  *
  * No source-module imports
  * ------------------------
- * This file has ZERO imports from `src/`. It accesses the DB singletons'
- * state via the shared `globalThis.vellumAssistant.dbSingletons` slots
- * that `src/memory/db-singleton.ts` also reads/writes. The slot shape
- * is duplicated here on purpose: keeping this file off the production
- * import graph is what protects the test preload from a broken
- * `node_modules` symlink (DB ghost #3). The two declarations MUST stay
- * in sync — if you change one, change the other.
+ * This file has ZERO runtime imports from `src/`. It accesses the DB
+ * singletons' state via the shared `globalThis.vellumAssistant.dbSingletons`
+ * slots that `src/persistence/db-singleton.ts` also reads/writes, typed by the
+ * shared ambient `VellumDbSlots` (declared in
+ * `src/vellum-assistant-namespace.d.ts`). That ambient type is pure
+ * compile-time information — referencing it adds nothing to this file's runtime
+ * import graph — so keeping the helper off the production import graph (what
+ * protects the test preload from a broken `node_modules` symlink, DB ghost #3)
+ * still holds.
  *
  * Production code that needs to close + reopen the DBs (post-migration,
  * post-restore, post-vbundle-import, on shutdown) should use `resetDb()`
- * from `src/memory/db-connection.ts` instead.
+ * from `src/persistence/db-connection.ts` instead.
  */
 
 import { resetGatewayAclStore } from "./helpers/gateway-acl-store.js";
 
-// Mirrors `src/memory/db-singleton.ts`. Duplicated by design — see the
-// "No source-module imports" section above.
-type DbSlotKey = "main" | "main-readonly" | "logs" | "memory" | "telemetry";
-
-type DbSlot = {
-  db: unknown;
-  closer: (() => void) | null;
-};
-
-type DbSlots = Record<DbSlotKey, DbSlot>;
-
-type VellumAssistantNamespace = {
-  dbSingletons?: DbSlots;
-};
-
-function emptySlot(): DbSlot {
+function emptySlot(): VellumDbSlot {
   return { db: null, closer: null };
 }
 
-function dbSlots(): DbSlots {
-  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
-  const ns = (g.vellumAssistant ??= {});
+function dbSlots(): VellumDbSlots {
+  const ns = (globalThis.vellumAssistant ??= {});
   return (ns.dbSingletons ??= {
     main: emptySlot(),
     "main-readonly": emptySlot(),

package/src/__tests__/disk-pressure-routes.test.ts

@@ -21,11 +21,18 @@ mock.module("../runtime/assistant-event.js", () => ({
 
 mock.module("../runtime/assistant-event-hub.js", () => ({
   AssistantEventHub: class {},
-  broadcastMessage: () => {},
+  broadcastMessage: (message: unknown, conversationId?: string) => {
+    const event = { message, conversationId };
+    for (const callback of eventSubscribers) {
+      callback(event);
+    }
+  },
   capabilityForMessageType: () => undefined,
   assistantEventHub: {
     publish: async (event: unknown) => {
-      for (const callback of eventSubscribers) callback(event);
+      for (const callback of eventSubscribers) {
+        callback(event);
+      }
     },
     subscribe: ({ callback }: { callback: (event: unknown) => void }) => {
       eventSubscribers.add(callback);
@@ -87,7 +94,9 @@ function getRoute(endpoint: string, method: string) {
   const route = ROUTES.find(
     (r) => r.endpoint === endpoint && r.method === method,
   );
-  if (!route) throw new Error(`${method} ${endpoint} route not registered`);
+  if (!route) {
+    throw new Error(`${method} ${endpoint} route not registered`);
+  }
   return route;
 }
 

package/src/__tests__/document-tool-security.test.ts

@@ -3,9 +3,12 @@ import { beforeEach, describe, expect, test } from "bun:test";
 import { getDocumentById } from "../documents/document-store.js";
 import { getSqlite } from "../persistence/db-connection.js";
 import {
+  executeDocumentCreate,
   executeDocumentDelete,
+  executeDocumentFind,
   executeDocumentList,
   executeDocumentRead,
+  executeDocumentReplaceText,
   executeDocumentUpdate,
 } from "../tools/document/document-tool.js";
 import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
@@ -338,3 +341,95 @@ describe("executeDocumentUpdate — input validation", () => {
     expect(body.error).toContain("Invalid input: surface_id is required");
   });
 });
+
+// ── model-input schema validation (LUM-2854) ─────────────────────────
+
+describe("document tools — model-input schema validation", () => {
+  beforeEach(() => {
+    bootstrapDocumentTables();
+    seedFixtureDocuments();
+  });
+
+  test("document_find rejects a non-string query instead of crashing downstream", () => {
+    const result = executeDocumentFind(
+      { surface_id: "doc-current", query: 42 },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "document_find"');
+    expect(result.content).toContain("query");
+  });
+
+  test("document_find rejects a missing query cleanly", () => {
+    const result = executeDocumentFind(
+      { surface_id: "doc-current" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('Invalid input for tool "document_find"');
+  });
+
+  test("document_find treats null option flags as omitted", () => {
+    const result = executeDocumentFind(
+      {
+        surface_id: "doc-current",
+        query: "current",
+        regex: null,
+        case_sensitive: null,
+      },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    const body = parseResult<{ total_matches: number }>(result);
+    expect(body.total_matches).toBe(1);
+  });
+
+  test("document_create rejects a non-string title instead of persisting it", () => {
+    const result = executeDocumentCreate(
+      { title: 42, initial_content: "hello" },
+      makeContext({ conversationId: "conv-current" }),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Invalid input for tool "document_create"',
+    );
+    expect(result.content).toContain("title");
+  });
+
+  test("document_update rejects a non-string content before the bespoke checks", () => {
+    const result = executeDocumentUpdate(
+      { surface_id: "doc-current", content: 42 },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Invalid input for tool "document_update"',
+    );
+  });
+
+  test("document_list still silently ignores a malformed query", () => {
+    const result = executeDocumentList({ query: 42 }, makeContext());
+    expect(result.isError).toBe(false);
+    const body = parseResult<{ documents: Array<{ surface_id: string }> }>(
+      result,
+    );
+    expect(body.documents.map((d) => d.surface_id)).toEqual(["doc-current"]);
+  });
+
+  test("document_replace_text rejects a non-number max_replacements", () => {
+    const result = executeDocumentReplaceText(
+      {
+        surface_id: "doc-current",
+        find: "current",
+        replace: "new",
+        max_replacements: "3",
+      },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      'Invalid input for tool "document_replace_text"',
+    );
+    expect(result.content).toContain("max_replacements");
+  });
+});

package/src/__tests__/drain-kick-guard.test.ts

@@ -0,0 +1,232 @@
+/**
+ * kickQueueDrain — the never-rejecting drain trigger.
+ *
+ * Fire-and-forget drain sites (the agent loop's `finally`, route handlers
+ * releasing the processing lock) call kickQueueDrain instead of drainQueue
+ * directly. A drain whose promise rejects has nothing left to re-trigger it,
+ * so the guard retries once, and on a second failure notifies every queued
+ * sender while leaving the queue intact for the next drain trigger.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { kickQueueDrain } from "../daemon/conversation-process.js";
+import {
+  MessageQueue,
+  type QueuedMessage,
+} from "../daemon/conversation-queue-manager.js";
+
+interface FakeEvent {
+  type: string;
+  message?: string;
+  category?: string;
+  requestId?: string;
+}
+
+/**
+ * MessageQueue whose `peek` throws for the first `peekFailures` calls.
+ * `drainQueue`'s batch builder reads `peek(0)` before anything else, so
+ * each induced failure rejects exactly one drain attempt.
+ */
+class FlakyQueue extends MessageQueue {
+  peekFailures = 0;
+
+  override peek(index: number = 0): QueuedMessage | undefined {
+    if (this.peekFailures > 0) {
+      this.peekFailures -= 1;
+      throw new Error("batch build exploded");
+    }
+    return super.peek(index);
+  }
+}
+
+function makeQueued(
+  content: string,
+  requestId: string,
+  events: FakeEvent[],
+): QueuedMessage {
+  return {
+    content,
+    attachments: [],
+    requestId,
+    onEvent: (event: FakeEvent) => {
+      events.push(event);
+    },
+    sentAt: Date.now(),
+  } as unknown as QueuedMessage;
+}
+
+function makeFakeConversation(
+  options: { persistError?: Error; activityFailures?: number } = {},
+) {
+  const queue = new FlakyQueue();
+  const persistCalls: string[] = [];
+  // Post-dequeue failure injection: emitActivityState runs after the
+  // message has been popped from the queue, so a throw here exercises the
+  // restore path rather than the pre-mutation (peek) path.
+  let activityFailures = options.activityFailures ?? 0;
+  const conversation = {
+    conversationId: "conv-drain-kick",
+    queue,
+    pendingSteerRepair: false,
+    preactivatedSkillIds: undefined as string[] | undefined,
+    messages: [] as unknown[],
+    surfaceActionRequestIds: new Set<string>(),
+    activeSurfaceId: undefined,
+    ensureHostProxiesForTurn: () => {},
+    usageStats: { inputTokens: 0, outputTokens: 0, estimatedCost: 0 },
+    getTurnChannelContext: () => null,
+    setTurnChannelContext: () => {},
+    getTurnInterfaceContext: () => null,
+    setTurnInterfaceContext: () => {},
+    setTransportHints: () => {},
+    emitActivityState: () => {
+      if (activityFailures > 0) {
+        activityFailures -= 1;
+        throw new Error("activity emit exploded");
+      }
+    },
+    isProcessing: () => false,
+    persistUserMessage: async (opts: { content: string }) => {
+      persistCalls.push(opts.content);
+      if (options.persistError) {
+        throw options.persistError;
+      }
+      return { id: `msg-${persistCalls.length}`, deduplicated: true };
+    },
+  };
+  return { conversation, queue, persistCalls };
+}
+
+describe("kickQueueDrain", () => {
+  test("a drain that rejects is retried once and the retry drains the queue", async () => {
+    const events: FakeEvent[] = [];
+    // Persist fails with a non-busy error so the retry terminates on the
+    // drop-and-continue path instead of entering the full agent loop.
+    const { conversation, queue, persistCalls } = makeFakeConversation({
+      persistError: new Error("disk exploded"),
+    });
+    queue.push(makeQueued("hello there", "r1", events));
+    queue.peekFailures = 1;
+
+    await kickQueueDrain(conversation as never);
+
+    // The first attempt rejected before touching the queue; the retry got
+    // all the way to persist — the queue did not strand.
+    expect(persistCalls.length).toBe(1);
+    expect(queue.length).toBe(0);
+    expect(
+      events.filter((event) => event.category === "queue_drain_failed"),
+    ).toEqual([]);
+  });
+
+  test("a second failure notifies every queued sender and keeps the queue intact", async () => {
+    const events: FakeEvent[] = [];
+    const { conversation, queue, persistCalls } = makeFakeConversation();
+    queue.push(makeQueued("first", "r1", events));
+    queue.push(makeQueued("second", "r2", events));
+    queue.peekFailures = 2;
+
+    await kickQueueDrain(conversation as never);
+
+    // Both attempts rejected: nothing was drained or dropped, and each
+    // sender received a queue_drain_failed error so the stall is visible.
+    expect(persistCalls).toEqual([]);
+    expect(queue.length).toBe(2);
+    expect(queue.peek(0)?.requestId).toBe("r1");
+    expect(queue.peek(1)?.requestId).toBe("r2");
+    const failures = events.filter(
+      (event) =>
+        event.type === "error" && event.category === "queue_drain_failed",
+    );
+    expect(failures.map((event) => event.requestId).sort()).toEqual([
+      "r1",
+      "r2",
+    ]);
+  });
+
+  test("a throw after the dequeue restores the message so the retry retries it", async () => {
+    const events: FakeEvent[] = [];
+    // Persist fails with a non-busy error so the retry terminates on the
+    // drop-and-continue path instead of entering the full agent loop.
+    const { conversation, queue, persistCalls } = makeFakeConversation({
+      persistError: new Error("disk exploded"),
+      activityFailures: 1,
+    });
+    queue.push(makeQueued("hello there", "r1", events));
+
+    await kickQueueDrain(conversation as never);
+
+    // The first attempt popped r1 and then threw; the restore put it back,
+    // so the retry drained r1 itself instead of skipping past it.
+    expect(persistCalls).toEqual(["hello there"]);
+    expect(queue.length).toBe(0);
+    expect(
+      events.filter((event) => event.category === "queue_drain_failed"),
+    ).toEqual([]);
+  });
+
+  test("a persistent post-dequeue throw leaves the message queued and notified", async () => {
+    const events: FakeEvent[] = [];
+    const { conversation, queue, persistCalls } = makeFakeConversation({
+      activityFailures: 2,
+    });
+    queue.push(makeQueued("hello there", "r1", events));
+
+    await kickQueueDrain(conversation as never);
+
+    // Both attempts popped and restored r1: it is back at the head and its
+    // sender was told about the stall — not silently lost.
+    expect(persistCalls).toEqual([]);
+    expect(queue.length).toBe(1);
+    expect(queue.peek(0)?.requestId).toBe("r1");
+    expect(
+      events.filter(
+        (event) =>
+          event.type === "error" && event.category === "queue_drain_failed",
+      ).length,
+    ).toBe(1);
+  });
+
+  test("a batch popped before a throw is restored in order", async () => {
+    const events: FakeEvent[] = [];
+    const { conversation, queue, persistCalls } = makeFakeConversation({
+      activityFailures: 2,
+    });
+    queue.push(makeQueued("first", "r1", events));
+    queue.push(makeQueued("second", "r2", events));
+
+    await kickQueueDrain(conversation as never);
+
+    // Both batchable messages were shifted out together; both attempts threw
+    // after the pop, and the restore preserved their order for the next
+    // drain trigger.
+    expect(persistCalls).toEqual([]);
+    expect(queue.length).toBe(2);
+    expect(queue.peek(0)?.requestId).toBe("r1");
+    expect(queue.peek(1)?.requestId).toBe("r2");
+    const failures = events.filter(
+      (event) =>
+        event.type === "error" && event.category === "queue_drain_failed",
+    );
+    expect(failures.map((event) => event.requestId).sort()).toEqual([
+      "r1",
+      "r2",
+    ]);
+  });
+
+  test("a healthy drain runs once with no retry and no failure events", async () => {
+    const events: FakeEvent[] = [];
+    const { conversation, queue, persistCalls } = makeFakeConversation({
+      persistError: new Error("disk exploded"),
+    });
+    queue.push(makeQueued("hello there", "r1", events));
+
+    await kickQueueDrain(conversation as never);
+
+    expect(persistCalls.length).toBe(1);
+    expect(queue.length).toBe(0);
+    expect(
+      events.filter((event) => event.category === "queue_drain_failed"),
+    ).toEqual([]);
+  });
+});

package/src/__tests__/dynamic-skill-background-guard.test.ts

@@ -19,6 +19,10 @@ import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { RiskLevel } from "../permissions/types.js";
 import type { ToolExecutionResult } from "../tools/types.js";
+import {
+  installThresholdReaderMock,
+  thresholdReaderMock,
+} from "./gateway-threshold-reader-mock.js";
 
 // ---------------------------------------------------------------------------
 // Mock setup — mirrors require-fresh-approval.test.ts patterns
@@ -37,8 +41,20 @@ let dynamicSkillLoad = false;
  */
 let checkDecision = "prompt";
 
+// The real builder returns undefined for these contexts (guardian turns with
+// no channel coordinates), which is what this suite wants. It is registered
+// rather than hard-coded because `mock.module` is process-global: a stub that
+// always returned undefined would also be the builder other test files see,
+// silently stripping the channel coordinates their contexts supply. Captured
+// by value first — `mock.module` swaps the module's exports in place, so
+// reading it through the namespace inside the factory would recurse.
+const realCellQueryModule =
+  await import("../permissions/channel-permission-query.js");
 mock.module("../permissions/channel-permission-query.js", () => ({
-  buildChannelPermissionCellQuery: () => undefined,
+  buildChannelPermissionCellQuery:
+    realCellQueryModule.buildChannelPermissionCellQuery,
+  effectiveChannelCellThreshold:
+    realCellQueryModule.effectiveChannelCellThreshold,
 }));
 
 // The scenario under test is "no trust rule covers this load" (a covering rule
@@ -74,11 +90,8 @@ mock.module("../tools/registry.js", () => ({
 
 // Background threshold "medium" covers the medium-risk load — the guard,
 // not the threshold, must be what blocks the dynamic case.
-mock.module("../permissions/gateway-threshold-reader.js", () => ({
-  getAutoApproveThreshold: async () => "medium",
-  refreshAutoApproveThreshold: async () => null,
-  _clearGlobalCacheForTesting: () => {},
-}));
+installThresholdReaderMock();
+thresholdReaderMock.threshold = "medium";
 
 mock.module("../tools/shared/filesystem/path-policy.js", () => ({
   sandboxPolicy: () => ({ ok: false }),

package/src/__tests__/emit-event-signal.test.ts

@@ -1,7 +1,7 @@
 /**
  * Behavioral test for the generic CLI→daemon event bridge.
  *
- * Callers write a JSON-encoded {@link ServerMessage} to
+ * Callers write a JSON-encoded {@link AssistantEvent} to
  * `<signalsDir>/emit-event`. {@link handleEmitEventSignal} reads that
  * payload and republishes it through the {@link assistantEventHub} so
  * SSE subscribers receive it.
@@ -10,8 +10,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterEach, describe, expect, test } from "bun:test";
 
-import type { ServerMessage } from "../daemon/message-protocol.js";
-import type { AssistantEvent } from "../runtime/assistant-event.js";
+import type { AssistantEvent, AssistantEventEnvelope } from "../api/index.js";
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";
 import { handleEmitEventSignal } from "../signals/emit-event.js";
 import { getSignalsDir } from "../util/platform.js";
@@ -33,14 +32,14 @@ afterEach(() => {
 });
 
 describe("handleEmitEventSignal", () => {
-  test("reads a ServerMessage from the signal file and publishes it to the event hub", async () => {
+  test("reads a AssistantEvent from the signal file and publishes it to the event hub", async () => {
     mkdirSync(getSignalsDir(), { recursive: true });
 
-    const payload: ServerMessage = { type: "contacts_changed" };
+    const payload: AssistantEvent = { type: "contacts_changed" };
 
     writeFileSync(signalPath(), JSON.stringify(payload), "utf-8");
 
-    const received: AssistantEvent[] = [];
+    const received: AssistantEventEnvelope[] = [];
     let resolveDelivered: (() => void) | null = null;
     const delivered = new Promise<void>((resolve) => {
       resolveDelivered = resolve;

package/src/__tests__/encrypted-store-test-helpers.ts

@@ -7,13 +7,15 @@
  *
  * No source-module imports
  * ------------------------
- * This file has ZERO imports from `src/`. It accesses the store-path
+ * This file has ZERO runtime imports from `src/`. It accesses the store-path
  * override state via the shared `globalThis.vellumAssistant.storePathOverride`
- * slot that `src/security/store-path-override.ts` also reads/writes. The
- * slot shape is duplicated here on purpose: keeping this file off the
- * production import graph is what protects the test preload from a
- * broken `node_modules` symlink (DB ghost #3). The two declarations MUST
- * stay in sync — if you change one, change the other.
+ * slot that `src/security/store-path-override.ts` also reads/writes, typed by
+ * the shared ambient `VellumStorePathOverride` (declared in
+ * `src/vellum-assistant-namespace.d.ts`). That ambient type is pure
+ * compile-time information — referencing it adds nothing to this file's runtime
+ * import graph — so keeping the helper off the production import graph (what
+ * protects the test preload from a broken `node_modules` symlink, DB ghost #3)
+ * still holds.
  *
  * Most tests no longer need these overrides: the test preload places
  * `VELLUM_WORKSPACE_DIR` at `<tmpRoot>/workspace`, so `getProtectedDir()`
@@ -22,20 +24,8 @@
  * (env-var fallbacks, migration corner cases, etc.).
  */
 
-// Mirrors `src/security/store-path-override.ts`. Duplicated by design — see
-// the "No source-module imports" section above.
-type PathSlot = {
-  storePath: string | null;
-  storeKeyPath: string | null;
-};
-
-type VellumAssistantNamespace = {
-  storePathOverride?: PathSlot;
-};
-
-function pathSlot(): PathSlot {
-  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
-  const ns = (g.vellumAssistant ??= {});
+function pathSlot(): VellumStorePathOverride {
+  const ns = (globalThis.vellumAssistant ??= {});
   return (ns.storePathOverride ??= { storePath: null, storeKeyPath: null });
 }