@cosmicdrift/kumiko-bundled-features 0.309.0 → 0.311.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.309.0",
+  "version": "0.311.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.309.0",
-    "@cosmicdrift/kumiko-framework": "0.309.0",
-    "@cosmicdrift/kumiko-headless": "0.309.0",
-    "@cosmicdrift/kumiko-renderer": "0.309.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.309.0",
-    "@cosmicdrift/kumiko-types": "0.309.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.311.0",
+    "@cosmicdrift/kumiko-framework": "0.311.0",
+    "@cosmicdrift/kumiko-headless": "0.311.0",
+    "@cosmicdrift/kumiko-renderer": "0.311.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.311.0",
+    "@cosmicdrift/kumiko-types": "0.311.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.309.0",
-    "@cosmicdrift/kumiko-locale-es": "0.309.0",
+    "@cosmicdrift/kumiko-locale-de": "0.311.0",
+    "@cosmicdrift/kumiko-locale-es": "0.311.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/audit/__tests__/escape-hatch-audit.integration.test.ts

@@ -12,6 +12,7 @@ import {
   type TestStack,
   testTenantId,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import * as z from "zod";
 import { createConfigFeature } from "../../config";
 import { createTenantFeature } from "../../tenant";
@@ -71,18 +72,21 @@ type AuditRow = {
 type AuditResponse = { rows: AuditRow[]; nextBefore: string | null };
 
 async function pollForEscapeHatchRow(): Promise<AuditRow> {
-  const deadline = Date.now() + 2000;
-  while (Date.now() < deadline) {
-    const res = await stack.http.queryOk<AuditResponse>(
-      AuditQueries.list,
-      { eventType: ESCAPE_HATCH_USED_EVENT },
-      adminOfSameTenant,
-    );
-    const row = res.rows[0];
-    if (row) return row;
-    await new Promise((resolve) => setTimeout(resolve, 50));
-  }
-  throw new Error("escape-hatch-used audit row did not appear within 2s");
+  let row: AuditRow | undefined;
+  await waitFor(
+    async () => {
+      const res = await stack.http.queryOk<AuditResponse>(
+        AuditQueries.list,
+        { eventType: ESCAPE_HATCH_USED_EVENT },
+        adminOfSameTenant,
+      );
+      row = res.rows[0];
+      return row !== undefined;
+    },
+    { delays: Array(40).fill(50) },
+  );
+  if (row === undefined) throw new Error("escape-hatch-used audit row did not appear within 2s");
+  return row;
 }
 
 describe("createEscapeHatchAuditSink — persists audit:event:escape-hatch-used", () => {

package/src/delivery/__tests__/delivery.integration.test.ts

@@ -26,6 +26,7 @@ import {
   testTenantId,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import * as z from "zod";
 import { createChannelEmailFeature } from "../../channel-email/feature";
 import { createInMemoryTransport, type EmailMessage } from "../../channel-email/types";
@@ -1502,21 +1503,6 @@ describe("flow 16: repeated unsubscribe clicks are idempotent", () => {
 // non-string `to` as a broadcast target ("tenant" in to).
 const asyncRecipient = "7";
 
-async function waitFor(check: () => Promise<void>, timeoutMs = 10000): Promise<void> {
-  const start = Date.now();
-  let lastErr: unknown;
-  for (;;) {
-    try {
-      await check();
-      return;
-    } catch (err) {
-      lastErr = err;
-      if (Date.now() - start > timeoutMs) throw lastErr;
-      await new Promise((resolve) => setTimeout(resolve, 50));
-    }
-  }
-}
-
 function makeStubRunner(): {
   runner: JobRunner;
   dispatched: Array<{
@@ -1580,13 +1566,16 @@ describe("flow 17: async render→send pipeline", () => {
 
       // Email: queued → render job → send job → sent. Proves the framework
       // jobRunner-into-job-ctx injection (render dispatches send) end-to-end.
-      await waitFor(async () => {
-        const rows = await selectMany(db, deliveryAttemptsTable, {
-          notificationType: "app:notify:async-e2e",
-          channel: "email",
-        });
-        expect(rows.some((r) => r["status"] === "sent")).toBe(true);
-      });
+      await waitFor(
+        async () => {
+          const rows = await selectMany(db, deliveryAttemptsTable, {
+            notificationType: "app:notify:async-e2e",
+            channel: "email",
+          });
+          expect(rows.some((r) => r["status"] === "sent")).toBe(true);
+        },
+        { delays: Array(40).fill(250) },
+      );
       const email = emailTransport.sent.find((m) => m.to === testEmail(asyncRecipient));
       expect(email).toBeDefined();
       expect(email?.subject).toBe("Async Subject");
@@ -1594,13 +1583,16 @@ describe("flow 17: async render→send pipeline", () => {
       expect(email?.html).toContain("<!DOCTYPE html>");
 
       // Push: no render step → dispatched straight to delivery.send.
-      await waitFor(async () => {
-        const rows = await selectMany(db, deliveryAttemptsTable, {
-          notificationType: "app:notify:async-e2e",
-          channel: "push",
-        });
-        expect(rows.some((r) => r["status"] === "sent")).toBe(true);
-      });
+      await waitFor(
+        async () => {
+          const rows = await selectMany(db, deliveryAttemptsTable, {
+            notificationType: "app:notify:async-e2e",
+            channel: "push",
+          });
+          expect(rows.some((r) => r["status"] === "sent")).toBe(true);
+        },
+        { delays: Array(40).fill(250) },
+      );
       expect(
         pushTransport.sent.find((m) => m.token === testPushToken(asyncRecipient)),
       ).toBeDefined();

package/src/file-derivatives/__tests__/public-variant-cross-tenant.integration.test.ts

@@ -0,0 +1,224 @@
+// Proves kumiko-framework#3255: `publicTenantResolution: "fileRef"` lets a
+// single shared platform host serve every tenant's public variants — the
+// variant is read from the FileRef row's own tenant, not the host's, while
+// resolveApexTenant still gates the host and the FileRef-tenant's own
+// `isPublic` predicate remains the default-deny gate. Default ("host")
+// mode is unchanged: a tenant B file requested through tenant A's host
+// still 404s, identically to any other unknown FileRef.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createImageField,
+  defineFeature,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+  EXT_DERIVATIVE_RENDERER,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-framework/testing";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { createConfigFeature } from "../../config";
+import { fileFoundationFeature } from "../../file-foundation";
+import { createFileDerivativesFeature } from "../feature";
+import type { DerivativePublicPredicateArgs } from "../handlers/public-variant.query";
+import { PUBLIC_VARIANT_BY_FILE_REF_QN } from "../handlers/public-variant-by-file-ref.query";
+
+const VARIANT_BYTES = new Uint8Array([4, 2, 4, 2]);
+const fakeRender: DerivativeRendererPlugin["render"] = async () => VARIANT_BYTES;
+
+const TENANT_A = testTenantId(11);
+const TENANT_B = testTenantId(12);
+const HOST_A = "cross-tenant-a.example.com";
+
+let receivedArgs: DerivativePublicPredicateArgs[] = [];
+const gadgetEntity = createEntity({
+  table: "cross_tenant_public_variant_gadgets",
+  fields: {
+    img: createImageField({ variants: { thumb: { maxEdge: 160, format: "webp" } } }),
+  },
+});
+
+const gadgetPredicateFeature = defineFeature("crosstenantpublicvarianttest", (r) => {
+  r.entity("gadget", gadgetEntity);
+  r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "gadget", {
+    isPublic: (args: DerivativePublicPredicateArgs) => {
+      receivedArgs.push(args);
+      return args.entityId === "public-1";
+    },
+  });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+});
+
+const userA = createTestUser({ id: 1, tenantId: TENANT_A, roles: ["Admin"] });
+const userB = createTestUser({ id: 2, tenantId: TENANT_B, roles: ["Admin"] });
+
+async function uploadImage(
+  stack: TestStack,
+  asUser: typeof userA,
+  entityId: string,
+): Promise<string> {
+  const token = await stack.jwt.sign(asUser);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from([1, 2, 3])], "img.jpg", { type: "image/jpeg" }));
+  fd.append("entityType", "gadget");
+  fd.append("entityId", entityId);
+  fd.append("fieldName", "img");
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+    body,
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+describe("file-derivatives :: publicTenantResolution 'fileRef' — cross-tenant shared host", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    patchFileInstanceofForBunTest();
+    stack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        fileFoundationFeature,
+        createFilesFeature(),
+        createFileDerivativesFeature({
+          resolveApexTenant: (host) => (host === HOST_A ? TENANT_A : null),
+          publicTenantResolution: "fileRef",
+        }),
+        gadgetPredicateFeature,
+      ],
+      files: { storageProvider: createInMemoryFileProvider() },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    receivedArgs = [];
+    await stack.redis.flushNamespace();
+  });
+
+  test("a tenant B public file is served through tenant A's shared host, isPublic runs against tenant B", async () => {
+    const fileId = await uploadImage(stack, userB, "public-1");
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(200);
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
+    expect(receivedArgs).toHaveLength(1);
+    expect(receivedArgs[0]?.tenantId).toBe(TENANT_B);
+  });
+
+  test("a tenant A public file is also served through tenant A's host", async () => {
+    const fileId = await uploadImage(stack, userA, "public-1");
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(200);
+    expect(receivedArgs[0]?.tenantId).toBe(TENANT_A);
+  });
+
+  test("a non-public tenant B file, an unknown fileRefId, and an unknown host all 404 with the same body", async () => {
+    const privateFileId = await uploadImage(stack, userB, "private-1");
+
+    const privateRes = await stack.app.request(`http://${HOST_A}/media/${privateFileId}/thumb`);
+    const unknownFileRefRes = await stack.app.request(
+      `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
+    );
+
+    expect(privateRes.status).toBe(404);
+    expect(unknownFileRefRes.status).toBe(404);
+
+    const unknownFileRefBody = await unknownFileRefRes.text();
+    expect(await privateRes.text()).toBe(unknownFileRefBody);
+  });
+
+  test("an unknown host 404s even for a public file, before isPublic runs", async () => {
+    const publicFileId = await uploadImage(stack, userB, "public-1");
+    const unknownFileRefRes = await stack.app.request(
+      `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
+    );
+    receivedArgs = [];
+
+    const unknownHostRes = await stack.app.request(
+      `http://unknown-host.example.com/media/${publicFileId}/thumb`,
+    );
+
+    expect(unknownHostRes.status).toBe(404);
+    expect(await unknownHostRes.text()).toBe(await unknownFileRefRes.text());
+    expect(receivedArgs).toHaveLength(0);
+  });
+
+  test("PUBLIC_VARIANT_BY_FILE_REF_QN is registered on the stack in 'fileRef' mode", () => {
+    expect(stack.registry.getQueryHandler(PUBLIC_VARIANT_BY_FILE_REF_QN)).toBeDefined();
+  });
+});
+
+describe("file-derivatives :: default ('host') mode is unchanged", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    patchFileInstanceofForBunTest();
+    stack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        fileFoundationFeature,
+        createFilesFeature(),
+        createFileDerivativesFeature({
+          resolveApexTenant: (host) => (host === HOST_A ? TENANT_A : null),
+        }),
+        gadgetPredicateFeature,
+      ],
+      files: { storageProvider: createInMemoryFileProvider() },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    receivedArgs = [];
+    await stack.redis.flushNamespace();
+  });
+
+  test("a tenant B public file requested through tenant A's host 404s, identical body to an unknown FileRef", async () => {
+    const fileId = await uploadImage(stack, userB, "public-1");
+
+    const crossTenantRes = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+    const unknownFileRefRes = await stack.app.request(
+      `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
+    );
+
+    expect(crossTenantRes.status).toBe(404);
+    expect(unknownFileRefRes.status).toBe(404);
+    expect(await crossTenantRes.text()).toBe(await unknownFileRefRes.text());
+  });
+
+  test("PUBLIC_VARIANT_BY_FILE_REF_QN is not registered in default mode — not reachable via the generic /api/query dispatch", () => {
+    expect(stack.registry.getQueryHandler(PUBLIC_VARIANT_BY_FILE_REF_QN)).toBeUndefined();
+  });
+});
+
+describe("createFileDerivativesFeature :: publicTenantResolution requires resolveApexTenant", () => {
+  test("throws when 'fileRef' is passed without resolveApexTenant", () => {
+    expect(() => createFileDerivativesFeature({ publicTenantResolution: "fileRef" })).toThrow();
+  });
+});

package/src/file-derivatives/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.310.0",
+    "type": "improvement",
+    "title": "publicTenantResolution \"fileRef\" reads a public variant from its FileRef's own tenant",
+    "detail": "`createFileDerivativesFeature({ resolveApexTenant, publicTenantResolution: \"fileRef\" })`\nkeeps resolveApexTenant as the host gate (an unknown host still 404s), but\nreads the variant in the tenant that owns the FileRef, so one shared\nplatform host serves `/media/:fileRefId/:variant` for every tenant. The\nFileRef tenant's `isPublic` predicate stays the default-deny gate; unknown\nand non-public FileRefs answer the identical 404. Default \"host\" keeps the\nprevious behavior. In \"fileRef\" mode the anonymous\n`file-derivatives:query:public-variant-by-file-ref` query is also reachable\nover `/api`, independent of the host, and returns only variants the\npredicate allows. Passing publicTenantResolution without resolveApexTenant\nthrows at construction."
+  },
   {
     "version": "0.287.0",
     "type": "improvement",

package/src/file-derivatives/feature.ts

@@ -18,6 +18,10 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
 import { PUBLIC_VARIANT_QN, publicVariantQuery } from "./handlers/public-variant.query";
+import {
+  PUBLIC_VARIANT_BY_FILE_REF_QN,
+  publicVariantByFileRefQuery,
+} from "./handlers/public-variant-by-file-ref.query";
 
 const FEATURE_NAME = "file-derivatives";
 
@@ -42,6 +46,8 @@ export type PublicVariantResolveApexTenant = (
   host: string,
 ) => Promise<TenantId | null> | TenantId | null;
 
+export type PublicVariantTenantResolution = "host" | "fileRef";
+
 export type FileDerivativesOptions = {
   /** Host → tenantId for the anonymous `/media/:fileRefId/:variant` route.
    *  Without this option, neither the httpRoute NOR the `publicVariant`
@@ -52,6 +58,14 @@ export type FileDerivativesOptions = {
   readonly resolveApexTenant?: PublicVariantResolveApexTenant;
   /** Base path of the public variant route. Default "/media". */
   readonly basePath?: string;
+  /** How the route picks the tenant a variant is read from. "host" (default):
+   *  tenant = resolveApexTenant(host). "fileRef": resolveApexTenant still
+   *  gates the host (an unknown host still 404s), but the variant itself is
+   *  read from the FileRef row's own tenant — a single shared platform host
+   *  then serves every tenant's public variants. The FileRef-tenant's own
+   *  `isPublic` predicate remains the default-deny gate either way; requires
+   *  `resolveApexTenant`. */
+  readonly publicTenantResolution?: PublicVariantTenantResolution;
 };
 
 // Raw handler-return of publicVariantQuery — systemQuery dispatches
@@ -73,13 +87,22 @@ type PublicVariantQueryResult = {
 // — only a name, resolved against the field's own `variants` declaration —
 // and only after the app's registered `isPublic` predicate for the FileRef's
 // entityType says yes. tenantId is resolved from the request Host via
-// `resolveApexTenant`, NEVER read from the request payload.
+// `resolveApexTenant`, NEVER read from the request payload — in
+// `publicTenantResolution: "fileRef"` mode the tenant instead comes from the
+// FileRef row matching `fileRefId` (never from the payload either), and the
+// by-file-ref handler is reachable over `/api` independently of any Host,
+// but still only returns a variant its FileRef-tenant's `isPublic` allows.
 export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}): FeatureDefinition {
   const basePath = opts.basePath ?? "/media";
+  if (opts.publicTenantResolution !== undefined && !opts.resolveApexTenant) {
+    throw new Error(
+      "createFileDerivativesFeature: publicTenantResolution requires resolveApexTenant — it only changes which tenant a variant is read from, resolveApexTenant still gates the host.",
+    );
+  }
 
   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\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. 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.",
+      "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\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. `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",
@@ -127,8 +150,18 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     // `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) {
+        r.queryHandler(publicVariantByFileRefQuery);
+      }
 
       r.httpRoute({
         method: "GET",
@@ -156,9 +189,10 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
           let result: PublicVariantQueryResult;
           try {
             // @cast-boundary engine-payload — shape comes from
-            // publicVariantQuery's return type.
+            // publicVariantQuery's return type (publicVariantByFileRefQuery
+            // returns exactly that, or null, never its own shape).
             result = (await systemQuery(
-              PUBLIC_VARIANT_QN,
+              routeQn,
               { fileRefId, variant },
               tenantId,
             )) as PublicVariantQueryResult;

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

@@ -0,0 +1,40 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createAnonymousUser,
+  defineQueryHandler,
+  isUuid,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { PUBLIC_VARIANT_QN, publicVariantPayloadSchema } from "./public-variant.query";
+
+type FileRefTenantRow = {
+  readonly tenantId: TenantId;
+};
+
+const BY_FILE_REF_ESCAPE_HATCH_REASON =
+  "shared public host serves every tenant's public variants; the FileRef row names the tenant, and publicVariantQuery's isPublic gate still runs inside that tenant via queryAs";
+
+// Full QN this handler is registered under, mirrors PUBLIC_VARIANT_QN.
+export const PUBLIC_VARIANT_BY_FILE_REF_QN = "file-derivatives:query:public-variant-by-file-ref";
+
+export const publicVariantByFileRefQuery = defineQueryHandler({
+  name: "public-variant-by-file-ref",
+  schema: publicVariantPayloadSchema,
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  agent: { expose: false },
+  rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
+  escapeHatch: {
+    reason: BY_FILE_REF_ESCAPE_HATCH_REASON,
+  },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<FileRefTenantRow>(
+      ctx.db.unsafeRaw(BY_FILE_REF_ESCAPE_HATCH_REASON),
+      fileRefsTable,
+      { id: query.payload.fileRefId, isDeleted: false },
+    );
+    if (!row || !isUuid(row.tenantId)) return null;
+
+    return ctx.queryAs(createAnonymousUser(row.tenantId), PUBLIC_VARIANT_QN, query.payload);
+  },
+});

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

@@ -16,6 +16,11 @@
 // feature.ts), `ctx.user.tenantId` instead comes from that dispatcher's own
 // `anonymousAccess` resolution — tenant provenance there depends on the
 // consumer's `resolverTrust`/anonymousAccess setup, not the host.
+//
+// In `publicTenantResolution: "fileRef"` mode, this handler is also the
+// `ctx.queryAs(createAnonymousUser(fileRefTenantId), ...)` target of
+// publicVariantByFileRefQuery — tenantId there comes from the FileRef row,
+// 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";
@@ -72,15 +77,19 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
 // def itself — mirrors managed-pages' BY_SLUG_QN.
 export const PUBLIC_VARIANT_QN = "file-derivatives:query:public-variant";
 
+// Shared with publicVariantByFileRefQuery — same payload shape, both routes
+// forward `{ fileRefId, variant }` unchanged.
+export const publicVariantPayloadSchema = z.object({
+  // Loose, version-agnostic UUID shape (same as isUuid/TENANT_ID_REGEX in
+  // packages/types) — not zod's `.uuid()`, which is stricter than this
+  // repo's convention and would reject valid v7/nil ids the DB accepts.
+  fileRefId: z.string().refine(isUuid, "invalid fileRefId"),
+  variant: z.string().min(1).max(64),
+});
+
 export const publicVariantQuery = defineQueryHandler({
   name: "public-variant",
-  schema: z.object({
-    // Loose, version-agnostic UUID shape (same as isUuid/TENANT_ID_REGEX in
-    // packages/types) — not zod's `.uuid()`, which is stricter than this
-    // repo's convention and would reject valid v7/nil ids the DB accepts.
-    fileRefId: z.string().refine(isUuid, "invalid fileRefId"),
-    variant: z.string().min(1).max(64),
-  }),
+  schema: publicVariantPayloadSchema,
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
   agent: { expose: false },
   // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData

package/src/file-derivatives/index.ts

@@ -1,4 +1,8 @@
-export type { FileDerivativesOptions, PublicVariantResolveApexTenant } from "./feature";
+export type {
+  FileDerivativesOptions,
+  PublicVariantResolveApexTenant,
+  PublicVariantTenantResolution,
+} from "./feature";
 export { createFileDerivativesFeature, fileDerivativesFeature } from "./feature";
 export type {
   DerivativePublicPredicateArgs,

package/src/inbound-provider-imap/__tests__/plugin-mocked.test.ts

@@ -5,6 +5,7 @@
 import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import { EventEmitter } from "node:events";
 import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import { sleep, waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import {
   type InboundMailContext,
   isInboundAuthError,
@@ -152,13 +153,6 @@ const account: MailAccountRecord = {
   watchState: "idle",
 };
 
-async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
-  const t0 = Date.now();
-  while (!predicate() && Date.now() - t0 < timeoutMs) {
-    await Bun.sleep(5);
-  }
-}
-
 function ctxWithDoc(doc: string | null): InboundMailContext {
   return {
     _userId: "imap-plugin-mocked",
@@ -332,7 +326,9 @@ describe("imapInboundMailPlugin — mocked imapflow", () => {
 
     // drainNew() does MIME-parsing before onMessages fires — a fixed sleep
     // flakes on a loaded CI runner; poll instead.
-    await waitFor(() => received.some((batch) => batch.some((m) => m.subject === "pushed")));
+    await waitFor(() => received.some((batch) => batch.some((m) => m.subject === "pushed")), {
+      delays: Array(40).fill(5),
+    });
     expect(received.some((batch) => batch.some((m) => m.subject === "pushed"))).toBe(true);
 
     await stop();
@@ -347,11 +343,13 @@ describe("imapInboundMailPlugin — mocked imapflow", () => {
       },
     });
     lastIdleClient?.emit("error", new Error("socket hang up"));
-    await waitFor(() => errors >= 1);
+    await waitFor(() => errors >= 1, { delays: Array(40).fill(5) });
     lastIdleClient?.emit("error", new Error("second"));
-    // Confirms onError stays unsubscribed after the first error — polls the
-    // same bounded window rather than betting on a fixed sleep outlasting it.
-    await waitFor(() => errors >= 2, 100);
+    // Confirms onError stays unsubscribed after the first error. This is a
+    // grace period for a negative outcome, not a wait-for-true condition, so
+    // it's a single sleep (not a poll loop) rather than waitFor, which would
+    // throw once errors never reaches 2.
+    await sleep(100);
     expect(errors).toBe(1);
     await stop().catch(() => {});
   });

package/src/jobs/__tests__/projection-rebuild-job.integration.test.ts

@@ -40,7 +40,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { sleep } from "@cosmicdrift/kumiko-framework/testing";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
 import { createJobsFeature } from "../feature";
 import { createJobRunLogger } from "../job-run-logger";
 import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
@@ -148,7 +148,7 @@ describe("projection-rebuild job (jobs feature composed)", () => {
     }
 
     // Poll until the worker drained the queue and the rebuild refilled.
-    for (let i = 0; i < 40 && (await getCount()) !== 2; i++) await sleep(200);
+    await waitFor(async () => (await getCount()) === 2, { delays: Array(40).fill(200) });
     expect(await getCount()).toBe(2);
 
     // getCount()==2 only proves rebuildProjection's own writes landed — the
@@ -156,13 +156,15 @@ describe("projection-rebuild job (jobs feature composed)", () => {
     // async append that starts only after the handler returns, so it can
     // still be in flight here. Poll status too instead of racing it.
     let runs: readonly { jobName: string; status: string }[] = [];
-    for (let i = 0; i < 40; i++) {
-      runs = await selectMany<{ jobName: string; status: string }>(db, jobRunsTable, {
-        jobName: PROJECTION_REBUILD_JOB,
-      });
-      if (runs.some((r) => r.status === "completed")) break;
-      await sleep(200);
-    }
+    await waitFor(
+      async () => {
+        runs = await selectMany<{ jobName: string; status: string }>(db, jobRunsTable, {
+          jobName: PROJECTION_REBUILD_JOB,
+        });
+        return runs.some((r) => r.status === "completed");
+      },
+      { delays: Array(40).fill(200) },
+    );
     expect(runs.length).toBeGreaterThanOrEqual(1);
     expect(runs.some((r) => r.status === "completed")).toBe(true);
   }, 30000);