@fragno-dev/db 0.2.2 → 0.4.1

package/src/fragments/internal-fragment.test.ts

@@ -1,21 +1,38 @@
+import { beforeAll, describe, expect, it } from "vitest";
+
 import SQLite from "better-sqlite3";
 import { SqliteDialect } from "kysely";
-import { beforeAll, describe, expect, it } from "vitest";
+
 import { instantiate } from "@fragno-dev/core";
-import { internalFragmentDef, internalSchema, SETTINGS_NAMESPACE } from "./internal-fragment";
-import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
-import { DrizzleAdapter } from "../adapters/drizzle/drizzle-adapter";
+
 import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
+import { getRegistryForAdapterSync } from "../internal/adapter-registry";
+import { dbNow } from "../query/db-now";
 import { ExponentialBackoffRetryPolicy, NoRetryPolicy } from "../query/unit-of-work/retry-policy";
 import type { FragnoId } from "../schema/create";
+import {
+  internalFragmentDef,
+  internalSchema,
+  SETTINGS_NAMESPACE,
+  getSchemaVersionFromDatabase,
+} from "./internal-fragment";
+
+type OptionsWithAdapter = FragnoPublicConfigWithDatabase & {
+  databaseAdapter: SqlAdapter;
+};
 
 describe("Internal Fragment", () => {
   let sqliteDatabase: SQLite.Database;
-  let adapter: DrizzleAdapter;
+  let adapter: SqlAdapter;
   let fragment: ReturnType<typeof instantiateFragment>;
 
-  function instantiateFragment(options: FragnoPublicConfigWithDatabase) {
-    return instantiate(internalFragmentDef).withConfig({}).withOptions(options).build();
+  function instantiateFragment(options: OptionsWithAdapter) {
+    return instantiate(internalFragmentDef)
+      .withConfig({ registry: getRegistryForAdapterSync(options.databaseAdapter) })
+      .withOptions(options)
+      .build();
   }
 
   beforeAll(async () => {
@@ -25,19 +42,20 @@ describe("Internal Fragment", () => {
       database: sqliteDatabase,
     });
 
-    adapter = new DrizzleAdapter({
+    adapter = new SqlAdapter({
       dialect,
       driverConfig: new BetterSQLite3DriverConfig(),
     });
 
     {
-      const migrations = adapter.prepareMigrations(internalSchema, "");
+      const migrations = adapter.prepareMigrations(internalSchema, null);
       await migrations.executeWithDriver(adapter.driver, 0);
     }
 
     // Instantiate fragment with shared database adapter
-    const options: FragnoPublicConfigWithDatabase = {
+    const options: OptionsWithAdapter = {
       databaseAdapter: adapter,
+      databaseNamespace: null,
     };
 
     fragment = instantiateFragment(options);
@@ -151,11 +169,14 @@ describe("Internal Fragment", () => {
 
 describe("Hook Service", () => {
   let sqliteDatabase: SQLite.Database;
-  let adapter: DrizzleAdapter;
+  let adapter: SqlAdapter;
   let fragment: ReturnType<typeof instantiateFragment>;
 
-  function instantiateFragment(options: FragnoPublicConfigWithDatabase) {
-    return instantiate(internalFragmentDef).withConfig({}).withOptions(options).build();
+  function instantiateFragment(options: OptionsWithAdapter) {
+    return instantiate(internalFragmentDef)
+      .withConfig({ registry: getRegistryForAdapterSync(options.databaseAdapter) })
+      .withOptions(options)
+      .build();
   }
 
   beforeAll(async () => {
@@ -165,18 +186,19 @@ describe("Hook Service", () => {
       database: sqliteDatabase,
     });
 
-    adapter = new DrizzleAdapter({
+    adapter = new SqlAdapter({
       dialect,
       driverConfig: new BetterSQLite3DriverConfig(),
     });
 
     {
-      const migrations = adapter.prepareMigrations(internalSchema, "");
+      const migrations = adapter.prepareMigrations(internalSchema, null);
       await migrations.executeWithDriver(adapter.driver, 0);
     }
 
-    const options: FragnoPublicConfigWithDatabase = {
+    const options: OptionsWithAdapter = {
       databaseAdapter: adapter,
+      databaseNamespace: null,
     };
 
     fragment = instantiateFragment(options);
@@ -224,62 +246,119 @@ describe("Hook Service", () => {
     const events = await fragment.inContext(async function () {
       return await this.handlerTx()
         .withServiceCalls(
-          () => [fragment.services.hookService.getPendingHookEvents("test-namespace")] as const,
+          () => [fragment.services.hookService.getHooksByNamespace("test-namespace")] as const,
         )
         .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    expect(events).toHaveLength(1);
-    expect(events[0]).toMatchObject({
+    const event = events.find((entry) => entry.hookName === "onTest" && entry.status === "pending");
+    expect(event).toBeDefined();
+    expect(event).toMatchObject({
       hookName: "onTest",
       payload: { test: "data" },
       attempts: 0,
       maxAttempts: 5,
-      idempotencyKey: nonce,
+      status: "pending",
+      nonce,
     });
   });
 
-  it("should mark a hook event as completed", async () => {
-    const nonce = "test-nonce-2";
-    let eventId: FragnoId;
+  it("should paginate hooks by namespace with a cursor", async () => {
+    const namespace = "page-cursor";
+    const createdAt1 = new Date("2024-01-01T00:00:00.000Z");
+    const createdAt2 = new Date("2024-01-02T00:00:00.000Z");
+    const createdAt3 = new Date("2024-01-03T00:00:00.000Z");
+
+    let id1!: FragnoId;
+    let id2!: FragnoId;
+    let id3!: FragnoId;
 
     await fragment.inContext(async function () {
       await this.handlerTx()
         .mutate(({ forSchema }) => {
           const uow = forSchema(internalSchema);
-          eventId = uow.create("fragno_hooks", {
-            namespace: "test-namespace",
-            hookName: "onComplete",
-            payload: { test: "data" },
+          id1 = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onPage1",
+            payload: { test: "page-1" },
             status: "pending",
             attempts: 0,
             maxAttempts: 5,
             lastAttemptAt: null,
             nextRetryAt: null,
             error: null,
-            nonce,
+            nonce: "test-nonce-page-1",
+            createdAt: createdAt1,
+          });
+          id2 = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onPage2",
+            payload: { test: "page-2" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-page-2",
+            createdAt: createdAt2,
+          });
+          id3 = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onPage3",
+            payload: { test: "page-3" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-page-3",
+            createdAt: createdAt3,
           });
         })
         .execute();
     });
 
-    await fragment.inContext(async function () {
-      await this.handlerTx()
-        .withServiceCalls(() => [fragment.services.hookService.markHookCompleted(eventId)] as const)
+    const firstPage = await fragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              fragment.services.hookService.getHooksByNamespacePage(namespace, { pageSize: 2 }),
+            ] as const,
+        )
+        .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    const result = await fragment.inContext(async function () {
+    expect(firstPage.items).toHaveLength(2);
+    expect(firstPage.hasNextPage).toBe(true);
+    expect(firstPage.cursor).toBeDefined();
+    expect(firstPage.items.map((event) => event.id.externalId)).toEqual([
+      id3.externalId,
+      id2.externalId,
+    ]);
+
+    const secondPage = await fragment.inContext(async function () {
       return await this.handlerTx()
-        .withServiceCalls(() => [fragment.services.hookService.getHookById(eventId)] as const)
-        .transform(({ serviceResult: [event] }) => event)
+        .withServiceCalls(
+          () =>
+            [
+              fragment.services.hookService.getHooksByNamespacePage(namespace, {
+                cursor: firstPage.cursor ?? undefined,
+                pageSize: 2,
+              }),
+            ] as const,
+        )
+        .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    expect(result).toBeDefined();
-    expect(result?.status).toBe("completed");
-    expect(result?.lastAttemptAt).toBeInstanceOf(Date);
+    expect(secondPage.items).toHaveLength(1);
+    expect(secondPage.hasNextPage).toBe(false);
+    expect(secondPage.items[0]?.id.externalId).toBe(id1.externalId);
   });
 
   it("should mark a hook event as processing", async () => {
@@ -435,121 +514,464 @@ describe("Hook Service", () => {
     expect(result?.error).toBe("Max attempts reached");
   });
 
-  it("should retrieve stale events ready for retry", async () => {
-    const nonce = "test-nonce-6";
-    let eventId: FragnoId;
-
+  it("should claim only ready pending events and mark them processing", async () => {
+    const namespace = "claim-ready";
     const pastTime = new Date(Date.now() - 10000);
+    const futureTime = new Date(Date.now() + 60000);
+
+    let nullRetryId!: FragnoId;
+    let pastRetryId!: FragnoId;
+    let futureRetryId!: FragnoId;
+    let otherNamespaceId!: FragnoId;
 
     await fragment.inContext(async function () {
-      const createdId = await this.handlerTx()
+      await this.handlerTx()
         .mutate(({ forSchema }) => {
           const uow = forSchema(internalSchema);
-          return uow.create("fragno_hooks", {
-            namespace: "test-namespace",
-            hookName: "onStale",
-            payload: { test: "stale" },
+          nullRetryId = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onNullRetry",
+            payload: { test: "null" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-claim-null",
+          });
+          pastRetryId = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onPastRetry",
+            payload: { test: "past" },
             status: "pending",
             attempts: 1,
             maxAttempts: 5,
             lastAttemptAt: pastTime,
             nextRetryAt: pastTime,
             error: "Previous error",
+            nonce: "test-nonce-claim-past",
+          });
+          futureRetryId = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onFutureRetry",
+            payload: { test: "future" },
+            status: "pending",
+            attempts: 1,
+            maxAttempts: 5,
+            lastAttemptAt: new Date(),
+            nextRetryAt: futureTime,
+            error: "Previous error",
+            nonce: "test-nonce-claim-future",
+          });
+          otherNamespaceId = uow.create("fragno_hooks", {
+            namespace: "other-namespace",
+            hookName: "onOtherNamespace",
+            payload: { test: "other" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-claim-other",
+          });
+        })
+        .execute();
+    });
+
+    const claimed = await fragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () => [fragment.services.hookService.claimPendingHookEvents(namespace)] as const,
+        )
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+    });
+
+    expect(claimed).toHaveLength(2);
+    const claimedIds = new Set(claimed.map((event) => event.id.externalId));
+    expect(claimedIds.has(nullRetryId.externalId)).toBe(true);
+    expect(claimedIds.has(pastRetryId.externalId)).toBe(true);
+    expect(claimedIds.has(futureRetryId.externalId)).toBe(false);
+    expect(claimedIds.has(otherNamespaceId.externalId)).toBe(false);
+
+    const [nullEvent, pastEvent, futureEvent, otherEvent] = await fragment.inContext(
+      async function () {
+        return await this.handlerTx()
+          .withServiceCalls(
+            () =>
+              [
+                fragment.services.hookService.getHookById(nullRetryId),
+                fragment.services.hookService.getHookById(pastRetryId),
+                fragment.services.hookService.getHookById(futureRetryId),
+                fragment.services.hookService.getHookById(otherNamespaceId),
+              ] as const,
+          )
+          .transform(({ serviceResult: [nullResult, pastResult, futureResult, otherResult] }) => [
+            nullResult,
+            pastResult,
+            futureResult,
+            otherResult,
+          ])
+          .execute();
+      },
+    );
+
+    expect(nullEvent?.status).toBe("processing");
+    expect(nullEvent?.lastAttemptAt).toBeInstanceOf(Date);
+    expect(pastEvent?.status).toBe("processing");
+    expect(pastEvent?.lastAttemptAt).toBeInstanceOf(Date);
+    expect(futureEvent?.status).toBe("pending");
+    expect(otherEvent?.status).toBe("pending");
+  });
+
+  it("should return claimed ids with incremented versions", async () => {
+    const namespace = "claim-version";
+    const nonce = "test-nonce-claim-version";
+    let createdId!: FragnoId;
+
+    await fragment.inContext(async function () {
+      createdId = await this.handlerTx()
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(internalSchema);
+          return uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onClaimVersion",
+            payload: { test: "version" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: null,
+            error: null,
             nonce,
           });
         })
         .execute();
-      eventId = createdId;
     });
 
-    const events = await fragment.inContext(async function () {
+    const claimed = await fragment.inContext(async function () {
       return await this.handlerTx()
         .withServiceCalls(
-          () => [fragment.services.hookService.getPendingHookEvents("test-namespace")] as const,
+          () => [fragment.services.hookService.claimPendingHookEvents(namespace)] as const,
         )
         .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    const staleEvent = events.find((e) => e.id.externalId === eventId.externalId);
-    expect(staleEvent).toBeDefined();
-    expect(staleEvent?.hookName).toBe("onStale");
-    expect(staleEvent?.attempts).toBe(1);
+    expect(claimed).toHaveLength(1);
+    expect(claimed[0]?.id.externalId).toBe(createdId.externalId);
+    expect(claimed[0]?.id.version).toBe(createdId.version + 1);
   });
 
-  it("should not retrieve events from different namespace", async () => {
-    const nonce = "test-nonce-7";
+  it("should claim stale processing events and return stuck metadata", async () => {
+    const namespace = "claim-stuck";
+    const staleBefore = dbNow().plus({ minutes: -1 });
+    const staleLastAttemptAt = new Date(Date.now() - 5 * 60_000);
+    const freshLastAttemptAt = new Date(Date.now() - 10_000);
+    const staleNextRetryAt = new Date(Date.now() + 60_000);
+
+    let staleId!: FragnoId;
+    let freshId!: FragnoId;
+
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .mutate(({ forSchema }) => {
+          const uow = forSchema(internalSchema);
+          staleId = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onStuck",
+            payload: { test: "stuck" },
+            status: "processing",
+            attempts: 1,
+            maxAttempts: 5,
+            lastAttemptAt: staleLastAttemptAt,
+            nextRetryAt: staleNextRetryAt,
+            error: null,
+            nonce: "test-nonce-stuck",
+          });
+          freshId = uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onFresh",
+            payload: { test: "fresh" },
+            status: "processing",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: freshLastAttemptAt,
+            nextRetryAt: null,
+            error: null,
+            nonce: "test-nonce-fresh",
+          });
+        })
+        .execute();
+    });
+
+    const claimResult = await fragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              fragment.services.hookService.claimStuckProcessingHookEvents(namespace, staleBefore),
+            ] as const,
+        )
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+    });
+
+    expect(claimResult.events).toHaveLength(1);
+    expect(claimResult.events[0]?.hookName).toBe("onStuck");
+    expect(claimResult.events[0]?.id.version).toBe(staleId.version + 1);
+
+    expect(claimResult.stuckEvents).toHaveLength(1);
+    expect(claimResult.stuckEvents[0]?.hookName).toBe("onStuck");
+    expect(claimResult.stuckEvents[0]?.id.externalId).toBe(staleId.externalId);
+    expect(claimResult.stuckEvents[0]?.id.version).toBe(staleId.version);
+    expect(claimResult.stuckEvents[0]?.lastAttemptAt?.getTime()).toBe(staleLastAttemptAt.getTime());
+    expect(claimResult.stuckEvents[0]?.nextRetryAt?.getTime()).toBe(staleNextRetryAt.getTime());
+
+    const [staleEvent, freshEvent] = await fragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () =>
+            [
+              fragment.services.hookService.getHookById(staleId),
+              fragment.services.hookService.getHookById(freshId),
+            ] as const,
+        )
+        .transform(({ serviceResult: [staleResult, freshResult] }) => [staleResult, freshResult])
+        .execute();
+    });
+
+    expect(staleEvent?.status).toBe("processing");
+    expect(staleEvent?.nextRetryAt).toBeNull();
+    expect(staleEvent?.lastAttemptAt).toBeInstanceOf(Date);
+    expect(staleEvent?.lastAttemptAt?.getTime()).toBeGreaterThan(staleLastAttemptAt.getTime());
+    expect(freshEvent?.lastAttemptAt).toBeInstanceOf(Date);
+    expect(
+      Math.abs((freshEvent?.lastAttemptAt?.getTime() ?? 0) - freshLastAttemptAt.getTime()),
+    ).toBeLessThan(2000);
+  });
+
+  it("should return now when pending hooks have no nextRetryAt", async () => {
+    const namespace = "wake-now";
 
     await fragment.inContext(async function () {
       await this.handlerTx()
         .mutate(({ forSchema }) => {
           const uow = forSchema(internalSchema);
           uow.create("fragno_hooks", {
-            namespace: "other-namespace",
-            hookName: "onOther",
-            payload: { test: "other" },
+            namespace,
+            hookName: "onImmediate",
+            payload: { test: "now" },
             status: "pending",
             attempts: 0,
             maxAttempts: 5,
             lastAttemptAt: null,
             nextRetryAt: null,
             error: null,
-            nonce,
+            nonce: "test-nonce-now",
           });
         })
         .execute();
     });
 
-    const events = await fragment.inContext(async function () {
+    const wakeAt = await fragment.inContext(async function () {
       return await this.handlerTx()
         .withServiceCalls(
-          () => [fragment.services.hookService.getPendingHookEvents("test-namespace")] as const,
+          () => [fragment.services.hookService.getNextHookWakeAt(namespace)] as const,
         )
         .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    const otherEvent = events.find((e) => e.hookName === "onOther");
-    expect(otherEvent).toBeUndefined();
+    expect(wakeAt).toBeInstanceOf(Date);
+    expect(Math.abs((wakeAt as Date).getTime() - Date.now())).toBeLessThan(5000);
   });
 
-  it("should not retrieve events not yet ready for retry", async () => {
-    const nonce = "test-nonce-8";
-    let eventId: FragnoId;
-
-    const futureTime = new Date(Date.now() + 60000);
+  it("should return earliest scheduled hook time", async () => {
+    const namespace = "wake-future";
+    const soon = new Date(Date.now() + 10000);
+    const later = new Date(Date.now() + 60000);
 
     await fragment.inContext(async function () {
-      const createdId = await this.handlerTx()
+      await this.handlerTx()
         .mutate(({ forSchema }) => {
           const uow = forSchema(internalSchema);
-          return uow.create("fragno_hooks", {
-            namespace: "test-namespace",
-            hookName: "onFuture",
-            payload: { test: "future" },
+          uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onSoon",
+            payload: { test: "soon" },
             status: "pending",
-            attempts: 1,
+            attempts: 0,
             maxAttempts: 5,
-            lastAttemptAt: new Date(),
-            nextRetryAt: futureTime,
-            error: "Previous error",
-            nonce,
+            lastAttemptAt: null,
+            nextRetryAt: soon,
+            error: null,
+            nonce: "test-nonce-soon",
+          });
+          uow.create("fragno_hooks", {
+            namespace,
+            hookName: "onLater",
+            payload: { test: "later" },
+            status: "pending",
+            attempts: 0,
+            maxAttempts: 5,
+            lastAttemptAt: null,
+            nextRetryAt: later,
+            error: null,
+            nonce: "test-nonce-later",
           });
         })
         .execute();
-      eventId = createdId;
     });
 
-    const events = await fragment.inContext(async function () {
+    const wakeAt = await fragment.inContext(async function () {
       return await this.handlerTx()
         .withServiceCalls(
-          () => [fragment.services.hookService.getPendingHookEvents("test-namespace")] as const,
+          () => [fragment.services.hookService.getNextHookWakeAt(namespace)] as const,
         )
         .transform(({ serviceResult: [result] }) => result)
         .execute();
     });
 
-    const futureEvent = events.find((e) => e.id.externalId === eventId.externalId);
-    expect(futureEvent).toBeUndefined();
+    expect(wakeAt).toEqual(soon);
+  });
+
+  it("should return null when no pending hooks exist", async () => {
+    const namespace = "wake-none";
+    const wakeAt = await fragment.inContext(async function () {
+      return await this.handlerTx()
+        .withServiceCalls(
+          () => [fragment.services.hookService.getNextHookWakeAt(namespace)] as const,
+        )
+        .transform(({ serviceResult: [result] }) => result)
+        .execute();
+    });
+
+    expect(wakeAt).toBeNull();
+  });
+});
+
+describe("getSchemaVersionFromDatabase", () => {
+  function createTestSetup() {
+    const sqliteDatabase = new SQLite(":memory:");
+    const dialect = new SqliteDialect({ database: sqliteDatabase });
+    const adapter = new SqlAdapter({
+      dialect,
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    function instantiateFragment(options: FragnoPublicConfigWithDatabase) {
+      return instantiate(internalFragmentDef).withConfig({}).withOptions(options).build();
+    }
+
+    return { sqliteDatabase, adapter, instantiateFragment };
+  }
+
+  async function setupAndMigrate() {
+    const { sqliteDatabase, adapter, instantiateFragment } = createTestSetup();
+    // Create tables without writing a version record, so tests control version state
+    const migrations = adapter.prepareMigrations(internalSchema, "");
+    await migrations.executeWithDriver(adapter.driver, 0, undefined, {
+      updateVersionInMigration: false,
+    });
+    const fragment = instantiateFragment({
+      databaseAdapter: adapter,
+      databaseNamespace: null,
+    });
+    return { sqliteDatabase, adapter, fragment };
+  }
+
+  it("should return 0 when no version exists", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    const version = await getSchemaVersionFromDatabase(fragment, "nonexistent");
+    expect(version).toBe(0);
+  });
+
+  it("should find version stored under empty-string namespace", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    // Write version under empty-string namespace (key = ".schema_version")
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [fragment.services.settingsService.set("", "schema_version", "5")])
+        .execute();
+    });
+
+    const version = await getSchemaVersionFromDatabase(fragment, "");
+    expect(version).toBe(5);
+  });
+
+  it("should find version via back-compat when stored under internalSchema.name but read with empty string", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    // Write version under "fragno_internal" namespace (legacy key from buggy code)
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [
+          fragment.services.settingsService.set(internalSchema.name, "schema_version", "3"),
+        ])
+        .execute();
+    });
+
+    // Reading with "" should find it via back-compat fallback
+    const version = await getSchemaVersionFromDatabase(fragment, "");
+    expect(version).toBe(3);
+  });
+
+  it("should find version via back-compat when stored under empty string but read with internalSchema.name", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    // Write version under empty-string namespace
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [fragment.services.settingsService.set("", "schema_version", "7")])
+        .execute();
+    });
+
+    // Reading with internalSchema.name should find it via back-compat fallback
+    const version = await getSchemaVersionFromDatabase(fragment, internalSchema.name);
+    expect(version).toBe(7);
+  });
+
+  it("should prefer primary namespace over back-compat fallback", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    // Write version under BOTH namespaces with different values
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [
+          fragment.services.settingsService.set("", "schema_version", "10"),
+          fragment.services.settingsService.set(internalSchema.name, "schema_version", "20"),
+        ])
+        .execute();
+    });
+
+    // Reading with "" should find 10 (primary), not 20 (back-compat)
+    const versionEmpty = await getSchemaVersionFromDatabase(fragment, "");
+    expect(versionEmpty).toBe(10);
+
+    // Reading with internalSchema.name should find 20 (primary), not 10 (back-compat)
+    const versionNamed = await getSchemaVersionFromDatabase(fragment, internalSchema.name);
+    expect(versionNamed).toBe(20);
+  });
+
+  it("should not use back-compat for non-internal namespaces", async () => {
+    const { fragment } = await setupAndMigrate();
+
+    // Write version under "some-fragment"
+    await fragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [
+          fragment.services.settingsService.set("some-fragment", "schema_version", "4"),
+        ])
+        .execute();
+    });
+
+    // Reading with a different non-internal namespace should NOT find it
+    const version = await getSchemaVersionFromDatabase(fragment, "other-fragment");
+    expect(version).toBe(0);
   });
 });