@cosmicdrift/kumiko-framework 0.285.2 → 0.287.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.285.2",
+  "version": "0.287.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.285.2",
-    "@cosmicdrift/kumiko-types": "0.285.2",
+    "@cosmicdrift/kumiko-http": "0.287.0",
+    "@cosmicdrift/kumiko-types": "0.287.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.285.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.287.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/index.ts

@@ -44,7 +44,10 @@ export { patAllows, qnMatches } from "./pat-scope";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
 export { type RequestContextData, requestContext } from "./request-context";
-export { requestIdMiddleware } from "./request-id-middleware";
+export {
+  buildRequestContextDataFromRequest,
+  requestIdMiddleware,
+} from "./request-id-middleware";
 export { createApiRoutes } from "./routes";
 export type { KumikoServer, ServerOptions } from "./server";
 export { buildServer } from "./server";

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

@@ -16,43 +16,47 @@ function sanitizeClientId(value: string | undefined): string | undefined {
   return value !== undefined && SAFE_ID_RE.test(value) ? value : undefined;
 }
 
+// Request.headers.get() returns `string | null` (Fetch API); Hono's
+// c.req.header() normalizes that to `string | undefined`. Match Hono's
+// contract here so both builders return the exact same RequestContextData
+// shape regardless of which one a call-site uses.
+function header(req: Request, name: string): string | undefined {
+  return req.headers.get(name) ?? undefined;
+}
+
 /**
- * Builds the RequestContextData record for a Hono request — requestId
+ * Builds the RequestContextData record for a raw Fetch Request — requestId
  * (client-supplied + sanitized, or generated), correlationId (mirrors
  * requestId unless the client set its own), the underlying abort signal,
- * and the client IP/User-Agent. Extracted out of `requestIdMiddleware` so
- * call-sites that invoke a handler outside that middleware's `next()`
- * chain (e.g. server.ts's httpRoute→systemQuery mount) can still populate
- * the same AsyncLocalStorage record via `requestContext.run(...)`.
+ * and the client IP/User-Agent. Extracted out of `buildRequestContextData`
+ * so call-sites that only have a `Request` (no Hono `Context`) — e.g.
+ * server-runtime's static-fallback page-head resolver, which runs outside
+ * Hono's router entirely — can still populate the same AsyncLocalStorage
+ * record via `requestContext.run(...)`.
  */
-export function buildRequestContextData(c: Context): RequestContextData {
-  const requestId =
-    sanitizeClientId(c.req.header(REQUEST_ID_HEADER)) ?? requestContext.generateId();
-  const correlationId = sanitizeClientId(c.req.header(CORRELATION_ID_HEADER)) ?? requestId;
+export function buildRequestContextDataFromRequest(req: Request): RequestContextData {
+  const requestId = sanitizeClientId(header(req, REQUEST_ID_HEADER)) ?? requestContext.generateId();
+  const correlationId = sanitizeClientId(header(req, CORRELATION_ID_HEADER)) ?? requestId;
 
-  // Hono exposes the underlying Fetch Request — its `signal` aborts
-  // when the client disconnects (mobile back-press, tab close). We
-  // propagate it through requestContext so framework internals can
-  // honour cancellation at long-running checkpoints. Older Hono /
-  // adapter combos may not populate `c.req.raw.signal`; conditional
-  // spread keeps `signal: undefined` out of the stored record so
-  // downstream `signal?` checks behave as if no signal exists.
-  const signal = c.req.raw?.signal;
+  // The Fetch Request's `signal` aborts when the client disconnects (mobile
+  // back-press, tab close). We propagate it through requestContext so
+  // framework internals can honour cancellation at long-running checkpoints.
+  const signal = req.signal;
   // Client IP for per-IP rate limiting. Trust `x-forwarded-for` when
   // present (proxy/CDN) — first hop is the originating client. Adapter-
   // specific socket-address fallback (bun, node) is not standardized
   // in Hono; deployments behind a proxy should always set xff. Without
   // either we leave `ip` undefined and skip ip-bucketed checks rather
   // than fabricate one.
-  const xff = c.req.header("x-forwarded-for");
+  const xff = header(req, "x-forwarded-for");
   const ip = xff?.split(",")[0]?.trim();
-  const userAgent = c.req.header("user-agent");
+  const userAgent = header(req, "user-agent");
   // Runs before auth-middleware, so this reaches public routes too (e.g.
   // signup-request) — that's the whole point: the active UI locale must
   // survive to anonymous callers, not just authenticated ones.
   const locale = resolveHeaderLocale({
-    headerLocale: c.req.header(LOCALE_HEADER_NAME),
-    acceptLanguage: c.req.header("accept-language"),
+    headerLocale: header(req, LOCALE_HEADER_NAME),
+    acceptLanguage: header(req, "accept-language"),
   });
 
   return {
@@ -65,6 +69,23 @@ export function buildRequestContextData(c: Context): RequestContextData {
   };
 }
 
+/**
+ * Builds the RequestContextData record for a Hono request. Thin wrapper
+ * around `buildRequestContextDataFromRequest(c.req.raw)` — kept as its own
+ * export because most call-sites (server.ts's httpRoute→systemQuery mount,
+ * `requestIdMiddleware` below) already hold a Hono `Context`.
+ */
+export function buildRequestContextData(c: Context): RequestContextData {
+  // Older Hono / adapter combos may leave c.req.raw unset even though it's
+  // typed as Request — degrade to a bare id pair (no signal/ip/ua/locale)
+  // instead of letting req.headers.get() throw on every request.
+  if (!c.req.raw) {
+    const requestId = requestContext.generateId();
+    return { requestId, correlationId: requestId };
+  }
+  return buildRequestContextDataFromRequest(c.req.raw);
+}
+
 /**
  * Assigns a requestId + correlationId to every request and wraps execution
  * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "boot-time reachability warning for nav entries outside the app's sidebar allowlist, filter helper moved into the framework",
+    "detail": "Adds `warnOnUnreachableNavScreens(allNavQns, allowedNavQns, navAllowlistExempt?)`\nto packages/framework/src/engine/boot-validator/nav.ts, in the same\nnon-fatal console.warn style as the existing warnOnNavAccessInversion.\nThe rule checks screen reachability, not nav-QN membership: it builds\nthe set of screens reached by an allowlisted nav, then warns for every\nunallowlisted nav whose screen isn't in that set. A naive \"nav QN not\nin allowlist\" rule was tried first and measured against the real\nofflot-app schema (58 navs, 30 allowlisted) — it fired 28 warnings per\nboot, mostly app-shell leaves that intentionally re-target a screen an\nallowlisted nav already reaches, which would have buried the one real\nbug (offlot's VIN screen) in noise. The reachability rule fires 8 times\non the same schema, all of them either the real bug or exemptable.\nValidateBootOptions gains `navAllowlist?: ReadonlySet<string>` and\n`navAllowlistExempt?: ReadonlySet<string>`; when navAllowlist is set,\nvalidateBoot calls the new warning right after warnOnNavAccessInversion,\npassing navAllowlistExempt through so an app can mark navs whose screen\nis reachable outside the sidebar (e.g. as a sub-page of a generated\nsettings hub) without regenerating the noise.\nSeparately, `filterAppSchemaNavsByAllowlist` and `NavReparentOverride`\nmove from offlot-app's local copy into\npackages/renderer-web/src/layout/filter-app-schema-navs.ts and are now\nexported from @cosmicdrift/kumiko-renderer-web, reusing nav-tree.tsx's\nexisting (now exported) qualifyNavId instead of keeping a second copy\nof that qualification logic in sync across apps.\nfw#3019 covered offlot's app-local allowlist but not solon#113, which\nassigns navs to workspaces via `r.workspace({ nav: [...] })` and never\npasses navAllowlist — the warning stayed silent for that shape.\npackages/framework/src/engine/boot-validator/workspaces.ts gains\n`deriveNavAllowlistFromWorkspaces(allNavQns, allWorkspaceQns)`, which\nunions every `WorkspaceDefinition.nav` entry with every nav QN whose\n`NavDefinition.workspaces` self-assigns to at least one workspace — both\nfields already hold fully-qualified QNs (same as validateWorkspaces /\nvalidateNavs compare them), so no re-qualification step is needed.\n`resolveNavAllowlist(explicitAllowlist, allNavQns, allWorkspaceQns)`\nwraps it: an explicit `navAllowlist` always wins, otherwise the derived\nset is used only when the app has at least one workspace (an app with\nnone must produce no warnings), else `undefined` (no check runs).\nvalidateBoot now calls `resolveNavAllowlist` before\nwarnOnUnreachableNavScreens instead of gating on `options.navAllowlist`\ndirectly."
+  },
   {
     "version": "0.285.0",
     "type": "improvement",

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

@@ -1,10 +1,17 @@
 import { describe, expect, test } from "bun:test";
-import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type {
+  DerivativeRendererPlugin,
+  VariantSpec,
+} 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";
+import {
+  createDerivativesContext,
+  type OverlayResolverPlugin,
+  resolveRenderer,
+} from "../derivatives-context";
 
 const FILE_REF_ID = "11111111-1111-4111-8111-111111111111";
 const TENANT_ID = "22222222-2222-4222-8222-222222222222";
@@ -39,9 +46,19 @@ function countingRenderer(): {
 // 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 {
+function fakeDbWithFileRef(row: {
+  storageKey: string;
+  mimeType: string;
+  entityType?: string | null;
+  entityId?: string | null;
+  fieldName?: string | null;
+}): unknown {
   const canned: Record<string, unknown> = {
-    ...row,
+    storageKey: row.storageKey,
+    mimeType: row.mimeType,
+    entityType: row.entityType ?? null,
+    entityId: row.entityId ?? null,
+    fieldName: row.fieldName ?? null,
     id: FILE_REF_ID,
     tenantId: TENANT_ID,
     isDeleted: false,
@@ -214,3 +231,139 @@ describe("createDerivativesContext — variant()", () => {
     expect(result.mimeType).toBe("image/jpeg");
   });
 });
+
+describe("createDerivativesContext — variant() overlay token resolution", () => {
+  const QR_LAYER = {
+    kind: "qr",
+    dataToken: "public-url",
+    widthPct: 0.2,
+    gravity: "center",
+  } as const;
+
+  function specForwardingRenderer(): {
+    plugin: DerivativeRendererPlugin;
+    specs: () => VariantSpec[];
+  } {
+    const specs: VariantSpec[] = [];
+    const plugin: DerivativeRendererPlugin = {
+      render: async (_input, spec) => {
+        specs.push(spec);
+        return new Uint8Array([1]);
+      },
+    };
+    return { plugin, specs: () => specs };
+  }
+
+  async function setupWithOverlayResolver(resolve: OverlayResolverPlugin["resolve"]) {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), "image/jpeg");
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin: renderPlugin, specs } = specForwardingRenderer();
+    const registry = fakeRegistry([
+      { entityName: "image/*", options: renderPlugin },
+      { entityName: "vehicle", options: { resolve } },
+    ]);
+    const db = fakeDbWithFileRef({
+      storageKey: "tenant/photo.jpg",
+      mimeType: "image/jpeg",
+      entityType: "vehicle",
+      entityId: "vehicle-1",
+      fieldName: "publicImage",
+    });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+    return { ctx, specs };
+  }
+
+  test("a registered resolver's value lands in resolvedOverlays, never in overlays, before the renderer sees it", async () => {
+    const { ctx, specs } = await setupWithOverlayResolver(async (args) => {
+      expect(args).toEqual({
+        entityId: "vehicle-1",
+        tenantId: TENANT_ID,
+        fieldName: "publicImage",
+        dataToken: "public-url",
+      });
+      return "https://example.com/v/vehicle-1";
+    });
+
+    await ctx.variant(FILE_REF_ID, { overlays: [QR_LAYER] }, "card");
+
+    expect(specs()).toHaveLength(1);
+    expect(specs()[0]?.overlays).toBeUndefined();
+    expect(specs()[0]?.resolvedOverlays).toEqual([
+      { kind: "qr", data: "https://example.com/v/vehicle-1", widthPct: 0.2, gravity: "center" },
+    ]);
+  });
+
+  test("no resolver registered for the entityType throws InternalError instead of rendering without the QR", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), "image/jpeg");
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin: renderPlugin } = specForwardingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: renderPlugin }]);
+    const db = fakeDbWithFileRef({
+      storageKey: "tenant/photo.jpg",
+      mimeType: "image/jpeg",
+      entityType: "vehicle",
+      entityId: "vehicle-1",
+      fieldName: "publicImage",
+    });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+
+    const err = await ctx.variant(FILE_REF_ID, { overlays: [QR_LAYER] }, "card").catch((e) => e);
+    expect(err).toBeInstanceOf(InternalError);
+    expect((err as InternalError).httpStatus).toBe(500);
+  });
+
+  test("a resolver returning an empty string throws instead of silently dropping the QR", async () => {
+    const { ctx } = await setupWithOverlayResolver(async () => "");
+
+    const err = await ctx.variant(FILE_REF_ID, { overlays: [QR_LAYER] }, "card").catch((e) => e);
+    expect(err).toBeInstanceOf(InternalError);
+  });
+
+  test("a qr overlay on a FileRef missing entityType/entityId/fieldName throws instead of skipping resolution", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), "image/jpeg");
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin: renderPlugin } = specForwardingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: renderPlugin }]);
+    const db = fakeDbWithFileRef({ storageKey: "tenant/photo.jpg", mimeType: "image/jpeg" });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+
+    const err = await ctx.variant(FILE_REF_ID, { overlays: [QR_LAYER] }, "card").catch((e) => e);
+    expect(err).toBeInstanceOf(InternalError);
+  });
+
+  test("an image-only overlay list resolves without any entityType/entityId/fieldName", async () => {
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), "image/jpeg");
+    const files = createFileContext(() => Promise.resolve(provider));
+    const { plugin: renderPlugin, specs } = specForwardingRenderer();
+    const registry = fakeRegistry([{ entityName: "image/*", options: renderPlugin }]);
+    const db = fakeDbWithFileRef({ storageKey: "tenant/photo.jpg", mimeType: "image/jpeg" });
+    const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
+    const imageLayer = {
+      kind: "image",
+      imageBase64: "aGVsbG8=",
+      widthPct: 0.3,
+      gravity: "south-east",
+    } as const;
+
+    await ctx.variant(FILE_REF_ID, { overlays: [imageLayer] }, "card");
+
+    expect(specs()[0]?.resolvedOverlays).toEqual([imageLayer]);
+  });
+
+  test("overlays change the variant suffix without touching the source storage key", async () => {
+    const { ctx } = await setupWithOverlayResolver(async () => "https://example.com/v/vehicle-1");
+    const provider = createInMemoryFileProvider();
+    await provider.write("tenant/photo.jpg", new Uint8Array([1, 2, 3]), "image/jpeg");
+
+    const withOverlay = await ctx.variant(FILE_REF_ID, { overlays: [QR_LAYER] }, "card");
+    const withoutOverlay = await ctx.variant(FILE_REF_ID, {}, "card");
+
+    expect(withOverlay.storageKey).not.toBe(withoutOverlay.storageKey);
+    expect(withOverlay.storageKey.startsWith("tenant/photo.card-")).toBe(true);
+    expect(withoutOverlay.storageKey.startsWith("tenant/photo.card-")).toBe(true);
+  });
+});

package/src/derivatives/derivatives-context.ts

@@ -1,10 +1,15 @@
 import type {
   DerivativeRendererPlugin,
   DerivativesContext,
+  OverlayLayer,
+  ResolvedOverlayLayer,
   VariantSpec,
 } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { type AnyDb, fetchOne } from "../bun-db/query";
-import { EXT_DERIVATIVE_RENDERER } from "../engine/extension-names";
+import {
+  EXT_DERIVATIVE_OVERLAY_RESOLVER,
+  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";
@@ -60,13 +65,145 @@ export function resolveRenderer(
   return undefined;
 }
 
+export type OverlayResolverArgs = {
+  readonly entityId: string;
+  readonly tenantId: TenantId;
+  readonly fieldName: string;
+  readonly dataToken: string;
+};
+
+export type OverlayResolverPlugin = {
+  readonly resolve: (args: OverlayResolverArgs) => string | Promise<string>;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind, same pattern as isDerivativeRendererPlugin.
+function isOverlayResolverPlugin(o: unknown): o is OverlayResolverPlugin {
+  return typeof o === "object" && o !== null && "resolve" in o && typeof o.resolve === "function";
+}
+
 type FileRefRow = {
   readonly storageKey: string;
   readonly mimeType: string;
+  readonly entityType: string | null;
+  readonly entityId: string | null;
+  readonly fieldName: string | null;
 };
 
 function isFileRefRow(row: Record<string, unknown>): row is FileRefRow {
-  return typeof row["storageKey"] === "string" && typeof row["mimeType"] === "string";
+  return (
+    typeof row["storageKey"] === "string" &&
+    typeof row["mimeType"] === "string" &&
+    (row["entityType"] === null || typeof row["entityType"] === "string") &&
+    (row["entityId"] === null || typeof row["entityId"] === "string") &&
+    (row["fieldName"] === null || typeof row["fieldName"] === "string")
+  );
+}
+
+// A qr overlay needs the FileRef's field identity to pick a resolver and to
+// hand the resolver something to look up — narrows the 3 nullable columns
+// together so the throw below can name whichever one is actually missing.
+type FieldIdentifiedFileRef = FileRefRow & {
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly fieldName: string;
+};
+
+function hasFieldIdentity(row: FileRefRow): row is FieldIdentifiedFileRef {
+  return row.entityType !== null && row.entityId !== null && row.fieldName !== null;
+}
+
+type QrOverlayContext = {
+  readonly row: FieldIdentifiedFileRef;
+  readonly plugin: OverlayResolverPlugin;
+};
+
+// Looks up the entityType's resolver once per variant() call (not once per
+// qr layer) and fails before any layer is touched — a spec with 3 qr layers
+// and no registration throws once, not on the first layer only.
+function resolveQrOverlayContext(row: FileRefRow, registry: Registry): QrOverlayContext {
+  if (!hasFieldIdentity(row)) {
+    throw new InternalError({
+      message:
+        "derivatives.variant: a qr overlay requires the FileRef's entityType/entityId/fieldName, but at least one is missing.",
+      details: { entityType: row.entityType, entityId: row.entityId, fieldName: row.fieldName },
+    });
+  }
+  const usage = registry
+    .getExtensionUsages(EXT_DERIVATIVE_OVERLAY_RESOLVER)
+    .find((u) => u.entityName === row.entityType);
+  if (!usage) {
+    throw new InternalError({
+      message: `derivatives.variant: no ${EXT_DERIVATIVE_OVERLAY_RESOLVER} registered for entityType "${row.entityType}".`,
+      details: { entityType: row.entityType },
+    });
+  }
+  if (!isOverlayResolverPlugin(usage.options)) {
+    throw new Error(
+      `derivatives.variant: "${usage.entityName}" registered ${EXT_DERIVATIVE_OVERLAY_RESOLVER} without a resolve(args) — extension options must be an OverlayResolverPlugin.`,
+    );
+  }
+  return { row, plugin: usage.options };
+}
+
+async function resolveQrLayer(
+  layer: Extract<OverlayLayer, { kind: "qr" }>,
+  context: QrOverlayContext,
+  tenantId: TenantId,
+): Promise<ResolvedOverlayLayer> {
+  const { dataToken, ...placement } = layer;
+  const data = await context.plugin.resolve({
+    entityId: context.row.entityId,
+    tenantId,
+    fieldName: context.row.fieldName,
+    dataToken,
+  });
+  if (!data) {
+    throw new InternalError({
+      message: `derivatives.variant: ${EXT_DERIVATIVE_OVERLAY_RESOLVER} resolved dataToken "${dataToken}" to an empty value for entityType "${context.row.entityType}".`,
+      details: { entityType: context.row.entityType, dataToken },
+    });
+  }
+  return { ...placement, data };
+}
+
+// A non-qr layer is already ResolvedOverlayLayer-shaped (see
+// ResolvedOverlayLayer's `image` member) — this only exists because TS can't
+// derive that from `layer.kind !== "qr"` across a Promise.all/map boundary.
+function resolveOverlayLayer(
+  layer: OverlayLayer,
+  qrContext: QrOverlayContext | undefined,
+  tenantId: TenantId,
+): Promise<ResolvedOverlayLayer> | ResolvedOverlayLayer {
+  if (layer.kind !== "qr") return layer;
+  if (!qrContext) {
+    throw new Error(
+      "derivatives.variant: unreachable — resolveOverlaySpec only omits a qr context when the spec has no qr layer.",
+    );
+  }
+  return resolveQrLayer(layer, qrContext, tenantId);
+}
+
+// Resolves every `qr` layer's dataToken to a concrete value and moves the
+// whole overlay list to `resolvedOverlays` — BEFORE variantSuffix() hashes
+// the spec, so a resolver whose target changes (e.g. a base-URL rotation)
+// invalidates the cache instead of serving a stale target under the old key.
+async function resolveOverlaySpec(
+  spec: VariantSpec,
+  row: FileRefRow,
+  registry: Registry,
+  tenantId: TenantId,
+): Promise<VariantSpec> {
+  if (!spec.overlays || spec.overlays.length === 0) return spec;
+
+  const qrContext = spec.overlays.some((layer) => layer.kind === "qr")
+    ? resolveQrOverlayContext(row, registry)
+    : undefined;
+
+  const resolvedOverlays = await Promise.all(
+    spec.overlays.map((layer) => resolveOverlayLayer(layer, qrContext, tenantId)),
+  );
+  return { ...spec, overlays: undefined, resolvedOverlays };
 }
 
 // sourceMimeType is client-controlled (it's `file.type` off the upload — see
@@ -144,16 +281,20 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
         });
       }
 
+      // Resolves qr dataTokens to concrete values BEFORE the spec is hashed
+      // — see resolveOverlaySpec.
+      const resolvedSpec = await resolveOverlaySpec(spec, row, deps.registry, deps.tenantId);
+
       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));
+      const target = src.derive(variantSuffix(name, resolvedSpec));
       // 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);
+      const mimeType = outputMimeType(resolvedSpec, row.mimeType);
 
       // ponytail: exists→render→write is a TOCTOU window under concurrent
       // requests for the same variant (duplicate render + write). Ceiling:
@@ -168,7 +309,7 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
       }
 
       const original = await src.read();
-      const result = await renderer.render(original, spec, row.mimeType);
+      const result = await renderer.render(original, resolvedSpec, row.mimeType);
       await target.write(result, mimeType);
       return {
         storageKey: target.key,

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

@@ -0,0 +1,290 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import type { NavDefinition, WorkspaceDefinition } from "../../types";
+import { warnOnUnreachableNavScreens } from "../nav";
+import { deriveNavAllowlistFromWorkspaces, resolveNavAllowlist } from "../workspaces";
+
+function navMap(
+  entries: ReadonlyArray<[string, NavDefinition & { readonly featureName: string }]>,
+): Map<string, NavDefinition & { readonly featureName: string }> {
+  return new Map(entries);
+}
+
+function workspaceMap(
+  entries: ReadonlyArray<[string, WorkspaceDefinition & { readonly featureName: string }]>,
+): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
+  return new Map(entries);
+}
+
+describe("warnOnUnreachableNavScreens", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("does not warn for an unallowlisted nav whose screen is reached by an allowlisted nav", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        {
+          id: "a",
+          label: "A",
+          screen: "vehicles:screen:vin",
+          featureName: "vehicles",
+        },
+      ],
+      [
+        "vehicles:nav:b",
+        {
+          id: "b",
+          label: "B",
+          screen: "vehicles:screen:vin",
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+
+    warnOnUnreachableNavScreens(allNavQns, new Set(["vehicles:nav:a"]));
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("warns only for the unallowlisted nav whose screen nobody else reaches", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        {
+          id: "a",
+          label: "A",
+          screen: "vehicles:screen:vin",
+          featureName: "vehicles",
+        },
+      ],
+      [
+        "vehicles:nav:b",
+        {
+          id: "b",
+          label: "B",
+          screen: "vehicles:screen:vin",
+          featureName: "vehicles",
+        },
+      ],
+      [
+        "vehicles:nav:c",
+        {
+          id: "c",
+          label: "C",
+          screen: "vehicles:screen:title",
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+
+    warnOnUnreachableNavScreens(allNavQns, new Set(["vehicles:nav:a"]));
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("vehicles:nav:c");
+    expect(msg).toContain("vehicles");
+    expect(msg).toContain("vehicles:screen:title");
+  });
+
+  test("navAllowlistExempt suppresses the warning for an exempted nav", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        {
+          id: "a",
+          label: "A",
+          screen: "vehicles:screen:vin",
+          featureName: "vehicles",
+        },
+      ],
+      [
+        "vehicles:nav:c",
+        {
+          id: "c",
+          label: "C",
+          screen: "vehicles:screen:title",
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+
+    warnOnUnreachableNavScreens(
+      allNavQns,
+      new Set(["vehicles:nav:a"]),
+      new Set(["vehicles:nav:c"]),
+    );
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("never warns for a nav without a screen (pure grouping entry)", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:group",
+        {
+          id: "group",
+          label: "Group",
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+
+    warnOnUnreachableNavScreens(allNavQns, new Set());
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("resolveNavAllowlist (fw#3019 solon#113: workspace-derived allowlist)", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("does not warn for a nav listed in a workspace's nav array", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([
+      [
+        "vehicles:workspace:main",
+        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
+      ],
+    ]);
+
+    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
+    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("does not warn for a nav that self-assigns via workspaces", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        {
+          id: "a",
+          label: "A",
+          screen: "vehicles:screen:vin",
+          workspaces: ["vehicles:workspace:main"],
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([
+      ["vehicles:workspace:main", { id: "main", label: "Main", featureName: "vehicles" }],
+    ]);
+
+    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
+    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("warns for a nav in no workspace whose screen nobody else reaches (solon#113)", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
+      ],
+      [
+        "vehicles:nav:orphan",
+        { id: "orphan", label: "Orphan", screen: "vehicles:screen:title", featureName: "vehicles" },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([
+      [
+        "vehicles:workspace:main",
+        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
+      ],
+    ]);
+
+    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
+    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]![0] as string).toContain("vehicles:nav:orphan");
+  });
+
+  test("does not warn when the app has no workspaces at all", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([]);
+
+    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
+
+    expect(allowlist).toBeUndefined();
+  });
+
+  test("an explicit navAllowlist wins over the workspace-derived one", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([
+      [
+        "vehicles:workspace:main",
+        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
+      ],
+    ]);
+
+    const allowlist = resolveNavAllowlist(new Set(), allNavQns, allWorkspaceQns);
+    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
+
+    expect(allowlist).toEqual(new Set());
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]![0] as string).toContain("vehicles:nav:a");
+  });
+});
+
+describe("deriveNavAllowlistFromWorkspaces", () => {
+  test("unions workspace.nav entries and self-assigning nav.workspaces entries", () => {
+    const allNavQns = navMap([
+      [
+        "vehicles:nav:a",
+        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
+      ],
+      [
+        "vehicles:nav:b",
+        {
+          id: "b",
+          label: "B",
+          screen: "vehicles:screen:title",
+          workspaces: ["vehicles:workspace:main"],
+          featureName: "vehicles",
+        },
+      ],
+    ]);
+    const allWorkspaceQns = workspaceMap([
+      [
+        "vehicles:workspace:main",
+        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
+      ],
+    ]);
+
+    const allowlist = deriveNavAllowlistFromWorkspaces(allNavQns, allWorkspaceQns);
+
+    expect(allowlist).toEqual(new Set(["vehicles:nav:a", "vehicles:nav:b"]));
+  });
+});

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

@@ -46,6 +46,7 @@ import {
   validateNavCycles,
   validateNavs,
   warnOnNavAccessInversion,
+  warnOnUnreachableNavScreens,
 } from "./nav";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validateParentRefs } from "./parent-ref";
@@ -66,6 +67,7 @@ import {
 import { warnOnMissingSecurityBaseline } from "./security-baseline";
 import {
   collectWorkspaceQns,
+  resolveNavAllowlist,
   validateDefaultWorkspaceUniqueness,
   validateWorkspaces,
 } from "./workspaces";
@@ -85,6 +87,17 @@ export type ValidateBootOptions = {
    *  prod warning that nobody can silence per-role isn't worth the noise
    *  it generates on every boot. */
   readonly warnOnUniqueAccessRoles?: boolean;
+  /** QNs the app's sidebar allowlist admits. When set, every declared nav
+   *  whose screen isn't reachable from any allowlisted nav entry gets a
+   *  boot-time warning — that screen would otherwise be silently
+   *  unreachable via the sidebar (fw#3019). When omitted and the app has
+   *  workspaces, the allowlist is derived from `r.workspace({ nav })` and
+   *  `r.nav({ workspaces })` assignments instead. */
+  readonly navAllowlist?: ReadonlySet<string>;
+  /** Nav QNs deliberately left out of the sidebar allowlist because their
+   *  screen is reachable another way (e.g. as a sub-page of a generated
+   *  settings hub). Suppresses the navAllowlist warning for these QNs. */
+  readonly navAllowlistExempt?: ReadonlySet<string>;
 };
 
 /**
@@ -226,6 +239,14 @@ export function validateBoot(
 
   validateNavCycles(allNavQns);
   warnOnNavAccessInversion(allNavQns);
+  const effectiveNavAllowlist = resolveNavAllowlist(
+    options?.navAllowlist,
+    allNavQns,
+    allWorkspaceQns,
+  );
+  if (effectiveNavAllowlist !== undefined) {
+    warnOnUnreachableNavScreens(allNavQns, effectiveNavAllowlist, options?.navAllowlistExempt);
+  }
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);

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

@@ -171,6 +171,50 @@ export function warnOnNavAccessInversion(
   }
 }
 
+// `NavDefinition.screen` is authored already-qualified ("<feature>:screen:
+// <id>", see packages/types/src/nav.ts) — this only guards a short id
+// slipping through, since a wrong qualification here would make every nav
+// look orphaned (28 false positives on the real offlot-app schema instead
+// of the intended 8, see fw#3019 measurement).
+function qualifyNavScreenQn(featureName: string, screen: string): string {
+  return screen.includes(":screen:") ? screen : `${featureName}:screen:${screen}`;
+}
+
+// fw#3019: warn (never throw — a screen deliberately left out of the app's
+// sidebar is legitimate) when a declared nav's screen isn't reachable from
+// any allowlisted nav entry. Checking "nav QN not in allowlist" directly
+// warned 28x on the real offlot-app schema (58 navs, 30 allowed) — most of
+// them app-shell leaves that intentionally re-target a screen another,
+// allowlisted nav already reaches. Reachability warns only for a screen no
+// allowlisted nav points at, which is the actual "unreachable via sidebar"
+// bug (solon#113, offlot's VIN screen in pilot).
+export function warnOnUnreachableNavScreens(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+  allowedNavQns: ReadonlySet<string>,
+  navAllowlistExempt: ReadonlySet<string> = new Set(),
+): void {
+  const reachableScreenQns = new Set<string>();
+  for (const [qn, navDef] of allNavQns) {
+    if (!allowedNavQns.has(qn) || navDef.screen === undefined) continue;
+    reachableScreenQns.add(qualifyNavScreenQn(navDef.featureName, navDef.screen));
+  }
+
+  for (const [qn, navDef] of allNavQns) {
+    if (allowedNavQns.has(qn) || navDef.screen === undefined || navAllowlistExempt.has(qn)) {
+      continue;
+    }
+    const screenQn = qualifyNavScreenQn(navDef.featureName, navDef.screen);
+    if (reachableScreenQns.has(screenQn)) continue;
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      `[kumiko:boot] Nav entry "${qn}" declared by feature "${navDef.featureName}" points at ` +
+        `screen "${screenQn}", which no allowlisted nav entry reaches — it is unreachable via ` +
+        `the sidebar. If this is intentional (e.g. reachable through a generated hub), add ` +
+        `"${qn}" to navAllowlistExempt; otherwise add it to the allowlist.`,
+    );
+  }
+}
+
 // Roles we recognise at boot time. The framework has no explicit
 // role-registry (r.defineRoles is a type helper only), so we synthesise
 // one from every handler-access rule plus the "all"/"system" built-ins.

package/src/engine/boot-validator/pii-retention.ts

@@ -56,11 +56,11 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
     const fieldsByName = entity.fields;
 
     for (const [fieldName, field] of Object.entries(fieldsByName)) {
-      // ResolvedPiiFlags-Properties sind type-level optional. Auf Field-
-      // Defs die nicht via "& ResolvedPiiFlags" erweitert sind (Boolean,
-      // Money, Reference, Embedded, Tz, LocatedTimestamp, File*, Image*)
-      // liefert property-access undefined zur Runtime. Die TS-Compile-
-      // Time-Validation hat dort schon abgelehnt → Cast ist safe.
+      // ResolvedPiiFlags properties are type-level optional. On field defs
+      // not extended via "& ResolvedPiiFlags" (Boolean, Money, Reference,
+      // Embedded), property access returns undefined at runtime. TS
+      // compile-time validation already rejected that case elsewhere →
+      // the cast is safe.
       const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk
 
       const hasPii = Boolean(annot.pii);
@@ -195,7 +195,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         } else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) && !annot.subjectRef) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) — without the hook the V3 boot guard throws. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,
           );
         }
       }

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

@@ -48,6 +48,44 @@ const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
   SETTINGS_HUB_AUDIENCE_NAV_QNS,
 );
 
+// fw#3019: apps that assign navs to workspaces via `r.workspace({ nav })`
+// or `r.nav({ workspaces })` never pass an explicit navAllowlist (solon#113)
+// — without this, warnOnUnreachableNavScreens never runs for them. Both
+// `WorkspaceDefinition.nav` and `NavDefinition.workspaces` already hold
+// fully-qualified QNs (validateWorkspaces/validateNavs compare them
+// directly against allNavQns/allWorkspaceQns), so no re-qualification is
+// needed here.
+export function deriveNavAllowlistFromWorkspaces(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): ReadonlySet<string> {
+  const allowlist = new Set<string>();
+  for (const wsDef of allWorkspaceQns.values()) {
+    for (const navQn of wsDef.nav ?? []) {
+      allowlist.add(navQn);
+    }
+  }
+  for (const [navQn, navDef] of allNavQns) {
+    if (navDef.workspaces !== undefined && navDef.workspaces.length > 0) {
+      allowlist.add(navQn);
+    }
+  }
+  return allowlist;
+}
+
+// App-provided navAllowlist always wins (app knowledge beats derivation).
+// Falling back to derivation only when the app has workspaces at all avoids
+// flagging every nav as unreachable in a workspace-free app.
+export function resolveNavAllowlist(
+  explicitAllowlist: ReadonlySet<string> | undefined,
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): ReadonlySet<string> | undefined {
+  if (explicitAllowlist !== undefined) return explicitAllowlist;
+  if (allWorkspaceQns.size === 0) return undefined;
+  return deriveNavAllowlistFromWorkspaces(allNavQns, allWorkspaceQns);
+}
+
 // Single-default rule across the entire app. Mirrors how createApp validates
 // roles up front — a second `default: true` is a configuration error, not a
 // runtime fallback. Apps without any default fall back to "first workspace

package/src/engine/extension-names.ts

@@ -120,6 +120,23 @@ export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer" as const;
  */
 export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate" as const;
 
+/**
+ * `derivativeOverlayResolver` — per-entityType "resolve this overlay
+ * dataToken to its real value" contract for `file-derivatives`' overlay
+ * compositing (QR codes on a public variant).
+ *
+ * Apps register via `r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER,
+ * "<entityType>", { resolve: (args) => string | Promise<string> })`. Missing
+ * registration, or a resolve() returning an empty string, both throw —
+ * unlike `derivativePublicPredicate`, there is no default-deny answer here:
+ * an image silently rendered without its QR would look correct while being
+ * wrong.
+ *
+ * Registered/consumed by: `file-derivatives`'s `variant()`
+ * (derivatives-context.ts), before the variant's spec hash is computed.
+ */
+export const EXT_DERIVATIVE_OVERLAY_RESOLVER = "derivativeOverlayResolver" as const;
+
 /**
  * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
  * bei User-Forget oder Tenant-Destroy).

package/src/engine/factories.ts

@@ -419,22 +419,32 @@ export function createLocatedTimestampField<R extends true | false = false>(
   } as LocatedTimestampFieldDef & { required: R }; // @cast-boundary engine-payload
 }
 
-export function createFileField(overrides?: Partial<Omit<FileFieldDef, "type">>): FileFieldDef {
-  return { type: "file", ...overrides };
+export function createFileField(
+  overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
+): FileFieldDef {
+  return { type: "file", ...expandPersonalAnnotations(overrides) };
 }
 
-export function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type">>): ImageFieldDef {
-  return { type: "image", ...overrides };
+export function createImageField(
+  overrides?: Partial<Omit<ImageFieldDef, "type" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
+): ImageFieldDef {
+  return { type: "image", ...expandPersonalAnnotations(overrides) };
 }
 
-export function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type">>): FilesFieldDef {
-  return { type: "files", ...overrides };
+export function createFilesField(
+  overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
+): FilesFieldDef {
+  return { type: "files", ...expandPersonalAnnotations(overrides) };
 }
 
 export function createImagesField(
-  overrides?: Partial<Omit<ImagesFieldDef, "type">>,
+  overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> &
+    PersonalAnnotationsNoFind,
 ): ImagesFieldDef {
-  return { type: "images", ...overrides };
+  return { type: "images", ...expandPersonalAnnotations(overrides) };
 }
 
 // `F` läuft OHNE Constraint im Generic-Param damit TS die literal-types

package/src/engine/index.ts

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

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

@@ -731,6 +731,45 @@ describe("error handling", () => {
     expect(body.error).toContain("invalid_fieldName");
   });
 
+  // #3005: fileRefDeleteHook's GDPR-forget decision resolves entityType/
+  // fieldName against the registry — an attachment nobody can resolve must
+  // be rejected at upload, not silently accepted and left to the forget
+  // hook's conservative fallback.
+  test("upload with an entityType not registered in the registry is rejected", async () => {
+    const pngContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const res = await uploadFile(adminUser, "logo.png", pngContent, "image/png", {
+      entityType: "no-such-entity",
+      entityId: "1",
+      fieldName: "logo",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("unresolvable_field");
+  });
+
+  test("upload with a fieldName not declared on the resolved entity is rejected", async () => {
+    const pngContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const res = await uploadFile(adminUser, "logo.png", pngContent, "image/png", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "no-such-field",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("unresolvable_field");
+  });
+
+  test("upload with only entityType set (no fieldName) is rejected, not silently treated as unattached", async () => {
+    const pngContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const res = await uploadFile(adminUser, "logo.png", pngContent, "image/png", {
+      entityType: "tenant",
+      entityId: "1",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("unresolvable_field");
+  });
+
   test("upload without auth returns 401", async () => {
     const formData = new FormData();
     formData.append("file", new File([new Uint8Array(10)], "test.png", { type: "image/png" }));

package/src/files/file-routes.ts

@@ -14,6 +14,7 @@ import { createEventStoreExecutor } from "../db/event-store-executor";
 import { createTenantDb } from "../db/tenant-db";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer } from "../derivatives";
 import {
+  type FieldDefinition,
   isFileField,
   isUuid,
   type Registry,
@@ -100,6 +101,29 @@ function createDefaultGuard(privilegedRoles: readonly string[]): FileAccessGuard
   };
 }
 
+type AttachedFieldResolution =
+  | { readonly kind: "unattached" }
+  | { readonly kind: "resolved"; readonly fieldDef: FieldDefinition }
+  | { readonly kind: "unresolvable" };
+
+// entityType/fieldName drive the GDPR-forget decision downstream
+// (fileRefDeleteHook resolves the field's PII annotation from exactly this
+// pairing) — attaching to a field nobody can resolve would leave that
+// decision hanging on an unverified client string. Either both are omitted
+// (unattached upload, allowed) or both must resolve to a real registered
+// field.
+function resolveAttachedField(
+  registry: Registry | undefined,
+  entityType: string | undefined,
+  fieldName: string | undefined,
+): AttachedFieldResolution {
+  if (entityType === undefined && fieldName === undefined) return { kind: "unattached" };
+  const entity = entityType !== undefined ? registry?.getEntity(entityType) : undefined;
+  const fieldDef = entity && fieldName !== undefined ? entity.fields[fieldName] : undefined;
+  if (!entityType || !fieldName || !entity || !fieldDef) return { kind: "unresolvable" };
+  return { kind: "resolved", fieldDef };
+}
+
 export function createFileRoutes(options: FileRoutesOptions): Hono {
   const { db } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
@@ -171,15 +195,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     let maxSize = options.maxUploadSize ?? "10mb";
     let accept: readonly string[] | undefined;
 
-    if (options.registry && entityType && fieldName) {
-      const entity = options.registry.getEntity(entityType);
-      if (entity) {
-        const fieldDef = entity.fields[fieldName];
-        if (isFileField(fieldDef)) {
-          if (fieldDef.maxSize) maxSize = fieldDef.maxSize;
-          if (fieldDef.accept) accept = fieldDef.accept;
-        }
-      }
+    const attachedField = resolveAttachedField(options.registry, entityType, fieldName);
+    if (attachedField.kind === "unresolvable") {
+      return c.json(
+        {
+          error:
+            "unresolvable_field: entityType/fieldName must resolve to a registered entity field, or both must be omitted for an unattached upload",
+        },
+        400,
+      );
+    }
+    if (attachedField.kind === "resolved" && isFileField(attachedField.fieldDef)) {
+      if (attachedField.fieldDef.maxSize) maxSize = attachedField.fieldDef.maxSize;
+      if (attachedField.fieldDef.accept) accept = attachedField.fieldDef.accept;
     }
 
     const validationError = validateFile(

package/src/http/index.ts

@@ -1,2 +1,2 @@
 export type { EgressPolicy } from "@cosmicdrift/kumiko-http";
-export { egress } from "@cosmicdrift/kumiko-http";
+export { egress, isPublicHost } from "@cosmicdrift/kumiko-http";

package/src/observability/escape-hatch-report.ts

@@ -49,9 +49,11 @@ const fallbackReportWindow = createEscapeHatchReportWindow();
 const consoleLogger: Logger = {
   info() {},
   warn(msg, data) {
+    // biome-ignore lint/suspicious/noConsole: fallback for callers without a logger — dropping the call would lose the report silently.
     console.warn(msg, data);
   },
   error(msg, data) {
+    // biome-ignore lint/suspicious/noConsole: same fallback, see warn above.
     console.error(msg, data);
   },
   debug() {},