@cosmicdrift/kumiko-framework 0.305.0 → 0.306.0

package/src/db/__tests__/pg-error.test.ts

@@ -18,6 +18,20 @@ describe("extractPgError", () => {
   test("returns null for non-objects", () => {
     expect(extractPgError("nope")).toBeNull();
   });
+
+  test("normalizes Bun.SQL's errno/constraint into code/constraint_name", () => {
+    const info = extractPgError({
+      code: "ERR_POSTGRES_SERVER_ERROR",
+      errno: "23505",
+      constraint: "users_email_uq",
+    });
+    expect(info).toEqual({ code: "23505", constraint_name: "users_email_uq" });
+  });
+
+  test("leaves ERR_POSTGRES_SERVER_ERROR untouched when errno isn't a string", () => {
+    const info = extractPgError({ code: "ERR_POSTGRES_SERVER_ERROR" });
+    expect(info).toEqual({ code: "ERR_POSTGRES_SERVER_ERROR", constraint_name: undefined });
+  });
 });
 
 describe("isUniqueViolation", () => {

package/src/db/__tests__/system-db-view-export.test.ts

@@ -0,0 +1,107 @@
+// createUncheckedSystemDb() is framework-private (not re-exported from
+// db/index.ts); createSystemDbView is the public replacement, whose
+// unsafeRaw follows the source TenantDb's own escapeHatch gate instead of
+// handing out an ungated tenantDbRunner(db).
+
+import { describe, expect, test } from "bun:test";
+import * as dbBarrel from "@cosmicdrift/kumiko-framework/db";
+import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { AccessDeniedError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { unsafeRawForDeclaredStep, withSystemDbUnsafeRawGrant } from "../tenant-db";
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => {
+      throw new Error("system-db-view-export tests must not reach the DB");
+    },
+    begin: async () => {
+      throw new Error("system-db-view-export tests must not reach the DB");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("db barrel export", () => {
+  test("createUncheckedSystemDb is no longer exported from @cosmicdrift/kumiko-framework/db", () => {
+    expect("createUncheckedSystemDb" in dbBarrel).toBe(false);
+  });
+});
+
+describe("createSystemDbView(...).unsafeRaw", () => {
+  test("denies without a grant on the source TenantDb, without reporting on either side", () => {
+    const sourceReports: Array<{ kind: string; reason: string }> = [];
+    const viewReports: Array<{ kind: string; reason: string }> = [];
+    const source = createTenantDb(
+      fakeRunner(),
+      tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { report: (kind, reason) => sourceReports.push({ kind, reason }) },
+    );
+    const view = createSystemDbView(source, undefined, (kind, reason) =>
+      viewReports.push({ kind, reason }),
+    );
+
+    expect(() => view.unsafeRaw("x")).toThrow(AccessDeniedError);
+    expect(sourceReports).toEqual([]);
+    expect(viewReports).toEqual([]);
+  });
+
+  test("resolves to the source's own bound runner and reports through the source, not the view", () => {
+    const runner = fakeRunner();
+    const sourceReports: Array<{ kind: string; reason: string }> = [];
+    const viewReports: Array<{ kind: string; reason: string }> = [];
+    const source = createTenantDb(runner, tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler declared unsafeRaw" },
+      report: (kind, reason) => sourceReports.push({ kind, reason }),
+    });
+    const view = createSystemDbView(source, undefined, (kind, reason) =>
+      viewReports.push({ kind, reason }),
+    );
+
+    expect(view.unsafeRaw("x")).toBe(runner);
+    expect(sourceReports).toEqual([{ kind: "unsafe-raw", reason: "x" }]);
+    expect(viewReports).toEqual([]);
+  });
+
+  test("memberReadOnly on the source denies even with an unsafeRaw grant", () => {
+    const source = createTenantDb(
+      fakeRunner(),
+      tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { unsafeRaw: { reason: "handler declared unsafeRaw" }, memberReadOnly: true },
+    );
+    const view = createSystemDbView(source);
+
+    expect(() => view.unsafeRaw("x")).toThrow(AccessDeniedError);
+    expect(() => view.unsafeRaw("x")).toThrow(/read-only/);
+  });
+});
+
+describe("unsafeRawForDeclaredStep(createSystemDbView(...))", () => {
+  test("throws AccessDeniedError, not InternalError, without a grant on the source", () => {
+    const source = createTenantDb(fakeRunner(), tenantId, "tenant");
+    const view = createSystemDbView(source);
+
+    expect(() => unsafeRawForDeclaredStep(view, "x")).toThrow(AccessDeniedError);
+  });
+});
+
+describe("withSystemDbUnsafeRawGrant(createSystemDbView(...))", () => {
+  test("returns the view unchanged — no rebind, so no rights upgrade over the source's own gate", () => {
+    const source = createTenantDb(fakeRunner(), tenantId, "tenant");
+    const view = createSystemDbView(source);
+
+    const rebound = withSystemDbUnsafeRawGrant(view, { reason: "hook grant" }, "some hook");
+    expect(rebound).toBe(view);
+    expect(() => rebound.unsafeRaw("x")).toThrow(AccessDeniedError);
+  });
+});

package/src/db/__tests__/tenant-db-no-raw.test.ts

@@ -3,6 +3,7 @@ import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { InternalError } from "../../errors";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
+import { asRawClient } from "../query";
 import { createTenantDb, createUncheckedSystemDb, withUnsafeRawGrant } from "../tenant-db";
 import { tenantDbRunner } from "../tenant-db-runner";
 
@@ -26,6 +27,15 @@ describe("TenantDb has no .raw", () => {
     // @ts-expect-error TenantDb no longer exposes `raw`.
     expect(tdb.raw).toBeUndefined();
   });
+
+  test("createTenantDb rejects an already tenant-scoped TenantDb: compile error, and raw access throws", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    expect(() => {
+      // @ts-expect-error TenantDb is already tenant-scoped; createTenantDb only accepts a raw DbRunner.
+      const rewrapped = createTenantDb(tdb, tenantId);
+      asRawClient(tenantDbRunner(rewrapped));
+    }).toThrow();
+  });
 });
 
 describe("tenantDbRunner", () => {

package/src/db/__tests__/with-systemdb-unsafe-raw-grant.test.ts

@@ -0,0 +1,71 @@
+// fw#3198 — unit coverage for withSystemDbUnsafeRawGrant: passthrough for
+// unknown values, no stacking across repeated rebinds, and the gated runner
+// registered under declaredUnsafeRawRunners (unsafeRawForDeclaredStep).
+
+import { describe, expect, test } from "bun:test";
+import type { UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { AccessDeniedError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  unsafeRawForDeclaredStep,
+  withSystemDbUnsafeRawGrant,
+} from "../tenant-db";
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("withSystemDbUnsafeRawGrant", () => {
+  test("passes through a value not built by createUncheckedSystemDb, unchanged", () => {
+    const notBuilt = { unsafeRaw: () => fakeRunner() } as unknown as UncheckedSystemDb;
+    const rebound = withSystemDbUnsafeRawGrant(notBuilt, { reason: "x" }, "some hook");
+    expect(rebound).toBe(notBuilt);
+  });
+
+  test("without a grant, unsafeRaw denies with AccessDeniedError naming the caller", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, undefined, 'postSave hook of feature "x"');
+    expect(() => gated.unsafeRaw("a reason")).toThrow(AccessDeniedError);
+    expect(() => gated.unsafeRaw("a reason")).toThrow(/postSave hook of feature "x"/);
+  });
+
+  test("with a grant, unsafeRaw resolves to the original runner", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, { reason: "hook reason" }, "hook");
+    expect(gated.unsafeRaw("hook reason")).toBe(runner);
+  });
+
+  test("repeated rebinding is not stacked — a second rebind reflects only its own grant", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const grantedFirst = withSystemDbUnsafeRawGrant(systemDb, { reason: "first" }, "hook-1");
+    const deniedSecond = withSystemDbUnsafeRawGrant(grantedFirst, undefined, "hook-2");
+    expect(() => deniedSecond.unsafeRaw("first")).toThrow(AccessDeniedError);
+    // Re-granting from the ORIGINAL systemDb (not stacked through grantedFirst) still works.
+    const grantedThird = withSystemDbUnsafeRawGrant(systemDb, { reason: "third" }, "hook-3");
+    expect(grantedThird.unsafeRaw("third")).toBe(runner);
+  });
+
+  test("the gated runner is registered for unsafeRawForDeclaredStep", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, { reason: "hook reason" }, "hook");
+    expect(unsafeRawForDeclaredStep(gated, "hook reason")).toBe(runner);
+  });
+});

package/src/db/index.ts

@@ -155,7 +155,7 @@ export {
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
 export {
   castTenantRows,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
   SYSTEM_SCOPE_CHECK_BRAND,
 } from "./tenant-db";

package/src/db/pg-error.ts

@@ -21,6 +21,19 @@ export function extractPgError(e: unknown): PgErrorInfo | null {
     // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
     const code = (layer as { code?: string }).code;
     const constraintName = (layer as { constraint_name?: string }).constraint_name; // @cast-boundary error-details
+    // Bun.SQL carries the SQLSTATE in `errno` (string) and the constraint name
+    // in `constraint`, not in postgres-js's `code`/`constraint_name`.
+    if (code === "ERR_POSTGRES_SERVER_ERROR") {
+      const errno = (layer as { errno?: unknown }).errno; // @cast-boundary error-details
+      const constraint = (layer as { constraint?: unknown }).constraint; // @cast-boundary error-details
+      if (typeof errno === "string") {
+        return {
+          code: errno,
+          constraint_name:
+            constraintName ?? (typeof constraint === "string" ? constraint : undefined),
+        };
+      }
+    }
     if (code !== undefined || constraintName !== undefined) {
       return { code, constraint_name: constraintName };
     }

package/src/db/queries/__tests__/{unsafe-read-retrying.test.ts → unsafe-read-retrying.integration.test.ts}

@@ -1,16 +1,10 @@
-// #2323: event-store.ts's and projection-rebuild.ts's plain SELECT helpers
-// read via asRawClient(db).unsafe() directly, bypassing the #1163
-// closed-connection retry that only covered bun-db/query.ts's own
-// selectMany/countWhere. Routed the non-locking read call sites through
-// unsafeReadRetrying instead — this test mirrors
-// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
-// the retry now fires. Writes (insertSubsequentEventRow, upsertSnapshot,
-// markProjectionRebuilding, ...) stay unretried per #1358, and the
-// FOR UPDATE / FOR UPDATE SKIP LOCKED reads in event-consumer.ts are always
-// called inside transaction() (verified against their only call sites) — the
-// retry guard there is a no-op, so those are left as asRawClient calls too.
+// event-store.ts's and projection-rebuild.ts's SELECT helpers run through
+// unsafeReadRetrying; this proves the retry fires using a real captured
+// driver error. Writes and the FOR UPDATE reads inside transaction() stay
+// out of scope — unretried by design.
 
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
+import { captureClosedConnectionError } from "../../../testing/closed-connection-error";
 import {
   selectAggregateMaxVersion,
   selectEventsHighWaterMark,
@@ -22,24 +16,28 @@ import {
   selectEventsForProjectionRebuildBatch,
 } from "../projection-rebuild";
 
-function closedConnectionError(): Error {
-  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
-}
+let closedConnectionError: unknown;
+
+beforeAll(async () => {
+  closedConnectionError = await captureClosedConnectionError();
+});
 
 type RecordedCall = { readonly sql: string; readonly params: readonly unknown[] | undefined };
 
 type FakeClient = {
   unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
   begin: () => never;
+  options: { max: number };
   calls: number;
   recordedCalls: RecordedCall[];
 };
 
-function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+function fakeClient(failures: unknown[], row: Record<string, unknown>): FakeClient {
   const remaining = [...failures];
   const client: FakeClient = {
     calls: 0,
     recordedCalls: [],
+    options: { max: 1 },
     unsafe: async (sql, params) => {
       client.calls++;
       client.recordedCalls.push({ sql, params });
@@ -54,9 +52,9 @@ function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient
   return client;
 }
 
-describe("framework db/queries — closed-connection retry (#2323)", () => {
+describe("framework db/queries — closed-connection retry", () => {
   test("selectStreamMaxVersion retries once and returns the version", async () => {
-    const db = fakeClient([closedConnectionError()], { v: 5 });
+    const db = fakeClient([closedConnectionError], { v: 5 });
     const result = await selectStreamMaxVersion(db as never, "agg1", "t1");
     expect(result).toBe(5);
     expect(db.calls).toBe(2);
@@ -65,28 +63,28 @@ describe("framework db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("selectAggregateMaxVersion retries once and returns the version", async () => {
-    const db = fakeClient([closedConnectionError()], { v: 7 });
+    const db = fakeClient([closedConnectionError], { v: 7 });
     const result = await selectAggregateMaxVersion(db as never, "agg1");
     expect(result).toBe(7);
     expect(db.calls).toBe(2);
   });
 
   test("selectEventsHighWaterMark retries once and returns the max id", async () => {
-    const db = fakeClient([closedConnectionError()], { max: 42n });
+    const db = fakeClient([closedConnectionError], { max: 42n });
     const result = await selectEventsHighWaterMark(db as never);
     expect(result).toBe(42n);
     expect(db.calls).toBe(2);
   });
 
   test("selectNextEventIdAfter retries once and returns the next id", async () => {
-    const db = fakeClient([closedConnectionError()], { id: 43n });
+    const db = fakeClient([closedConnectionError], { id: 43n });
     const result = await selectNextEventIdAfter(db as never, 42n);
     expect(result).toBe(43n);
     expect(db.calls).toBe(2);
   });
 
   test("selectEventsForProjectionRebuildBatch retries once and returns rows", async () => {
-    const db = fakeClient([closedConnectionError()], { id: "1", type: "created" });
+    const db = fakeClient([closedConnectionError], { id: "1", type: "created" });
     const rows = await selectEventsForProjectionRebuildBatch(
       db as never,
       ["user"],
@@ -99,17 +97,19 @@ describe("framework db/queries — closed-connection retry (#2323)", () => {
   });
 
   test("countSubscribedEvents retries once and returns the count", async () => {
-    const db = fakeClient([closedConnectionError()], { n: 12n });
+    const db = fakeClient([closedConnectionError], { n: 12n });
     const result = await countSubscribedEvents(db as never, ["user"], ["user:created"]);
     expect(result).toBe(12n);
     expect(db.calls).toBe(2);
   });
 
-  test("gives up after the single retry when the connection stays closed", async () => {
-    const db = fakeClient([closedConnectionError(), closedConnectionError()], { v: 5 });
-    await expect(selectStreamMaxVersion(db as never, "agg1", "t1")).rejects.toThrow(
-      "connection was closed",
+  test("gives up after exhausting pool-bounded retries (max: 1 → 3 total calls)", async () => {
+    const db = fakeClient([closedConnectionError, closedConnectionError, closedConnectionError], {
+      v: 5,
+    });
+    await expect(selectStreamMaxVersion(db as never, "agg1", "t1")).rejects.toBe(
+      closedConnectionError,
     );
-    expect(db.calls).toBe(2);
+    expect(db.calls).toBe(3);
   });
 });

package/src/db/tenant-db.ts

@@ -73,25 +73,49 @@ export function unsafeRawForDeclaredStep(
   if (!runner) {
     throw new InternalError({
       message:
-        "unsafeRawForDeclaredStep received a holder not built by createTenantDb or " +
-        "createUncheckedSystemDb — no declared unsafeRaw runner bound.",
+        "unsafeRawForDeclaredStep received a holder not built by createTenantDb, " +
+        "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
     });
   }
   return runner(reason);
 }
 
-// buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
-// mode from the caller's own tenantId, never a foreign one.
-//
-// dbOutsideTransaction is optional so every existing single-arg call site
-// (jobs, tests, delivery-service.ts) keeps compiling — those callers have no
-// outside-tx source to hand in and never needed one. Only
-// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
-// is reachable through `ctx.systemDb`.
-export function createUncheckedSystemDb(
+const systemDbRebinders = new WeakMap<
+  UncheckedSystemDb,
+  (grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string) => UncheckedSystemDb
+>();
+
+// Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
+// rebuilt from the original db/dbOutsideTransaction/report, never stacked onto a prior rebind.
+// Inputs not built by createUncheckedSystemDb pass through unchanged.
+export function withSystemDbUnsafeRawGrant(
+  systemDb: UncheckedSystemDb,
+  grant: EscapeHatchDeclaration | undefined,
+  deniedCallerLabel: string,
+): UncheckedSystemDb {
+  const rebind = systemDbRebinders.get(systemDb);
+  return rebind ? rebind(grant, deniedCallerLabel) : systemDb;
+}
+
+// Ungated when `gate` is absent (the handler's own ctx.systemDb — systemScope() is
+// itself the grant there). Gated by a hook's own escapeHatch when `gate.kind` is
+// "hook-grant": unsafeRaw then denies without `hasGrant(gate.grant)`, same error shape
+// as ctx.db.unsafeRaw's denial in createTenantDb below. Gated by the source TenantDb's
+// own escapeHatch when `gate.kind` is "source-tenant-db" (createSystemDbView): unsafeRaw
+// defers entirely to db's own declared runner (reason/memberReadOnly/grant check and
+// report) — the view's own `report` is never called for unsafe-raw in that mode, and a
+// source not built by createTenantDb fails closed.
+function buildUncheckedSystemDb(
   db: TenantDb,
-  dbOutsideTransaction?: TenantDb,
-  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+  dbOutsideTransaction: TenantDb | undefined,
+  report: EscapeHatchReporter,
+  gate?:
+    | {
+        readonly kind: "hook-grant";
+        readonly grant: EscapeHatchDeclaration | undefined;
+        readonly deniedCallerLabel: string;
+      }
+    | { readonly kind: "source-tenant-db" },
 ): UncheckedSystemDb {
   const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
 
@@ -113,9 +137,19 @@ export function createUncheckedSystemDb(
   }
 
   function grantedUnsafeRawRunner(reason: string): DbRunner {
+    if (gate?.kind === "source-tenant-db") {
+      return unsafeRawForDeclaredStep(db, reason);
+    }
     if (reason.trim().length === 0) {
       throw new Error("unsafeRaw requires a non-empty reason");
     }
+    if (gate && !hasGrant(gate.grant)) {
+      throw new AccessDeniedError({
+        message:
+          'ctx.systemDb.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+          `${gate.deniedCallerLabel} to allow unsafeRaw.`,
+      });
+    }
     report("unsafe-raw", reason);
     return tenantDbRunner(db);
   }
@@ -178,9 +212,52 @@ export function createUncheckedSystemDb(
     },
   };
   declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+  if (gate?.kind !== "source-tenant-db") {
+    systemDbRebinders.set(uncheckedSystemDb, (grant, deniedCallerLabel) =>
+      buildUncheckedSystemDb(
+        withUnsafeRawGrant(db, grant),
+        dbOutsideTransaction && withUnsafeRawGrant(dbOutsideTransaction, grant),
+        report,
+        { kind: "hook-grant", grant, deniedCallerLabel },
+      ),
+    );
+  }
   return uncheckedSystemDb;
 }
 
+// Framework-private (not re-exported from db/index.ts): buildHandlerContext
+// (pipeline/dispatch-shared.ts) always builds "system" mode from the caller's
+// own tenantId, never a foreign one.
+//
+// dbOutsideTransaction is optional so every existing single-arg call site
+// (jobs/job-runner.ts, tests) keeps compiling — those callers have no
+// outside-tx source to hand in and never needed one. Only
+// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
+// is reachable through `ctx.systemDb`.
+//
+// Ungated here (the handler's own systemScope() is the grant); a hook's own
+// escapeHatch is layered on afterwards via withSystemDbUnsafeRawGrant. Public
+// callers use createSystemDbView instead, whose unsafeRaw follows the source
+// TenantDb's own escapeHatch gate.
+export function createUncheckedSystemDb(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+): UncheckedSystemDb {
+  return buildUncheckedSystemDb(db, dbOutsideTransaction, report);
+}
+
+// Public: must never grant more raw access than the source TenantDb — unlike
+// createUncheckedSystemDb (framework-private; r.systemScope()/a job IS the
+// declaration), this view's unsafeRaw defers entirely to db's own escapeHatch gate.
+export function createSystemDbView(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+  report: EscapeHatchReporter = fallbackEscapeHatchReporter(db.tenantId),
+): UncheckedSystemDb {
+  return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
+}
+
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {
   return rows as unknown as readonly T[];

package/src/engine/__tests__/boot-validator-gdpr-storage.test.ts

@@ -15,7 +15,12 @@ import { defineFeature } from "../define-feature";
 const udr = () => defineFeature("user-data-rights", () => {});
 const fileProvider = (name: string) =>
   defineFeature(`file-provider-${name}`, (r) => {
-    r.useExtension("fileProvider", name);
+    // build is never invoked here — the boot check only cares that a provider is mounted.
+    r.useExtension("fileProvider", name, {
+      build: async () => {
+        throw new Error("test stub — never invoked");
+      },
+    });
   });
 
 const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;

package/src/engine/__tests__/boot-validator-s0-integration.test.ts

@@ -104,8 +104,8 @@ describe("S0 Integration — full surface stack", () => {
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
 
-      r.useExtension(EXT_USER_DATA, "user", {});
-      r.useExtension(EXT_USER_DATA, "comment", {});
+      r.useExtension(EXT_USER_DATA, "user", { export: async () => null });
+      r.useExtension(EXT_USER_DATA, "comment", { export: async () => null });
 
       r.writeHandler({
         name: "user:rename",

package/src/engine/__tests__/boot-validator.test.ts

@@ -358,7 +358,7 @@ describe("boot-validator", () => {
     const self = defineFeature("tier-stub", (r) => {
       r.extendsRegistrar("tenantTierResolver", { onRegister: () => {} });
       r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
-      r.useExtension("tenantTierResolver", "dummy");
+      r.useExtension("tenantTierResolver", "dummy", { build: async () => () => new Set() });
     });
     expect(() => validateBoot([self])).not.toThrow();
   });

package/src/engine/__tests__/tier-resolver-extension.test.ts

@@ -15,7 +15,7 @@ function tierResolverFeature(name: string) {
   return defineFeature(name, (r) => {
     r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, { onRegister: () => {} });
     r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
-    r.useExtension(TENANT_TIER_RESOLVER_EXT, "dummy");
+    r.useExtension(TENANT_TIER_RESOLVER_EXT, "dummy", { build: async () => () => new Set() });
   });
 }