@cosmicdrift/kumiko-bundled-features 0.193.1 → 0.195.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.193.1",
+  "version": "0.195.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>",
@@ -125,12 +125,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.193.1",
-    "@cosmicdrift/kumiko-framework": "0.193.1",
-    "@cosmicdrift/kumiko-headless": "0.193.1",
-    "@cosmicdrift/kumiko-renderer": "0.193.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.193.1",
-    "@cosmicdrift/kumiko-types": "0.193.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.195.0",
+    "@cosmicdrift/kumiko-framework": "0.195.0",
+    "@cosmicdrift/kumiko-headless": "0.195.0",
+    "@cosmicdrift/kumiko-renderer": "0.195.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.195.0",
+    "@cosmicdrift/kumiko-types": "0.195.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",

package/src/channel-email/smtp-transport.ts

@@ -35,10 +35,10 @@ export type SmtpTransportOptions = {
     readonly user: string;
     readonly pass: string;
   };
-  /** Default From-Adresse, app-weit. Eine einzelne Mail kann sie über
-   *  `EmailMessage.from` überschreiben (Reply aus einem bestimmten
-   *  Postfach); ohne Override greift diese. Format akzeptiert beides:
-   *  "noreply@ex.com" oder "Name <noreply@ex.com>". */
+  /** App-wide default From. A single send can override it via
+   *  `EmailMessage.from` (reply from a specific mailbox); without an
+   *  override this applies. Accepts both "noreply@ex.com" and
+   *  "Name <noreply@ex.com>". */
   readonly from: string;
 };
 

package/src/derivatives-sharp/__tests__/render.test.ts

@@ -216,6 +216,25 @@ describe("renderImage — validation", () => {
     const meta = await sharp(output).metadata();
     expect(meta.format).toBe("webp");
   });
+
+  test("a sourceMimeType matching an inherited Object.prototype key throws instead of using it as an encoder", async () => {
+    // Plain-object lookup on SOURCE_FORMAT_ENCODERS would resolve
+    // "constructor" to Object (an inherited key, not a real entry) without
+    // an Object.hasOwn guard — proving the throw path, not a silent pass-through.
+    const input = await unmappedFormatFixture(50, 50);
+    await expect(renderImage(input, {}, "constructor")).rejects.toThrow(/no output encoder/);
+  });
+
+  test("image/png ignores spec.quality instead of switching into lossy palette quantization", async () => {
+    const input = await pngFixture(50, 50);
+    const withQuality = await renderImage(input, { quality: 10 }, "image/png");
+    const withoutQuality = await renderImage(input, {}, "image/png");
+    const withQualityMeta = await sharp(withQuality).metadata();
+    // A quality-driven palette encode would quantize to a small color count;
+    // an ignored quality keeps the full-color (non-palette) PNG.
+    expect(withQualityMeta.format).toBe("png");
+    expect(Buffer.compare(withQuality, withoutQuality)).toBe(0);
+  });
 });
 
 describe("imageMetadata", () => {

package/src/derivatives-sharp/render.ts

@@ -98,7 +98,10 @@ const SOURCE_FORMAT_ENCODERS: Record<string, (pipeline: Sharp, quality?: number)
   // The upload whitelist admits the sloppy-but-common image/jpg alias
   "image/jpg": (pipeline, quality) =>
     pipeline.jpeg(quality !== undefined ? { quality } : undefined),
-  "image/png": (pipeline, quality) => pipeline.png(quality !== undefined ? { quality } : undefined),
+  // sharp's PngOptions.quality doesn't mean JPEG/WebP-style compression —
+  // it switches PNG into palette quantization (lossless -> color-reduced,
+  // banding instead of a softer/smaller image). Ignore it, same as gif.
+  "image/png": (pipeline) => pipeline.png(),
   "image/webp": (pipeline, quality) =>
     pipeline.webp(quality !== undefined ? { quality } : undefined),
   "image/avif": (pipeline, quality) =>
@@ -125,7 +128,7 @@ function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string
   }
 
   const encode = SOURCE_FORMAT_ENCODERS[sourceMimeType];
-  if (!encode) {
+  if (!Object.hasOwn(SOURCE_FORMAT_ENCODERS, sourceMimeType) || encode === undefined) {
     throw new Error(
       `derivatives-sharp: no output encoder for source mimeType "${sourceMimeType}" — set spec.format to pick an explicit output format.`,
     );

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

@@ -1,13 +1,15 @@
 // Proves GET {basePath}/:fileRefId/:variant end-to-end: anonymous, no
 // Authorization header, tenant resolved ONLY from Host (never the payload),
 // default-deny when no `derivativePublicPredicate` is registered for the
-// FileRef's entityType (or it returns false), the fixed preset-name
-// pre-check running BEFORE any DB/systemQuery work, and the Step-1
-// requestContext fix that makes `rateLimit: {per: "ip"}` actually gate an
-// r.httpRoute handler invoked via systemQuery (#1951).
+// FileRef's entityType (or it returns false), the variant spec resolving
+// from the FileRef's field declaration (not a fixed preset map, #1985), and
+// the Step-1 requestContext fix that makes `rateLimit: {per: "ip"}` actually
+// gate an r.httpRoute handler invoked via systemQuery (#1951).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import {
+  createEntity,
+  createImageField,
   defineFeature,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
@@ -26,7 +28,10 @@ import {
   buildMultipartBody,
   patchFileInstanceofForBunTest,
 } from "@cosmicdrift/kumiko-framework/testing";
-import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type {
+  DerivativeRendererPlugin,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
 import { createConfigFeature } from "../../config";
 import { fileFoundationFeature } from "../../file-foundation";
 import { createFileDerivativesFeature } from "../feature";
@@ -35,16 +40,43 @@ import type { DerivativePublicPredicateArgs } from "../handlers/public-variant.q
 const VARIANT_BYTES = new Uint8Array([7, 7, 7]);
 
 let renderCalls = 0;
-const fakeRender: DerivativeRendererPlugin["render"] = async () => {
+let lastRenderSpec: VariantSpec | null = null;
+const fakeRender: DerivativeRendererPlugin["render"] = async (_input, spec) => {
   renderCalls++;
+  lastRenderSpec = spec;
   return VARIANT_BYTES;
 };
 
 const PUBLIC_WIDGET_ID = "widget-public";
 const OTHER_WIDGET_ID = "widget-other";
 
+// `full` deliberately overrides the built-in preset's maxEdge (2560) — this
+// is what proves the route resolves the spec from the field declaration
+// (#1985), not from the frozen preset constants. `plan` is a name with no
+// preset counterpart at all — the exact motivating case from #1985 (an app
+// declaring its own variant name). `heroWide` uses characters (uppercase,
+// underscore-adjacent camelCase) outside a naive `[a-z0-9-]` guard — the
+// `variants` map has no runtime charset constraint, so the route's
+// syntactic pre-check must not narrow it. `plain` has no variants at all,
+// for the "field declares no variants" 404 case.
+const widgetEntity = createEntity({
+  table: "public_variant_widgets",
+  fields: {
+    img: createImageField({
+      variants: {
+        thumb: { maxEdge: 160, format: "webp" },
+        full: { maxEdge: 4096, format: "webp" },
+        plan: { maxEdge: 4096, format: "webp" },
+        heroWide: { maxEdge: 3200, format: "webp" },
+      },
+    }),
+    plain: createImageField(),
+  },
+});
+
 let predicateCalls = 0;
 const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
+  r.entity("widget", widgetEntity);
   r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
     isPublic: (args: DerivativePublicPredicateArgs) => {
       predicateCalls++;
@@ -91,6 +123,7 @@ afterAll(async () => {
 
 beforeEach(async () => {
   renderCalls = 0;
+  lastRenderSpec = null;
   predicateCalls = 0;
   // Fresh rate-limit bucket per test — no carry-over.
   await stack.redis.flushNamespace();
@@ -99,13 +132,14 @@ beforeEach(async () => {
 async function uploadFile(
   asUser: typeof userA,
   attach: { entityType: string; entityId: string },
+  fieldName = "img",
 ): 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", attach.entityType);
   fd.append("entityId", attach.entityId);
-  fd.append("fieldName", "img");
+  fd.append("fieldName", fieldName);
   const { body, contentType } = await buildMultipartBody(fd);
   const res = await stack.app.request("/api/files", {
     method: "POST",
@@ -174,21 +208,84 @@ describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
     expect(await revalidate.arrayBuffer()).toEqual(new ArrayBuffer(0));
   });
 
-  test("invalid variant name → 404, pre-check runs before any DB/systemQuery work", async () => {
+  test("syntactically malformed variant names → 404, pre-check runs before any DB/systemQuery work", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+    // Well-formed-looking but unregistered names (e.g. "not-a-preset") now
+    // reach the DB — the pre-check is purely syntactic since #1985, not a
+    // name list. Only pathological input is rejected here.
+    const malformedNames = [
+      "a".repeat(65), // over the 64-char cap
+      "foo%2Fbar", // decodes to a path separator
+      "foo..bar", // "." isn't in the allowed charset either
+      "foo%20bar", // decodes to a space
+    ];
+
+    for (const name of malformedNames) {
+      const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/${name}`);
+      expect(res.status).toBe(404);
+    }
+    expect(predicateCalls).toBe(0);
+    expect(renderCalls).toBe(0);
+  });
+
+  test("the field's own spec is used, not the built-in preset — proves resolution comes from the field declaration (#1985)", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/full`);
+
+    expect(res.status).toBe(200);
+    // widgetEntity's "img" field declares maxEdge:4096 for "full" — the
+    // built-in `full` preset (presets.ts) is maxEdge:2560. Getting 4096 here
+    // proves the spec came from the field, not the frozen preset constant.
+    expect(lastRenderSpec?.maxEdge).toBe(4096);
+  });
+
+  test("a field-declared name with no preset counterpart is served end-to-end — the exact case #1985 reported", async () => {
     const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
 
-    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/not-a-preset`);
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/plan`);
+
+    expect(res.status).toBe(200);
+    expect(lastRenderSpec?.maxEdge).toBe(4096);
+  });
+
+  test("a declared name outside [a-z0-9-] (camelCase) is still reachable — the syntactic gate isn't a narrower name list", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/heroWide`);
+
+    expect(res.status).toBe(200);
+    expect(lastRenderSpec?.maxEdge).toBe(3200);
+  });
+
+  test("a preset name the field doesn't declare in its variants → 404", async () => {
+    const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
+
+    // widgetEntity's "img" field declares only thumb/full — "card" and
+    // "hero" aren't in its variants map.
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/card`);
 
     expect(res.status).toBe(404);
-    expect(predicateCalls).toBe(0);
+    expect(predicateCalls).toBeGreaterThan(0);
+    expect(renderCalls).toBe(0);
+  });
+
+  test("a FileRef whose field declares no variants at all → 404", async () => {
+    const fileId = await uploadFile(
+      userA,
+      { entityType: "widget", entityId: PUBLIC_WIDGET_ID },
+      "plain",
+    );
+
+    const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
+
+    expect(res.status).toBe(404);
+    expect(predicateCalls).toBeGreaterThan(0);
     expect(renderCalls).toBe(0);
   });
 
   test("unknown fileRefId → 404", async () => {
-    // Valid UUID shape (the id column's type) but no matching row — a
-    // malformed/non-UUID id is a separate concern shared with the
-    // already-merged #1950 route (same fetchOne-by-id pattern), out of
-    // scope here.
+    // Valid UUID shape (the id column's type) but no matching row.
     const res = await stack.app.request(
       `http://${HOST_A}/media/00000000-0000-4000-8000-000000000000/thumb`,
     );
@@ -196,6 +293,17 @@ describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
     expect(res.status).toBe(404);
   });
 
+  test("malformed fileRefId → 404, pre-check runs before any DB/systemQuery work", async () => {
+    // Unlike #1950 (auth-gated), this route is anonymous — a non-UUID id
+    // reaching fetchOne() would throw Postgres 22P02 on an unauthenticated
+    // request, an unauth DoS primitive. Must 404 at the httpRoute pre-check.
+    const res = await stack.app.request(`http://${HOST_A}/media/not-a-uuid/thumb`);
+
+    expect(res.status).toBe(404);
+    expect(predicateCalls).toBe(0);
+    expect(renderCalls).toBe(0);
+  });
+
   test("cross-tenant: FileRef under tenant A, request resolves to tenant B → 404", async () => {
     const fileId = await uploadFile(userA, { entityType: "widget", entityId: PUBLIC_WIDGET_ID });
 

package/src/file-derivatives/feature.ts

@@ -16,13 +16,27 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
 import { PUBLIC_VARIANT_QN, publicVariantQuery } from "./handlers/public-variant.query";
-import { PRESET_VARIANT_NAMES } from "./presets";
 
 const FEATURE_NAME = "file-derivatives";
 
-// Widened from the readonly-tuple type of PRESET_VARIANT_NAMES so
-// `.includes(variant)` accepts a plain `string` param without an `as` cast.
-const VALID_VARIANT_NAMES: readonly string[] = PRESET_VARIANT_NAMES;
+// fileRefsTable.id is a UUID column — a malformed id must fail here, not at
+// the DB. Without this, an anonymous, internet-facing caller can throw a
+// Postgres 22P02 on every request (Bun.SQL pools the failed connection),
+// a DoS primitive with no auth required.
+const FILE_REF_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// Syntactic only, no registry/name-list lookup: a valid preset name plus a
+// random UUID reaches the same DB read anyway, so an allow-list of known
+// names defends nothing a determined caller can't route around — it only
+// blocks the cheaper of two equally-costly attacks. What a name actually
+// resolves to is decided by the field declaration in publicVariantQuery;
+// this just keeps pathological input (path separators, `..`, oversized
+// strings) out before that DB round-trip. `variants` keys have no runtime
+// charset constraint (`Readonly<Record<string, VariantSpec>>`), so this
+// stays permissive rather than guessing a convention — narrower than this
+// would silently 404 a legitimately declared name again. Do not reintroduce
+// a name list here "for safety" — see #1985.
+const VARIANT_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
 export type PublicVariantResolveApexTenant = (
   host: string,
@@ -46,21 +60,23 @@ type PublicVariantQueryResult = {
 } | null;
 
 // file-derivatives — derive-on-first-use file variants (thumbnails,
-// resized/reformatted images) plus an opt-in ANONYMOUS route that serves
-// one of 4 fixed presets (thumb/card/hero/full) for a FileRef whose
+// resized/reformatted images) plus an opt-in ANONYMOUS route that serves any
+// variant an app declared on the FileRef's field (`createImageField({
+// variants: {...} })`, including but not limited to the `thumb`/`card`/
+// `hero`/`full` presets exported from `./presets`), for a FileRef whose
 // entityType has a registered, default-deny `derivativePublicPredicate`.
 //
 // The route never serves the original and never accepts a free VariantSpec
-// — only a preset name from the fixed list, 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.
+// — 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.
 export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}): FeatureDefinition {
   const basePath = opts.basePath ?? "/media";
 
   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 ONE of the 4 fixed presets (thumb/card/hero/full) for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef.",
+      "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.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -100,12 +116,14 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
           // template, so Hono can't infer the param type from a literal.
           const fileRefId = c.req.param("fileRefId");
           const variant = c.req.param("variant");
-          // Pre-check against the FIXED preset list before systemQuery runs
-          // at all — stops a caller from burning rate-limit budget/DB
-          // lookups on arbitrary variant names (thumb-a, thumb-b, ...).
-          // 404, not 400 — an invalid name and "doesn't exist" must answer
-          // identically, no name-oracle.
-          if (!fileRefId || !variant || !VALID_VARIANT_NAMES.includes(variant)) {
+          // 404, not 400 — a syntactically bad name and "doesn't exist" must
+          // answer identically, no name-oracle.
+          if (
+            !fileRefId ||
+            !variant ||
+            !VARIANT_NAME_RE.test(variant) ||
+            !FILE_REF_ID_RE.test(fileRefId)
+          ) {
             return c.text("not found", 404);
           }
 

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

@@ -1,7 +1,9 @@
-// Public-Read of a derived FileRef variant (thumbnail/card/hero/full) — the
-// anonymous counterpart to GET /files/:id/variant/:name (#1950, auth-gated,
-// field-declared variants). This route never serves the original, never
-// accepts a free VariantSpec, and only serves one of the 4 fixed presets.
+// Public-Read of a derived FileRef variant — the anonymous counterpart to
+// GET /files/:id/variant/:name (#1950, auth-gated). Both routes resolve the
+// same way: the variant spec comes from the FileRef's field declaration
+// (`createImageField({ variants: {...} })`), not a fixed list — an app that
+// declares its own variant name gets it served here too. This route never
+// serves the original and never accepts a free VariantSpec, only a name.
 // Default-deny: an entityType with no `EXT_DERIVATIVE_PUBLIC_PREDICATE`
 // registration, or a predicate that returns false, both answer `null` —
 // the httpRoute wrapper in feature.ts turns that into a 404, same as a
@@ -11,6 +13,7 @@
 // httpRoute wrapper's `resolveApexTenant`), never from the payload.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { resolveFieldVariant } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   defineQueryHandler,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -19,13 +22,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import { z } from "zod";
-import { card, full, hero, PRESET_VARIANT_NAMES, thumb } from "../presets";
-
-const VARIANT_SPECS = { thumb, card, hero, full } as const;
 
 type FileRefRow = {
   readonly entityType: string | null;
   readonly entityId: string | null;
+  readonly fieldName: string | null;
 };
 
 export type DerivativePublicPredicateArgs = {
@@ -58,7 +59,7 @@ export const publicVariantQuery = defineQueryHandler({
   name: "public-variant",
   schema: z.object({
     fileRefId: z.string(),
-    variant: z.enum(PRESET_VARIANT_NAMES),
+    variant: z.string().min(1).max(64),
   }),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
   // ponytail: "ip" trusts the first x-forwarded-for hop (buildRequestContextData
@@ -76,8 +77,8 @@ export const publicVariantQuery = defineQueryHandler({
       isDeleted: false,
     });
     if (!row) return null;
-    const { entityType, entityId } = row;
-    if (entityType === null || entityId === null) return null;
+    const { entityType, entityId, fieldName } = row;
+    if (entityType === null || entityId === null || fieldName === null) return null;
 
     const usage = ctx.registry
       .getExtensionUsages(EXT_DERIVATIVE_PUBLIC_PREDICATE)
@@ -103,7 +104,8 @@ export const publicVariantQuery = defineQueryHandler({
       );
     }
 
-    const spec = VARIANT_SPECS[query.payload.variant];
+    const spec = resolveFieldVariant(ctx.registry, entityType, fieldName, query.payload.variant);
+    if (!spec) return null;
     const result = await derivatives.variant(query.payload.fileRefId, spec, query.payload.variant);
     const bytes = await files.ref(result.storageKey).read();
 

package/src/file-derivatives/index.ts

@@ -1,3 +1,3 @@
 export type { FileDerivativesOptions, PublicVariantResolveApexTenant } from "./feature";
 export { createFileDerivativesFeature, fileDerivativesFeature } from "./feature";
-export { card, full, hero, PRESET_VARIANT_NAMES, thumb } from "./presets";
+export { card, full, hero, thumb } from "./presets";

package/src/file-derivatives/presets.ts

@@ -1,13 +1,10 @@
 import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 
+// Ready-made specs to spread into a field's own `variants` declaration
+// (`createImageField({ variants: { thumb, full: { ...full, maxEdge: 4096 } } })`)
+// — not an allow-list. Which names a route serves is decided entirely by
+// what a field declares (#1985), these are just common defaults.
 export const thumb = { maxEdge: 160, fit: "cover", format: "webp" } as const satisfies VariantSpec;
 export const card = { maxEdge: 640, fit: "inside", format: "webp" } as const satisfies VariantSpec;
 export const hero = { maxEdge: 1600, fit: "inside", format: "webp" } as const satisfies VariantSpec;
 export const full = { maxEdge: 2560, fit: "inside", format: "webp" } as const satisfies VariantSpec;
-
-// Single source of truth for the 4 preset variant names — the public
-// variant route (#1951) validates its `:variant` path param against this
-// list BEFORE any DB lookup or systemQuery dispatch, and the query
-// handler's Zod schema enums against it too. Keep in sync with the
-// preset exports above.
-export const PRESET_VARIANT_NAMES = ["thumb", "card", "hero", "full"] as const;

package/src/form-draft/__tests__/cleanup.integration.test.ts

@@ -120,6 +120,20 @@ async function backdate(draftKey: string, daysAgo: number): Promise<void> {
   );
 }
 
+// applyEntityEvent only stamps modified_at on updated/deleted/restored, never
+// on created (framework/src/db/apply-entity-event.ts) — a draft saved exactly
+// once has modified_at IS NULL, which is the real-world case the cleanup
+// query's COALESCE(modified_at, inserted_at) fallback exists for.
+async function backdateInsertedOnly(draftKey: string, daysAgo: number): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE "read_form_drafts"
+     SET "inserted_at" = now() - ($1::int * interval '1 day'),
+         "modified_at" = NULL
+     WHERE "draft_key" = $2`,
+    [daysAgo, draftKey],
+  );
+}
+
 async function backdateFileRef(storageKey: string, daysAgo: number): Promise<void> {
   await asRawClient(stack.db).unsafe(
     `UPDATE "file_refs" SET "inserted_at" = now() - ($1::int * interval '1 day')
@@ -190,6 +204,19 @@ describe("form-draft cleanup job", () => {
     });
     expect(await draftExists("wizard:three-days-old")).toBe(true);
   });
+
+  test("deletes a draft saved exactly once (modified_at IS NULL), falling back to inserted_at", async () => {
+    await saveDraft("wizard:once-saved");
+    await backdateInsertedOnly("wizard:once-saved", 31);
+    await saveDraft("wizard:fresh-once-saved");
+    await backdateInsertedOnly("wizard:fresh-once-saved", 1);
+    await dispatchCleanup();
+
+    await waitFor(async () => {
+      expect(await draftExists("wizard:once-saved")).toBe(false);
+    });
+    expect(await draftExists("wizard:fresh-once-saved")).toBe(true);
+  });
 });
 
 describe("form-draft cleanup job — FileRef release (#1915)", () => {

package/src/form-draft/__tests__/form-draft.integration.test.ts

@@ -184,13 +184,22 @@ describe("form-draft integration — ownership isolation", () => {
 describe("form-draft integration — list", () => {
   test("list returns open drafts for a screenId, newest first, without the blob's values", async () => {
     await saveDraft("wizard:a", { name: "First" }, 0);
+    // savedAt is a millisecond stamp (#1960) — sleep is best-effort only;
+    // under CI load two saves can still tie, so assert the comparator
+    // contract (savedAt desc, then id desc) rather than a fixed key order.
+    await Bun.sleep(20);
     await saveDraft("wizard:b", { name: "Second" }, 1);
 
     const { drafts } = await listDrafts("wizard");
-    expect(drafts.map((d) => d.draftKey)).toEqual(["wizard:b", "wizard:a"]);
-    expect(drafts[0]?.stepIndex).toBe(1);
-    expect(drafts[0]?.savedAt).toBeTruthy();
-    expect(drafts[0]).not.toHaveProperty("values");
+    expect(drafts).toHaveLength(2);
+    expect(new Set(drafts.map((d) => d.draftKey))).toEqual(new Set(["wizard:a", "wizard:b"]));
+    const [first, second] = drafts;
+    expect(first?.savedAt).toBeTruthy();
+    expect(first).not.toHaveProperty("values");
+    const byTime = second!.savedAt.localeCompare(first!.savedAt);
+    const byId = second!.id.localeCompare(first!.id);
+    expect(byTime < 0 || (byTime === 0 && byId < 0)).toBe(true);
+    if (first!.draftKey === "wizard:b") expect(first!.stepIndex).toBe(1);
   });
 
   test("list excludes a draft whose screenId is only a prefix, not a full segment match", async () => {
@@ -209,6 +218,22 @@ describe("form-draft integration — list", () => {
     expect(drafts.map((d) => d.draftKey)).toEqual(["scr%en:a"]);
   });
 
+  test("a screenId containing an underscore is matched literally, not as a single-char wildcard", async () => {
+    await saveDraft("wizar_:a", {}, 0);
+    await saveDraft("wizardX:a", {}, 0);
+
+    const { drafts } = await listDrafts("wizar_");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wizar_:a"]);
+  });
+
+  test("a screenId containing a literal backslash is matched literally", async () => {
+    await saveDraft("wiz\\ard:a", {}, 0);
+    await saveDraft("wizard:a", {}, 0);
+
+    const { drafts } = await listDrafts("wiz\\ard");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wiz\\ard:a"]);
+  });
+
   test("list resolves an empty array when nothing was ever saved for the screenId", async () => {
     expect((await listDrafts("no-such-screen")).drafts).toEqual([]);
   });

package/src/form-draft/entity.ts

@@ -24,7 +24,7 @@ export const formDraftEntity = createEntity({
     // feeds the GDPR-hook-coverage boot guard (it's a plain FK into `user`,
     // not content of its own) — see ../form-draft-user-data for the
     // required export/delete hook coverage.
-    ownerId: createTextField({ subjectRef: true }),
+    ownerId: createTextField({ subjectRef: true, required: true }),
     draftKey: createTextField({ required: true, maxLength: FORM_DRAFT_KEY_MAX_LENGTH }),
     // The blob shape is fixed by issue #1889, not left to the caller:
     // { values: Record<string, unknown>, stepIndex: number, savedAt: string }.

package/src/form-draft/feature.ts

@@ -13,7 +13,6 @@ import { discardDraftWrite } from "./handlers/discard.write";
 import { getDraftQuery } from "./handlers/get.query";
 import { listDraftsQuery } from "./handlers/list.query";
 import { saveDraftWrite } from "./handlers/save.write";
-import { FORM_DRAFT_FEATURE_I18N } from "./i18n";
 
 function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>): void {
   r.describe(
@@ -41,8 +40,6 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
 
   r.config({ keys: { retentionDays: formDraftRetentionDaysConfig } });
   r.job("cleanup", { trigger: { cron: "0 3 * * *" }, concurrency: "skip" }, cleanupDraftsJob);
-
-  r.translations({ keys: FORM_DRAFT_FEATURE_I18N });
 }
 
 export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/src/form-draft/handlers/__tests__/list.query.test.ts

@@ -0,0 +1,26 @@
+// byNewestFirst — the sort issue #1960 traced the flake to: form-draft.integration.test.ts
+// creates two drafts fast enough to land on the same millisecond savedAt, and the query had
+// no ORDER BY at all, so ties fell back to Postgres' undefined row order. These cases can't be
+// forced through the integration stack (no clock control on the real save path, and seeding a
+// row directly would bypass the event store), so the comparator is unit-tested directly here.
+
+import { describe, expect, test } from "bun:test";
+import { byNewestFirst } from "../list.query";
+
+function draft(id: string, savedAt: string) {
+  return { id, draftKey: `wizard:${id}`, stepIndex: 0, savedAt };
+}
+
+describe("byNewestFirst", () => {
+  test("a later savedAt sorts before an earlier one", () => {
+    const older = draft("a", "2026-01-01T00:00:00.000Z");
+    const newer = draft("b", "2026-01-01T00:00:00.001Z");
+    expect([older, newer].sort(byNewestFirst)).toEqual([newer, older]);
+  });
+
+  test("a tied savedAt still sorts deterministically, regardless of input order", () => {
+    const a = draft("aaaa", "2026-01-01T00:00:00.000Z");
+    const b = draft("bbbb", "2026-01-01T00:00:00.000Z");
+    expect([a, b].sort(byNewestFirst)).toEqual([b, a].sort(byNewestFirst));
+  });
+});