@cosmicdrift/kumiko-framework 0.197.1 → 0.199.0

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

@@ -99,23 +99,42 @@ describe("flattenMoney — Insert/Update Convert (major units → minor units)",
 });
 
 describe("rehydrateMoney — Read Convert (minor units → major units)", () => {
-  test("{ <name>: minorUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency, amountMinor } }", () => {
+  test("{ <name>: scaledUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency, amountScaled, amountMinor } }", () => {
     const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 450, currency: "EUR", amountMinor: 45000 } });
+    expect(out).toEqual({
+      buyingPrice: { amount: 450, currency: "EUR", amountScaled: 45000, amountMinor: 45000 },
+    });
+  });
+
+  test("amountMinor is a deprecated alias of amountScaled, same value", () => {
+    const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity)[
+      "buyingPrice"
+    ] as MoneyRead;
+    expect(out.amountMinor).toBe(out.amountScaled);
   });
 
   test("PG-BIGINT als String wird zu number gecastet", () => {
     // Postgres-driver liefert BIGINT manchmal als String (>2^53 sicher).
     const out = rehydrateMoney({ buyingPrice: "45000", buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
+    expect(out["buyingPrice"]).toEqual({
+      amount: 450,
+      currency: "EUR",
+      amountScaled: 45000,
+      amountMinor: 45000,
+    });
   });
 
   test("fehlende Currency-Spalte fällt auf entity.defaultCurrency", () => {
     const out = rehydrateMoney({ buyingPrice: 45000 }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
+    expect(out["buyingPrice"]).toEqual({
+      amount: 450,
+      currency: "EUR",
+      amountScaled: 45000,
+      amountMinor: 45000,
+    });
   });
 
-  test("amountMinor bleibt exakter Integer über mehrere Additionen (fw#1830)", () => {
+  test("amountScaled bleibt exakter Integer über mehrere Additionen (fw#1830)", () => {
     const rows = [10, 20, 30].map(
       (minor) =>
         rehydrateMoney({ buyingPrice: minor, buyingPriceCurrency: "EUR" }, orderEntity)[
@@ -124,7 +143,7 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
     );
     const [a, b, c] = rows;
 
-    expect(a!.amountMinor + b!.amountMinor).toBe(c!.amountMinor);
+    expect(a!.amountScaled + b!.amountScaled).toBe(c!.amountScaled);
   });
 
   test("null/undefined amount → Field wird aus Output entfernt", () => {
@@ -143,12 +162,12 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
       orderEntity,
     );
     expect(out).toEqual({
-      buyingPrice: { amount: 450, currency: "EUR", amountMinor: 45000 },
-      sellingPrice: { amount: 600, currency: "USD", amountMinor: 60000 },
+      buyingPrice: { amount: 450, currency: "EUR", amountScaled: 45000, amountMinor: 45000 },
+      sellingPrice: { amount: 600, currency: "USD", amountScaled: 60000, amountMinor: 60000 },
     });
   });
 
-  test("Round-Trip: flatten dann rehydrate ergibt dasselbe amount/currency, plus amountMinor", () => {
+  test("Round-Trip: flatten dann rehydrate ergibt dasselbe amount/currency, plus amountScaled", () => {
     const original = {
       buyingPrice: { amount: 450.5, currency: "EUR" },
       sellingPrice: { amount: 56799.16, currency: "USD" },
@@ -156,15 +175,25 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
     const flat = flattenMoney(original, orderEntity);
     const rehydrated = rehydrateMoney(flat, orderEntity);
     expect(rehydrated).toEqual({
-      buyingPrice: { amount: 450.5, currency: "EUR", amountMinor: 45050 },
-      sellingPrice: { amount: 56799.16, currency: "USD", amountMinor: 5679916 },
+      buyingPrice: { amount: 450.5, currency: "EUR", amountScaled: 45050, amountMinor: 45050 },
+      sellingPrice: {
+        amount: 56799.16,
+        currency: "USD",
+        amountScaled: 5679916,
+        amountMinor: 5679916,
+      },
     });
   });
 
-  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR, amountMinor:45000 }", () => {
+  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR, amountScaled:45000 }", () => {
     const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR", amountMinor: 45000 });
+    expect(out["buyingPrice"]).toEqual({
+      amount: 450,
+      currency: "EUR",
+      amountScaled: 45000,
+      amountMinor: 45000,
+    });
   });
 
   test("ist pure — input wird nicht mutiert", () => {
@@ -180,7 +209,7 @@ describe("rehydrateMoney — Read Convert (minor units → major units)", () =>
     ).toThrow(/not a safe integer — DB corruption/);
   });
 
-  test("fractional string amount (fw#1833) → loud throw statt amountMinor mit Nachkommastelle", () => {
+  test("fractional string amount (fw#1833) → loud throw statt amountScaled mit Nachkommastelle", () => {
     expect(() =>
       rehydrateMoney({ buyingPrice: "45000.7", buyingPriceCurrency: "EUR" }, orderEntity),
     ).toThrow(/not a safe integer — DB corruption/);
@@ -208,7 +237,9 @@ describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () =>
 
     // DB liefert dieselben Spalten zurück
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 990, currency: "USD", amountMinor: 99_000 } });
+    expect(out).toEqual({
+      buyingPrice: { amount: 990, currency: "USD", amountScaled: 99_000, amountMinor: 99_000 },
+    });
   });
 
   test("List-Pfad: mehrere Rows hintereinander rehydraten", () => {
@@ -219,9 +250,9 @@ describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () =>
     ];
     const apiRows = dbRows.map((r) => rehydrateMoney(r, orderEntity));
     expect(apiRows).toEqual([
-      { buyingPrice: { amount: 1, currency: "EUR", amountMinor: 100 } },
-      { buyingPrice: { amount: 2, currency: "USD", amountMinor: 200 } },
-      { buyingPrice: { amount: 3, currency: "GBP", amountMinor: 300 } },
+      { buyingPrice: { amount: 1, currency: "EUR", amountScaled: 100, amountMinor: 100 } },
+      { buyingPrice: { amount: 2, currency: "USD", amountScaled: 200, amountMinor: 200 } },
+      { buyingPrice: { amount: 3, currency: "GBP", amountScaled: 300, amountMinor: 300 } },
     ]);
   });
 });

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { SYSTEM_TENANT_ID } from "../../engine";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { createTenantDb, createUncheckedSystemDb, SYSTEM_SCOPE_CHECK_BRAND } from "../tenant-db";
+
+// createUncheckedSystemDb wraps a "system"-mode TenantDb (r.systemScope())
+// so a handler must explicitly clear a self-check before using it — none of
+// these checks execute a query, so a runner that always throws is enough to
+// prove the wrapper never falls through to the DB on a mismatch.
+function unusedRunner(): DbRunner {
+  return {
+    unsafe: async () => {
+      throw new Error("unchecked-system-db tests must not reach the DB");
+    },
+    begin: async () => {
+      throw new Error("unchecked-system-db tests must not reach the DB");
+    },
+  } as DbRunner;
+}
+
+const own = testTenantId(1);
+const foreign = testTenantId(2);
+
+describe("createUncheckedSystemDb", () => {
+  test("carries the SYSTEM_SCOPE_CHECK_BRAND", () => {
+    const systemDb = createTenantDb(unusedRunner(), own, "system");
+    const unchecked = createUncheckedSystemDb(systemDb);
+
+    expect(unchecked[SYSTEM_SCOPE_CHECK_BRAND]).toBe(true);
+  });
+
+  describe("assertTenantMatch", () => {
+    test("returns the underlying TenantDb when the tenantId matches", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.assertTenantMatch(own)).toBe(systemDb);
+    });
+
+    test("throws AccessDeniedError when the tenantId doesn't match", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.assertTenantMatch(foreign)).toThrow(/tenant self-check failed/);
+    });
+  });
+
+  describe("assertRowsTenant", () => {
+    test("returns the rows unchanged when every row matches", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: own, name: "b" },
+      ];
+
+      expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
+    });
+
+    test("throws AccessDeniedError on the first mismatched row instead of filtering", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: foreign, name: "b" },
+      ];
+
+      expect(() => unchecked.assertRowsTenant(rows, "tenantId")).toThrow(
+        /row tenant self-check failed/,
+      );
+    });
+
+    test("an empty row array trivially passes", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.assertRowsTenant([], "tenantId")).toEqual([]);
+    });
+
+    test("accepts SYSTEM_TENANT_ID rows as reference data, mirroring tenant-mode readWhere", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+      const rows = [
+        { tenantId: own, name: "a" },
+        { tenantId: SYSTEM_TENANT_ID, name: "global-default" },
+      ];
+
+      expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
+    });
+  });
+
+  describe("acknowledgeCrossTenant", () => {
+    test("returns the underlying TenantDb without comparing tenants when given a reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(unchecked.acknowledgeCrossTenant("user feature is cross-tenant by design")).toBe(
+        systemDb,
+      );
+    });
+
+    test("throws on an empty reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.acknowledgeCrossTenant("")).toThrow(/non-empty reason/);
+    });
+
+    test("throws on a whitespace-only reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const unchecked = createUncheckedSystemDb(systemDb);
+
+      expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
+    });
+  });
+});

package/src/db/dialect.ts

@@ -377,10 +377,16 @@ export function primaryKey(opts: {
 // Limits: no nested SqlExpression composition (drizzle's recursive
 // `sql\`${other}\``) — schema-files use single-level expressions only.
 
+// Unforgeable via JSON — a client-supplied jsonb value can fake `kind:
+// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (bun-db/query.ts)
+// can't be tricked into treating request data as a raw SQL literal.
+export const SQL_EXPR_BRAND: unique symbol = Symbol("sql-expr");
+
 export type SqlExpression = {
   readonly kind: "sql-expr";
   readonly text: string;
   readonly params: readonly unknown[];
+  readonly [SQL_EXPR_BRAND]: true;
 };
 
 export function sql(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlExpression {
@@ -397,10 +403,15 @@ export function sql(strings: TemplateStringsArray, ...values: readonly unknown[]
       }
     }
   }
-  return { kind: "sql-expr", text: parts.join(""), params };
+  return { kind: "sql-expr", text: parts.join(""), params, [SQL_EXPR_BRAND]: true };
 }
 
-sql.raw = (text: string): SqlExpression => ({ kind: "sql-expr", text, params: [] });
+sql.raw = (text: string): SqlExpression => ({
+  kind: "sql-expr",
+  text,
+  params: [],
+  [SQL_EXPR_BRAND]: true,
+});
 
 // ---- table() — the schema-table factory ----
 //

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

@@ -5,6 +5,7 @@ import { coerceRow, extractTableInfo } from "../db/query";
 import { buildOwnershipClause, shiftParams } from "../engine/ownership";
 import type { EntityId } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+import { UnprocessableError } from "../errors";
 import { getStreamVersion } from "../event-store";
 import { rehydrateCompoundTypes } from "./compound-types";
 import { decodeCursor, encodeCursor } from "./cursor";
@@ -54,7 +55,17 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       // ctx.searchAdapter erst zur Laufzeit weil createEventStoreExecutor
       // beim Definition-Time noch keinen Server-Context hat).
       const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
-      if (payload.search && effectiveSearchAdapter && entityName) {
+      if (payload.search) {
+        // #2032 — a search term with no adapter wired must fail loud, not
+        // silently return the unfiltered list dressed up as a search result.
+        if (!effectiveSearchAdapter) {
+          throw new UnprocessableError("search_adapter_not_wired", {
+            details: {
+              entity: entityName,
+              hint: "Wire a SearchAdapter for this entity, or remove `searchable` from the field/screen.",
+            },
+          });
+        }
         const results = await effectiveSearchAdapter.search(user.tenantId, payload.search, {
           filterType: entityName,
         });

package/src/db/index.ts

@@ -143,5 +143,10 @@ export {
   toSnakeCase,
   toTableName,
 } from "./table-builder";
-export type { TenantDb, TenantDbMode } from "./tenant-db";
-export { castTenantRows, createTenantDb } from "./tenant-db";
+export type { TenantDb, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
+export {
+  castTenantRows,
+  createTenantDb,
+  createUncheckedSystemDb,
+  SYSTEM_SCOPE_CHECK_BRAND,
+} from "./tenant-db";

package/src/db/money.ts

@@ -3,10 +3,15 @@
 // Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
 //   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
 //   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
-//   Read-Form:   { amount, currency, amountMinor } — amount in MAJOR units again,
-//                amountMinor sits alongside as exact integer cents (fw#1830) for
-//                callers that need cent-exact comparisons (e.g. invoice sums)
-//                instead of round-tripping the float amount through /100·*100.
+//   Read-Form:   { amount, currency, amountScaled } — amount in MAJOR units again,
+//                amountScaled sits alongside as the exact integer value in
+//                MINOR_UNIT_SCALE units (fw#1830) for callers that need
+//                scale-exact comparisons (e.g. invoice sums) instead of
+//                round-tripping the float amount through /100·*100.
+//                `amountMinor` stays as a @deprecated alias of the same
+//                value until #1976/4 and #1976/5 migrate their remaining
+//                consumers (renderer-web/primitives/index.tsx,
+//                renderer/components/render-field.tsx) off the old name.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
 // "the integer minor unit" — this file used to just pass the API amount
@@ -40,8 +45,8 @@ export function toMinorUnits(amount: number): number {
   return Math.round(amount * MINOR_UNIT_SCALE);
 }
 
-function toMajorUnits(amountMinor: number): number {
-  return amountMinor / MINOR_UNIT_SCALE;
+function toMajorUnits(amountScaled: number): number {
+  return amountScaled / MINOR_UNIT_SCALE;
 }
 
 // One money field's write payload — `{ amount, currency }` or a bare number
@@ -123,11 +128,20 @@ export function flattenMoney(
 }
 
 /** Shape of a single rehydrated money field — {amount major, currency,
- *  amountMinor exact integer cents}. Exported so consumers type their own
- *  copy against this instead of re-declaring the shape by hand. */
+ *  amountScaled exact integer value in MINOR_UNIT_SCALE units}. Exported so
+ *  consumers type their own copy against this instead of re-declaring the
+ *  shape by hand. */
 export type MoneyRead = {
   readonly amount: number;
   readonly currency: string;
+  readonly amountScaled: number;
+  /**
+   * @deprecated Use `amountScaled` — this name implies ISO-4217 minor units
+   * (cents), which is wrong once a currency needing a different scale than
+   * the current flat MINOR_UNIT_SCALE=100 lands (e.g. JPY, 0 decimals).
+   * Alias of `amountScaled`, kept until #1976/4 and #1976/5 migrate their
+   * consumers off it.
+   */
   readonly amountMinor: number;
 };
 
@@ -159,18 +173,18 @@ export function rehydrateMoney(
       continue;
     }
 
-    let amountMinor: number;
+    let amountScaled: number;
     if (typeof amountRaw === "number") {
-      amountMinor = amountRaw;
+      amountScaled = amountRaw;
     } else if (typeof amountRaw === "bigint") {
-      amountMinor = Number(amountRaw);
-      if (!Number.isSafeInteger(amountMinor)) {
+      amountScaled = Number(amountRaw);
+      if (!Number.isSafeInteger(amountScaled)) {
         throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a safe integer`);
       }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
-      amountMinor = Number(amountRaw);
-      if (!Number.isSafeInteger(amountMinor)) {
+      amountScaled = Number(amountRaw);
+      if (!Number.isSafeInteger(amountScaled)) {
         throw new Error(
           `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`,
         );
@@ -184,7 +198,13 @@ export function rehydrateMoney(
     const currency =
       typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
 
-    result[name] = { amount: toMajorUnits(amountMinor), currency, amountMinor };
+    // amountMinor: deprecated alias, same value as amountScaled — see MoneyRead.
+    result[name] = {
+      amount: toMajorUnits(amountScaled),
+      currency,
+      amountScaled,
+      amountMinor: amountScaled,
+    };
   }
 
   return result;

package/src/db/table-builder.ts

@@ -25,6 +25,7 @@ import {
   moneyAmount,
   table as pgTable,
   plainDate,
+  SQL_EXPR_BRAND,
   type SqlExpression,
   serial,
   sql,
@@ -586,7 +587,12 @@ export function buildEntityTable<E extends EntityDefinition>(
                 .filter((c, i) => c !== def.columns[i])
                 .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`)
                 .join(" AND ");
-              const partialWhere: SqlExpression = { kind: "sql-expr", text: whereText, params: [] };
+              const partialWhere: SqlExpression = {
+                kind: "sql-expr",
+                text: whereText,
+                params: [],
+                [SQL_EXPR_BRAND]: true,
+              };
               indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
                 .on(...bidxCols)
                 .where(partialWhere);

package/src/db/tenant-db.ts

@@ -1,5 +1,10 @@
 import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
-import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import {
+  SYSTEM_SCOPE_CHECK_BRAND,
+  type TenantDb,
+  type TenantDbMode,
+  type UncheckedSystemDb,
+} from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
   asEntityTableMeta,
   asRawClient,
@@ -12,12 +17,59 @@ import {
   type WhereObject,
 } from "../db/query";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
+import { AccessDeniedError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 
 type Table = SchemaTable;
 
-export type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
+export {
+  SYSTEM_SCOPE_CHECK_BRAND,
+  type TenantDb,
+  type TenantDbMode,
+  type UncheckedSystemDb,
+} from "@cosmicdrift/kumiko-types/tenant-db-types";
+
+// buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
+// mode from the caller's own tenantId, never a foreign one.
+export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
+  const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
+
+  return {
+    [SYSTEM_SCOPE_CHECK_BRAND]: true,
+
+    assertTenantMatch(tenantId) {
+      if (tenantId !== db.tenantId) {
+        throw new AccessDeniedError({
+          message: `systemScope() tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+        });
+      }
+      return db;
+    },
+
+    // Fails closed on any mismatch rather than silently dropping rows.
+    // Reference rows (tenantId === SYSTEM_TENANT_ID) are allowed, mirroring
+    // "tenant"-mode readWhere's own [tenantId, SYSTEM_TENANT_ID] allowlist.
+    assertRowsTenant<T>(rows: readonly T[], tenantField: keyof T): readonly T[] {
+      const hasOffender = rows.some(
+        (row) => !allowedTenantIds.includes(row[tenantField] as TenantId),
+      );
+      if (hasOffender) {
+        throw new AccessDeniedError({
+          message: `systemScope() row tenant self-check failed on field "${String(tenantField)}"`,
+        });
+      }
+      return rows;
+    },
+
+    acknowledgeCrossTenant(reason) {
+      if (reason.trim().length === 0) {
+        throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+      }
+      return db;
+    },
+  };
+}
 
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {

package/src/derivatives/derivatives-context.ts

@@ -107,6 +107,15 @@ function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
   }
 }
 
+// `deps.db` is whatever the caller passes through — in the write-handler
+// pipeline (dispatch-shared.ts) that's the handler's open DbTx. `variant()`
+// then holds that transaction open across a full render (decode/resize/
+// encode) plus the storage read+write, not just the fetchOne/exists checks.
+// On a later rollback in the same handler, a variant already written to
+// storage is orphaned there (row never committed, bytes never cleaned up).
+// Prefer this context from the job/MSP path, where `deps.db` isn't tied to
+// an in-flight write transaction; a synchronous write handler rendering a
+// large image should hand off to a job instead of calling `variant()` inline.
 export function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext {
   return {
     variant: async (fileRefId, spec, name) => {

package/src/engine/__tests__/build-app-schema.test.ts

@@ -71,6 +71,26 @@ describe("buildAppSchema", () => {
     });
   });
 
+  // kumiko-framework#2034: createKumikoApp's boot diagnostic reads
+  // `screens[].dormant` from the CLIENT schema, not from the registry —
+  // this pins that the flag actually survives the server→client projection
+  // instead of only living in the registry's verbatim `feature.screens`.
+  test("custom screen's `dormant` flag survives the buildAppSchema projection verbatim (#2034)", () => {
+    const dormantScreenFeature = defineFeature("privacy", (r) => {
+      r.screen({
+        id: "privacy-center",
+        type: "custom",
+        renderer: { react: { __component: "PrivacyCenterScreen" } },
+        dormant: true,
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([dormantScreenFeature]));
+    const screen = app.features.find((f) => f.featureName === "privacy")?.screens[0];
+
+    expect(screen).toMatchObject({ id: "privacy-center", dormant: true });
+  });
+
   test("Feature ohne r.translations lässt das Feld weg (omit-undefined-Pattern)", () => {
     const f = defineFeature("bare", (r) => {
       r.nav({ id: "x", label: "X" });
@@ -79,6 +99,36 @@ describe("buildAppSchema", () => {
     expect(app.features[0]?.translations).toBeUndefined();
   });
 
+  // #2062: buildAppSchema itself has no context, so the boot entrypoint
+  // (createKumikoServer, runProdApp) forwards its own context.searchAdapter
+  // presence check in via options.searchAdapterMissing.
+  test("options.searchAdapterMissing: true landet auf jeder FeatureSchema", () => {
+    const orderFeature = defineFeature("orders", (r) => {
+      r.nav({ id: "list", label: "List" });
+    });
+    const fleetFeature = defineFeature("fleet", (r) => {
+      r.nav({ id: "list", label: "List" });
+    });
+    const app = buildAppSchema(createRegistry([orderFeature, fleetFeature]), {
+      searchAdapterMissing: true,
+    });
+
+    expect(app.features.length).toBeGreaterThan(0);
+    expect(app.features.every((f) => f.searchAdapterMissing === true)).toBe(true);
+  });
+
+  test("options.searchAdapterMissing ohne/false lässt das Feld weg (omit-undefined-Pattern)", () => {
+    const f = defineFeature("bare", (r) => {
+      r.nav({ id: "x", label: "X" });
+    });
+
+    expect(buildAppSchema(createRegistry([f])).features[0]?.searchAdapterMissing).toBeUndefined();
+    expect(
+      buildAppSchema(createRegistry([f]), { searchAdapterMissing: false }).features[0]
+        ?.searchAdapterMissing,
+    ).toBeUndefined();
+  });
+
   test("Workspaces — definition + aufgelöste navMembers landen auf AppSchema-Ebene", () => {
     const ordersFeature = defineFeature("orders", (r) => {
       r.nav({ id: "list", label: "List" });

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

@@ -38,7 +38,7 @@ describe("r.nav() — registration", () => {
       r.nav({
         id: "products",
         label: "shop:nav.products",
-        icon: "box",
+        icon: "package",
         order: 10,
         parent: "shop:nav:catalog",
         screen: "shop:screen:products",
@@ -47,7 +47,7 @@ describe("r.nav() — registration", () => {
     });
     const nav = feature.navs["products"];
     expect(nav).toMatchObject({
-      icon: "box",
+      icon: "package",
       order: 10,
       parent: "shop:nav:catalog",
       screen: "shop:screen:products",
@@ -78,6 +78,14 @@ describe("r.nav() — registration", () => {
       }),
     ).not.toThrow();
   });
+
+  test("@ts-expect-error: icon must be a registered NavIconKey, not any string", () => {
+    const feature = defineFeature("shop", (r) => {
+      // @ts-expect-error — "seting" is a typo of "settings", not a NavIconKey
+      r.nav({ id: "catalog", label: "x", icon: "seting" });
+    });
+    expect(feature.navs["catalog"]).toBeDefined();
+  });
 });
 
 describe("r.screen({ nav }) — inline nav sugar", () => {
@@ -89,13 +97,13 @@ describe("r.screen({ nav }) — inline nav sugar", () => {
         type: "entityList",
         entity: "product",
         columns: ["name"],
-        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+        nav: { label: "shop:nav.products", icon: "package", order: 5 },
       });
     });
     expect(feature.navs["products"]).toMatchObject({
       id: "products",
       label: "shop:nav.products",
-      icon: "box",
+      icon: "package",
       order: 5,
       screen: "shop:screen:products",
     });