@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -121,108 +121,117 @@ async function requestIngestForFileRef(
   });
 }
 
-export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
-  );
-  r.uiHints({
-    displayLabel: "Document Ingest Foundation",
-    category: "storage",
-    recommended: false,
-  });
-  // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
-  // tenant-subject ciphertext and needs the destroy hook below.
-  r.requires({ features: ["config", "tenant-lifecycle"] });
-
-  r.entity({ name: "documentExtract", ...documentExtractEntity });
-  r.useExtension(EXT_TENANT_DATA, "documentExtract", {
-    destroy: documentExtractTenantDestroyHook,
-  });
-
-  // No onRegister: resolution happens at boot and per-apply, not on register.
-  r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
-  r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
-
-  const ocrLanguageConfigKey = r.config(
-    "ocrLanguage",
-    createTenantConfig("text", {
-      default: "deu+eng",
-      // Tesseract -l argument syntax: one or more 3-letter language codes
-      // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
-      // reach the OCR provider call unvalidated (#1501).
-      pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-  const maxPagesPerFileConfigKey = r.config(
-    "maxPagesPerFile",
-    createTenantConfig("number", {
-      default: 50,
-      // Without a bound a tenant could set 0 (silently kills ingest) or an
-      // unbounded value (OCR worker runs per-file for as long as the PDF
-      // has pages — job-queue starvation) (#1501).
-      bounds: { min: 1, max: 500 },
-      write: access.roles("TenantAdmin", "SystemAdmin"),
-      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
-    }),
-  );
-
-  // "fileName" can carry a real person's name, but it reaches both events already as the
-  // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
-  // append() passes through; shredding the fileRef's key shreds it here too.
-  r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
-    piiFields: "none",
-    version: 2,
-    migrations: [
-      {
-        fromVersion: 1,
-        toVersion: 2,
-        // The sentinel can never match a real where.provider filter (providers
-        // may not register under it) — an upcast v1 row reads as unclaimed
-        // instead of silently misrouting to a currently mounted provider.
-        transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
-      },
-    ],
-  });
-  r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
-    piiFields: "none",
-  });
-
-  r.multiStreamProjection({
-    name: "request-ingest",
-    apply: {
-      [FILE_REF_CREATED]: async (event, _tx, ctx) => {
-        // entity-event payloads are generic Record<string, unknown> — parse
-        // at the MSP boundary (same pattern as storage-tracking's readNumber).
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
-        // skip: malformed / incomplete payload — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-      [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
-        // fileRef.restored carries { previous }, the pre-restore soft-deleted
-        // row (event-store-executor-write.ts restore()) — same field shape
-        // as fileRef.created's payload.
-        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
-        // skip: malformed / incomplete previous snapshot — don't poison the consumer
-        if (!parsed.success) return;
-        await requestIngestForFileRef(event, parsed.data, ctx);
-      },
-    },
-  });
-
-  // fileRef delete/forget cleanup: documentExtract rows are derived data —
-  // once the source file is gone (soft-deleted or Art.17-forgotten), the
-  // extracted text has no reason to survive it either.
-  r.multiStreamProjection({
-    name: "forget-extract-with-file-ref",
-    apply: {
-      [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
-      [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
-      [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+export function createDocumentIngestFoundationFeature() {
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
+      );
+      r.uiHints({
+        displayLabel: "Document Ingest Foundation",
+        category: "storage",
+        recommended: false,
+      });
+      // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
+      // tenant-subject ciphertext and needs the destroy hook below.
+      r.requires({ features: ["config", "tenant-lifecycle"] });
+
+      r.entity({ name: "documentExtract", ...documentExtractEntity });
+      r.useExtension(EXT_TENANT_DATA, "documentExtract", {
+        destroy: documentExtractTenantDestroyHook,
+      });
+
+      // No onRegister: resolution happens at boot and per-apply, not on register.
+      r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
+      r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
+
+      const ocrLanguageConfigKey = r.config(
+        "ocrLanguage",
+        createTenantConfig("text", {
+          default: "deu+eng",
+          // Tesseract -l argument syntax: one or more 3-letter language codes
+          // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
+          // reach the OCR provider call unvalidated (#1501).
+          pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+      const maxPagesPerFileConfigKey = r.config(
+        "maxPagesPerFile",
+        createTenantConfig("number", {
+          default: 50,
+          // Without a bound a tenant could set 0 (silently kills ingest) or an
+          // unbounded value (OCR worker runs per-file for as long as the PDF
+          // has pages — job-queue starvation) (#1501).
+          bounds: { min: 1, max: 500 },
+          write: access.roles("TenantAdmin", "SystemAdmin"),
+          read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+        }),
+      );
+
+      // "fileName" can carry a real person's name, but it reaches both events already as the
+      // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
+      // append() passes through; shredding the fileRef's key shreds it here too.
+      r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
+        piiFields: "none",
+        version: 2,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            // The sentinel can never match a real where.provider filter (providers
+            // may not register under it) — an upcast v1 row reads as unclaimed
+            // instead of silently misrouting to a currently mounted provider.
+            transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
+          },
+        ],
+      });
+      r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
+        piiFields: "none",
+      });
+
+      r.multiStreamProjection({
+        name: "request-ingest",
+        apply: {
+          [FILE_REF_CREATED]: async (event, _tx, ctx) => {
+            // entity-event payloads are generic Record<string, unknown> — parse
+            // at the MSP boundary (same pattern as storage-tracking's readNumber).
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
+            // skip: malformed / incomplete payload — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+          [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
+            // fileRef.restored carries { previous }, the pre-restore soft-deleted
+            // row (event-store-executor-write.ts restore()) — same field shape
+            // as fileRef.created's payload.
+            const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
+            // skip: malformed / incomplete previous snapshot — don't poison the consumer
+            if (!parsed.success) return;
+            await requestIngestForFileRef(event, parsed.data, ctx);
+          },
+        },
+      });
+
+      // fileRef delete/forget cleanup: documentExtract rows are derived data —
+      // once the source file is gone (soft-deleted or Art.17-forgotten), the
+      // extracted text has no reason to survive it either.
+      r.multiStreamProjection({
+        name: "forget-extract-with-file-ref",
+        apply: {
+          [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
+          [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
+          [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
+        },
+      });
+
+      return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
     },
-  });
+    { dedupeOptions: {} },
+  );
+}
 
-  return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
-});
+/** @deprecated Use createDocumentIngestFoundationFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const documentIngestFoundationFeature = createDocumentIngestFoundationFeature();

package/packages/bundled-features/src/document-ingest-foundation/forget-extract-with-file-ref.ts

@@ -57,7 +57,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
   const parsed = documentExtractCreatedPayloadSchema.safeParse(event.payload);
   // skip: malformed payload — don't poison the consumer
   if (!parsed.success) return;
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef still live — the extract is legitimate
   if (await isFileRefLive(tenantDb, parsed.data.fileRefId)) return;
   const user = createSystemUser(event.tenantId);
@@ -70,7 +70,7 @@ export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   // skip: fileRef is live again — request-ingest and this consumer poll via
   // separate cursors, so a delete→restore round-trip can finish before this
   // consumer sees fileRef.deleted; forgetting would drop the live file's extract.
@@ -79,6 +79,6 @@ export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (even
 };
 
 export const forgetExtractOnFileRefForgottenHook: MultiStreamApplyFn = async (event, tx) => {
-  const tenantDb = createTenantDb(tx, event.tenantId);
+  const tenantDb = createTenantDb({ db: tx, tenantId: event.tenantId });
   await forgetExtractsForFileRef(event, tenantDb);
 };

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -18,7 +18,10 @@ export {
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.js";
-export { documentIngestFoundationFeature } from "./feature.js";
+export {
+  createDocumentIngestFoundationFeature,
+  documentIngestFoundationFeature,
+} from "./feature.js";
 export { readIngestPages, writeIngestPages } from "./pages.js";
 export {
   type DocumentIngestProviderOptions,

package/packages/bundled-features/src/feature-toggles/global-feature-state-table.ts

@@ -1,4 +1,3 @@
-import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
   declareGlobalTenancy,
@@ -6,6 +5,7 @@ import {
   instant,
   integer,
   table as pgTable,
+  requireEntityTableMeta,
   type SchemaTable,
   sql,
   text,

package/packages/bundled-features/src/feature-toggles/handlers/set.write.ts

@@ -1,4 +1,4 @@
-import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,
@@ -158,10 +158,8 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
       // and filtering by payload.featureName is trivial at query time.
       // This mirrors how `config` handles the same constraint for
       // its config-changed events.
-      // unsafeAppendEvent — bundled-features ohne lokalen Wrapper. Apps
-      // mit `bun kumiko codegen` kriegen `.kumiko/define.ts` als strict-
-      // path; bundled-features bleibt bei der unsafe-Variante. Schema-
-      // Validation läuft trotzdem via r.defineEvent("toggle-set", ...).
+      // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
+      // bundled-features cannot see. Schema validation still runs via r.defineEvent("toggle-set", ...).
       await ctx.unsafeAppendEvent({
         aggregateId: SYSTEM_TENANT_ID,
         aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,

package/packages/bundled-features/src/feature-toggles/toggle-runtime.ts

@@ -1,5 +1,5 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   computeEffectiveFeatures,
   type Registry,

package/packages/bundled-features/src/file-derivatives/feature.ts

@@ -100,137 +100,142 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     );
   }
 
-  return defineFeature(FEATURE_NAME, (r) => {
-    r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
-    );
-    r.uiHints({
-      displayLabel: "File Derivatives",
-      category: "storage",
-      recommended: false,
-    });
-    // Needs a storage provider to read the original + write the variant —
-    // without file-foundation there's nothing to derive from or write to.
-    r.requires({ features: ["file-foundation"] });
-    // variant() reads fileRefsTable, which "files" (not file-foundation)
-    // owns — without this, mounting file-derivatives + file-foundation
-    // alone boots fine but fails at request-time with a SQL error the first
-    // time variant() runs.
-    r.requires({ features: ["files"] });
-
-    r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution (exact MIME match,
-        // then `<type>/*` wildcard) happens at request-time in
-        // resolveRenderer, mirrors file-foundation's fileProvider point.
-      },
-    });
-    r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution happens at
-        // request-time in publicVariantQuery, keyed by the FileRef's
-        // entityType.
-      },
-    });
-    r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
-      onRegister: () => {
-        // No side-effects at register-time — resolution happens in
-        // variant(), keyed by the FileRef's entityType, before the spec
-        // hash is computed.
-      },
-    });
-
-    // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
-    // registers publicVariantQuery into the feature's dispatch table as a
-    // side effect of being called, independent of what's done with its
-    // return value. Calling it unconditionally would make `publicVariant`
-    // (access: ["anonymous", ...]) reachable via the generic `/api` query
-    // dispatch even when the httpRoute below isn't mounted, bypassing the
-    // "tenantId comes from the host, never the payload" invariant that only
-    // `resolveApexTenant` enforces.
-    if (opts.resolveApexTenant) {
-      const resolveApexTenant = opts.resolveApexTenant;
-      const byFileRef = opts.publicTenantResolution === "fileRef";
-      const routeQn = byFileRef ? PUBLIC_VARIANT_BY_FILE_REF_QN : PUBLIC_VARIANT_QN;
-
-      r.queryHandler(publicVariantQuery);
-      // publicVariantByFileRefQuery is the ONLY way "fileRef" mode is
-      // reachable — registered ONLY in that mode for the same reason
-      // publicVariantQuery is gated above: registering it unconditionally
-      // would expose its unsafeRaw, cross-tenant FileRef lookup via the
-      // generic `/api` query dispatch even in default "host" mode.
-      if (byFileRef) {
-        // The handler reads the FileRef-tenant's row to keep a blocked
-        // tenant's public variants from staying reachable — require the
-        // dependency so a missing mount fails boot, not the tenant check
-        // silently no-op-ing at request time.
-        r.requires({ features: ["tenant"] });
-        r.queryHandler(publicVariantByFileRefQuery);
-      }
-
-      r.httpRoute({
-        method: "GET",
-        path: `${basePath}/:fileRefId/:variant`,
-        anonymous: true,
-        handler: async (c, { systemQuery }) => {
-          // `param(...)` is string|undefined here — `path` is a computed
-          // template, so Hono can't infer the param type from a literal.
-          const fileRefId = c.req.param("fileRefId");
-          const variant = c.req.param("variant");
-          // 404, not 400 — a syntactically bad name and "doesn't exist" must
-          // answer identically, no name-oracle. fileRefsTable.id is a UUID
-          // column — a malformed id must fail here, not at the DB. Without
-          // this, an anonymous, internet-facing caller can throw a Postgres
-          // 22P02 on every request (Bun.SQL pools the failed connection), a
-          // DoS primitive with no auth required.
-          if (!fileRefId || !variant || !VARIANT_NAME_RE.test(variant) || !isUuid(fileRefId)) {
-            return c.text("not found", 404);
-          }
-
-          const host = c.req.header("host") ?? new URL(c.req.url).host;
-          const tenantId = await resolveApexTenant(host);
-          if (!tenantId) return c.text("not found", 404);
-
-          let result: PublicVariantQueryResult;
-          try {
-            // @cast-boundary engine-payload — shape comes from
-            // publicVariantQuery's return type (publicVariantByFileRefQuery
-            // returns exactly that, or null, never its own shape).
-            result = (await systemQuery(
-              routeQn,
-              { fileRefId, variant },
-              tenantId,
-            )) as PublicVariantQueryResult;
-          } catch (err) {
-            if (err instanceof RateLimitError) {
-              return c.text("rate limited", 429);
-            }
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, no logger wired into HttpRouteHandlerDeps
-            console.error(
-              `file-derivatives: public-variant query failed for fileRefId="${fileRefId}" variant="${variant}"`,
-              err,
-            );
-            return c.text("variant unavailable", 503);
-          }
-          if (!result) return c.text("not found", 404);
-
-          const bytes = Buffer.from(result.dataBase64, "base64");
-          const etag = computeRevisionEtag([tenantId, fileRefId, variant, result.revision]);
-          return cachedResponse(c.req.raw, {
-            body: bytes,
-            etag,
-            cache: { kind: "revalidate", maxAgeSeconds: 60 },
-            // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
-            headers: {
-              "content-type": result.mimeType,
-              vary: "Host",
-              "x-content-type-options": "nosniff",
-            },
-          });
+  return defineFeature(
+    FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
+      );
+      r.uiHints({
+        displayLabel: "File Derivatives",
+        category: "storage",
+        recommended: false,
+      });
+      // Needs a storage provider to read the original + write the variant —
+      // without file-foundation there's nothing to derive from or write to.
+      r.requires({ features: ["file-foundation"] });
+      // variant() reads fileRefsTable, which "files" (not file-foundation)
+      // owns — without this, mounting file-derivatives + file-foundation
+      // alone boots fine but fails at request-time with a SQL error the first
+      // time variant() runs.
+      r.requires({ features: ["files"] });
+
+      r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution (exact MIME match,
+          // then `<type>/*` wildcard) happens at request-time in
+          // resolveRenderer, mirrors file-foundation's fileProvider point.
+        },
+      });
+      r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution happens at
+          // request-time in publicVariantQuery, keyed by the FileRef's
+          // entityType.
         },
       });
-    }
-  });
+      r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
+        onRegister: () => {
+          // No side-effects at register-time — resolution happens in
+          // variant(), keyed by the FileRef's entityType, before the spec
+          // hash is computed.
+        },
+      });
+
+      // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
+      // registers publicVariantQuery into the feature's dispatch table as a
+      // side effect of being called, independent of what's done with its
+      // return value. Calling it unconditionally would make `publicVariant`
+      // (access: ["anonymous", ...]) reachable via the generic `/api` query
+      // dispatch even when the httpRoute below isn't mounted, bypassing the
+      // "tenantId comes from the host, never the payload" invariant that only
+      // `resolveApexTenant` enforces.
+      if (opts.resolveApexTenant) {
+        const resolveApexTenant = opts.resolveApexTenant;
+        const byFileRef = opts.publicTenantResolution === "fileRef";
+        const routeQn = byFileRef ? PUBLIC_VARIANT_BY_FILE_REF_QN : PUBLIC_VARIANT_QN;
+
+        r.queryHandler(publicVariantQuery);
+        // publicVariantByFileRefQuery is the ONLY way "fileRef" mode is
+        // reachable — registered ONLY in that mode for the same reason
+        // publicVariantQuery is gated above: registering it unconditionally
+        // would expose its unsafeRaw, cross-tenant FileRef lookup via the
+        // generic `/api` query dispatch even in default "host" mode.
+        if (byFileRef) {
+          // The handler reads the FileRef-tenant's row to keep a blocked
+          // tenant's public variants from staying reachable — require the
+          // dependency so a missing mount fails boot, not the tenant check
+          // silently no-op-ing at request time.
+          r.requires({ features: ["tenant"] });
+          r.queryHandler(publicVariantByFileRefQuery);
+        }
+
+        r.httpRoute({
+          method: "GET",
+          path: `${basePath}/:fileRefId/:variant`,
+          anonymous: true,
+          handler: async (c, { systemQuery }) => {
+            // `param(...)` is string|undefined here — `path` is a computed
+            // template, so Hono can't infer the param type from a literal.
+            const fileRefId = c.req.param("fileRefId");
+            const variant = c.req.param("variant");
+            // 404, not 400 — a syntactically bad name and "doesn't exist" must
+            // answer identically, no name-oracle. fileRefsTable.id is a UUID
+            // column — a malformed id must fail here, not at the DB. Without
+            // this, an anonymous, internet-facing caller can throw a Postgres
+            // 22P02 on every request (Bun.SQL pools the failed connection), a
+            // DoS primitive with no auth required.
+            if (!fileRefId || !variant || !VARIANT_NAME_RE.test(variant) || !isUuid(fileRefId)) {
+              return c.text("not found", 404);
+            }
+
+            const host = c.req.header("host") ?? new URL(c.req.url).host;
+            const tenantId = await resolveApexTenant(host);
+            if (!tenantId) return c.text("not found", 404);
+
+            let result: PublicVariantQueryResult;
+            try {
+              // @cast-boundary engine-payload — shape comes from
+              // publicVariantQuery's return type (publicVariantByFileRefQuery
+              // returns exactly that, or null, never its own shape).
+              result = (await systemQuery(
+                routeQn,
+                { fileRefId, variant },
+                tenantId,
+              )) as PublicVariantQueryResult;
+            } catch (err) {
+              if (err instanceof RateLimitError) {
+                return c.text("rate limited", 429);
+              }
+              // biome-ignore lint/suspicious/noConsole: ops-visible fallback, no logger wired into HttpRouteHandlerDeps
+              console.error(
+                `file-derivatives: public-variant query failed for fileRefId="${fileRefId}" variant="${variant}"`,
+                err,
+              );
+              return c.text("variant unavailable", 503);
+            }
+            if (!result) return c.text("not found", 404);
+
+            const bytes = Buffer.from(result.dataBase64, "base64");
+            const etag = computeRevisionEtag([tenantId, fileRefId, variant, result.revision]);
+            return cachedResponse(c.req.raw, {
+              body: bytes,
+              etag,
+              cache: { kind: "revalidate", maxAgeSeconds: 60 },
+              // Explicit here, not left to the app-wide security-headers default, so the route stays safe standalone.
+              headers: {
+                "content-type": result.mimeType,
+                vary: "Host",
+                "x-content-type-options": "nosniff",
+              },
+            });
+          },
+        });
+      }
+    },
+    Object.keys(opts).length === 0 ? { dedupeOptions: {} } : undefined,
+  );
 }
 
+/** @deprecated Use createFileDerivativesFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
 export const fileDerivativesFeature = createFileDerivativesFeature();

package/packages/bundled-features/src/file-derivatives/handlers/public-variant-by-file-ref.query.ts

@@ -1,4 +1,4 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   createAnonymousUser,
   defineQueryHandler,

package/packages/bundled-features/src/file-derivatives/handlers/public-variant.query.ts

@@ -23,7 +23,7 @@
 // but this handler's own isPublic gate runs exactly the same either way.
 
 import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { resolveFieldVariant } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   defineQueryHandler,