@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

package/src/persistence/migrations/__tests__/run-migrations.test.ts

@@ -346,6 +346,161 @@ describe("runMigrationSteps — checkpointing", () => {
     expect(result.skipped).toEqual([]);
   });
 
+  test("defers a step whose dependency failed this boot, without checkpointing it", async () => {
+    /**
+     * A step must not run against the missing state a failed prerequisite was
+     * supposed to create. It is deferred — not run, not checkpointed — and
+     * reported in `deferred` so readiness gating can surface it.
+     */
+
+    // GIVEN a failing creator step and a dependent step
+    const calls = { creator: 0, dependent: 0 };
+    const steps: MigrationStep[] = [
+      {
+        name: "creatorStep",
+        run: () => {
+          calls.creator++;
+          throw new Error("creator failed");
+        },
+      },
+      {
+        name: "dependentStep",
+        dependsOn: ["creatorStep"],
+        run: () => {
+          calls.dependent++;
+        },
+      },
+    ];
+    const db = createTestDb();
+
+    // WHEN the runner executes
+    const result = await runMigrationSteps(db, steps);
+
+    // THEN the dependent step never ran and is reported deferred
+    expect(calls.dependent).toBe(0);
+    expect(result.failed).toEqual(["creatorStep"]);
+    expect(result.deferred).toEqual(["dependentStep"]);
+
+    // AND nothing was written to the ledger for the deferred step —
+    // no 'started' marker and no applied checkpoint
+    const rows = getSqliteFrom(db)
+      .query(
+        `SELECT 1 FROM memory_checkpoints WHERE key = 'step:dependentStep'`,
+      )
+      .all();
+    expect(rows).toEqual([]);
+  });
+
+  test("a deferred step runs on the next boot once its dependency succeeds", async () => {
+    /**
+     * Deferral is a retry mechanism, not a permanent skip: once the
+     * prerequisite is applied on a later boot, the deferred step runs.
+     */
+
+    // GIVEN a creator that fails on its first run and a dependent step
+    const calls = { creator: 0, dependent: 0 };
+    const steps: MigrationStep[] = [
+      {
+        name: "creatorStep",
+        run: () => {
+          calls.creator++;
+          if (calls.creator === 1) {
+            throw new Error("transient failure");
+          }
+        },
+      },
+      {
+        name: "dependentStep",
+        dependsOn: ["creatorStep"],
+        run: () => {
+          calls.dependent++;
+        },
+      },
+    ];
+    const db = createTestDb();
+
+    // WHEN the first boot defers the dependent step
+    const first = await runMigrationSteps(db, steps);
+    expect(first.deferred).toEqual(["dependentStep"]);
+
+    // AND the next boot retries
+    const second = await runMigrationSteps(db, steps);
+
+    // THEN both steps run and nothing is deferred or failed
+    expect(calls).toEqual({ creator: 2, dependent: 1 });
+    expect(second.applied).toEqual(["creatorStep", "dependentStep"]);
+    expect(second.deferred).toEqual([]);
+    expect(second.failed).toEqual([]);
+  });
+
+  test("a step depending on an earlier same-boot step runs without deferral", async () => {
+    /**
+     * The runner adds each success to the in-memory applied set, so a
+     * dependency satisfied earlier in the same boot does not defer the
+     * dependent step — creator and dependent can ship in one release.
+     */
+
+    // GIVEN a creator and a dependent, both pending
+    const order: string[] = [];
+    const steps: MigrationStep[] = [
+      {
+        name: "creatorStep",
+        run: () => {
+          order.push("creator");
+        },
+      },
+      {
+        name: "dependentStep",
+        dependsOn: ["creatorStep"],
+        run: () => {
+          order.push("dependent");
+        },
+      },
+    ];
+    const db = createTestDb();
+
+    // WHEN the runner executes both in one boot
+    const result = await runMigrationSteps(db, steps);
+
+    // THEN they run in order with no deferral
+    expect(order).toEqual(["creator", "dependent"]);
+    expect(result.applied).toEqual(["creatorStep", "dependentStep"]);
+    expect(result.deferred).toEqual([]);
+  });
+
+  test("a step whose dependency is already checkpointed runs normally", async () => {
+    /**
+     * A dependency applied on a prior boot satisfies dependsOn through the
+     * checkpoint ledger, so the dependent step runs even though the creator
+     * was skipped this boot.
+     */
+
+    // GIVEN a database where the creator step was applied on a prior boot
+    const creator: MigrationStep = {
+      name: "creatorStep",
+      run: () => {
+        // no-op
+      },
+    };
+    const db = createTestDb();
+    await runMigrationSteps(db, [creator]);
+
+    // WHEN a dependent step ships in a later release
+    const dependent: MigrationStep = {
+      name: "dependentStep",
+      dependsOn: ["creatorStep"],
+      run: () => {
+        // no-op
+      },
+    };
+    const result = await runMigrationSteps(db, [creator, dependent]);
+
+    // THEN the dependent step runs while the creator is skipped
+    expect(result.skipped).toEqual(["creatorStep"]);
+    expect(result.applied).toEqual(["dependentStep"]);
+    expect(result.deferred).toEqual([]);
+  });
+
   test("writes 'started' marker before running each step", async () => {
     const db = createTestDb();
     const raw = getSqliteFrom(db);

package/src/persistence/migrations/helpers/relocation.ts

@@ -6,6 +6,11 @@ import {
   parseChangesFromStdout,
   runAsyncSqlite,
 } from "../../db-async-query.js";
+import {
+  type DrizzleDb,
+  getMemorySqlite,
+  getSqliteFrom,
+} from "../../db-connection.js";
 
 const log = getLogger("memory-db");
 
@@ -145,7 +150,9 @@ export async function drainStagedTable(
   const staging = `${table}${RELOCATING_SUFFIX}`;
 
   // Nothing to do once the staging table is gone (drain finished previously).
-  if (!tableExistsInMain(raw, staging)) return;
+  if (!tableExistsInMain(raw, staging)) {
+    return;
+  }
 
   // Build a select list from the staging table's actual columns: apply any
   // per-column transform, copy a present column verbatim, NULL-fill an absent
@@ -228,3 +235,39 @@ export async function drainStagedTable(
   }
   log.info({ table }, "relocation: complete — staging dropped");
 }
+
+/**
+ * Run one memory-table relocation end to end: ensure the table's schema on the
+ * memory connection, stage `main.<table>` aside via
+ * {@link stageTableForRelocation}, then drain the staged rows into the memory
+ * DB in awaited batches via {@link drainStagedTable} per the spec. Because the
+ * drain is awaited as part of the migration step, later startup work observes
+ * the finished move.
+ *
+ * Throws (rather than returning) if the memory database cannot be opened, so
+ * the runner records the step as failed instead of applied and retries it on a
+ * later boot — never renaming the source aside without a target to write to,
+ * and never marking the relocation done while it has not happened. The throw
+ * is caught per-step by the runner, so startup is not aborted.
+ */
+export async function runMemoryTableRelocation(
+  database: DrizzleDb,
+  spec: RelocationSpec,
+  ensureSchema: (memoryRaw: Database) => void,
+): Promise<void> {
+  const memoryRaw = getMemorySqlite();
+  if (!memoryRaw) {
+    throw new Error(
+      `memory database unavailable — deferring ${spec.table} relocation`,
+    );
+  }
+
+  ensureSchema(memoryRaw);
+
+  const raw = getSqliteFrom(database);
+  const needsDrain = stageTableForRelocation(raw, spec.table);
+
+  if (needsDrain) {
+    await drainStagedTable(raw, spec);
+  }
+}

package/src/persistence/migrations/run-migrations.ts

@@ -109,6 +109,8 @@ export interface MigrationRunResult {
   failed: string[];
   /** Steps skipped because a prior run already applied them. */
   skipped: string[];
+  /** Steps not run because a declared dependsOn prerequisite is not applied. */
+  deferred: string[];
 }
 
 /**
@@ -213,6 +215,11 @@ export function recoverCrashedMigrations(database: DrizzleDb): string[] {
  * Individual step failures are caught and logged so one broken migration does
  * not prevent independent later ones from succeeding; a failed step is not
  * checkpointed and is retried on the next boot.
+ *
+ * A step whose declared `dependsOn` prerequisites are not all applied — because
+ * a dependency failed this boot or was never run — is deferred rather than
+ * executed against missing state. A deferred step writes nothing to the ledger,
+ * so it retries on the next boot once its prerequisites have been applied.
  */
 export async function runMigrationSteps(
   database: DrizzleDb,
@@ -242,6 +249,7 @@ export async function runMigrationSteps(
   const failed: string[] = [];
   const skipped: string[] = [];
   const ran: string[] = [];
+  const deferred: string[] = [];
 
   const totalSteps = steps.length;
   for (const [index, step] of steps.entries()) {
@@ -257,6 +265,19 @@ export async function runMigrationSteps(
       continue;
     }
 
+    // Defer a step whose prerequisites are not applied rather than run it
+    // against missing state. Nothing is written to the ledger — no 'started'
+    // marker, no checkpoint — so the step retries on the next boot.
+    const missing = (obj.dependsOn ?? []).filter((dep) => !applied.has(dep));
+    if (missing.length > 0) {
+      deferred.push(name);
+      log.warn(
+        { migration: name, missing, step: stepNumber, totalSteps },
+        `Deferring migration "${name}" — prerequisites not applied: ${missing.join(", ")}`,
+      );
+      continue;
+    }
+
     try {
       if (checkpointable) {
         markStarted.run(`${STEP_CHECKPOINT_PREFIX}${name}`, Date.now());
@@ -276,6 +297,9 @@ export async function runMigrationSteps(
       if (checkpointable) {
         markApplied.run(`${STEP_CHECKPOINT_PREFIX}${name}`, Date.now());
         ran.push(name);
+        // Record the success in the in-memory set too, so a later step in this
+        // same boot can depend on it without being deferred.
+        applied.add(name);
       }
     } catch (err) {
       // Leave the 'started' marker in place (if one was written) —
@@ -289,7 +313,7 @@ export async function runMigrationSteps(
     }
   }
 
-  return { applied: ran, failed, skipped };
+  return { applied: ran, failed, skipped, deferred };
 }
 
 /**

package/src/persistence/schema/infrastructure.ts

@@ -170,6 +170,10 @@ export const llmRequestLogs = sqliteTable(
   ],
 );
 
+// Per-turn diagnostics for memory recall, recording hit counts, latency,
+// and the injected text. Lives in the dedicated memory database
+// (`assistant-memory.db`), not main — access it via the memory connection
+// (`getMemoryDb()` / `getMemorySqlite()`).
 export const memoryRecallLogs = sqliteTable(
   "memory_recall_logs",
   {
@@ -202,6 +206,9 @@ export const memoryRecallLogs = sqliteTable(
   ],
 );
 
+// Per-turn log of memory-v2 concept/skill activations. Lives in the
+// dedicated memory database (`assistant-memory.db`), not main — access it
+// via the memory connection (`getMemoryDb()` / `getMemorySqlite()`).
 export const memoryV2ActivationLogs = sqliteTable(
   "memory_v2_activation_logs",
   {
@@ -277,6 +284,8 @@ export const llmUsageEvents = sqliteTable(
 // One row per conversation started on the activation-rail bootstrap template.
 // Lets the activation funnel telemetry scope its events to activation
 // conversations without inspecting the bootstrap template at emit time.
+// Lives in the dedicated memory database (`assistant-memory.db`), not main —
+// access it via the memory connection (`getMemoryDb()` / `getMemorySqlite()`).
 export const activationSessions = sqliteTable("activation_sessions", {
   conversationId: text("conversation_id").primaryKey(),
   createdAt: integer("created_at").notNull(),

package/src/persistence/schema/memory-core.ts

@@ -72,6 +72,9 @@ export const memoryEmbeddings = sqliteTable(
   ],
 );
 
+// Background job queue for the memory plugin. Lives in the dedicated memory
+// database (`assistant-memory.db`), not main — access it via the memory
+// connection (`getMemoryDb()` / `getMemorySqlite()`).
 export const memoryJobs = sqliteTable("memory_jobs", {
   id: text("id").primaryKey(),
   type: text("type").notNull(),

package/src/persistence/schema/memory-injection.ts

@@ -44,6 +44,8 @@ export const memoryV3EverInjected = sqliteTable(
 );
 
 // Per-turn log of which memory-v3 cards were selected, with lane attribution.
+// Lives in the dedicated memory database (`assistant-memory.db`), not main —
+// access it via the memory connection (`getMemoryDb()` / `getMemorySqlite()`).
 export const memoryV3Selections = sqliteTable(
   "memory_v3_selections",
   {

package/src/persistence/steps.ts

@@ -443,6 +443,10 @@ import { migrateMoveSkillLoadedEventsToTelemetryDb } from "./migrations/332-move
 import { migrateCreateTelemetryEventsTable } from "./migrations/333-create-telemetry-events-table.js";
 import { migrateBackfillTelemetryEventsOutbox } from "./migrations/334-backfill-telemetry-events-outbox.js";
 import { migrateCollapseMemoryEmbedBacklog } from "./migrations/335-collapse-memory-embed-backlog.js";
+import { migrateMoveMemoryV2ActivationLogsToMemoryDb } from "./migrations/336-move-memory-v2-activation-logs-to-memory-db.js";
+import { migrateMoveMemoryRecallLogsToMemoryDb } from "./migrations/337-move-memory-recall-logs-to-memory-db.js";
+import { migrateMoveMemoryV3SelectionsToMemoryDb } from "./migrations/338-move-memory-v3-selections-to-memory-db.js";
+import { migrateMoveActivationSessionsToMemoryDb } from "./migrations/339-move-activation-sessions-to-memory-db.js";
 import type { MigrationStep } from "./migrations/run-migrations.js";
 
 export const migrationSteps: MigrationStep[] = [
@@ -1357,4 +1361,36 @@ export const migrationSteps: MigrationStep[] = [
   migrateCreateTelemetryEventsTable,
   migrateBackfillTelemetryEventsOutbox,
   migrateCollapseMemoryEmbedBacklog,
+  {
+    name: "migrateMoveMemoryV2ActivationLogsToMemoryDb",
+    run: migrateMoveMemoryV2ActivationLogsToMemoryDb,
+    // 256's backfill reads memory_v2_activation_logs from main, so the move
+    // must not run on a database where 256 is still pending.
+    dependsOn: [
+      "migrateMemoryV2ActivationLogs",
+      "migrateMemoryV2InjectionEvents",
+    ],
+  },
+  {
+    name: "migrateMoveMemoryRecallLogsToMemoryDb",
+    run: migrateMoveMemoryRecallLogsToMemoryDb,
+    dependsOn: [
+      "migrateCreateMemoryRecallLogs",
+      "migrateMemoryRecallLogsQueryContext",
+      "migrateDeletePrivateConversations",
+    ],
+  },
+  {
+    name: "migrateMoveMemoryV3SelectionsToMemoryDb",
+    run: migrateMoveMemoryV3SelectionsToMemoryDb,
+    dependsOn: [
+      "migrateAddMemoryV3Selections",
+      "migrateMemoryV3SelectionsMessageIdAndSections",
+    ],
+  },
+  {
+    name: "migrateMoveActivationSessionsToMemoryDb",
+    run: migrateMoveActivationSessionsToMemoryDb,
+    dependsOn: ["createActivationSessionsTable"],
+  },
 ];

package/src/platform/client.test.ts

@@ -287,34 +287,13 @@ describe("VellumPlatformClient", () => {
       });
     });
 
-    test("coerced false with share_analytics_chosen=false (never chose) maps to true", async () => {
+    test("explicit false is an opt-out", async () => {
       globalThis.fetch = mock(
         async () =>
           new Response(
             JSON.stringify({
               share_analytics: false,
-              share_analytics_chosen: false,
-              share_diagnostics: true,
-              share_diagnostics_accepted_version: "2026-06-18",
-            }),
-            { status: 200 },
-          ),
-      ) as unknown as typeof globalThis.fetch;
-
-      const client = await VellumPlatformClient.create();
-      const consent = await client!.getOwnerConsent();
-      expect(consent!.shareAnalytics).toBe(true);
-    });
-
-    test("explicit false with share_analytics_chosen=true stays an opt-out", async () => {
-      globalThis.fetch = mock(
-        async () =>
-          new Response(
-            JSON.stringify({
-              share_analytics: false,
-              share_analytics_chosen: true,
               share_diagnostics: false,
-              share_diagnostics_chosen: true,
               share_diagnostics_accepted_version: "2026-06-18",
             }),
             { status: 200 },
@@ -330,28 +309,6 @@ describe("VellumPlatformClient", () => {
       });
     });
 
-    test("false without a *_chosen field (older platform) stays authoritative", async () => {
-      globalThis.fetch = mock(
-        async () =>
-          new Response(
-            JSON.stringify({
-              share_analytics: false,
-              share_diagnostics: false,
-              share_diagnostics_accepted_version: "",
-            }),
-            { status: 200 },
-          ),
-      ) as unknown as typeof globalThis.fetch;
-
-      const client = await VellumPlatformClient.create();
-      const consent = await client!.getOwnerConsent();
-      expect(consent).toEqual({
-        shareAnalytics: false,
-        shareDiagnostics: false,
-        shareDiagnosticsAcceptedVersion: "",
-      });
-    });
-
     test("null share_diagnostics (owner never chose) maps to true with the version gate still closed", async () => {
       globalThis.fetch = mock(
         async () =>

package/src/platform/client.ts

@@ -18,11 +18,9 @@ let _missingPrereqsWarned = false;
 
 export interface OwnerConsent {
   /**
-   * Telemetry is opt-out: a null wire value (the owner was never shown the
-   * choice) maps to `true` here — only an explicit opt-out disables sharing.
-   * A `false` accompanied by `share_analytics_chosen: false` is the platform
-   * coercing a never-chose null to a strict boolean, not a real opt-out, so
-   * it also maps to `true`.
+   * Telemetry is opt-out: the owner-consent endpoint returns effective
+   * values (a never-chose null is served as consented), so an explicit
+   * `false` is the only thing that disables sharing.
    */
   shareAnalytics: boolean;
   /** Same opt-out semantics as {@link shareAnalytics}. */
@@ -132,10 +130,11 @@ export class VellumPlatformClient {
   /**
    * Fetch the platform owner's telemetry consent for this assistant.
    *
+   * The endpoint returns effective consent values (a never-chose null is
+   * served as consented); an explicit `false` is the only disable.
+   *
    * Returns `null` whenever the consent is unknown — missing assistant id,
-   * any non-2xx response (e.g. 404 before the endpoint is deployed), a
-   * malformed body, or a network error. Callers treat `null` as default-off.
-   * Never throws.
+   * any non-2xx response, a malformed body, or a network error. Never throws.
    */
   async getOwnerConsent(): Promise<OwnerConsent | null> {
     if (!this.assistantId) {
@@ -156,9 +155,7 @@ export class VellumPlatformClient {
 
       const body = (await res.json()) as {
         share_analytics?: unknown;
-        share_analytics_chosen?: unknown;
         share_diagnostics?: unknown;
-        share_diagnostics_chosen?: unknown;
         share_diagnostics_accepted_version?: unknown;
       };
       if (
@@ -172,16 +169,9 @@ export class VellumPlatformClient {
       }
 
       return {
-        // Opt-out: anything but an explicit false enables sharing. A false
-        // with `*_chosen: false` is a platform-coerced never-chose default
-        // (not a real opt-out), so it enables too. An absent `*_chosen`
-        // (older platform) leaves false authoritative.
-        shareAnalytics:
-          body.share_analytics !== false ||
-          body.share_analytics_chosen === false,
-        shareDiagnostics:
-          body.share_diagnostics !== false ||
-          body.share_diagnostics_chosen === false,
+        // Opt-out: anything but an explicit false enables sharing.
+        shareAnalytics: body.share_analytics !== false,
+        shareDiagnostics: body.share_diagnostics !== false,
         // Back-compat: an older platform that doesn't return this field yields
         // "" → fails the trace-collection version gate → fail-closed (no trace).
         shareDiagnosticsAcceptedVersion: