@cosmicdrift/kumiko-framework 0.189.0 → 0.191.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.189.0",
+  "version": "0.191.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>",
@@ -95,6 +95,10 @@
       "types": "./src/files/index.ts",
       "default": "./src/files/index.ts"
     },
+    "./derivatives": {
+      "types": "./src/derivatives/index.ts",
+      "default": "./src/derivatives/index.ts"
+    },
     "./jobs": {
       "types": "./src/jobs/index.ts",
       "default": "./src/jobs/index.ts"
@@ -182,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.189.0",
+    "@cosmicdrift/kumiko-types": "0.191.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -198,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.189.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.191.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/server.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
+import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { EXT_FILE_PROVIDER } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
 import { createAnonymousUser } from "../engine/system-user";
@@ -507,14 +508,23 @@ export function buildServer(options: ServerOptions): KumikoServer {
       // prefix before the first ":" owns the MSP. Used to reject
       // cross-feature ctx.appendEvent calls at emit-site.
       const mspOwner = msp.name.split(":")[0];
+      const mspFiles = fileProviderResolver
+        ? createFileContext(() => fileProviderResolver(event.tenantId))
+        : undefined;
       const applyCtx = createMultiStreamApplyContext({
         registry: options.registry,
         db: rawRunner,
         tenantId: event.tenantId,
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
-        ...(fileProviderResolver && {
-          files: createFileContext(() => fileProviderResolver(event.tenantId)),
+        ...(mspFiles && { files: mspFiles }),
+        ...(mspFiles && {
+          derivatives: createDerivativesContext({
+            files: mspFiles,
+            registry: options.registry,
+            db: rawRunner,
+            tenantId: event.tenantId,
+          }),
         }),
       });
       await applyFn(event, rawRunner, applyCtx);

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

@@ -0,0 +1,162 @@
+// Proves ctx.derivatives actually arrives on BOTH context-building paths
+// this cut wires it into: the HTTP write-handler path (dispatch-shared.ts
+// buildHandlerContext) and the job path (job-runner.ts handleJob). A unit
+// test on createDerivativesContext alone can't catch a forgotten wiring
+// point — this is that test.
+
+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 { createFilesFeature } from "../../files/feature";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+import { buildMultipartBody, patchFileInstanceofForBunTest, waitFor } from "../../testing";
+
+const fakeRender: DerivativeRendererPlugin["render"] = async () => new Uint8Array([9, 9, 9]);
+
+const jobResults: Array<{ storageKey: string; mimeType: string; rendered: boolean }> = [];
+
+const derivativesTestFeature = defineFeature("derivativestest", (r) => {
+  r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, { onRegister: () => {} });
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", { render: fakeRender });
+
+  r.writeHandler(
+    "make-variant",
+    z.object({ fileRefId: z.string() }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "no ctx.derivatives on write-handler ctx" }),
+        );
+      }
+      const result = await ctx.derivatives.variant(
+        event.payload.fileRefId,
+        { maxEdge: 100 },
+        "thumb",
+      );
+      return { isSuccess: true as const, data: result };
+    },
+    { access: { openToAll: true } },
+  );
+
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload, ctx) => {
+    const fileRefId = (payload as { fileRefId: string }).fileRefId;
+    if (!ctx.derivatives) {
+      throw new Error("no ctx.derivatives on job ctx");
+    }
+    const result = await ctx.derivatives.variant(fileRefId, { maxEdge: 200 }, "card");
+    jobResults.push(result);
+  });
+});
+
+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(), derivativesTestFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+    jobs: { consumerLane: "worker" },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function uploadFile(asUser = user): 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" }));
+  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("ctx.derivatives wiring — HTTP write-handler path", () => {
+  test("a real write-handler sees ctx.derivatives and variant() returns a storage key", async () => {
+    const fileId = await uploadFile();
+
+    const result = await stack.http.writeOk<{
+      storageKey: string;
+      mimeType: string;
+      rendered: boolean;
+    }>("derivativestest:write:make-variant", { fileRefId: fileId }, user);
+
+    expect(result.storageKey).toContain("thumb-");
+    expect(result.mimeType).toBe("image/jpeg");
+    expect(result.rendered).toBe(true);
+  });
+});
+
+describe("ctx.derivatives wiring — job path", () => {
+  test("a job handler sees ctx.derivatives and variant() returns a storage key", async () => {
+    jobResults.length = 0;
+    const fileId = await uploadFile();
+
+    // handleJob resolves tenant scope from payload.tenantId (falls back to
+    // SYSTEM_TENANT_ID otherwise) — without it the derivatives lookup can't
+    // find the file uploaded under the test tenant.
+    await stack.jobRunner?.dispatch("derivativestest:job:record", { fileRefId: fileId, tenantId });
+
+    await waitFor(() => {
+      expect(jobResults.length).toBeGreaterThan(0);
+    });
+    expect(jobResults[0]?.storageKey).toContain("card-");
+    expect(jobResults[0]?.rendered).toBe(true);
+  });
+});
+
+// variant() filters on `id`, `tenantId`, and `isDeleted` — a unit test can't
+// tell a real Postgres query from a stub that ignores those filters, so
+// these three run against the real DB via setupTestStack.
+describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () => {
+  test("an unknown fileRefId throws", async () => {
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: "00000000-0000-4000-8000-999999999999" },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  test("a soft-deleted fileRef throws", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+    const deleteRes = await stack.app.request(`/api/files/${fileId}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(deleteRes.status).toBe(200);
+
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: fileId },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+
+  test("a fileRef uploaded under a different tenant is not resolvable", async () => {
+    const foreignFileId = await uploadFile(otherTenantUser);
+
+    const err = await stack.http.writeErr(
+      "derivativestest:write:make-variant",
+      { fileRefId: foreignFileId },
+      user,
+    );
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+  });
+});

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

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { Registry } from "../../engine/types";
+import { createFileContext } from "../../files/file-handle";
+import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { createDerivativesContext, resolveRenderer } from "../derivatives-context";
+
+const FILE_REF_ID = "11111111-1111-4111-8111-111111111111";
+const TENANT_ID = "22222222-2222-4222-8222-222222222222";
+
+// Minimal fake Registry — same pattern as provider-resolver.test.ts's
+// fakeRegistry: only getExtensionUsages is exercised by resolveRenderer.
+function fakeRegistry(usages: ReadonlyArray<{ entityName: string; options: unknown }>): Registry {
+  return {
+    getExtensionUsages: () => usages,
+  } as unknown as Registry;
+}
+
+function countingRenderer(): {
+  plugin: DerivativeRendererPlugin;
+  calls: () => number;
+} {
+  let calls = 0;
+  const plugin: DerivativeRendererPlugin = {
+    render: async () => {
+      calls++;
+      return new Uint8Array([calls]);
+    },
+  };
+  return { plugin, calls: () => calls };
+}
+
+// bun-db's fetchOne(db, table, where) duck-types `db` as a TenantDb via
+// tenantDbDelegate() and, when it matches, delegates straight to
+// db.selectMany(...) instead of building raw SQL — so a fake satisfying that
+// shape exercises variant()'s own logic without a live Postgres connection.
+// selectMany evaluates `where` against the canned row instead of ignoring
+// it: variant()'s two mandatory filters (tenantId, isDeleted) are real
+// integration-test territory, but a fake that returns the row unconditionally
+// would let those filters be deleted here without a single red test.
+function fakeDbWithFileRef(row: { storageKey: string; mimeType: string }): unknown {
+  const canned: Record<string, unknown> = {
+    ...row,
+    id: FILE_REF_ID,
+    tenantId: TENANT_ID,
+    isDeleted: false,
+  };
+  return {
+    raw: { unsafe: () => {} },
+    tenantId: TENANT_ID,
+    selectMany: async (_table: unknown, where?: Record<string, unknown>) => {
+      const matches = Object.entries(where ?? {}).every(([key, value]) => canned[key] === value);
+      return matches ? [canned] : [];
+    },
+    fetchOne: async () => canned,
+    insertOne: async () => undefined,
+    updateMany: async () => [],
+    deleteMany: async () => {},
+  };
+}
+
+describe("resolveRenderer", () => {
+  test("exact MIME match wins over a wildcard", () => {
+    const { plugin: exactPlugin } = countingRenderer();
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([
+      { entityName: "image/*", options: wildcardPlugin },
+      { entityName: "image/png", options: exactPlugin },
+    ]);
+    expect(resolveRenderer(registry, "image/png")).toBe(exactPlugin);
+  });
+
+  test("falls back to a `<type>/*` wildcard when no exact match exists", () => {
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: wildcardPlugin }]);
+    expect(resolveRenderer(registry, "image/jpeg")).toBe(wildcardPlugin);
+  });
+
+  test("no match returns undefined — caller throws with the known-list", () => {
+    const registry = fakeRegistry([]);
+    expect(resolveRenderer(registry, "application/pdf")).toBeUndefined();
+  });
+
+  test("a `; charset=` suffix on the source mimeType doesn't break resolution", () => {
+    const { plugin } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/jpeg", options: plugin }]);
+    expect(resolveRenderer(registry, "image/jpeg; charset=binary")).toBe(plugin);
+  });
+
+  test("a registered usage without a render() throws instead of falling back to the wildcard", () => {
+    const { plugin: wildcardPlugin } = countingRenderer();
+    const registry = fakeRegistry([
+      { entityName: "image/*", options: wildcardPlugin },
+      { entityName: "image/png", options: { renderer: () => {} } },
+    ]);
+    expect(() => resolveRenderer(registry, "image/png")).toThrow(/image\/png/);
+  });
+});
+
+describe("createDerivativesContext — variant()", () => {
+  async function setup(mimeType = "image/jpeg") {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), mimeType);
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin, calls } = countingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: plugin }]);
+    const db = fakeDbWithFileRef({ storageKey: "tenant/photo.jpg", mimeType });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+    return { ctx, calls, provider };
+  }
+
+  test("derive-on-first-use: first call renders, second call with the same spec hits the cache", async () => {
+    const { ctx, calls } = await setup();
+    const spec = { maxEdge: 320 } as const;
+
+    const first = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    expect(first.rendered).toBe(true);
+    expect(calls()).toBe(1);
+
+    const second = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    expect(second.rendered).toBe(false);
+    expect(calls()).toBe(1);
+    expect(second.storageKey).toBe(first.storageKey);
+  });
+
+  test("a changed spec renders again at a different key", async () => {
+    const { ctx, calls } = await setup();
+    const first = await ctx.variant(FILE_REF_ID, { maxEdge: 320 }, "thumb");
+    const second = await ctx.variant(FILE_REF_ID, { maxEdge: 640 }, "thumb");
+
+    expect(calls()).toBe(2);
+    expect(second.rendered).toBe(true);
+    expect(second.storageKey).not.toBe(first.storageKey);
+  });
+
+  test("no renderer registered for the mimeType throws, naming the known patterns", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/doc.pdf", new Uint8Array([1]));
+    const files = createFileContext(() => Promise.resolve(provider));
+    const registry = fakeRegistry([{ entityName: "image/*", options: countingRenderer().plugin }]);
+    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\/\*/);
+  });
+
+  test("mimeType is consistent across a fresh render and a cache hit for the same spec", async () => {
+    const { ctx } = await setup();
+    const spec = { format: "webp" } as const;
+
+    const first = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    const second = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(first.mimeType).toBe("image/webp");
+    expect(second.mimeType).toBe("image/webp");
+  });
+
+  test("the mimeType written to storage matches the mimeType returned to the caller", async () => {
+    const { ctx, provider } = await setup();
+    const spec = { format: "webp" } as const;
+
+    const result = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(provider.mimeTypeOf(result.storageKey)).toBe(result.mimeType);
+    expect(result.mimeType).toBe("image/webp");
+  });
+});

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

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { specHash, variantSuffix } from "../variant-key";
+
+describe("specHash — key stability", () => {
+  test("key order doesn't matter", () => {
+    expect(specHash({ fit: "cover", maxEdge: 512 })).toBe(specHash({ maxEdge: 512, fit: "cover" }));
+  });
+
+  test("an explicit undefined is neutral, same as omitting the key", () => {
+    expect(specHash({ fit: "cover" })).toBe(specHash({ fit: "cover", blur: undefined }));
+  });
+
+  test("nested object keys are sorted too", () => {
+    expect(specHash({ size: { width: 1, height: 2 } })).toBe(
+      specHash({ size: { height: 2, width: 1 } }),
+    );
+  });
+
+  test("a changed value produces a different hash — the whole point of hashing the spec", () => {
+    expect(specHash({ maxEdge: 512 })).not.toBe(specHash({ maxEdge: 640 }));
+  });
+});
+
+describe("variantSuffix", () => {
+  test("the name is part of the suffix — same spec, different name diverges", () => {
+    const spec = { maxEdge: 512 } as const;
+    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("a path-traversal name is rejected — it would escape the tenant prefix in the derived key", () => {
+    expect(() => variantSuffix("../evil", {})).toThrow(/variant name/);
+  });
+
+  test("a name containing a slash is rejected", () => {
+    expect(() => variantSuffix("a/b", {})).toThrow(/variant name/);
+  });
+
+  test("an empty name is rejected", () => {
+    expect(() => variantSuffix("", {})).toThrow(/variant name/);
+  });
+
+  test("a name over 32 chars is rejected", () => {
+    expect(() => variantSuffix("a".repeat(40), {})).toThrow(/variant name/);
+  });
+
+  test("ordinary names pass through", () => {
+    expect(() => variantSuffix("thumb", {})).not.toThrow();
+    expect(() => variantSuffix("card-2x", {})).not.toThrow();
+    expect(() => variantSuffix("Hero", {})).not.toThrow();
+  });
+});

package/src/derivatives/derivatives-context.ts

@@ -0,0 +1,146 @@
+import type {
+  DerivativeRendererPlugin,
+  DerivativesContext,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
+import { type AnyDb, fetchOne } from "../bun-db/query";
+import { EXT_DERIVATIVE_RENDERER } from "../engine/extension-names";
+import type { Registry, TenantId } from "../engine/types";
+import type { FileContext } from "../files/file-handle";
+import { fileRefsTable } from "../files/file-ref-table";
+import { assertSafeStorageKey } from "../files/types";
+import { variantSuffix } from "./variant-key";
+
+export type DerivativesContextDeps = {
+  readonly files: FileContext;
+  readonly registry: Registry;
+  readonly db: AnyDb;
+  readonly tenantId: TenantId;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind, same pattern as isFileProviderPlugin.
+function isDerivativeRendererPlugin(o: unknown): o is DerivativeRendererPlugin {
+  return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
+}
+
+// Mirrors validateFile's mime-normalization: strip a `; charset=…` suffix,
+// trim, lowercase — so a provider-supplied `image/jpeg; charset=binary`
+// still resolves.
+function normalizeMimeType(mimeType: string): string {
+  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+}
+
+export function resolveRenderer(
+  registry: Registry,
+  mimeType: string,
+): DerivativeRendererPlugin | undefined {
+  const normalized = normalizeMimeType(mimeType);
+  const usages = registry.getExtensionUsages(EXT_DERIVATIVE_RENDERER);
+
+  const exact = usages.find((u) => u.entityName === normalized);
+  if (exact) {
+    if (!isDerivativeRendererPlugin(exact.options))
+      throw new Error(
+        `derivatives.resolveRenderer: "${exact.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
+      );
+    return exact.options;
+  }
+
+  const wildcard = usages.find((u) => u.entityName === `${normalized.split("/")[0]}/*`);
+  if (wildcard) {
+    if (!isDerivativeRendererPlugin(wildcard.options))
+      throw new Error(
+        `derivatives.resolveRenderer: "${wildcard.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`,
+      );
+    return wildcard.options;
+  }
+
+  return undefined;
+}
+
+type FileRefRow = {
+  readonly storageKey: string;
+  readonly mimeType: string;
+};
+
+function isFileRefRow(row: Record<string, unknown>): row is FileRefRow {
+  return typeof row["storageKey"] === "string" && typeof row["mimeType"] === "string";
+}
+
+// The spec — not the renderer — determines the output mimeType, so it's the
+// single source of truth for both what gets written to storage and what the
+// caller receives; a cache hit never runs the renderer, so there's nothing
+// else to derive it from.
+function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
+  switch (spec.format) {
+    case "webp":
+      return "image/webp";
+    case "avif":
+      return "image/avif";
+    case "jpeg":
+      return "image/jpeg";
+    default:
+      return sourceMimeType;
+  }
+}
+
+export function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext {
+  return {
+    variant: async (fileRefId, spec, name) => {
+      const row = await fetchOne<Record<string, unknown>>(deps.db, fileRefsTable, {
+        id: fileRefId,
+        tenantId: deps.tenantId,
+        isDeleted: false,
+      });
+      if (!row) {
+        throw new Error(`derivatives.variant: no fileRef found for id "${fileRefId}"`);
+      }
+      if (!isFileRefRow(row)) {
+        throw new Error(
+          `derivatives.variant: fileRef "${fileRefId}" is missing storageKey/mimeType`,
+        );
+      }
+
+      const renderer = resolveRenderer(deps.registry, row.mimeType);
+      if (!renderer) {
+        const known =
+          deps.registry
+            .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
+            .map((u) => u.entityName)
+            .join(", ") || "<none>";
+        throw new Error(
+          `derivatives.variant: no renderer registered for mimeType "${row.mimeType}". Known: ${known}.`,
+        );
+      }
+
+      const src = deps.files.ref(row.storageKey);
+      // ponytail: derived key keeps the source extension regardless of the
+      // spec's format — widen deriveKey if a storage backend ever routes on
+      // extension.
+      const target = src.derive(variantSuffix(name, spec));
+      // Belt-and-suspenders: variantSuffix already rejects an unsafe name,
+      // this catches a traversal segment reaching the key through any other
+      // path (e.g. a future deriveKey change).
+      assertSafeStorageKey(target.key);
+      const mimeType = outputMimeType(spec, row.mimeType);
+
+      if (await target.exists()) {
+        return {
+          storageKey: target.key,
+          mimeType,
+          rendered: false,
+        };
+      }
+
+      const original = await src.read();
+      const result = await renderer.render(original, spec, row.mimeType);
+      await target.write(result, mimeType);
+      return {
+        storageKey: target.key,
+        mimeType,
+        rendered: true,
+      };
+    },
+  };
+}

package/src/derivatives/index.ts

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

package/src/derivatives/variant-key.ts

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+
+// Deterministic JSON: object keys sorted (recursively), `undefined` values
+// dropped, arrays keep their order. Two specs that are semantically equal
+// (same keys, different insertion order; explicit `undefined` vs. omitted)
+// serialize identically.
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// A key built from the variant name alone would keep serving stale pixels
+// 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);
+}
+
+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
+  // like "../../other-tenant/x" would escape the tenant prefix the key is
+  // built under.
+  if (!VARIANT_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `derivatives: variant name must match ${VARIANT_NAME_PATTERN.source} (letters, digits, hyphens; max 32 chars), got "${name}"`,
+    );
+  }
+  return `${name}-${specHash(spec)}`;
+}

package/src/engine/extension-names.ts

@@ -87,6 +87,23 @@ export const EXT_FILE_PROVIDER = "fileProvider" as const;
 // des file-foundation-Features MUSS diese Konstante mitziehen.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as const;
 
+/**
+ * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
+ * (file-derivatives).
+ *
+ * Renderer-Features (a future `derivatives-*` feature) register via
+ * `r.useExtension(EXT_DERIVATIVE_RENDERER, "<mimePattern>", { render })`,
+ * where `<mimePattern>` is an exact MIME type (`application/pdf`) or a
+ * type-wildcard (`image/*`). `ctx.derivatives.variant(...)` resolves the
+ * renderer for a FileRef's MIME type at call time — exact match first,
+ * wildcard second.
+ *
+ * No `r.extensionSelector` and no config key: unlike `fileProvider`, the
+ * resolution is deterministic from the MIME type — no tenant ever picks a
+ * different image library for the same content type.
+ */
+export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer" 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_RENDERER,
   EXT_EXTERNAL_RESOURCE,
   EXT_FILE_PROVIDER,
   EXT_INFRA_RESOURCE,

package/src/files/in-memory-provider.ts

@@ -10,6 +10,11 @@ export type InMemoryFileProvider = FileStorageProvider & {
   // Test-only introspection: keys currently stored. Useful for assertions
   // like `expect(provider.keys()).toContain("tenant/foo.jpg")`.
   keys(): readonly string[];
+  // Test-only introspection: the mimeType a write()/writeStream() stored for
+  // a key — undefined mirrors an untracked write. FileStorageProvider has no
+  // read-back-metadata method (mimeType lives on the FileRef row in prod),
+  // so this is the only way a test can assert what actually landed in storage.
+  mimeTypeOf(key: string): string | undefined;
   // Test-only reset between cases. beforeEach-friendly.
   clear(): void;
 };
@@ -93,6 +98,10 @@ export function createInMemoryFileProvider(): InMemoryFileProvider {
       return Array.from(store.keys());
     },
 
+    mimeTypeOf(key) {
+      return store.get(key)?.mimeType;
+    },
+
     clear() {
       store.clear();
     },

package/src/jobs/job-runner.ts

@@ -3,6 +3,7 @@ import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
+import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { createSystemUser } from "../engine/system-user";
 import {
   type AppContext,
@@ -393,17 +394,33 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // at runtime the write-handler path never would (framework#1532).
     const notify = context._notifyFactory?.(jobSystemUser, tenantId);
     const configDb = context.db as DbConnection | undefined; // @cast-boundary db-operator
+    // Shared by the config accessor and ctx.derivatives below — both need the
+    // same tenant-scoped db, and building it twice would let the two calls
+    // drift apart.
+    const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
     const config =
-      context._configAccessorFactory && configDb
+      context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
             user: { id: jobSystemUser.id, tenantId },
-            db: createTenantDb(configDb, tenantId, "system"),
+            db: tenantScopedDb,
             secrets: context.secrets,
           })
         : undefined;
+    // Mirror dispatch-shared.ts: ctx.derivatives needs files+db, same
+    // tenant-scoped db the config accessor above uses.
+    const derivatives =
+      files && tenantScopedDb
+        ? createDerivativesContext({
+            files,
+            registry,
+            db: tenantScopedDb,
+            tenantId,
+          })
+        : context.derivatives;
     const jobContext: AppContext = {
       ...context,
       files,
+      derivatives,
       ...(notify !== undefined && { notify }),
       ...(config !== undefined && { config }),
       // The runner owns the registry it resolved this job from — expose it so

package/src/pipeline/dispatch-shared.ts

@@ -4,6 +4,7 @@ import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
 import { createTenantDb } from "../db/tenant-db";
+import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
 import type {
@@ -209,6 +210,14 @@ export async function buildHandlerContext(
   // to a statically-injected context.files (tests).
   const fileResolver = context._fileProviderResolver;
   const files = fileResolver ? createFileContext(() => fileResolver(user.tenantId)) : context.files;
+  // ctx.derivatives builds on ctx.files (needs a FileContext to read the
+  // original + write the variant) plus db (to look up the FileRef row) — so
+  // it can only be constructed exactly when files+db both resolved; falls
+  // back to a statically-injected context.derivatives otherwise (tests).
+  const derivatives =
+    files && db
+      ? createDerivativesContext({ files, registry, db, tenantId: user.tenantId })
+      : context.derivatives;
 
   // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
   // resolves to kumiko_<feature>_foo. Unknown feature falls back to noop
@@ -565,6 +574,7 @@ export async function buildHandlerContext(
     notify,
     ...(config && { config }),
     ...(files && { files }),
+    ...(derivatives && { derivatives }),
     // preSave hooks need `changes`/`previous`/`isNew`, which only exist once
     // a handler actually starts building its write — bound here so entity
     // CRUD handlers (entity-handlers.ts) can forward it to the executor

package/src/pipeline/multi-stream-apply-context.ts

@@ -1,3 +1,4 @@
+import type { DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
 import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
 import type { DbRunner } from "../db/connection";
 import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
@@ -29,6 +30,8 @@ export type MultiStreamApplyContextDeps = {
   // Same FileContext the outer AppContext carries, passed through so
   // MSP applies can reach binaries without another wiring indirection.
   readonly files?: FileContext;
+  // Same DerivativesContext the outer AppContext carries — mirrors `files`.
+  readonly derivatives?: DerivativesContext;
 };
 
 export function createMultiStreamApplyContext(
@@ -36,6 +39,7 @@ export function createMultiStreamApplyContext(
 ): MultiStreamApplyContext {
   return {
     ...(deps.files ? { files: deps.files } : {}),
+    ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
     appendEvent: (async (args: AppendEventArgs) => {
       await appendDomainEventCore(
         {