@cosmicdrift/kumiko-framework 0.193.1 → 0.195.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.193.1",
+  "version": "0.195.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.193.1",
+    "@cosmicdrift/kumiko-types": "0.195.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.193.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.195.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/http-route-rate-limit.integration.test.ts

@@ -0,0 +1,71 @@
+// kumiko-framework#1977: r.httpRoute's systemQuery used to always run with
+// requestContext.get()?.ip === undefined, so a `rateLimit: {per: "ip"}`
+// handler invoked through it silently never bucketed — see server.ts's
+// systemQuery wiring. Proves the fix: repeated calls through the same
+// httpRoute, same client IP, DO hit the limit.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
+import { RateLimitError } from "../../errors";
+import { setupTestStack, type TestStack } from "../../stack";
+
+const SYSTEM_TENANT_ID = "00000000-0000-4000-8000-000000000000" as TenantId;
+
+const ipLimitedFeature = defineFeature("rl-http", (r) => {
+  r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+  r.queryHandler("ping", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip", limit: 2, windowSeconds: 60 },
+  });
+  r.httpRoute({
+    method: "GET",
+    path: "/ping",
+    anonymous: true,
+    handler: async (c, deps) => {
+      try {
+        await deps.systemQuery("rl-http:query:ping", {}, SYSTEM_TENANT_ID);
+        return c.json({ ok: true });
+      } catch (err) {
+        if (err instanceof RateLimitError) return c.json({ ok: false }, 429);
+        throw err;
+      }
+    },
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ipLimitedFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.redis.flushNamespace();
+});
+
+describe("r.httpRoute → systemQuery propagates requestContext for per-ip rate limiting", () => {
+  test("2 calls allowed, 3rd from the same IP is rate-limited", async () => {
+    const call = () => stack.app.request("/ping", { headers: { "x-forwarded-for": "9.9.9.1" } });
+
+    expect((await call()).status).toBe(200);
+    expect((await call()).status).toBe(200);
+    expect((await call()).status).toBe(429);
+  });
+
+  test("a different client IP gets its own bucket", async () => {
+    const callAs = (ip: string) =>
+      stack.app.request("/ping", { headers: { "x-forwarded-for": ip } });
+
+    expect((await callAs("9.9.9.2")).status).toBe(200);
+    expect((await callAs("9.9.9.2")).status).toBe(200);
+    expect((await callAs("9.9.9.2")).status).toBe(429);
+
+    expect((await callAs("9.9.9.3")).status).toBe(200);
+  });
+});

package/src/api/server.ts

@@ -778,7 +778,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
             // systemQuery is silent dead-code: enforceRateLimit reads
             // requestContext.get()?.ip, which is undefined here, so
             // buildBucketKey always returns {kind: "skip"}.
-            requestContext.run(buildRequestContextData(c), () =>
+            requestContext.run(requestContext.get() ?? buildRequestContextData(c), () =>
               dispatcher.query(type, payload, createAnonymousUser(tenantId)),
             ),
         });

package/src/db/__tests__/migrate-generator.test.ts

@@ -165,6 +165,23 @@ describe("renderMigrationSql — managed recreate vs unmanaged in-place", () =>
     expect(sql).not.toContain("WARN: column-type-change");
   });
 
+  test("unmanaged: date → timestamptz type change emits the symmetric UTC-anchored USING clause", () => {
+    const prev = snapshotFromMetas([
+      meta("store_invoices", { name: "period_from", pgType: "date", notNull: true }),
+    ]);
+    const next = snapshotFromMetas([
+      meta("store_invoices", { name: "period_from", pgType: "timestamptz", notNull: true }),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), {
+      name: "invoice-date-widen",
+      sequenceNumber: 8,
+    });
+    expect(sql).toContain(
+      'ALTER TABLE "store_invoices" ALTER COLUMN "period_from" TYPE timestamptz USING ("period_from"::timestamp AT TIME ZONE \'UTC\');',
+    );
+    expect(sql).not.toContain("WARN: column-type-change");
+  });
+
   test("managed: multiple recreate reasons at once → all named in the warning", () => {
     const prev = snapshotFromMetas([
       meta("read_b", { name: "old_col", pgType: "text", notNull: false }, "managed"),

package/src/db/__tests__/money.test.ts

@@ -7,7 +7,7 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createMoneyField, createTextField } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
-import { flattenMoney, rehydrateMoney } from "../money";
+import { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "../money";
 
 const orderEntity: EntityDefinition = createEntity({
   defaultCurrency: "EUR",
@@ -115,17 +115,16 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
     expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
   });
 
-  test("amountMinor bleibt exakter Integer, amount kann Float-Drift haben (fw#1830)", () => {
+  test("amountMinor bleibt exakter Integer über mehrere Additionen (fw#1830)", () => {
     const rows = [10, 20, 30].map(
       (minor) =>
         rehydrateMoney({ buyingPrice: minor, buyingPriceCurrency: "EUR" }, orderEntity)[
           "buyingPrice"
-        ] as { amount: number; amountMinor: number },
+        ] as MoneyRead,
     );
     const [a, b, c] = rows;
 
     expect(a!.amountMinor + b!.amountMinor).toBe(c!.amountMinor);
-    expect(a!.amount + b!.amount).not.toBe(c!.amount);
   });
 
   test("null/undefined amount → Field wird aus Output entfernt", () => {
@@ -178,7 +177,19 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
   test("korrupte string-amount (kein number) → loud throw, kein silent drop", () => {
     expect(() =>
       rehydrateMoney({ buyingPrice: "not-a-number", buyingPriceCurrency: "EUR" }, orderEntity),
-    ).toThrow(/not a number — DB corruption/);
+    ).toThrow(/not a safe integer — DB corruption/);
+  });
+
+  test("fractional string amount (fw#1833) → loud throw statt amountMinor mit Nachkommastelle", () => {
+    expect(() =>
+      rehydrateMoney({ buyingPrice: "45000.7", buyingPriceCurrency: "EUR" }, orderEntity),
+    ).toThrow(/not a safe integer — DB corruption/);
+  });
+
+  test("string amount jenseits von Number.MAX_SAFE_INTEGER → loud throw statt Präzisionsverlust", () => {
+    expect(() =>
+      rehydrateMoney({ buyingPrice: "9007199254740993", buyingPriceCurrency: "EUR" }, orderEntity),
+    ).toThrow(/not a safe integer — DB corruption/);
   });
 
   test("unerwarteter amount-Typ (boolean) → loud throw", () => {
@@ -222,3 +233,28 @@ describe("flattenMoney — Strict-Mode Throw", () => {
     );
   });
 });
+
+// kumiko-framework#1972: the write-handler-facing counterpart a custom
+// totals check needs when reconciling a top-level money field's payload
+// (major units, `{amount, currency}` or bare number) against an
+// embedded-list row sum (minor-unit integers by convention).
+describe("moneyPayloadToMinorUnits", () => {
+  test("{ amount, currency } object, crooked amount, rounds to the exact cent", () => {
+    expect(moneyPayloadToMinorUnits({ amount: 1234.56, currency: "EUR" })).toBe(123456);
+  });
+
+  test("legacy bare-number payload (also major units, per flattenMoney's permissive-insert contract)", () => {
+    expect(moneyPayloadToMinorUnits(1234.56)).toBe(123456);
+  });
+
+  test("a round amount does not mask a factor-of-100 regression: 30 major -> 3000 minor, not 30", () => {
+    expect(moneyPayloadToMinorUnits({ amount: 30, currency: "EUR" })).toBe(3000);
+  });
+
+  test("undefined for a payload without a numeric amount (nothing to compare)", () => {
+    expect(moneyPayloadToMinorUnits({ currency: "EUR" })).toBeUndefined();
+    expect(moneyPayloadToMinorUnits("100")).toBeUndefined();
+    expect(moneyPayloadToMinorUnits(null)).toBeUndefined();
+    expect(moneyPayloadToMinorUnits(undefined)).toBeUndefined();
+  });
+});

package/src/db/event-store-executor-read.ts

@@ -166,7 +166,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       const listSql = `SELECT * FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
 
       const rawRows = await executeRawQuery<Record<string, unknown>>(db.raw, listSql, params);
-      // Read-Side rehydrate pro Row + snake→camel coercion für driver-agnostic Feldnamen.
+      // Per-row read-side rehydrate + snake→camel coercion for driver-agnostic field names.
       // Coerce BEFORE rehydrate/decrypt: the raw SELECT * rows carry snake_case
       // column names, while compound-type lookups (rehydrateMoney et al.) and the
       // encrypted/pii field lists are all camelCase — running either first on a

package/src/db/index.ts

@@ -100,7 +100,7 @@ export {
   runMigrationsFromDir,
   splitSqlStatements,
 } from "./migrate-runner";
-export { flattenMoney, rehydrateMoney } from "./money";
+export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money";
 export {
   constraintOf,
   extractPgError,

package/src/db/migrate-generator.ts

@@ -284,10 +284,20 @@ function renderColumnChange(tableName: string, change: ColumnChange): readonly s
       out.push(
         `ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE date USING (${col} AT TIME ZONE 'UTC')::date;`,
       );
+    } else if (from === "date" && (to === "timestamptz" || to === "timestamptz(3)")) {
+      // Same non-determinism, reversed: a bare `date → timestamptz` cast
+      // interprets the calendar date at session-TimeZone midnight. Anchor
+      // explicitly at UTC midnight instead.
+      out.push(
+        `-- date → ${to}: explicit UTC anchor — a bare cast would use the session TimeZone (non-deterministic).`,
+      );
+      out.push(
+        `ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to} USING (${col}::timestamp AT TIME ZONE 'UTC');`,
+      );
     } else {
-      // pg ALTER TYPE braucht oft USING-clause für nicht-implicit-castable
-      // type-changes. Wir emittieren das als Reviewer-Kommentar + raw cast —
-      // App-Author muss prüfen ob das gewünscht ist.
+      // pg ALTER TYPE often needs a USING clause for non-implicitly-castable
+      // type changes. Emitted as a reviewer comment + raw cast — the app
+      // author has to confirm it's intended.
       out.push(`-- WARN: column-type-change ${from} → ${to}. Review USING-clause if needed.`);
       out.push(`ALTER TABLE ${tbl} ALTER COLUMN ${col} TYPE ${to};`);
     }

package/src/db/money.ts

@@ -44,6 +44,27 @@ function toMajorUnits(amountMinor: number): number {
   return amountMinor / MINOR_UNIT_SCALE;
 }
 
+// One money field's write payload — `{ amount, currency }` or a bare number
+// (both MAJOR units, see file header) — reduced to minor units. This is the
+// counterpart a write-handler needs when comparing a top-level money field
+// against an `embeddedSubFieldToZod` list-row sum: rows are minor-unit
+// integers by convention (currency lives on the head aggregate, not the
+// row), so the two can only be compared once the sibling amount has been
+// scaled the same way. `applyTotalsMatchRefinements` (schema-builder.ts)
+// uses this internally for `EmbeddedFieldDef.totalsMatch`; exported so a
+// custom write-handler doing its own total check doesn't have to re-derive
+// this unwrap-and-scale step by hand (kumiko-framework#1972 — a hand-rolled
+// comparison of a raw `{amount}` against a raw minor-unit row sum is exactly
+// what silently fails 100x off).
+export function moneyPayloadToMinorUnits(raw: unknown): number | undefined {
+  if (typeof raw === "number") return toMinorUnits(raw);
+  if (typeof raw === "object" && raw !== null && "amount" in raw) {
+    const amount = (raw as { amount: unknown }).amount;
+    if (typeof amount === "number") return toMinorUnits(amount);
+  }
+  return undefined;
+}
+
 /**
  * API → DB: money-Felder zu zwei flachen Spalten flatten.
  *
@@ -101,6 +122,15 @@ export function flattenMoney(
   return result;
 }
 
+/** Shape of a single rehydrated money field — {amount major, currency,
+ *  amountMinor exact integer cents}. Exported so consumers type their own
+ *  copy against this instead of re-declaring the shape by hand. */
+export type MoneyRead = {
+  readonly amount: number;
+  readonly currency: string;
+  readonly amountMinor: number;
+};
+
 /**
  * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
  *
@@ -134,15 +164,15 @@ export function rehydrateMoney(
       amountMinor = amountRaw;
     } else if (typeof amountRaw === "bigint") {
       amountMinor = Number(amountRaw);
-      if (Number.isNaN(amountMinor)) {
-        throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a number`);
+      if (!Number.isSafeInteger(amountMinor)) {
+        throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a safe integer`);
       }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
       amountMinor = Number(amountRaw);
-      if (Number.isNaN(amountMinor)) {
+      if (!Number.isSafeInteger(amountMinor)) {
         throw new Error(
-          `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a number — DB corruption?`,
+          `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`,
         );
       }
     } else {

package/src/derivatives/__tests__/derivatives-context.integration.test.ts

@@ -8,7 +8,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { z } from "zod";
 import { defineFeature, EXT_DERIVATIVE_RENDERER } from "../../engine";
-import { InternalError, writeFailure } from "../../errors";
+import { InternalError, NotFoundError, writeFailure } from "../../errors";
 import { createFilesFeature } from "../../files/feature";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
@@ -41,6 +41,37 @@ const derivativesTestFeature = defineFeature("derivativestest", (r) => {
     { access: { openToAll: true } },
   );
 
+  // Catches the error INSIDE the handler (not via HTTP serialization) so the
+  // test can assert `instanceof` on the concrete error class — the wire
+  // response only carries the serialized WireErrorInfo, which loses that.
+  r.writeHandler(
+    "probe-typed-error",
+    z.object({ fileRefId: z.string() }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "no ctx.derivatives on write-handler ctx" }),
+        );
+      }
+      try {
+        await ctx.derivatives.variant(event.payload.fileRefId, { maxEdge: 100 }, "thumb");
+        return { isSuccess: true as const, data: { threw: false } };
+      } catch (err) {
+        return {
+          isSuccess: true as const,
+          data: {
+            threw: true,
+            isNotFoundError: err instanceof NotFoundError,
+            notFoundHttpStatus: err instanceof NotFoundError ? err.httpStatus : undefined,
+            isInternalError: err instanceof InternalError,
+            internalHttpStatus: err instanceof InternalError ? err.httpStatus : undefined,
+          },
+        };
+      }
+    },
+    { access: { openToAll: true } },
+  );
+
   r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload, ctx) => {
     const fileRefId = (payload as { fileRefId: string }).fileRefId;
     if (!ctx.derivatives) {
@@ -70,10 +101,13 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-async function uploadFile(asUser = user): Promise<string> {
+async function uploadFile(
+  asUser = user,
+  file = new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }),
+): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
-  fd.append("file", new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }));
+  fd.append("file", file);
   const { body, contentType } = await buildMultipartBody(fd);
   const res = await stack.app.request("/api/files", {
     method: "POST",
@@ -129,7 +163,7 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: "00000000-0000-4000-8000-999999999999" },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
   });
 
   test("a soft-deleted fileRef throws", async () => {
@@ -146,7 +180,7 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: fileId },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
   });
 
   test("a fileRef uploaded under a different tenant is not resolvable", async () => {
@@ -157,6 +191,39 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: foreignFileId },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
+  });
+});
+
+describe("ctx.derivatives — typed errors from variant()", () => {
+  test("an unknown fileRefId throws NotFoundError with httpStatus 404", async () => {
+    const result = await stack.http.writeOk<{
+      threw: boolean;
+      isNotFoundError: boolean;
+      notFoundHttpStatus?: number;
+    }>(
+      "derivativestest:write:probe-typed-error",
+      { fileRefId: "00000000-0000-4000-8000-999999999999" },
+      user,
+    );
+    expect(result.threw).toBe(true);
+    expect(result.isNotFoundError).toBe(true);
+    expect(result.notFoundHttpStatus).toBe(404);
+  });
+
+  test("no renderer registered for the mimeType throws InternalError with httpStatus 500", async () => {
+    const fileId = await uploadFile(
+      user,
+      new File([Buffer.from([1, 2, 3])], "doc.pdf", { type: "application/pdf" }),
+    );
+
+    const result = await stack.http.writeOk<{
+      threw: boolean;
+      isInternalError: boolean;
+      internalHttpStatus?: number;
+    }>("derivativestest:write:probe-typed-error", { fileRefId: fileId }, user);
+    expect(result.threw).toBe(true);
+    expect(result.isInternalError).toBe(true);
+    expect(result.internalHttpStatus).toBe(500);
   });
 });

package/src/derivatives/__tests__/derivatives-context.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
 import type { Registry } from "../../engine/types";
+import { InternalError } from "../../errors";
 import { createFileContext } from "../../files/file-handle";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createDerivativesContext, resolveRenderer } from "../derivatives-context";
@@ -133,7 +134,7 @@ describe("createDerivativesContext — variant()", () => {
     expect(second.storageKey).not.toBe(first.storageKey);
   });
 
-  test("no renderer registered for the mimeType throws, naming the known patterns", async () => {
+  test("no renderer registered for the mimeType throws InternalError, naming the known patterns in details", async () => {
     const provider = createInMemoryFileProvider();
     await provider.write("tenant/doc.pdf", new Uint8Array([1]));
     const files = createFileContext(() => Promise.resolve(provider));
@@ -141,7 +142,13 @@ describe("createDerivativesContext — variant()", () => {
     const db = fakeDbWithFileRef({ storageKey: "tenant/doc.pdf", mimeType: "application/pdf" });
     const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
 
-    await expect(ctx.variant(FILE_REF_ID, {}, "thumb")).rejects.toThrow(/image\/\*/);
+    // The renderer list moved out of the client-visible `message` into
+    // `details` — InternalError's serialize() drops `details` from the wire
+    // response, so it must not be the only place a caller can find it.
+    const err = await ctx.variant(FILE_REF_ID, {}, "thumb").catch((e) => e);
+    expect(err).toBeInstanceOf(InternalError);
+    expect((err as InternalError).httpStatus).toBe(500);
+    expect((err as InternalError).details).toEqual({ knownRenderers: "image/*" });
   });
 
   test("mimeType is consistent across a fresh render and a cache hit for the same spec", async () => {

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

@@ -33,8 +33,8 @@ describe("variantSuffix", () => {
     expect(variantSuffix("thumb", spec)).not.toBe(variantSuffix("card", spec));
   });
 
-  test("shape is `<name>-<8 hex chars>`", () => {
-    expect(variantSuffix("thumb", { maxEdge: 512 })).toMatch(/^thumb-[0-9a-f]{8}$/);
+  test("shape is `<name>-<16 hex chars>`", () => {
+    expect(variantSuffix("thumb", { maxEdge: 512 })).toMatch(/^thumb-[0-9a-f]{16}$/);
   });
 
   test("a path-traversal name is rejected — it would escape the tenant prefix in the derived key", () => {

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

@@ -94,6 +94,7 @@ describe("GET /api/files/:id/variant/:name", () => {
 
     expect(res.status).toBe(200);
     expect(res.headers.get("Content-Type")).toBe("image/webp");
+    expect(res.headers.get("Cache-Control")).toBe("private, max-age=31536000, immutable");
     expect(new Uint8Array(await res.arrayBuffer())).toEqual(VARIANT_BYTES);
   });
 
@@ -166,4 +167,31 @@ describe("GET /api/files/:id/variant/:name", () => {
 
     expect(res.status).toBe(401);
   });
+
+  // createImageField has no `accept` restriction here, so validateFile
+  // never rejects a non-image upload against this field — the source
+  // mimeType a renderer has to handle is client-controlled, not just a
+  // deployment-time mount decision.
+  test("a source mimeType with no matching renderer (client uploaded a non-image) returns 415, not a 500", async () => {
+    const token = await stack.jwt.sign(user);
+    const fd = new FormData();
+    fd.append("file", new File([Buffer.from([1, 2, 3])], "doc.pdf", { type: "application/pdf" }));
+    fd.append("entityType", "photo");
+    fd.append("fieldName", "avatar");
+    const { body, contentType } = await buildMultipartBody(fd);
+    const uploadRes = await stack.app.request("/api/files", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+      body,
+    });
+    expect(uploadRes.status).toBe(201);
+    const { id: fileId } = (await uploadRes.json()) as { id: string };
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/thumb`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(415);
+    expect(await res.json()).toEqual({ error: "unsupported_media_type" });
+  });
 });

package/src/derivatives/derivatives-context.ts

@@ -6,6 +6,7 @@ import type {
 import { type AnyDb, fetchOne } from "../bun-db/query";
 import { EXT_DERIVATIVE_RENDERER } from "../engine/extension-names";
 import type { Registry, TenantId } from "../engine/types";
+import { InternalError, NotFoundError } from "../errors";
 import type { FileContext } from "../files/file-handle";
 import { fileRefsTable } from "../files/file-ref-table";
 import { assertSafeStorageKey } from "../files/types";
@@ -94,12 +95,10 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
         isDeleted: false,
       });
       if (!row) {
-        throw new Error(`derivatives.variant: no fileRef found for id "${fileRefId}"`);
+        throw new NotFoundError("fileRef", fileRefId);
       }
       if (!isFileRefRow(row)) {
-        throw new Error(
-          `derivatives.variant: fileRef "${fileRefId}" is missing storageKey/mimeType`,
-        );
+        throw new NotFoundError("fileRef", fileRefId);
       }
 
       const renderer = resolveRenderer(deps.registry, row.mimeType);
@@ -109,9 +108,10 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
             .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
             .map((u) => u.entityName)
             .join(", ") || "<none>";
-        throw new Error(
-          `derivatives.variant: no renderer registered for mimeType "${row.mimeType}". Known: ${known}.`,
-        );
+        throw new InternalError({
+          message: `derivatives.variant: no renderer registered for mimeType "${row.mimeType}".`,
+          details: { knownRenderers: known },
+        });
       }
 
       const src = deps.files.ref(row.storageKey);

package/src/derivatives/variant-key.ts

@@ -22,7 +22,7 @@ export function canonicalJson(value: unknown): string {
 // forever after a spec change; hashing the spec into the key means a
 // changed spec is automatically a new URL.
 export function specHash(spec: VariantSpec): string {
-  return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 8);
+  return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 16);
 }
 
 export const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;