@vellumai/assistant 0.7.0 → 0.7.2

package/src/__tests__/migration-export-http.test.ts

@@ -57,13 +57,13 @@ mock.module("../config/env.js", () => ({
   getRuntimeGatewayOriginSecret: () => undefined,
 }));
 
+import { defaultV1Options } from "../runtime/migrations/__tests__/v1-test-helpers.js";
 import { validateVBundle } from "../runtime/migrations/vbundle-validator.js";
 import {
   handleMigrationExport,
   handleMigrationValidate,
 } from "../runtime/routes/migration-routes.js";
 import { callHandler } from "./helpers/call-route-handler.js";
-
 // Test fixture data: a minimal SQLite header to simulate a real database file
 const SQLITE_HEADER = new Uint8Array([
   0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74,
@@ -143,7 +143,7 @@ describe("handleMigrationExport", () => {
     );
     expect(res.headers.get("Content-Length")).toBeDefined();
     expect(Number(res.headers.get("Content-Length"))).toBeGreaterThan(0);
-    expect(res.headers.get("X-Vbundle-Schema-Version")).toBe("1.0");
+    expect(res.headers.get("X-Vbundle-Schema-Version")).toBe("1");
     expect(res.headers.get("X-Vbundle-Manifest-Sha256")).toBeDefined();
     expect(res.headers.get("X-Vbundle-Manifest-Sha256")!.length).toBe(64);
   });
@@ -176,25 +176,25 @@ describe("handleMigrationExport", () => {
     const validationResult = validateVBundle(archiveData);
     const manifest = validationResult.manifest!;
 
-    expect(manifest.schema_version).toBe("1.0");
-    expect(manifest.source).toBe("runtime-export");
+    expect(manifest.schema_version).toBe(1);
+    expect(manifest.bundle_id).toBeDefined();
     expect(manifest.created_at).toBeDefined();
-    expect(manifest.manifest_sha256).toBeDefined();
+    expect(manifest.checksum).toBeDefined();
 
     // Verify file entries — workspace walk uses workspace/ prefix
-    const filePaths = manifest.files.map((f) => f.path);
+    const filePaths = manifest.contents.map((f) => f.path);
     expect(filePaths).toContain("workspace/data/db/assistant.db");
     expect(filePaths).toContain("workspace/config.json");
 
     // Verify each file entry has proper sha256 and size
-    for (const file of manifest.files) {
+    for (const file of manifest.contents) {
       expect(file.sha256).toBeDefined();
       expect(file.sha256.length).toBe(64);
-      expect(file.size).toBeGreaterThanOrEqual(0);
+      expect(file.size_bytes).toBeGreaterThanOrEqual(0);
     }
   });
 
-  test("custom description from JSON body is used in manifest", async () => {
+  test("custom description in JSON body is accepted but no longer surfaced in manifest", async () => {
     const req = new Request("http://localhost/v1/migrations/export", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -206,9 +206,9 @@ describe("handleMigrationExport", () => {
     const archiveData = new Uint8Array(arrayBuffer);
 
     const validationResult = validateVBundle(archiveData);
-    const manifest = validationResult.manifest!;
-
-    expect(manifest.description).toBe("My custom export description");
+    expect(validationResult.is_valid).toBe(true);
+    // v1 manifests intentionally drop the legacy `description` field —
+    // assert the export still succeeds even though the body carried one.
   });
 
   test("invalid JSON body is gracefully handled with defaults", async () => {
@@ -312,20 +312,20 @@ describe("export data population", () => {
     const validationResult = validateVBundle(archiveData);
     const manifest = validationResult.manifest!;
 
-    const dbFile = manifest.files.find(
+    const dbFile = manifest.contents.find(
       (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
-    expect(dbFile!.size).toBe(SQLITE_HEADER.length);
+    expect(dbFile!.size_bytes).toBe(SQLITE_HEADER.length);
 
-    const configFile = manifest.files.find(
+    const configFile = manifest.contents.find(
       (f) => f.path === "workspace/config.json",
     );
     expect(configFile).toBeDefined();
     const expectedConfigSize = Buffer.byteLength(
       JSON.stringify(TEST_CONFIG, null, 2) + "\n",
     );
-    expect(configFile!.size).toBe(expectedConfigSize);
+    expect(configFile!.size_bytes).toBe(expectedConfigSize);
   });
 
   test("manifest checksums match actual file content", async () => {
@@ -340,7 +340,7 @@ describe("export data population", () => {
     const validationResult = validateVBundle(archiveData);
     const manifest = validationResult.manifest!;
 
-    for (const fileEntry of manifest.files) {
+    for (const fileEntry of manifest.contents) {
       const tarEntry = entries.find((e) => e.name === fileEntry.path);
       expect(tarEntry).toBeDefined();
       expect(sha256Hex(tarEntry!.data)).toBe(fileEntry.sha256);
@@ -358,12 +358,12 @@ describe("export data population", () => {
     const validationResult = validateVBundle(archiveData);
     const manifest = validationResult.manifest!;
 
-    const dbFile = manifest.files.find(
+    const dbFile = manifest.contents.find(
       (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
     // The skeleton used size 0 — real export should have actual content
-    expect(dbFile!.size).toBeGreaterThan(0);
+    expect(dbFile!.size_bytes).toBeGreaterThan(0);
   });
 
   test("config content is real JSON (not empty object placeholder)", async () => {
@@ -390,17 +390,23 @@ describe("export data population", () => {
 // ---------------------------------------------------------------------------
 
 describe("export graceful fallback", () => {
-  test("nonexistent workspace produces valid archive with no files", async () => {
+  test("nonexistent workspace produces archive that fails the v1 contents refine", async () => {
     const { buildExportVBundle } =
       await import("../runtime/migrations/vbundle-builder.js");
 
     const result = buildExportVBundle({
       workspaceDir: join(testDir, "nonexistent-workspace"),
+      ...defaultV1Options(),
     });
 
+    // Under v1, every bundle MUST declare a `data/db/assistant.db` (or
+    // `workspace/data/db/assistant.db`) entry. A nonexistent workspace
+    // produces an empty contents array, which the validator's `.refine()`
+    // rejects. Documenting this so a future regression on the workspace
+    // walk doesn't silently produce a structurally-empty bundle.
     const validationResult = validateVBundle(result.archive);
-    expect(validationResult.is_valid).toBe(true);
-    expect(result.manifest.files).toHaveLength(0);
+    expect(validationResult.is_valid).toBe(false);
+    expect(result.manifest.contents).toHaveLength(0);
   });
 
   test("workspace walk includes db and config under workspace/ prefix", async () => {
@@ -409,22 +415,23 @@ describe("export graceful fallback", () => {
 
     const result = buildExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     const validationResult = validateVBundle(result.archive);
     expect(validationResult.is_valid).toBe(true);
 
-    const dbFile = result.manifest.files.find(
+    const dbFile = result.manifest.contents.find(
       (f) => f.path === "workspace/data/db/assistant.db",
     );
     expect(dbFile).toBeDefined();
-    expect(dbFile!.size).toBeGreaterThan(0);
+    expect(dbFile!.size_bytes).toBeGreaterThan(0);
 
-    const configFile = result.manifest.files.find(
+    const configFile = result.manifest.contents.find(
       (f) => f.path === "workspace/config.json",
     );
     expect(configFile).toBeDefined();
-    expect(configFile!.size).toBeGreaterThan(0);
+    expect(configFile!.size_bytes).toBeGreaterThan(0);
   });
 });
 

package/src/__tests__/migration-export-streaming.test.ts

@@ -55,12 +55,12 @@ mock.module("../config/env.js", () => ({
   setIngressPublicBaseUrl: () => {},
 }));
 
+import { defaultV1Options } from "../runtime/migrations/__tests__/v1-test-helpers.js";
 import {
   buildExportVBundle,
   streamExportVBundle,
 } from "../runtime/migrations/vbundle-builder.js";
 import { validateVBundle } from "../runtime/migrations/vbundle-validator.js";
-
 // Test fixture data: a minimal SQLite header to simulate a real database file
 const SQLITE_HEADER = new Uint8Array([
   0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74,
@@ -146,6 +146,7 @@ describe("streamExportVBundle", () => {
   test("returns a temp file that exists on disk", async () => {
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     try {
@@ -159,13 +160,14 @@ describe("streamExportVBundle", () => {
   test("manifest contains correct SHA-256 checksums for all files", async () => {
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     try {
       const archiveData = new Uint8Array(readFileSync(result.tempPath));
       const entries = parseTarEntries(archiveData);
 
-      for (const fileEntry of result.manifest.files) {
+      for (const fileEntry of result.manifest.contents) {
         const tarEntry = entries.find((e) => e.name === fileEntry.path);
         expect(tarEntry).toBeDefined();
         expect(sha256Hex(tarEntry!.data)).toBe(fileEntry.sha256);
@@ -178,11 +180,13 @@ describe("streamExportVBundle", () => {
   test("decompressed archive produces same files as buildExportVBundle", async () => {
     const streamResult = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     try {
       const syncResult = buildExportVBundle({
         workspaceDir: testDir,
+        ...defaultV1Options(),
       });
 
       const streamArchiveData = new Uint8Array(
@@ -212,10 +216,10 @@ describe("streamExportVBundle", () => {
       }
 
       // Same manifest file entries (excluding timing fields)
-      const streamManifestFiles = streamResult.manifest.files
+      const streamManifestFiles = streamResult.manifest.contents
         .slice()
         .sort((a, b) => a.path.localeCompare(b.path));
-      const syncManifestFiles = syncResult.manifest.files
+      const syncManifestFiles = syncResult.manifest.contents
         .slice()
         .sort((a, b) => a.path.localeCompare(b.path));
 
@@ -225,8 +229,8 @@ describe("streamExportVBundle", () => {
       expect(streamManifestFiles.map((f) => f.sha256)).toEqual(
         syncManifestFiles.map((f) => f.sha256),
       );
-      expect(streamManifestFiles.map((f) => f.size)).toEqual(
-        syncManifestFiles.map((f) => f.size),
+      expect(streamManifestFiles.map((f) => f.size_bytes)).toEqual(
+        syncManifestFiles.map((f) => f.size_bytes),
       );
     } finally {
       await streamResult.cleanup();
@@ -236,6 +240,7 @@ describe("streamExportVBundle", () => {
   test("cleanup removes the temp file", async () => {
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     expect(existsSync(result.tempPath)).toBe(true);
@@ -252,6 +257,7 @@ describe("streamExportVBundle round-trip", () => {
   test("streaming archive passes validateVBundle with matching manifest", async () => {
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     try {
@@ -266,15 +272,15 @@ describe("streamExportVBundle round-trip", () => {
       expect(validationResult.manifest!.schema_version).toBe(
         result.manifest.schema_version,
       );
-      expect(validationResult.manifest!.manifest_sha256).toBe(
-        result.manifest.manifest_sha256,
+      expect(validationResult.manifest!.checksum).toBe(
+        result.manifest.checksum,
       );
 
       // Verify file entries match
       const validatedFiles = validationResult
-        .manifest!.files.slice()
+        .manifest!.contents.slice()
         .sort((a, b) => a.path.localeCompare(b.path));
-      const resultFiles = result.manifest.files
+      const resultFiles = result.manifest.contents
         .slice()
         .sort((a, b) => a.path.localeCompare(b.path));
 
@@ -316,6 +322,7 @@ describe("streamExportVBundle config sanitization", () => {
 
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     try {
@@ -359,6 +366,7 @@ describe("streamExportVBundle cleanup", () => {
   test("calling cleanup twice does not throw", async () => {
     const result = await streamExportVBundle({
       workspaceDir: testDir,
+      ...defaultV1Options(),
     });
 
     await result.cleanup();

package/src/__tests__/migration-export-to-gcs.test.ts

@@ -242,7 +242,12 @@ describe("handleMigrationExportToGcs — happy path", () => {
         }),
       });
 
-      const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
       expect(res.status).toBe(202);
 
       const body = (await res.json()) as AcceptedResponse;
@@ -275,7 +280,7 @@ describe("handleMigrationExportToGcs — happy path", () => {
       const validation = validateVBundle(new Uint8Array(capturedBody!));
       expect(validation.is_valid).toBe(true);
       expect(validation.errors).toHaveLength(0);
-      expect(validation.manifest?.manifest_sha256).toBe(result.sha256);
+      expect(validation.manifest?.checksum).toBe(result.sha256);
     } finally {
       await fixture.close();
     }
@@ -319,7 +324,12 @@ describe("handleMigrationExportToGcs — concurrency", () => {
           }),
         },
       );
-      const firstRes = await callHandler(handleMigrationExportToGcs, firstReq, undefined, 202);
+      const firstRes = await callHandler(
+        handleMigrationExportToGcs,
+        firstReq,
+        undefined,
+        202,
+      );
       expect(firstRes.status).toBe(202);
       const firstBody = (await firstRes.json()) as AcceptedResponse;
 
@@ -338,7 +348,12 @@ describe("handleMigrationExportToGcs — concurrency", () => {
           }),
         },
       );
-      const secondRes = await callHandler(handleMigrationExportToGcs, secondReq, undefined, 202);
+      const secondRes = await callHandler(
+        handleMigrationExportToGcs,
+        secondReq,
+        undefined,
+        202,
+      );
       expect(secondRes.status).toBe(409);
       const secondBody = (await secondRes.json()) as ErrorEnvelope;
       expect(secondBody.error.code).toBe("export_in_progress");
@@ -375,7 +390,12 @@ describe("handleMigrationExportToGcs — upload failure", () => {
         }),
       });
 
-      const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
       expect(res.status).toBe(202);
       const body = (await res.json()) as AcceptedResponse;
 
@@ -419,7 +439,12 @@ describe("handleMigrationExportToGcs — redirect handling", () => {
         }),
       });
 
-      const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
       expect(res.status).toBe(202);
       const body = (await res.json()) as AcceptedResponse;
 
@@ -446,7 +471,12 @@ describe("handleMigrationExportToGcs — URL validation", () => {
           upload_url: "http://storage.googleapis.com/b/o?X-Goog-Signature=fake",
         }),
       });
-      const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+      const res = await callHandler(
+        handleMigrationExportToGcs,
+        req,
+        undefined,
+        202,
+      );
       expect(res.status).toBe(400);
       const body = (await res.json()) as ErrorEnvelope;
       expect(body.error.code).toBe("invalid_upload_url");
@@ -466,7 +496,12 @@ describe("handleMigrationExportToGcs — URL validation", () => {
         upload_url: "https://evil.example.com/bucket/obj?X-Goog-Signature=fake",
       }),
     });
-    const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+    const res = await callHandler(
+      handleMigrationExportToGcs,
+      req,
+      undefined,
+      202,
+    );
     expect(res.status).toBe(400);
     const body = (await res.json()) as ErrorEnvelope;
     expect(body.error.code).toBe("invalid_upload_url");
@@ -482,7 +517,12 @@ describe("handleMigrationExportToGcs — URL validation", () => {
           "https://storage.googleapis.com/bucket/..%2Fother?X-Goog-Signature=fake",
       }),
     });
-    const res = await callHandler(handleMigrationExportToGcs, req, undefined, 202);
+    const res = await callHandler(
+      handleMigrationExportToGcs,
+      req,
+      undefined,
+      202,
+    );
     expect(res.status).toBe(400);
     const body = (await res.json()) as ErrorEnvelope;
     expect(body.error.code).toBe("invalid_upload_url");

package/src/__tests__/migration-import-commit-http.test.ts

@@ -11,7 +11,7 @@
  * - Auth: route policy enforcement (settings.write scope required)
  * - Integration: existing routes are unaffected by the new endpoint
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
@@ -237,41 +237,90 @@ interface VBundleFile {
   data: Uint8Array;
 }
 
+/**
+ * Build a v1-shape vbundle archive for HTTP/import tests.
+ *
+ * Mirrors the v1 ten-field manifest that `buildVBundle()` produces, so the
+ * fixtures here pass the same `ManifestSchema` zod validation the real
+ * importer applies. The manifest's `checksum` is computed against the
+ * canonical JSON with `checksum` set to "" (matches `computeManifestChecksum`
+ * in vbundle-validator.ts).
+ *
+ * Adds a synthetic `data/db/assistant.db` entry to `contents` when the caller
+ * doesn't supply one, satisfying the schema's `.refine()` constraint that
+ * every bundle must reference an assistant.db file.
+ */
 function createValidVBundle(
   files?: VBundleFile[],
   overrides?: Partial<{
-    schema_version: string;
-    source: string;
-    description: string;
+    bundle_id: string;
+    origin_mode: "managed" | "self-hosted-remote" | "self-hosted-local";
+    secrets_redacted: boolean;
+    min_runtime_version: string;
+    max_runtime_version: string | null;
   }>,
 ): Uint8Array {
   const dbData = new Uint8Array([0x53, 0x51, 0x4c, 0x69, 0x74, 0x65]);
   const bundleFiles = files ?? [{ path: "data/db/assistant.db", data: dbData }];
 
-  const fileEntries = bundleFiles.map((f) => ({
+  // v1 schema requires contents to include data/db/assistant.db (legacy) or
+  // workspace/data/db/assistant.db (current). If the caller's files don't
+  // satisfy that refine, inject a synthetic legacy-path db entry — this
+  // matches the pattern used in vbundle-streaming-importer.test.ts.
+  const hasDbEntry = bundleFiles.some(
+    (f) =>
+      f.path === "data/db/assistant.db" ||
+      f.path === "workspace/data/db/assistant.db",
+  );
+  const allFiles: VBundleFile[] = hasDbEntry
+    ? bundleFiles
+    : [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
+        ...bundleFiles,
+      ];
+
+  const contents = allFiles.map((f) => ({
     path: f.path,
     sha256: sha256Hex(f.data),
-    size: f.data.length,
+    size_bytes: f.data.length,
   }));
 
   const manifestWithoutChecksum = {
-    schema_version: overrides?.schema_version ?? "1.0",
+    schema_version: 1 as const,
+    bundle_id: overrides?.bundle_id ?? randomUUID(),
     created_at: new Date().toISOString(),
-    source: overrides?.source ?? "test",
-    description: overrides?.description ?? "Test bundle",
-    files: fileEntries,
+    assistant: {
+      id: "self",
+      name: "Test",
+      runtime_version: "0.0.0-test",
+    },
+    origin: {
+      mode: overrides?.origin_mode ?? "self-hosted-local",
+    },
+    compatibility: {
+      min_runtime_version: overrides?.min_runtime_version ?? "0.0.0-test",
+      max_runtime_version:
+        overrides?.max_runtime_version === undefined
+          ? null
+          : overrides.max_runtime_version,
+    },
+    contents,
+    checksum: "",
+    secrets_redacted: overrides?.secrets_redacted ?? false,
+    export_options: {
+      include_logs: false,
+      include_browser_state: false,
+      include_memory_vectors: false,
+    },
   };
 
-  const manifestSha256 = sha256Hex(canonicalizeJson(manifestWithoutChecksum));
-  const manifest = {
-    ...manifestWithoutChecksum,
-    manifest_sha256: manifestSha256,
-  };
+  const checksum = sha256Hex(canonicalizeJson(manifestWithoutChecksum));
+  const manifest = { ...manifestWithoutChecksum, checksum };
   const manifestData = new TextEncoder().encode(JSON.stringify(manifest));
 
   const tarEntries = [
     { name: "manifest.json", data: manifestData },
-    ...bundleFiles.map((f) => ({ name: f.path, data: f.data })),
+    ...allFiles.map((f) => ({ name: f.path, data: f.data })),
   ];
 
   const tar = createTarArchive(tarEntries);
@@ -445,9 +494,9 @@ describe("handleMigrationImport", () => {
   });
 
   test("includes manifest in response", async () => {
+    const fixedBundleId = "11111111-2222-4333-8444-555555555555";
     const vbundle = createValidVBundle(undefined, {
-      source: "test-import-source",
-      description: "Test import commit",
+      bundle_id: fixedBundleId,
     });
     const req = new Request("http://localhost/v1/migrations/import", {
       method: "POST",
@@ -459,9 +508,10 @@ describe("handleMigrationImport", () => {
     const body = (await res.json()) as ImportCommitResponse;
 
     expect(body.manifest).toBeDefined();
-    expect(body.manifest.schema_version).toBe("1.0");
-    expect(body.manifest.source).toBe("test-import-source");
-    expect(body.manifest.description).toBe("Test import commit");
+    expect(body.manifest.schema_version).toBe(1);
+    expect(body.manifest.bundle_id).toBe(fixedBundleId);
+    expect(body.manifest.assistant).toBeDefined();
+    expect(body.manifest.origin).toEqual({ mode: "self-hosted-local" });
   });
 
   test("POST with multipart form data works", async () => {
@@ -607,6 +657,107 @@ describe("handleMigrationImport — validation failures", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// HTTP handler tests: version_incompatible (Codex P2 regression)
+//
+// Pin: a bundle whose min_runtime_version exceeds APP_VERSION must surface as
+// a 4xx user-actionable response (422 Unprocessable Entity), not a 500
+// InternalError. Body mirrors the platform's PR #5470 response shape so
+// clients can render the same UX regardless of which gate (platform or
+// runtime) rejected the bundle.
+// ---------------------------------------------------------------------------
+
+describe("handleMigrationImport — version_incompatible", () => {
+  test("incompatible bundle returns 422 with structured body, not 500", async () => {
+    const vbundle = createValidVBundle(undefined, {
+      min_runtime_version: "99.0.0",
+    });
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: toArrayBuffer(vbundle),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    const body = (await res.json()) as {
+      error: {
+        code: string;
+        message: string;
+        details?: {
+          reason: string;
+          bundle_compat: {
+            min_runtime_version: string;
+            max_runtime_version: string | null;
+          };
+          runtime_version: string;
+        };
+      };
+    };
+
+    expect(res.status).toBe(422);
+    expect(body.error.code).toBe("UNPROCESSABLE_ENTITY");
+    expect(body.error.message).toContain("99.0.0");
+    expect(body.error.details).toBeDefined();
+    expect(body.error.details!.reason).toBe("version_incompatible");
+    expect(body.error.details!.bundle_compat.min_runtime_version).toBe(
+      "99.0.0",
+    );
+    expect(body.error.details!.bundle_compat.max_runtime_version).toBeNull();
+    expect(typeof body.error.details!.runtime_version).toBe("string");
+  });
+
+  test("incompatible bundle does not modify disk", async () => {
+    const originalDb = new Uint8Array(readFileSync(testDbPath));
+    const originalConfig = readFileSync(testConfigPath, "utf8");
+
+    const vbundle = createValidVBundle(undefined, {
+      min_runtime_version: "99.0.0",
+    });
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: toArrayBuffer(vbundle),
+    });
+
+    await callHandler(handleMigrationImport, req);
+
+    const currentDb = new Uint8Array(readFileSync(testDbPath));
+    const currentConfig = readFileSync(testConfigPath, "utf8");
+
+    expect(currentDb).toEqual(originalDb);
+    expect(currentConfig).toBe(originalConfig);
+  });
+
+  // Regression: the route handler pre-checks runtime-version compat using
+  // `validation.manifest.compatibility` before calling `resetDb()` and
+  // `commitImport()`. If a future refactor reorders the close to come
+  // before the gate, an incompatible bundle would still 422 (commitImport
+  // has its own defense-in-depth gate) but it would unnecessarily close
+  // and reopen the live SQLite singleton on every rejected import.
+  //
+  // We can't easily spy on `resetDb` here without mocking `db-connection.js`
+  // module-wide (which other tests in this file rely on for real). The
+  // semantic regression — disk unchanged + 422 — is covered by the two
+  // tests above. This test is a marker so future readers know the pre-
+  // check intent; if it ever starts failing, recheck `handleMigrationImport`
+  // ordering against the comment at line 861-862 ("Validate the bundle
+  // before closing the DB to avoid an unnecessary close/reopen cycle when
+  // the bundle is invalid").
+  test("incompatible bundle short-circuits before resetDb (intent marker)", async () => {
+    const vbundle = createValidVBundle(undefined, {
+      min_runtime_version: "99.0.0",
+    });
+    const req = new Request("http://localhost/v1/migrations/import", {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: toArrayBuffer(vbundle),
+    });
+
+    const res = await callHandler(handleMigrationImport, req);
+    expect(res.status).toBe(422);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // commitImport unit tests
 // ---------------------------------------------------------------------------