@cosmicdrift/kumiko-framework 0.191.0 → 0.193.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.191.0",
+  "version": "0.193.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.191.0",
+    "@cosmicdrift/kumiko-types": "0.193.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.191.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.193.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/request-id-middleware.ts

@@ -1,5 +1,5 @@
 import type { Context, Next } from "hono";
-import { requestContext } from "./request-context";
+import { type RequestContextData, requestContext } from "./request-context";
 
 const REQUEST_ID_HEADER = "X-Request-ID";
 const CORRELATION_ID_HEADER = "X-Correlation-ID";
@@ -14,6 +14,47 @@ function sanitizeClientId(value: string | undefined): string | undefined {
   return value !== undefined && SAFE_ID_RE.test(value) ? value : undefined;
 }
 
+/**
+ * Builds the RequestContextData record for a Hono request — requestId
+ * (client-supplied + sanitized, or generated), correlationId (mirrors
+ * requestId unless the client set its own), the underlying abort signal,
+ * and the client IP/User-Agent. Extracted out of `requestIdMiddleware` so
+ * call-sites that invoke a handler outside that middleware's `next()`
+ * chain (e.g. server.ts's httpRoute→systemQuery mount) can still populate
+ * the same AsyncLocalStorage record via `requestContext.run(...)`.
+ */
+export function buildRequestContextData(c: Context): RequestContextData {
+  const requestId =
+    sanitizeClientId(c.req.header(REQUEST_ID_HEADER)) ?? requestContext.generateId();
+  const correlationId = sanitizeClientId(c.req.header(CORRELATION_ID_HEADER)) ?? requestId;
+
+  // Hono exposes the underlying Fetch Request — its `signal` aborts
+  // when the client disconnects (mobile back-press, tab close). We
+  // propagate it through requestContext so framework internals can
+  // honour cancellation at long-running checkpoints. Older Hono /
+  // adapter combos may not populate `c.req.raw.signal`; conditional
+  // spread keeps `signal: undefined` out of the stored record so
+  // downstream `signal?` checks behave as if no signal exists.
+  const signal = c.req.raw?.signal;
+  // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
+  // present (proxy/CDN) — first hop is the originating client. Adapter-
+  // specific socket-address fallback (bun, node) is not standardized
+  // in Hono; deployments behind a proxy should always set xff. Without
+  // either we leave `ip` undefined and skip ip-bucketed checks rather
+  // than fabricate one.
+  const xff = c.req.header("x-forwarded-for");
+  const ip = xff?.split(",")[0]?.trim();
+  const userAgent = c.req.header("user-agent");
+
+  return {
+    requestId,
+    correlationId,
+    ...(signal ? { signal } : {}),
+    ...(ip && ip.length > 0 ? { ip } : {}),
+    ...(userAgent !== undefined ? { userAgent } : {}),
+  };
+}
+
 /**
  * Assigns a requestId + correlationId to every request and wraps execution
  * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for
@@ -25,39 +66,11 @@ function sanitizeClientId(value: string | undefined): string | undefined {
  */
 export function requestIdMiddleware() {
   return async (c: Context, next: Next) => {
-    const requestId =
-      sanitizeClientId(c.req.header(REQUEST_ID_HEADER)) ?? requestContext.generateId();
-    const correlationId = sanitizeClientId(c.req.header(CORRELATION_ID_HEADER)) ?? requestId;
-    c.header(REQUEST_ID_HEADER, requestId);
-    c.header(CORRELATION_ID_HEADER, correlationId);
-    c.set("requestId", requestId);
-
-    // Hono exposes the underlying Fetch Request — its `signal` aborts
-    // when the client disconnects (mobile back-press, tab close). We
-    // propagate it through requestContext so framework internals can
-    // honour cancellation at long-running checkpoints. Older Hono /
-    // adapter combos may not populate `c.req.raw.signal`; conditional
-    // spread keeps `signal: undefined` out of the stored record so
-    // downstream `signal?` checks behave as if no signal exists.
-    const signal = c.req.raw?.signal;
-    // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
-    // present (proxy/CDN) — first hop is the originating client. Adapter-
-    // specific socket-address fallback (bun, node) is not standardized
-    // in Hono; deployments behind a proxy should always set xff. Without
-    // either we leave `ip` undefined and skip ip-bucketed checks rather
-    // than fabricate one.
-    const xff = c.req.header("x-forwarded-for");
-    const ip = xff?.split(",")[0]?.trim();
-    const userAgent = c.req.header("user-agent");
-    await requestContext.run(
-      {
-        requestId,
-        correlationId,
-        ...(signal ? { signal } : {}),
-        ...(ip && ip.length > 0 ? { ip } : {}),
-        ...(userAgent !== undefined ? { userAgent } : {}),
-      },
-      () => next(),
-    );
+    const data = buildRequestContextData(c);
+    c.header(REQUEST_ID_HEADER, data.requestId);
+    c.header(CORRELATION_ID_HEADER, data.correlationId);
+    c.set("requestId", data.requestId);
+
+    await requestContext.run(data, () => next());
   };
 }

package/src/api/server.ts

@@ -57,7 +57,8 @@ import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
-import { requestIdMiddleware } from "./request-id-middleware";
+import { requestContext } from "./request-context";
+import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware";
 import {
   DEFAULT_MAX_REQUEST_BYTES,
   registerBodyLimit,
@@ -769,7 +770,17 @@ export function buildServer(options: ServerOptions): KumikoServer {
             // it into a public response. The forced tenant already comes
             // from bypassing the HTTP layer entirely; no elevated role
             // is needed or wanted on top of that.
-            dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+            //
+            // httpRoute handlers run OUTSIDE /api/* — requestIdMiddleware
+            // (which wraps requestContext.run with ip/requestId/
+            // correlationId) never sees this request. Without this wrap,
+            // `rateLimit: {per: "ip", ...}` on a handler invoked via
+            // systemQuery is silent dead-code: enforceRateLimit reads
+            // requestContext.get()?.ip, which is undefined here, so
+            // buildBucketKey always returns {kind: "skip"}.
+            requestContext.run(buildRequestContextData(c), () =>
+              dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+            ),
         });
       switch (route.method) {
         case "GET":

package/src/derivatives/__tests__/field-variants.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { EntityDefinition, FieldDefinition, Registry } from "../../engine/types";
+import { resolveFieldVariant } from "../field-variants";
+
+// Minimal fake Registry — same pattern as derivatives-context.test.ts's
+// fakeRegistry: only getEntity is exercised by resolveFieldVariant.
+function fakeRegistry(entities: Readonly<Record<string, EntityDefinition>>): Registry {
+  const map = new Map(Object.entries(entities));
+  return {
+    getEntity: (name: string) => map.get(name),
+  } as unknown as Registry;
+}
+
+const THUMB_SPEC: VariantSpec = { maxEdge: 200, format: "webp" };
+
+function photoEntityWith(field: FieldDefinition): Readonly<Record<string, EntityDefinition>> {
+  return {
+    photo: { fields: { avatar: field } },
+  };
+}
+
+describe("resolveFieldVariant", () => {
+  test("returns the declared spec for a known variant name", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBe(THUMB_SPEC);
+  });
+
+  test("unknown variant name returns undefined", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "nope")).toBeUndefined();
+  });
+
+  test("__proto__ as a name returns undefined — the prototype-pollution case Object.hasOwn catches", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, "photo", "avatar", "__proto__")).toBeUndefined();
+  });
+
+  test("null entityType or fieldName returns undefined", () => {
+    const registry = fakeRegistry(
+      photoEntityWith({ type: "image", variants: { thumb: THUMB_SPEC } }),
+    );
+    expect(resolveFieldVariant(registry, null, "avatar", "thumb")).toBeUndefined();
+    expect(resolveFieldVariant(registry, "photo", null, "thumb")).toBeUndefined();
+  });
+
+  test("a non-image field returns undefined even when its own value looks variant-shaped", () => {
+    const registry = fakeRegistry(photoEntityWith({ type: "text" }));
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBeUndefined();
+  });
+
+  test("an image field without variants returns undefined", () => {
+    const registry = fakeRegistry(photoEntityWith({ type: "image" }));
+    expect(resolveFieldVariant(registry, "photo", "avatar", "thumb")).toBeUndefined();
+  });
+});

package/src/derivatives/__tests__/variant-key.test.ts

@@ -19,6 +19,12 @@ describe("specHash — key stability", () => {
   test("a changed value produces a different hash — the whole point of hashing the spec", () => {
     expect(specHash({ maxEdge: 512 })).not.toBe(specHash({ maxEdge: 640 }));
   });
+
+  test("different blurRegions produce different hashes — corrected regions need a fresh URL", () => {
+    expect(specHash({ blurRegions: [{ x: 0, y: 0, width: 0.5, height: 0.5 }] })).not.toBe(
+      specHash({ blurRegions: [{ x: 0.5, y: 0.5, width: 0.5, height: 0.5 }] }),
+    );
+  });
 });
 
 describe("variantSuffix", () => {

package/src/derivatives/__tests__/variant-route.integration.test.ts

@@ -0,0 +1,169 @@
+// Proves GET /api/files/:id/variant/:name end-to-end: real HTTP calls
+// through the auth+tenant+guard gate, resolveFieldVariant's whitelist, and
+// createDerivativesContext's cache path — same "wiring, not unit logic"
+// rationale as derivatives-context.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import {
+  createEntity,
+  createImageField,
+  defineFeature,
+  EXT_DERIVATIVE_RENDERER,
+} from "../../engine";
+import { createFilesFeature } from "../../files/feature";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
+
+const VARIANT_BYTES = new Uint8Array([9, 9, 9]);
+
+let renderCalls = 0;
+const fakeRender: DerivativeRendererPlugin["render"] = async () => {
+  renderCalls++;
+  return VARIANT_BYTES;
+};
+
+const photoEntity = createEntity({
+  table: "variant_route_photos",
+  fields: {
+    avatar: createImageField({ variants: { thumb: { maxEdge: 100, format: "webp" } } }),
+  },
+});
+
+const photoFeature = defineFeature("variantroutetest", (r) => {
+  r.entity("photo", photoEntity);
+  r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, { onRegister: () => {} });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+});
+
+let stack: TestStack;
+const tenantId = testTenantId(1);
+const user = createTestUser({ id: 1, tenantId, roles: ["Admin"] });
+const otherTenantId = testTenantId(2);
+const otherTenantUser = createTestUser({ id: 10, tenantId: otherTenantId, roles: ["Admin"] });
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [createFilesFeature(), photoFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+const DEFAULT_ATTACH = { entityType: "photo", fieldName: "avatar" };
+
+// `null` (not the default-param-triggering `undefined`) is the explicit
+// "unattached upload" sentinel — a caller passing `undefined` here would
+// silently fall back to DEFAULT_ATTACH instead.
+async function uploadFile(
+  asUser = user,
+  attach: { entityType: string; fieldName: string } | null = DEFAULT_ATTACH,
+): Promise<string> {
+  const token = await stack.jwt.sign(asUser);
+  const fd = new FormData();
+  fd.append("file", new File([Buffer.from([1, 2, 3])], "avatar.jpg", { type: "image/jpeg" }));
+  if (attach !== null) {
+    fd.append("entityType", attach.entityType);
+    fd.append("fieldName", attach.fieldName);
+  }
+  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("GET /api/files/:id/variant/:name", () => {
+  test("returns the rendered bytes with the spec's mimeType", async () => {
+    renderCalls = 0;
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/webp");
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
+  });
+
+  test("a second call hits the cache — the renderer runs only once", async () => {
+    renderCalls = 0;
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const first = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const second = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(new Uint8Array(await second.arrayBuffer())).toEqual(VARIANT_BYTES);
+    expect(renderCalls).toBe(1);
+  });
+
+  test("an undeclared variant name returns 404", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/nope`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("__proto__ as the variant name returns 404", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/__proto__`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("an unattached upload has no field to resolve a variant from — 404", async () => {
+    const fileId = await uploadFile(user, null);
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("a user from a different tenant gets 404 — tenant isolation", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(otherTenantUser);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  test("no Authorization header does not return 200", async () => {
+    const fileId = await uploadFile();
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`);
+
+    expect(res.status).toBe(401);
+  });
+});

package/src/derivatives/field-variants.ts

@@ -0,0 +1,20 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { Registry } from "../engine/types";
+
+// The field definition IS the whitelist: a request carries a variant NAME,
+// never a spec, so no caller can drive an arbitrary render. `hasOwn` and not
+// a plain index — `name` comes off a URL segment, and `__proto__` would
+// otherwise resolve to something truthy that is not a VariantSpec.
+export function resolveFieldVariant(
+  registry: Registry,
+  entityType: string | null,
+  fieldName: string | null,
+  name: string,
+): VariantSpec | undefined {
+  if (entityType === null || fieldName === null) return undefined;
+  const field = registry.getEntity(entityType)?.fields[fieldName];
+  if (field === undefined) return undefined;
+  if (field.type !== "image" && field.type !== "images") return undefined;
+  if (field.variants === undefined || !Object.hasOwn(field.variants, name)) return undefined;
+  return field.variants[name];
+}

package/src/derivatives/index.ts

@@ -1,3 +1,4 @@
 export type { DerivativesContextDeps } from "./derivatives-context";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context";
-export { canonicalJson, specHash, variantSuffix } from "./variant-key";
+export { resolveFieldVariant } from "./field-variants";
+export { canonicalJson, specHash, VARIANT_NAME_PATTERN, variantSuffix } from "./variant-key";

package/src/derivatives/variant-key.ts

@@ -25,7 +25,7 @@ export function specHash(spec: VariantSpec): string {
   return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 8);
 }
 
-const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
+export const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
 
 export function variantSuffix(name: string, spec: VariantSpec): string {
   // `name` ends up in a storage key (see deriveKey) — an unvalidated value

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

@@ -11,6 +11,8 @@ import {
   createEmbeddedListField,
   createEntity,
   createFilesField,
+  createImageField,
+  createImagesField,
   createJsonbField,
   createMultiSelectField,
   createTextField,
@@ -1355,6 +1357,138 @@ describe("boot-validator", () => {
     });
   });
 
+  describe("image variants", () => {
+    test("accepts a valid variant spec", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({
+                    variants: {
+                      profile: { fit: "cover", size: { width: 512, height: 512 }, format: "webp" },
+                    },
+                  }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
+
+    test("accepts a variant with only `format` — the legitimate format-only case, no size/maxEdge required", () => {
+      process.env["FILE_STORAGE_PROVIDER"] = "local";
+      try {
+        const features = [
+          defineFeature("profile", (r) => {
+            r.entity(
+              "person",
+              createEntity({
+                fields: {
+                  avatar: createImageField({ variants: { web: { format: "webp" } } }),
+                },
+              }),
+            );
+          }),
+        ];
+        expect(() => validateBoot(features)).not.toThrow();
+      } finally {
+        delete process.env["FILE_STORAGE_PROVIDER"];
+      }
+    });
+
+    test("rejects a variant setting both `size` and `maxEdge`", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({
+                  variants: {
+                    both: { size: { width: 100, height: 100 }, maxEdge: 200 },
+                  },
+                }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/both/);
+    });
+
+    test("rejects a variant name containing a slash", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { "a/b": { maxEdge: 200 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/must match/);
+    });
+
+    test("rejects maxEdge: 0", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { thumb: { maxEdge: 0 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/maxEdge/);
+    });
+
+    test("rejects quality: 101", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                avatar: createImageField({ variants: { thumb: { maxEdge: 200, quality: 101 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/quality/);
+    });
+
+    test("the same validation applies to `images` (multi) fields", () => {
+      const features = [
+        defineFeature("profile", (r) => {
+          r.entity(
+            "person",
+            createEntity({
+              fields: {
+                gallery: createImagesField({ variants: { "a/b": { maxEdge: 200 } } }),
+              },
+            }),
+          );
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/must match/);
+    });
+  });
+
   // --- entityList column-renderer form-check ---
   // Validator akzeptiert die `{ react: { __component: "Name" } }`-Form
   // (PlatformComponent → client-side Registry-Lookup) und prüft sie

package/src/engine/__tests__/engine.test.ts

@@ -814,6 +814,28 @@ describe("createApp", () => {
     );
   });
 
+  // hasMoneyField used to only look at top-level fields, so an entity whose
+  // only money lives inside an embedded-list sub-schema (e.g. invoice lines
+  // with no top-level money field) slipped past this check — its cells and
+  // totals would then silently render in entity.defaultCurrency ?? "EUR"
+  // regardless of the app's actual currency.
+  test("rejects an entity whose only money field is nested in an embedded list", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "invoice",
+        createEntity({
+          table: "Invoices",
+          fields: {
+            lines: createEmbeddedListField({ amount: { type: "money", required: true } }),
+          },
+        }),
+      );
+    });
+    expect(() => createApp({ roles: ["Admin"], features: [feature] })).toThrow(
+      "has money fields but no defaultCurrency",
+    );
+  });
+
   test("rejects unknown defaultCurrency", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
@@ -955,6 +977,9 @@ describe("createApp", () => {
               qty: { type: "decimal", scale: 3 },
             }),
           },
+          // meta.amount is money nested in an embedded field — needs a
+          // defaultCurrency the same as a top-level money field would.
+          defaultCurrency: "EUR",
         }),
       );
     });
@@ -1073,6 +1098,7 @@ describe("createApp", () => {
               { totalsMatch: { amount: "title" } },
             ),
           },
+          defaultCurrency: "EUR",
         }),
       );
     });
@@ -1093,6 +1119,7 @@ describe("createApp", () => {
               { totalsMatch: { amount: "ghostTotal" } },
             ),
           },
+          defaultCurrency: "EUR",
         }),
       );
     });

package/src/engine/boot-validator/entity-handler.ts

@@ -1,3 +1,5 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
 import type { EmbeddedFieldDef, EntityDefinition, FeatureDefinition } from "../types";
 
@@ -685,6 +687,56 @@ export function validateMultiSelectFields(feature: FeatureDefinition): void {
   }
 }
 
+// --- Image variant validation ---
+
+function isPositiveInt(value: number): boolean {
+  return Number.isInteger(value) && value > 0;
+}
+
+function assertValidVariantSpec(name: string, spec: VariantSpec, where: string): void {
+  if (!VARIANT_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Image variant "${name}" ${where} must match ${VARIANT_NAME_PATTERN.source} — the name becomes part of a storage key and a URL segment.`,
+    );
+  }
+  if (spec.size !== undefined && spec.maxEdge !== undefined) {
+    throw new Error(`Image variant "${name}" ${where} sets both "size" and "maxEdge" — pick one.`);
+  }
+  if (
+    spec.size !== undefined &&
+    !(isPositiveInt(spec.size.width) && isPositiveInt(spec.size.height))
+  ) {
+    throw new Error(
+      `Image variant "${name}" ${where} has a non-positive-integer "size" (${spec.size.width}x${spec.size.height}).`,
+    );
+  }
+  if (spec.maxEdge !== undefined && !isPositiveInt(spec.maxEdge)) {
+    throw new Error(
+      `Image variant "${name}" ${where} has a non-positive-integer "maxEdge" (${spec.maxEdge}).`,
+    );
+  }
+  if (spec.quality !== undefined && !(isPositiveInt(spec.quality) && spec.quality <= 100)) {
+    throw new Error(
+      `Image variant "${name}" ${where} has "quality" ${spec.quality} — must be an integer in 1..100.`,
+    );
+  }
+}
+
+// A bad spec is only visible when someone finally requests that variant —
+// possibly months later, in production. Catch it at boot instead.
+export function validateImageVariants(feature: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+      if (field.type !== "image" && field.type !== "images") continue;
+      if (field.variants === undefined) continue;
+      const where = `on "${entityName}.${fieldName}" in feature "${feature.name}"`;
+      for (const [name, spec] of Object.entries(field.variants)) {
+        assertValidVariantSpec(name, spec, where);
+      }
+    }
+  }
+}
+
 // --- Transition validation ---
 
 export function validateTransitions(feature: FeatureDefinition): void {

package/src/engine/boot-validator/index.ts

@@ -25,6 +25,7 @@ import {
   validateExtensionPreSaveWiring,
   validateFileFields,
   validateHandlerAccess,
+  validateImageVariants,
   validateLocatedTimestamps,
   validateMultiSelectFields,
   validateMultiStreamProjections,
@@ -168,6 +169,7 @@ export function validateBoot(
     validateApiExposureMatching(feature, allExposedApis, featureMap);
     validateEmbeddedFields(feature, featureMap);
     validateMultiSelectFields(feature);
+    validateImageVariants(feature);
     validateReferenceFields(feature, featureMap);
     validateTransitions(feature);
     validateExtensionUsages(feature, extensionProviders);

package/src/engine/create-app.ts

@@ -85,7 +85,17 @@ export function createApp(config: AppConfig): App {
   // Validate defaultCurrency on entities that have money fields
   for (const feature of config.features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      const hasMoneyField = Object.values(entity.fields).some((f) => f.type === "money");
+      // A top-level money field isn't the only way an entity can hold money —
+      // an embedded-list's sub-schema (e.g. invoice lines) can carry a money
+      // cell with no top-level money field at all. Without this, that entity
+      // slips past the defaultCurrency check and its cells/totals render in
+      // the entity.defaultCurrency ?? "EUR" fallback regardless of the app's
+      // actual currency.
+      const hasMoneyField = Object.values(entity.fields).some(
+        (f) =>
+          f.type === "money" ||
+          (f.type === "embedded" && Object.values(f.schema).some((s) => s.type === "money")),
+      );
       if (entity.defaultCurrency && !currencies.includes(entity.defaultCurrency)) {
         throw new Error(
           `Entity "${entityName}" in feature "${feature.name}" has defaultCurrency "${entity.defaultCurrency}" which is not in the currencies list. Available: ${currencies.join(", ")}`,

package/src/engine/extension-names.ts

@@ -104,6 +104,22 @@ export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as con
  */
 export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer" as const;
 
+/**
+ * `derivativePublicPredicate` — per-entityType "is this FileRef's derivative
+ * publicly readable?" gate for the anonymous variant route (file-derivatives).
+ *
+ * Apps register via
+ * `r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "<entityType>", { isPublic:
+ * (args, ctx) => boolean | Promise<boolean> })`, where `<entityType>` is the
+ * `entityType` string a FileRef carries from upload (e.g. "vehicle", "event").
+ * No registration for a given entityType is default-deny — the public route
+ * serves nothing for that entityType, not even a 403 (404, so existence isn't
+ * confirmed to an unauthorised caller).
+ *
+ * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ */
+export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate" as const;
+
 /**
  * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
  * bei User-Forget oder Tenant-Destroy).

package/src/engine/index.ts

@@ -77,6 +77,7 @@ export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
 export type { KumikoExtensionName } from "./extension-names";
 export {
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
   EXT_EXTERNAL_RESOURCE,
   EXT_FILE_PROVIDER,

package/src/files/file-routes.ts

@@ -4,9 +4,11 @@ import { getUser } from "../api/auth-middleware";
 import type { DbConnection } from "../db/connection";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { createTenantDb } from "../db/tenant-db";
+import { createDerivativesContext, resolveFieldVariant } from "../derivatives";
 import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
+import { createFileContext } from "./file-handle";
 import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
@@ -235,6 +237,48 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     });
   });
 
+  // GET /files/:id/variant/:name — a named derived version of the file.
+  // Same tenant + guard gate as the download above; the original stays
+  // reachable only through that route. The public, anonymous counterpart is
+  // a separate cut (#1951) and does not go through createFileRoutes.
+  api.get("/files/:id/variant/:name", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const name = c.req.param("name");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    // An unknown name and a denied file answer alike, so the route never
+    // confirms what exists. A missing renderer is NOT folded in here — that
+    // throws out of variant() as a 500, because a mount gap is a config
+    // error, not a missing variant.
+    const registry = options.registry;
+    const spec = registry
+      ? resolveFieldVariant(registry, fileRef.entityType, fileRef.fieldName, name)
+      : undefined;
+    if (!registry || !spec) return c.json({ error: "not_found" }, 404);
+
+    // Built per request: createFileContext caches the resolved provider, so
+    // one shared across requests would serve tenant A's store to tenant B.
+    const files = createFileContext(() => options.resolveProvider(user.tenantId));
+    const derivatives = createDerivativesContext({
+      files,
+      registry,
+      db,
+      tenantId: user.tenantId,
+    });
+    const result = await derivatives.variant(id, spec, name);
+    const data = await files.ref(result.storageKey).read();
+    // No Content-Length/Content-Disposition: fileRef.size is the ORIGINAL's
+    // size, and a variant is rendered for display, not for download.
+    return new Response(Buffer.from(data), {
+      headers: { "Content-Type": result.mimeType },
+    });
+  });
+
   // DELETE /files/:id — same guard, "delete" operation. Apps can differentiate
   // read vs delete in their custom guard (e.g. only uploaders delete).
   api.delete("/files/:id", async (c) => {

package/src/jobs/__tests__/job-runner-boot-timeout.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// Simulates an unreachable Redis: waitUntilReady() never resolves. Everything
+// else start() touches (Queue.on/close/add/upsertJobScheduler) is a no-op —
+// with an empty registry those code paths aren't exercised anyway.
+mock.module("bullmq", () => {
+  class FakeQueue {
+    on() {}
+    close() {
+      return Promise.resolve();
+    }
+    getJobCounts() {
+      return Promise.resolve({});
+    }
+    removeJobScheduler() {
+      return Promise.resolve();
+    }
+    upsertJobScheduler() {
+      return Promise.resolve();
+    }
+    add() {
+      return Promise.resolve();
+    }
+  }
+  class FakeWorker {
+    on() {}
+    waitUntilReady() {
+      return new Promise(() => {});
+    }
+    close() {
+      return Promise.resolve();
+    }
+  }
+  return { Queue: FakeQueue, Worker: FakeWorker };
+});
+
+import { createRegistry } from "../../engine";
+import type { AppContext } from "../../engine/types";
+import { createJobRunner } from "../job-runner";
+
+describe("createJobRunner start() boot timeout", () => {
+  test("rejects instead of hanging forever when the worker's Redis connection never becomes ready", async () => {
+    const registry = createRegistry([]);
+    const context: AppContext = {};
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl: "redis://localhost:6379",
+      consumerLane: "worker",
+      bootRedisTimeoutMs: 50,
+    });
+
+    await expect(runner.start()).rejects.toThrow(/Redis not reachable within 50ms \(lane=worker\)/);
+  });
+});

package/src/jobs/job-runner.ts

@@ -132,6 +132,10 @@ export type JobRunnerOptions = {
   // Tests set a unique prefix (e.g. `"test-${Date.now()}"`) for isolation —
   // two parallel test-runners never see each other's jobs.
   queueNamePrefix?: string | undefined;
+  // Override how long start() waits for the worker's Redis connection
+  // before failing boot. Defaults to BOOT_REDIS_TIMEOUT_MS; tests shrink it
+  // to keep an unreachable-Redis assertion fast.
+  bootRedisTimeoutMs?: number | undefined;
   getActiveTenantIds?: () => Promise<TenantId[]>;
   onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
   onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[]) => void;
@@ -192,9 +196,20 @@ function parseRedisOpts(url: string): { host: string; port: number; db?: number
   return result;
 }
 
+// redisOpts carries no connectTimeout/retry cap, so an unreachable Redis
+// would otherwise hang start() forever with no health endpoint to notice.
+const BOOT_REDIS_TIMEOUT_MS = 10_000;
+
+function timeoutReject(ms: number, message: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(message)), ms);
+  });
+}
+
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
   const { registry, context, redisUrl, consumerLane } = options;
   const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
+  const bootRedisTimeoutMs = options.bootRedisTimeoutMs ?? BOOT_REDIS_TIMEOUT_MS;
   const redisOpts = parseRedisOpts(redisUrl);
   // Use the context's tracer when present (observability-provider injected at
   // boot); otherwise noop so dispatch/handleJob stay zero-cost without config.
@@ -531,7 +546,15 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // worker's connections (main + blocking) are ready (fw#1805). This
       // mirrors the wait BullMQ already does internally for
       // upsertJobScheduler()/add() below when the lane has a cron/boot job.
-      await worker.waitUntilReady();
+      // Racing a timeout against it keeps an unreachable Redis from hanging
+      // start() forever — there's no worker health endpoint to notice.
+      await Promise.race([
+        worker.waitUntilReady(),
+        timeoutReject(
+          bootRedisTimeoutMs,
+          `job-runner: Redis not reachable within ${bootRedisTimeoutMs}ms (lane=${consumerLane})`,
+        ),
+      ]);
 
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the