@vellumai/assistant 0.10.3 → 0.10.4-staging.1

package/src/memory/__tests__/embedding-cache.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for `assistant/src/memory/embedding-cache.ts` — the shared dense-vector
+ * cache over the `memory_embeddings` table. Exercises the real SQL against a
+ * temp workspace DB (round-trip, dim-mismatch miss, key isolation, upsert).
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+let tmpWorkspace: string;
+let previousWorkspaceEnv: string | undefined;
+
+beforeAll(() => {
+  tmpWorkspace = mkdtempSync(join(tmpdir(), "embedding-cache-test-"));
+  previousWorkspaceEnv = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = tmpWorkspace;
+});
+
+afterAll(() => {
+  if (previousWorkspaceEnv === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = previousWorkspaceEnv;
+  }
+  rmSync(tmpWorkspace, { recursive: true, force: true });
+});
+
+// Deferred so internal `getWorkspaceDir()` resolves to the tmpdir set above.
+const { getDb } = await import("../db-connection.js");
+const { resetDbForTesting } =
+  await import("../../__tests__/db-test-helpers.js");
+const { initializeDb } = await import("../db-init.js");
+const { memoryEmbeddings } = await import("../schema.js");
+const { readEmbeddingCache, writeEmbeddingCache } =
+  await import("../embedding-cache.js");
+
+beforeEach(async () => {
+  resetDbForTesting();
+  // The first run pays the full cold-start migration chain; bump the hook
+  // timeout above bun's 5s default so the leading test doesn't flake in CI.
+  await initializeDb();
+}, 30_000);
+
+const KEY = {
+  targetType: "v3_section",
+  targetId: "people/alice#0",
+  provider: "local",
+  model: "test-model",
+  expectedDim: 4,
+} as const;
+
+function seed(
+  overrides: Partial<{
+    dense: number[];
+    contentHash: string;
+    now: number;
+  }> = {},
+): void {
+  writeEmbeddingCache(getDb(), {
+    targetType: KEY.targetType,
+    targetId: KEY.targetId,
+    provider: KEY.provider,
+    model: KEY.model,
+    dense: overrides.dense ?? [1, 2, 3, 4],
+    contentHash: overrides.contentHash ?? "hash-a",
+    now: overrides.now ?? 1000,
+  });
+}
+
+describe("embedding-cache", () => {
+  test("read returns null when nothing is cached", () => {
+    expect(readEmbeddingCache(getDb(), KEY)).toBeNull();
+  });
+
+  test("write then read round-trips the vector and content hash", () => {
+    seed({ dense: [1, 2, 3, 4], contentHash: "hash-a" });
+
+    const got = readEmbeddingCache(getDb(), KEY);
+    expect(got).not.toBeNull();
+    expect(got!.dense).toEqual([1, 2, 3, 4]);
+    expect(got!.contentHash).toBe("hash-a");
+  });
+
+  test("read misses when the configured dimension differs from the stored row", () => {
+    seed();
+    expect(readEmbeddingCache(getDb(), { ...KEY, expectedDim: 8 })).toBeNull();
+  });
+
+  test("read is isolated by targetType / targetId / provider / model", () => {
+    seed();
+    const db = getDb();
+    expect(
+      readEmbeddingCache(db, { ...KEY, targetType: "concept_page" }),
+    ).toBeNull();
+    expect(
+      readEmbeddingCache(db, { ...KEY, targetId: "people/bob#0" }),
+    ).toBeNull();
+    expect(readEmbeddingCache(db, { ...KEY, provider: "openai" })).toBeNull();
+    expect(readEmbeddingCache(db, { ...KEY, model: "other-model" })).toBeNull();
+  });
+
+  test("re-writing the same key upserts in place (one row, latest content)", () => {
+    const db = getDb();
+    seed({ dense: [1, 2, 3, 4], contentHash: "hash-a", now: 1000 });
+    seed({ dense: [5, 6, 7, 8], contentHash: "hash-b", now: 2000 });
+
+    const got = readEmbeddingCache(db, KEY);
+    expect(got!.dense).toEqual([5, 6, 7, 8]);
+    expect(got!.contentHash).toBe("hash-b");
+
+    // The unique key collapses both writes onto a single row.
+    const rows = db
+      .select()
+      .from(memoryEmbeddings)
+      .all()
+      .filter(
+        (r) => r.targetType === KEY.targetType && r.targetId === KEY.targetId,
+      );
+    expect(rows).toHaveLength(1);
+  });
+});

package/src/memory/compaction-ledger-store.ts

@@ -0,0 +1,107 @@
+import { and, desc, eq, lte } from "drizzle-orm";
+import { v4 as uuid } from "uuid";
+
+import { type DrizzleDb, getDb } from "./db-connection.js";
+import { conversationCompactionEvents } from "./schema.js";
+
+export interface CompactionEvent {
+  /** Wall-clock time the compaction ran (= `conversations.context_compacted_at`). */
+  compactedAt: number;
+  summary: string;
+  /** Count of leading persisted messages behind this compaction's summary. */
+  compactedMessageCount: number;
+}
+
+/**
+ * Append a compaction event to the ledger. Called alongside the
+ * `conversations` cache update on every compaction.
+ */
+export function appendCompactionEvent(
+  conversationId: string,
+  event: CompactionEvent,
+): void {
+  const db = getDb();
+  db.insert(conversationCompactionEvents)
+    .values({
+      id: uuid(),
+      conversationId,
+      compactedAt: event.compactedAt,
+      summary: event.summary,
+      compactedMessageCount: event.compactedMessageCount,
+      createdAt: Date.now(),
+    })
+    .run();
+}
+
+/**
+ * The most recent compaction event whose `compactedAt` is at-or-before
+ * `atOrBefore`, or null if none (or `atOrBefore` is null). This is the fork
+ * inheritance rule: a compaction applies to a fork only if it happened before
+ * the message being forked from.
+ */
+export function getLatestCompactionEventAtOrBefore(
+  conversationId: string,
+  atOrBefore: number | null,
+): CompactionEvent | null {
+  if (atOrBefore == null) return null;
+  const db = getDb();
+  const row = db
+    .select({
+      compactedAt: conversationCompactionEvents.compactedAt,
+      summary: conversationCompactionEvents.summary,
+      compactedMessageCount: conversationCompactionEvents.compactedMessageCount,
+    })
+    .from(conversationCompactionEvents)
+    .where(
+      and(
+        eq(conversationCompactionEvents.conversationId, conversationId),
+        lte(conversationCompactionEvents.compactedAt, atOrBefore),
+      ),
+    )
+    .orderBy(desc(conversationCompactionEvents.compactedAt))
+    .limit(1)
+    .get();
+  return row ?? null;
+}
+
+/**
+ * Copy the source conversation's ledger events with `compactedAt <=
+ * boundaryCreatedAt` into the fork, so the fork owns a correct ledger for its
+ * own future forks/compactions. Takes the active `db` so the copy joins the
+ * caller's transaction. No-op when the boundary is null.
+ */
+export function forkCompactionLedger(
+  db: DrizzleDb,
+  sourceConversationId: string,
+  forkConversationId: string,
+  boundaryCreatedAt: number | null,
+): void {
+  if (boundaryCreatedAt == null) return;
+  const events = db
+    .select({
+      compactedAt: conversationCompactionEvents.compactedAt,
+      summary: conversationCompactionEvents.summary,
+      compactedMessageCount: conversationCompactionEvents.compactedMessageCount,
+    })
+    .from(conversationCompactionEvents)
+    .where(
+      and(
+        eq(conversationCompactionEvents.conversationId, sourceConversationId),
+        lte(conversationCompactionEvents.compactedAt, boundaryCreatedAt),
+      ),
+    )
+    .all();
+  const now = Date.now();
+  for (const event of events) {
+    db.insert(conversationCompactionEvents)
+      .values({
+        id: uuid(),
+        conversationId: forkConversationId,
+        compactedAt: event.compactedAt,
+        summary: event.summary,
+        compactedMessageCount: event.compactedMessageCount,
+        createdAt: now,
+      })
+      .run();
+  }
+}

package/src/memory/conversation-crud.ts

@@ -34,6 +34,7 @@ import {
   MEMORY_V3_INJECTED_BLOCK_METADATA_KEY,
   seedEverInjectedFromSlugs,
 } from "../plugins/defaults/memory-v3-shadow/ever-injected-store.js";
+import { getCurrentSeq } from "../runtime/assistant-stream-state.js";
 import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
 import { UserError } from "../util/errors.js";
 import { safeParseRecord } from "../util/json.js";
@@ -45,6 +46,11 @@ import {
   linkAttachmentToMessage,
 } from "./attachments-store.js";
 import { AUTO_ANALYSIS_SOURCE } from "./auto-analysis-constants.js";
+import {
+  appendCompactionEvent,
+  forkCompactionLedger,
+  getLatestCompactionEventAtOrBefore,
+} from "./compaction-ledger-store.js";
 import {
   projectAssistantMessage,
   seedForkedConversationAttention,
@@ -591,6 +597,7 @@ export function createConversation(
 ) {
   const db = getDb();
   const now = Date.now();
+  const initialSeq = getCurrentSeq();
   const opts =
     typeof titleOrOpts === "string"
       ? { title: titleOrOpts }
@@ -629,6 +636,10 @@ export function createConversation(
     memoryScopeId,
     scheduleJobId: opts.scheduleJobId ?? null,
     forkParentConversationId: opts.forkParentConversationId ?? null,
+    // Snapshot↔stream alignment baseline, captured at the creation instant.
+    // 0 (nothing stamped yet this process) is stored as NULL so `/messages`
+    // reports null and the client cold-starts rather than aligning to seq 0.
+    seq: initialSeq > 0 ? initialSeq : null,
   };
 
   // Retry on SQLITE_BUSY and SQLITE_IOERR — transient disk I/O errors or WAL
@@ -928,16 +939,6 @@ export function forkConversation(params: {
     initialBoundaryIndex,
   );
 
-  const visibleWindowStartIndex = Math.max(
-    0,
-    Math.min(
-      sourceConversation.contextCompactedMessageCount,
-      sourceMessages.length,
-    ),
-  );
-  const preserveSourceCompactionState =
-    copyBoundaryIndex >= visibleWindowStartIndex;
-
   const messagesToCopy =
     copyBoundaryIndex >= 0
       ? sourceMessages.slice(0, copyBoundaryIndex + 1)
@@ -953,6 +954,23 @@ export function forkConversation(params: {
     sourceHistoryStrippedAt != null &&
     boundaryMessageCreatedAt != null &&
     boundaryMessageCreatedAt >= sourceHistoryStrippedAt;
+
+  // Inherit compaction by the same temporal rule: apply the most recent
+  // compaction whose event time is at-or-before the forked-from message. A
+  // compaction that ran after the boundary message did not exist at that point
+  // in the conversation, so the fork branches from full uncompacted history.
+  const inheritedCompaction = getLatestCompactionEventAtOrBefore(
+    sourceConversation.id,
+    boundaryMessageCreatedAt,
+  );
+  // The Slack chronological-context watermark is single-valued on the source
+  // row and reflects only the latest compaction, so carry it only when the
+  // fork inherits that latest compaction. Pairing the latest watermark with an
+  // older inherited summary (a fork between two compactions) would filter out
+  // Slack messages the older summary does not cover.
+  const inheritsLatestCompaction =
+    inheritedCompaction != null &&
+    inheritedCompaction.compactedAt === sourceConversation.contextCompactedAt;
   const forkParentMessageId = messagesToCopy.at(-1)?.id ?? null;
   const forkTitle =
     params.title ?? `${sourceConversation.title ?? "Untitled"} (Fork)`;
@@ -984,19 +1002,14 @@ export function forkConversation(params: {
       .set({
         forkParentConversationId: sourceConversation.id,
         forkParentMessageId,
-        contextSummary: preserveSourceCompactionState
-          ? sourceConversation.contextSummary
-          : null,
-        contextCompactedMessageCount: preserveSourceCompactionState
-          ? sourceConversation.contextCompactedMessageCount
-          : 0,
-        contextCompactedAt: preserveSourceCompactionState
-          ? sourceConversation.contextCompactedAt
-          : null,
-        slackContextCompactionWatermarkTs: preserveSourceCompactionState
+        contextSummary: inheritedCompaction?.summary ?? null,
+        contextCompactedMessageCount:
+          inheritedCompaction?.compactedMessageCount ?? 0,
+        contextCompactedAt: inheritedCompaction?.compactedAt ?? null,
+        slackContextCompactionWatermarkTs: inheritsLatestCompaction
           ? sourceConversation.slackContextCompactionWatermarkTs
           : null,
-        slackContextCompactionWatermarkAt: preserveSourceCompactionState
+        slackContextCompactionWatermarkAt: inheritsLatestCompaction
           ? sourceConversation.slackContextCompactionWatermarkAt
           : null,
         historyStrippedAt: inheritsHistoryStrippedAt
@@ -1042,8 +1055,8 @@ export function forkConversation(params: {
       forkedMessageIds,
       latestForkedAssistant,
       isFullHistoryFork: copyBoundaryIndex === sourceMessages.length - 1,
-      preserveSourceCompactionState,
-      visibleWindowStartIndex,
+      inheritedCompactedMessageCount:
+        inheritedCompaction?.compactedMessageCount ?? 0,
       diskSyncQueue,
     });
 
@@ -1076,8 +1089,13 @@ interface PopulateForkContentsArgs {
   latestForkedAssistant: { messageId: string; messageAt: number } | null;
   /** `copyBoundaryIndex === sourceMessages.length - 1` for the source. */
   isFullHistoryFork: boolean;
-  preserveSourceCompactionState: boolean;
-  visibleWindowStartIndex: number;
+  /**
+   * Count of leading messages behind the compaction event this fork inherits
+   * (0 when the fork branches from uncompacted history). Memory-slug seeding
+   * skips this prefix, since rows behind the fork's summary are not rendered
+   * and must stay re-injectable.
+   */
+  inheritedCompactedMessageCount: number;
   /**
    * When provided, a disk-sync entry is appended per copied message for the
    * caller to flush after commit. Omitted by the retrospective fork, whose
@@ -1109,8 +1127,7 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
     forkedMessageIds,
     latestForkedAssistant,
     isFullHistoryFork,
-    preserveSourceCompactionState,
-    visibleWindowStartIndex,
+    inheritedCompactedMessageCount,
     diskSyncQueue,
   } = args;
   const db = getDb();
@@ -1218,9 +1235,10 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
     // The v2 and v3 layers persist under separate metadata keys with the
     // same `# memory/concepts/<slug>.md` header convention, so each seeds
     // its own dedup record from its own blocks.
-    const visibleStartIndex = preserveSourceCompactionState
-      ? visibleWindowStartIndex
-      : 0;
+    const visibleStartIndex = Math.min(
+      inheritedCompactedMessageCount,
+      messagesToCopy.length,
+    );
     const inheritedSlugs = new Set<string>();
     const inheritedV3Slugs = new Set<string>();
     for (const message of messagesToCopy.slice(visibleStartIndex)) {
@@ -1256,6 +1274,15 @@ function populateForkContentsInProcess(args: PopulateForkContentsArgs): void {
     forkedMessageIds,
     lastCopiedSourceMessageId: messagesToCopy.at(-1)?.id ?? null,
   });
+
+  // Carry the source's compaction events that predate the fork boundary so the
+  // fork owns a correct ledger for its own future forks/compactions.
+  forkCompactionLedger(
+    db,
+    sourceConversationId,
+    fork.id,
+    messagesToCopy.at(-1)?.createdAt ?? null,
+  );
 }
 
 /**
@@ -1345,15 +1372,6 @@ export async function forkConversationForRetrospective(params: {
     sourceMessages,
     initialBoundaryIndex,
   );
-  const visibleWindowStartIndex = Math.max(
-    0,
-    Math.min(
-      sourceConversation.contextCompactedMessageCount,
-      sourceMessages.length,
-    ),
-  );
-  const preserveSourceCompactionState =
-    copyBoundaryIndex >= visibleWindowStartIndex;
   const messagesToCopy =
     copyBoundaryIndex >= 0
       ? sourceMessages.slice(0, copyBoundaryIndex + 1)
@@ -1365,6 +1383,17 @@ export async function forkConversationForRetrospective(params: {
     sourceHistoryStrippedAt != null &&
     boundaryMessageCreatedAt != null &&
     boundaryMessageCreatedAt >= sourceHistoryStrippedAt;
+  // Inherit the most recent compaction whose event time is at-or-before the
+  // forked-from message (see `forkConversation`).
+  const inheritedCompaction = getLatestCompactionEventAtOrBefore(
+    sourceConversation.id,
+    boundaryMessageCreatedAt,
+  );
+  // Carry the Slack watermark only when inheriting the latest compaction
+  // (see `forkConversation`).
+  const inheritsLatestCompaction =
+    inheritedCompaction != null &&
+    inheritedCompaction.compactedAt === sourceConversation.contextCompactedAt;
   const forkParentMessageId = messagesToCopy.at(-1)?.id ?? null;
   const forkTitle =
     params.title ?? `${sourceConversation.title ?? "Untitled"} (Fork)`;
@@ -1393,19 +1422,14 @@ export async function forkConversationForRetrospective(params: {
       .set({
         forkParentConversationId: sourceConversation.id,
         forkParentMessageId,
-        contextSummary: preserveSourceCompactionState
-          ? sourceConversation.contextSummary
-          : null,
-        contextCompactedMessageCount: preserveSourceCompactionState
-          ? sourceConversation.contextCompactedMessageCount
-          : 0,
-        contextCompactedAt: preserveSourceCompactionState
-          ? sourceConversation.contextCompactedAt
-          : null,
-        slackContextCompactionWatermarkTs: preserveSourceCompactionState
+        contextSummary: inheritedCompaction?.summary ?? null,
+        contextCompactedMessageCount:
+          inheritedCompaction?.compactedMessageCount ?? 0,
+        contextCompactedAt: inheritedCompaction?.compactedAt ?? null,
+        slackContextCompactionWatermarkTs: inheritsLatestCompaction
           ? sourceConversation.slackContextCompactionWatermarkTs
           : null,
-        slackContextCompactionWatermarkAt: preserveSourceCompactionState
+        slackContextCompactionWatermarkAt: inheritsLatestCompaction
           ? sourceConversation.slackContextCompactionWatermarkAt
           : null,
         historyStrippedAt: inheritsHistoryStrippedAt
@@ -1445,8 +1469,8 @@ export async function forkConversationForRetrospective(params: {
         forkedMessageIds,
         latestForkedAssistant,
         isFullHistoryFork: copyBoundaryIndex === sourceMessages.length - 1,
-        preserveSourceCompactionState,
-        visibleWindowStartIndex,
+        inheritedCompactedMessageCount:
+          inheritedCompaction?.compactedMessageCount ?? 0,
       });
     });
 
@@ -2117,15 +2141,27 @@ export function updateConversationContextWindow(
   contextCompactedMessageCount: number,
 ): void {
   const db = getDb();
-  db.update(conversations)
-    .set({
-      contextSummary,
-      contextCompactedMessageCount,
-      contextCompactedAt: Date.now(),
-      updatedAt: Date.now(),
-    })
-    .where(eq(conversations.id, id))
-    .run();
+  const now = Date.now();
+  // Update the hot-path cache columns and append the event to the ledger in a
+  // single transaction so the latest ledger event always matches the cache.
+  db.transaction(() => {
+    db.update(conversations)
+      .set({
+        contextSummary,
+        contextCompactedMessageCount,
+        contextCompactedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(conversations.id, id))
+      .run();
+    if (contextCompactedMessageCount > 0) {
+      appendCompactionEvent(id, {
+        compactedAt: now,
+        summary: contextSummary,
+        compactedMessageCount: contextCompactedMessageCount,
+      });
+    }
+  });
 }
 
 export function setConversationHistoryStrippedAt(
@@ -2218,6 +2254,45 @@ export function isConversationProcessing(id: string): boolean {
   return row?.processing_started_at != null;
 }
 
+/**
+ * Highest stream `seq` whose content is durably persisted to this
+ * conversation's message rows, read from the `conversations.seq` column. This
+ * is the snapshot↔stream alignment baseline `/messages` returns so a client
+ * applies only stream events with a higher `seq`. `null` when none was
+ * recorded (created before any stream activity, row predates the column, or
+ * the conversation row is absent), in which case the client cold-starts.
+ *
+ * Seeded at creation with the global high-water seq and advanced on each
+ * persistence flush by {@link recordConversationPersistedSeq}.
+ */
+export function getConversationPersistedSeq(id: string): number | null {
+  const row = rawGet<{ seq: number | null }>(
+    "SELECT seq FROM conversations WHERE id = ?",
+    id,
+  );
+  return row?.seq ?? null;
+}
+
+/**
+ * Record that conversation `id` has durably persisted all of its events
+ * through `seq`, writing the `conversations.seq` column. Called at each
+ * persistence flush with the `seq` of the last event whose content the write
+ * committed.
+ *
+ * Monotonic: the `WHERE seq IS NULL OR seq < ?` guard makes the update raise
+ * the high-water mark only, so out-of-order async commits never regress it.
+ * Non-positive or non-finite `seq` values are ignored.
+ */
+export function recordConversationPersistedSeq(id: string, seq: number): void {
+  if (!Number.isFinite(seq) || seq <= 0) return;
+  rawRun(
+    "UPDATE conversations SET seq = ? WHERE id = ? AND (seq IS NULL OR seq < ?)",
+    seq,
+    id,
+    seq,
+  );
+}
+
 /**
  * Set or clear the `surfaced_at` promotion marker for a conversation.
  *