@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/runtime/migrations/__tests__/vbundle-legacy-user-md.test.ts

@@ -150,9 +150,6 @@ describe("DefaultPathResolver prompts/USER.md translation", () => {
     expect(resolver.resolve("prompts/SOUL.md")).toBe(
       join(WORKSPACE_ROOT, "SOUL.md"),
     );
-    expect(resolver.resolve("prompts/UPDATES.md")).toBe(
-      join(WORKSPACE_ROOT, "UPDATES.md"),
-    );
   });
 
   test("skips unknown prompt filenames regardless of guardian state", () => {
@@ -230,6 +227,71 @@ describe("analyzeImport for legacy prompts/USER.md", () => {
     const userMd = report.files.find((f) => f.path === "prompts/USER.md");
     expect(userMd!.action).toBe("skip");
   });
+
+  test("retired workspace/UPDATES.md (current format) is a non-blocking skip", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new Uint8Array(),
+        },
+        {
+          path: "workspace/UPDATES.md",
+          data: new TextEncoder().encode("## Old release notes\n"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const report = analyzeImport({ manifest, pathResolver: resolver });
+
+    expect(report.can_import).toBe(true);
+    expect(report.conflicts).toHaveLength(0);
+    const updatesMd = report.files.find(
+      (f) => f.path === "workspace/UPDATES.md",
+    );
+    expect(updatesMd).toBeDefined();
+    expect(updatesMd!.action).toBe("skip");
+  });
+
+  test("retired prompts/UPDATES.md in a legacy bundle is a non-blocking skip", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new Uint8Array(),
+        },
+        {
+          path: "prompts/UPDATES.md",
+          data: new TextEncoder().encode("## Old release notes\n"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const report = analyzeImport({ manifest, pathResolver: resolver });
+
+    // Bundles exported while the update-bulletin feature existed must stay
+    // restorable — the retired file is dropped, never written back, and
+    // must not register an UNKNOWN_ARCHIVE_PATH conflict.
+    expect(report.can_import).toBe(true);
+    expect(report.conflicts).toHaveLength(0);
+    const updatesMd = report.files.find((f) => f.path === "prompts/UPDATES.md");
+    expect(updatesMd).toBeDefined();
+    expect(updatesMd!.action).toBe("skip");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -358,6 +420,91 @@ describe("commitImport for legacy prompts/USER.md", () => {
     expect(existsSync(join(USERS_DIR, "USER.md"))).toBe(false);
   });
 
+  test("retired workspace/UPDATES.md (current format) is never written back", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new Uint8Array(),
+        },
+        {
+          path: "workspace/UPDATES.md",
+          data: new TextEncoder().encode("## Old release notes\n"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const result = commitImport({
+      archiveData: archive,
+      pathResolver: resolver,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.success).toBe(true);
+      expect(
+        result.report.files.find((f) => f.path === "workspace/UPDATES.md")
+          ?.action,
+      ).toBe("skipped");
+      expect(result.report.warnings.some((w) => w.includes("UPDATES.md"))).toBe(
+        false,
+      );
+    }
+
+    // The retired bulletin file must not be resurrected in the workspace.
+    expect(existsSync(join(WORKSPACE_ROOT, "UPDATES.md"))).toBe(false);
+  });
+
+  test("retired prompts/UPDATES.md skips silently — no warning, nothing written", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "data/db/assistant.db",
+          data: new Uint8Array(),
+        },
+        {
+          path: "prompts/UPDATES.md",
+          data: new TextEncoder().encode("## Old release notes\n"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const result = commitImport({
+      archiveData: archive,
+      pathResolver: resolver,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.success).toBe(true);
+      expect(
+        result.report.files.find((f) => f.path === "prompts/UPDATES.md")
+          ?.action,
+      ).toBe("skipped");
+      // Silent skip: the commit report must agree with preflight, which
+      // raises neither a conflict nor a warning for retired paths.
+      expect(
+        result.report.warnings.some((w) => w.includes("prompts/UPDATES.md")),
+      ).toBe(false);
+    }
+
+    expect(existsSync(join(WORKSPACE_ROOT, "UPDATES.md"))).toBe(false);
+  });
+
   test("does NOT overwrite a customized users/<slug>.md", () => {
     const slug = "captain.md";
     const guardianPath = join(USERS_DIR, slug);

package/src/runtime/migrations/vbundle-import-analyzer.ts

@@ -19,6 +19,7 @@ import { join, resolve } from "node:path";
 
 import { resolveGuardianPersonaPath } from "../../prompts/persona-resolver.js";
 import { getLogger } from "../../util/logger.js";
+import { isRetiredArchivePath } from "./vbundle-import-policy.js";
 import type { ManifestType } from "./vbundle-validator.js";
 
 const log = getLogger("vbundle-import-analyzer");
@@ -30,12 +31,7 @@ const log = getLogger("vbundle-import-analyzer");
  * on import, its content is translated to `users/<slug>.md` at the
  * current guardian's location (see `DefaultPathResolver.resolve`).
  */
-const ALLOWED_PROMPT_FILENAMES = new Set([
-  "IDENTITY.md",
-  "SOUL.md",
-  "USER.md",
-  "UPDATES.md",
-]);
+const ALLOWED_PROMPT_FILENAMES = new Set(["IDENTITY.md", "SOUL.md", "USER.md"]);
 
 /** Archive path for the legacy guardian user persona file. */
 const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
@@ -123,6 +119,14 @@ export class DefaultPathResolver implements PathResolver {
       return null;
     }
 
+    // Retired-feature files (both legacy and workspace-format spellings)
+    // must never resolve to a disk target — resolving would write them
+    // back into the workspace on import. The analyzer and both importers
+    // turn the resulting null into a silent non-blocking skip.
+    if (isRetiredArchivePath(archivePath)) {
+      return null;
+    }
+
     // New format: workspace/ prefix — maps directly into the workspace dir
     if (archivePath.startsWith("workspace/") && this.workspaceDir) {
       const relPath = archivePath.slice("workspace/".length);
@@ -288,6 +292,25 @@ export function analyzeImport(
         continue;
       }
 
+      // Retired-feature file from a legacy bundle: nothing consumes it
+      // anymore, so drop it silently instead of blocking the restore with
+      // an UNKNOWN_ARCHIVE_PATH conflict.
+      if (isRetiredArchivePath(fileEntry.path)) {
+        log.info(
+          { path: fileEntry.path },
+          "Retired archive path in legacy bundle — will be skipped on import",
+        );
+        files.push({
+          path: fileEntry.path,
+          action: "skip",
+          bundle_size: fileEntry.size_bytes,
+          bundle_sha256: fileEntry.sha256,
+          current_size: null,
+          current_sha256: null,
+        });
+        continue;
+      }
+
       // Unknown archive path — would have nowhere to write
       conflicts.push({
         code: "UNKNOWN_ARCHIVE_PATH",

package/src/runtime/migrations/vbundle-import-policy.ts

@@ -34,6 +34,29 @@ export function isLegacyPersonaArchivePath(archivePath: string): boolean {
   return archivePath === LEGACY_USER_MD_ARCHIVE_PATH;
 }
 
+/**
+ * Archive paths for retired features. Bundles exported while those features
+ * existed still contain these entries; preflight and both importers must
+ * treat them as silent non-blocking skips (no conflict, no warning) so old
+ * backups stay restorable without noise, and the files are never written
+ * back to the workspace.
+ *
+ * `UPDATES.md` carried the retired update-bulletin release notes. Legacy
+ * bundles archived it as `prompts/UPDATES.md`; current-format bundles walk
+ * the workspace dir, so it appears as `workspace/UPDATES.md`. Both spellings
+ * must be retired — `DefaultPathResolver.resolve()` short-circuits them to
+ * `null` before any prefix handling so the workspace-format entry cannot
+ * resolve normally and recreate the file on import.
+ */
+export const RETIRED_ARCHIVE_PATHS: ReadonlySet<string> = new Set([
+  "prompts/UPDATES.md",
+  "workspace/UPDATES.md",
+]);
+
+export function isRetiredArchivePath(archivePath: string): boolean {
+  return RETIRED_ARCHIVE_PATHS.has(archivePath);
+}
+
 export function isConfigArchivePath(archivePath: string): boolean {
   return CONFIG_ARCHIVE_PATHS.has(archivePath);
 }

package/src/runtime/migrations/vbundle-importer.ts

@@ -322,7 +322,10 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
     const diskPath = pathResolver.resolve(fileEntry.path);
 
     if (!diskPath) {
-      // Unknown archive path — skip it
+      // Unknown archive path — skip it. Retired-feature paths (see
+      // `policy.RETIRED_ARCHIVE_PATHS`) are expected in legacy bundles and
+      // skip silently so the import report matches preflight; anything else
+      // unresolvable earns a warning.
       importedFiles.push({
         path: fileEntry.path,
         disk_path: "",
@@ -331,9 +334,11 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
         sha256: fileEntry.sha256,
         backup_path: null,
       });
-      warnings.push(
-        `Skipped "${fileEntry.path}": no known disk target for this archive path`,
-      );
+      if (!policy.isRetiredArchivePath(fileEntry.path)) {
+        warnings.push(
+          `Skipped "${fileEntry.path}": no known disk target for this archive path`,
+        );
+      }
       continue;
     }
 

package/src/runtime/migrations/vbundle-streaming-importer.ts

@@ -695,9 +695,14 @@ export async function streamCommitImport(
           sha256: expectedEntry.sha256,
           backup_path: null,
         });
-        warnings.push(
-          `Skipped "${archivePath}": no known disk target for this archive path`,
-        );
+        // Retired-feature paths (see `policy.RETIRED_ARCHIVE_PATHS`) are
+        // expected in legacy bundles and skip silently so the import report
+        // matches preflight; anything else unresolvable earns a warning.
+        if (!policy.isRetiredArchivePath(archivePath)) {
+          warnings.push(
+            `Skipped "${archivePath}": no known disk target for this archive path`,
+          );
+        }
         seen.add(archivePath);
         onProgress?.({
           archivePath,

package/src/runtime/pre-first-message-gate.ts

@@ -25,7 +25,7 @@
  * interaction resumes, so re-querying on miss is the correct behavior.)
  *
  * Callers should treat the gate as advisory + defense-in-depth: prefer to
- * skip at the service level (heartbeat, update-bulletin, etc.) so no run
+ * skip at the service level (heartbeat, etc.) so no run
  * row / conversation row is created at all, and rely on the gate inside
  * `runBackgroundJob` as the universal backstop.
  */

package/src/runtime/routes/__tests__/conversation-compaction-routes.test.ts

@@ -34,6 +34,7 @@ mock.module("../../../config/loader.js", () => ({
 // Source + conversation-crud module mocks
 // ---------------------------------------------------------------------
 
+import type { CompactionLogEvent } from "../../../memory/compaction-log-store-clickhouse.js";
 import type { LogRow } from "../../../memory/llm-request-log-store.js";
 
 interface FakeSourceState {
@@ -41,6 +42,9 @@ interface FakeSourceState {
   selectedCall: LogRow | null;
   turnBounds: { startTime: number; endTime: number } | null;
   compactionLogs: LogRow[];
+  /** null = compactionLogs destination not configured (legacy-only). */
+  compactionStoreEvents: CompactionLogEvent[] | null;
+  compactionStoreError: Error | null;
 }
 
 const state: FakeSourceState = {
@@ -48,6 +52,8 @@ const state: FakeSourceState = {
   selectedCall: null,
   turnBounds: null,
   compactionLogs: [],
+  compactionStoreEvents: null,
+  compactionStoreError: null,
 };
 
 // Records the inputs the handler passed to its collaborators so tests
@@ -63,8 +69,34 @@ const sourceCalls = {
     afterCreatedAt: number | null;
     beforeCreatedAt: number;
   }>,
+  getEventsBetweenArgs: [] as Array<{
+    conversationId: string;
+    afterStartedAt: number | null;
+    beforeStartedAt: number;
+  }>,
 };
 
+mock.module("../../../memory/compaction-log-store-clickhouse.js", () => ({
+  getCompactionLogStore: () =>
+    state.compactionStoreEvents === null && state.compactionStoreError === null
+      ? null
+      : {
+          getEventsBetween: async (
+            conversationId: string,
+            afterStartedAt: number | null,
+            beforeStartedAt: number,
+          ) => {
+            sourceCalls.getEventsBetweenArgs.push({
+              conversationId,
+              afterStartedAt,
+              beforeStartedAt,
+            });
+            if (state.compactionStoreError) throw state.compactionStoreError;
+            return state.compactionStoreEvents ?? [];
+          },
+        },
+}));
+
 mock.module("../../../memory/conversation-crud.js", () => ({
   getConversation: (id: string) =>
     state.conversation && state.conversation.id === id
@@ -105,6 +137,7 @@ mock.module("../../../memory/llm-request-log-source.js", () => ({
 
 // Imported AFTER the mocks so the handler picks up the fakes.
 import {
+  projectCompactionLogEventToTrailEvent,
   projectLogRowToCompactionTrailEvent,
   ROUTES,
 } from "../conversation-compaction-routes.js";
@@ -132,14 +165,52 @@ function fakeLogRow(overrides: Partial<LogRow> = {}): LogRow {
   };
 }
 
+function fakeCompactionLogEvent(
+  overrides: Partial<CompactionLogEvent> = {},
+): CompactionLogEvent {
+  return {
+    compactionId: "comp-1",
+    requestId: "req-1",
+    trigger: "budget",
+    startedAt: 3000,
+    finishedAt: 3500,
+    durationMs: 500,
+    preMessageCount: 12,
+    resultMessageCount: 4,
+    compacted: true,
+    previousEstimatedInputTokens: 900,
+    estimatedInputTokens: 300,
+    maxInputTokens: 1000,
+    thresholdTokens: 850,
+    compactedMessages: 10,
+    compactedPersistedMessages: 8,
+    preservedTailMessages: 2,
+    summaryCalls: 1,
+    summaryInputTokens: 880,
+    summaryOutputTokens: 120,
+    summaryModel: "test-model",
+    summaryFailed: false,
+    reason: "auto",
+    exhausted: false,
+    injectionMode: null,
+    autoCompressApplied: false,
+    summaryText: "summary text",
+    completed: true,
+    ...overrides,
+  };
+}
+
 beforeEach(() => {
   state.conversation = null;
   state.selectedCall = null;
   state.turnBounds = null;
   state.compactionLogs = [];
+  state.compactionStoreEvents = null;
+  state.compactionStoreError = null;
   sourceCalls.getRequestLogByIdArgs.length = 0;
   sourceCalls.getTurnTimeBoundsArgs.length = 0;
   sourceCalls.getCompactionLogsBetweenArgs.length = 0;
+  sourceCalls.getEventsBetweenArgs.length = 0;
 });
 
 // ---------------------------------------------------------------------
@@ -353,10 +424,180 @@ describe("handleGetCompactionTrail — happy path", () => {
   });
 });
 
+// ---------------------------------------------------------------------
+// Handler — compaction-log store path
+// ---------------------------------------------------------------------
+
+describe("handleGetCompactionTrail — compaction log store", () => {
+  test("serves the trail from the store and skips the legacy projection", async () => {
+    state.conversation = { id: "conv-1" };
+    state.selectedCall = fakeLogRow({
+      id: "call-1",
+      conversationId: "conv-1",
+      createdAt: 5000,
+    });
+    state.turnBounds = { startTime: 2000, endTime: 9000 };
+    state.compactionStoreEvents = [fakeCompactionLogEvent()];
+
+    const result = await handler({
+      pathParams: { id: "conv-1" },
+      queryParams: { callId: "call-1" },
+    });
+
+    // Same ±1ms-shifted turn window as the legacy path.
+    expect(sourceCalls.getEventsBetweenArgs).toEqual([
+      {
+        conversationId: "conv-1",
+        afterStartedAt: 1999,
+        beforeStartedAt: 9001,
+      },
+    ]);
+    expect(sourceCalls.getCompactionLogsBetweenArgs).toEqual([]);
+    expect(result.events).toEqual([
+      {
+        id: "comp-1",
+        createdAt: 3000,
+        model: "test-model",
+        provider: null,
+        inputTokens: 880,
+        outputTokens: 120,
+        durationMs: 500,
+        responsePreview: "summary text",
+        requestMessageCount: 12,
+        stopReason: "auto",
+        estimatedCostUsd: null,
+      },
+    ]);
+  });
+
+  test("falls back to the legacy projection when the store has no rows for the window", async () => {
+    state.conversation = { id: "conv-1" };
+    state.selectedCall = fakeLogRow({
+      id: "call-1",
+      conversationId: "conv-1",
+      createdAt: 5000,
+    });
+    state.turnBounds = { startTime: 2000, endTime: 9000 };
+    state.compactionStoreEvents = [];
+    state.compactionLogs = [
+      fakeLogRow({ id: "compaction-legacy", conversationId: "conv-1" }),
+    ];
+
+    const result = await handler({
+      pathParams: { id: "conv-1" },
+      queryParams: { callId: "call-1" },
+    });
+
+    expect(sourceCalls.getEventsBetweenArgs).toHaveLength(1);
+    expect(sourceCalls.getCompactionLogsBetweenArgs).toHaveLength(1);
+    expect(result.events).toHaveLength(1);
+    expect((result.events[0] as { id: string }).id).toBe("compaction-legacy");
+  });
+
+  test("falls back to the legacy projection when the store read throws", async () => {
+    state.conversation = { id: "conv-1" };
+    state.selectedCall = fakeLogRow({
+      id: "call-1",
+      conversationId: "conv-1",
+      createdAt: 5000,
+    });
+    state.turnBounds = { startTime: 2000, endTime: 9000 };
+    state.compactionStoreError = new Error("clickhouse unreachable");
+    state.compactionLogs = [
+      fakeLogRow({ id: "compaction-legacy", conversationId: "conv-1" }),
+    ];
+
+    const result = await handler({
+      pathParams: { id: "conv-1" },
+      queryParams: { callId: "call-1" },
+    });
+
+    expect(sourceCalls.getCompactionLogsBetweenArgs).toHaveLength(1);
+    expect(result.events).toHaveLength(1);
+    expect((result.events[0] as { id: string }).id).toBe("compaction-legacy");
+  });
+
+  test("falls back to the legacy projection when any event is missing its end row", async () => {
+    state.conversation = { id: "conv-1" };
+    state.selectedCall = fakeLogRow({
+      id: "call-1",
+      conversationId: "conv-1",
+      createdAt: 5000,
+    });
+    state.turnBounds = { startTime: 2000, endTime: 9000 };
+    state.compactionStoreEvents = [
+      fakeCompactionLogEvent(),
+      fakeCompactionLogEvent({
+        compactionId: "comp-2",
+        finishedAt: null,
+        durationMs: null,
+        completed: false,
+      }),
+    ];
+    state.compactionLogs = [
+      fakeLogRow({ id: "compaction-legacy", conversationId: "conv-1" }),
+    ];
+
+    const result = await handler({
+      pathParams: { id: "conv-1" },
+      queryParams: { callId: "call-1" },
+    });
+
+    expect(sourceCalls.getEventsBetweenArgs).toHaveLength(1);
+    expect(sourceCalls.getCompactionLogsBetweenArgs).toHaveLength(1);
+    expect(result.events).toHaveLength(1);
+    expect((result.events[0] as { id: string }).id).toBe("compaction-legacy");
+  });
+});
+
 // ---------------------------------------------------------------------
 // Projection unit tests
 // ---------------------------------------------------------------------
 
+describe("projectCompactionLogEventToTrailEvent", () => {
+  test("maps a completed event onto the wire shape", () => {
+    const event = projectCompactionLogEventToTrailEvent(
+      fakeCompactionLogEvent(),
+    );
+    expect(event).toEqual({
+      id: "comp-1",
+      createdAt: 3000,
+      model: "test-model",
+      provider: null,
+      inputTokens: 880,
+      outputTokens: 120,
+      durationMs: 500,
+      responsePreview: "summary text",
+      requestMessageCount: 12,
+      stopReason: "auto",
+      estimatedCostUsd: null,
+    });
+  });
+
+  test("maps an incomplete (start-only) event with nulls for end-phase fields", () => {
+    const event = projectCompactionLogEventToTrailEvent(
+      fakeCompactionLogEvent({
+        completed: false,
+        finishedAt: null,
+        durationMs: null,
+        summaryInputTokens: null,
+        summaryOutputTokens: null,
+        summaryModel: null,
+        reason: null,
+        summaryText: null,
+      }),
+    );
+    expect(event.durationMs).toBeNull();
+    expect(event.model).toBeNull();
+    expect(event.inputTokens).toBeNull();
+    expect(event.outputTokens).toBeNull();
+    expect(event.responsePreview).toBeNull();
+    expect(event.stopReason).toBeNull();
+    // The start row always carries the pre-compaction message count.
+    expect(event.requestMessageCount).toBe(12);
+  });
+});
+
 describe("projectLogRowToCompactionTrailEvent", () => {
   test("returns null for every summary-derived field when payloads are empty", () => {
     const event = projectLogRowToCompactionTrailEvent(fakeLogRow());