@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/db/table-builder.js

@@ -16,29 +16,28 @@ export function physicalColumnName(table, field) {
 // Returns column(s) for a field. Most fields return a single entry,
 // money returns two (amount + currency).
 //
-// `required: true` auf einem FieldDefinition mappt **immer** auf .notNull()
-// in der DB-Spalte. Die alte Implementation hat das nur für reference-
-// fields gemacht — text/select/number/etc. waren stillschweigend nullable
-// in der DB, auch wenn der API-Validator required erzwungen hat. Folge:
-// hand-written PgTable-Definitionen mussten daneben mit .notNull() pflegen,
-// was zu Doppel-Definitionen + Schema-Drift führte. Jetzt ist r.entity
-// die einzige Wahrheit.
+// `required: true` on a FieldDefinition always maps to .notNull() in the
+// database column. Previously this applied only to reference fields, while
+// text/select/number/etc. remained silently nullable even when the API
+// validator enforced required. That forced hand-written PgTable definitions
+// to add .notNull(), causing duplicate definitions and schema drift. Now
+// r.entity is the single source of truth.
 function fieldToColumns(name, field, entity) {
     const snakeName = toSnakeCase(name);
     switch (field.type) {
         case "text":
         case "longText": {
-            // Beide mappen auf PG `text` (unbounded). Unterschied lebt nur
-            // im Type-Layer: longText hat kein sortable/searchable/filterable
-            // (Sprint 5b vorab). Reihenfolge default() VOR notNull(): drizzle's
-            // column-builder chained beides; ohne default() hat die generierte
-            // SQL keinen DEFAULT-clause (bricht ALTER TABLE ADD COLUMN auf
-            // existing rows). longText hat heute kein default-feld im type,
-            // aber der check `field.default !== undefined` ist defensive.
+            // Both map to PG `text` (unbounded). The difference exists only in the
+            // type layer: longText has no sortable/searchable/filterable support.
+            // The order default() before notNull() matters: the column builder
+            // chains both; without default(), the generated SQL has no DEFAULT
+            // clause, which breaks ALTER TABLE ADD COLUMN on existing rows.
+            // longText currently has no default field in its type, but checking
+            // `field.default !== undefined` is defensive.
             const base = text(snakeName);
             const withDefault = "default" in field && field.default !== undefined ? base.default(field.default) : base;
             const mainCol = { [name]: field.required ? withDefault.notNull() : withDefault };
-            // lookupable → nullable HMAC-Blind-Index-Spalte (lock-step mit
+            // lookupable → nullable HMAC blind-index column (kept in lockstep with
             // fieldToColumnMeta in entity-table-meta.ts).
             if (field.type === "text" && field.lookupable === true) {
                 return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
@@ -54,23 +53,23 @@ function fieldToColumns(name, field, entity) {
                         : boolean(snakeName),
             };
         case "select": {
-            // default() durchreichen — entity-table-meta rendert deklarierte
-            // defaults, dieser Builder MUSS lock-step bleiben (sonst trägt das
-            // Meta am buildEntityTable-Objekt eine andere Spalte als die
-            // Migration, #255-Follow-up-Befund).
+            // Pass default() through because entity-table-meta renders declared
+            // defaults. This builder must stay in lockstep; otherwise the metadata
+            // on the buildEntityTable object describes a different column than the
+            // migration.
             const base = text(snakeName);
             const col = field.default !== undefined ? base.default(field.default) : base;
             return { [name]: field.required ? col.notNull() : col };
         }
         case "multiSelect":
-            // jsonb-Array<string> mit Default `[]` und immer NOT NULL.
+            // jsonb string array with default `[]`, always NOT NULL.
             //
-            // Der `required`-Flag auf MultiSelectFieldDef wird hier bewusst
-            // ignoriert: Mit Default `[]` ist das Feld strukturell never-null
-            // (Insert ohne Wert → leeres Array, nicht NULL). Read-Side-Code
-            // braucht keinen null-check, das ist API-Garantie. Wer "wirklich
-            // null" will (= "Feld noch nie gesetzt") nutzt einen separaten
-            // Status-Field oder ein optional-typed reference statt eines
+            // The `required` flag on MultiSelectFieldDef is intentionally ignored:
+            // with default `[]`, the field is structurally never null (an insert
+            // without a value produces an empty array, not NULL). Read-side code
+            // therefore needs no null check; this is an API guarantee. Code that
+            // needs actual null (meaning the field has never been set) should use
+            // a separate status field or an optional-typed reference instead of a
             // multi-select.
             return { [name]: jsonb(snakeName).default([]).notNull() };
         case "number": {
@@ -84,19 +83,18 @@ function fieldToColumns(name, field, entity) {
             return { [name]: field.required ? col.notNull() : col };
         }
         case "bigInt": {
-            // 64-bit-Integer fuer Audit-Counter, Byte-Sizes, Cumulative-Sums.
-            // mode:"number" liefert JS-`number` (sicher bis 2^53 ≈ 9 PB) statt
-            // JS-`bigint` — JSON-serialisierbar, Frontend-tauglich. Wer >2^53
-            // braucht (Astronomie-Astronomie), nutzt einen Text-Field mit
-            // eigenem Codec.
+            // 64-bit integer for audit counters, byte sizes, and cumulative sums.
+            // mode:"number" produces a JS `number` (safe up to 2^53 ≈ 9 PB) rather
+            // than JS `bigint`, making it JSON-serializable and frontend-friendly.
+            // Values above 2^53 should use a text field with a custom codec.
             const base = bigint(snakeName, { mode: "number" });
             const col = field.default !== undefined ? base.default(field.default) : base;
             return { [name]: field.required ? col.notNull() : col };
         }
         case "reference":
-            // Tier 2.7e-3: FK-Style UUID-Spalte. Multi-Mode (Tier 2.7e-Multi)
-            // speichert UUIDs als jsonb-Array<string>. Single-Mode bleibt
-            // klassische UUID-Spalte (NOT NULL nur bei required).
+            // FK-style UUID column. Multi-mode stores UUIDs as a jsonb string array;
+            // single-mode remains a conventional UUID column (NOT NULL only when
+            // required).
             if (field.multiple === true) {
                 return { [name]: jsonb(snakeName).default([]).notNull() };
             }
@@ -104,11 +102,12 @@ function fieldToColumns(name, field, entity) {
                 [name]: field.required ? uuid(snakeName).notNull() : uuid(snakeName),
             };
         case "money":
-            // BIGINT storing the integer minor unit (cents for EUR, yen for JPY —
-            // the currency column tells you which). INTEGER would cap at ~21 M EUR
-            // which is too tight for B2B invoices, property values or balance
-            // aggregates. BIGINT handles up to ~90 trillion EUR safely in JS.
-            // Currency hat immer einen Default, ist also strukturell .notNull().
+            // BIGINT stores the integer minor unit (cents for EUR, yen for JPY —
+            // the currency column identifies which). INTEGER would cap at about
+            // 21 M EUR, which is too low for B2B invoices, property values, or
+            // balance aggregates. BIGINT safely handles up to about 90 trillion
+            // EUR in JS.
+            // Currency always has a default, so it is structurally .notNull().
             return {
                 [name]: field.required ? moneyAmount(snakeName).notNull() : moneyAmount(snakeName),
                 [`${name}Currency`]: text(`${snakeName}_currency`)
@@ -116,47 +115,47 @@ function fieldToColumns(name, field, entity) {
                     .notNull(),
             };
         case "embedded":
-            // jsonb mit default `{}` und immer NOT NULL — analog zu multiSelect.
-            // `required` wird bewusst ignoriert weil der Default das Feld
-            // strukturell never-null macht. Wer optional-embedded möchte (=
-            // "Feld komplett weglassen können") modelliert das über ein
-            // wrapper-feld mit boolean-flag oder discriminierte-union.
+            // jsonb with default `{}`, always NOT NULL, analogous to multiSelect.
+            // `required` is intentionally ignored because the default makes the
+            // field structurally never null. To make embedded data optional (so
+            // the field can be omitted entirely), model it with a wrapper field
+            // and boolean flag or a discriminated union.
             // multiple → the value is a list of rows, so the empty default is `[]`.
             return field.multiple === true
                 ? { [name]: jsonb(snakeName).default([]).notNull() }
                 : { [name]: jsonb(snakeName).default({}).notNull() };
         case "jsonb":
-            // Free-form jsonb — keys nicht schema-validated. Default `{}`, NOT NULL
-            // (analog zu embedded). Use-case: custom-fields-Bundle's host-entity-
-            // `customFields`-Spalte (tenant-definierte dynamische keys).
+            // Free-form jsonb — keys are not schema-validated. Default `{}`, NOT NULL
+            // (analogous to embedded). Use case: the host entity's custom-fields
+            // bundle in the `customFields` column, whose keys are tenant-defined.
             return { [name]: jsonb(snakeName).default({}).notNull() };
         case "date": {
             // Real PG `date` — no time-of-day, no timezone. Temporal.PlainDate
             // end-to-end (see plainDate() in dialect.ts). Was aliased on instant()
-            // = TIMESTAMPTZ until kumiko-framework#1924 (TZ-dependent round-trip).
+            // = TIMESTAMPTZ (TZ-dependent round-trip).
             const col = plainDate(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "timestamp": {
-            // UTC-Instant — gespeichert als TIMESTAMPTZ in PG, gelesen/geschrieben
-            // als Temporal.Instant via instant() customType (siehe dialect.ts).
-            // Sprint F: Single-Mode-Welt — Caller-Code kennt nur Temporal.Instant,
-            // nie JS-Date. Auch Vergleiche (lte/gt/orderBy) akzeptieren Instants
-            // direkt, kein .toString()-Cast nötig.
+            // UTC instant — stored as TIMESTAMPTZ in PG and read/written as
+            // Temporal.Instant through the instant() customType (see dialect.ts).
+            // Callers use only Temporal.Instant, never JS Date. Comparisons
+            // (lte/gt/orderBy) also accept Instants directly, so no .toString()
+            // cast is needed.
             const col = instant(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "tz": {
-            // IANA-Zonenname als TEXT — Validierung über Zod-Schema (kommt im
-            // Validator-Schritt). Snake-Convention: `pickup_tz`.
+            // IANA time-zone name as TEXT — validated through the Zod schema in the
+            // validator step. Snake-case convention: `pickup_tz`.
             const col = text(snakeName);
             return { [name]: field.required ? col.notNull() : col };
         }
         case "locatedTimestamp": {
-            // ZWEI Spalten als atomares Pair: <name>_utc TIMESTAMPTZ + <name>_tz TEXT.
-            // _utc ist instant() (Temporal.Instant), _tz ist text (IANA-Name).
-            // Auto-Convert (at+tz → utc beim Insert; utc+tz → at beim Read) wird
-            // im Executor verdrahtet (Phase C). required propagiert auf beide.
+            // Two columns form an atomic pair: <name>_utc TIMESTAMPTZ + <name>_tz TEXT.
+            // _utc is instant() (Temporal.Instant), and _tz is text (IANA name).
+            // The executor wires automatic conversion (at+tz → utc on insert;
+            // utc+tz → at on read). required propagates to both columns.
             const utc = instant(`${snakeName}_utc`);
             const tz = text(`${snakeName}_tz`);
             return {
@@ -188,12 +187,12 @@ function fieldToColumns(name, field, entity) {
  * Derives a table name from an entity name:
  * 1. camelCase → snake_case (e.g. "memberTask" → "member_task")
  * 2. Simple English pluralization (category→categories, status→statuses, task→tasks)
- * 3. `read_` prefix — markiert die Tabelle als Event-Sourced-Read-Model,
- *    damit im DB-Tool sofort erkennbar ist dass App-Code nicht direkt
- *    reinschreibt. Event-Store (kumiko_events) + Framework-State
- *    (kumiko_*) haben ihren eigenen Prefix, normale App-Side-Tables
- *    (ohne ES-Anbindung) haben keinen — die drei Kategorien sind damit
- *    im Tabellenbrowser unterscheidbar.
+ * 3. `read_` prefix — marks the table as an event-sourced read model so
+ *    it is immediately distinguishable in database tools and application
+ *    code is not expected to write to it directly. The event store
+ *    (`kumiko_events`) and framework state (`kumiko_*`) use their own
+ *    prefixes; ordinary app-side tables without event-sourcing have none.
+ *    The three categories are therefore distinguishable in the table browser.
  */
 const ES_PLURAL_SUFFIXES = ["s", "sh", "ch", "x"];
 export const READ_MODEL_PREFIX = "read_";
@@ -219,12 +218,13 @@ export function buildBaseColumns(softDelete, idType = "uuid") {
         id: idColumn,
         tenantId: uuid("tenant_id").notNull(),
         version: integer("version").default(1).notNull(),
-        // Sprint F: Temporal.Instant durchgängig (siehe instant() in dialect.ts).
-        // Vorher mode default "date" → Inkonsistenz mit user-defined timestamp
-        // Felder (mode "string"). Jetzt: ein Mode für alle Timestamps.
+        // Temporal.Instant is used throughout (see instant() in dialect.ts).
+        // Previously the default mode was "date", which was inconsistent with
+        // user-defined timestamp fields (mode "string"). A single mode is now
+        // used for all timestamps.
         // customType doesn't expose Drizzle's `defaultNow()` shortcut — use raw
-        // SQL so PG sets the value on insert and we don't need to pass an
-        // Instant from JS for every row create.
+        // SQL so PG sets the value on insert and callers need not pass an
+        // Instant for every row creation.
         insertedAt: instant("inserted_at").default(sql `now()`).notNull(),
         modifiedAt: instant("modified_at"),
         // User-IDs are stringified UUIDs post-ES migration. Text (not uuid) so the
@@ -295,9 +295,9 @@ export function buildEntityTable(entityName, entity, options) {
     }
     // Default table name derived from entityName (e.g. "memberTask" → "read_member_tasks")
     const baseTableName = entity.table ?? toTableName(entityName);
-    // featureName-prefix wird zwischen read_ und den base-Namen geschoben,
-    // damit alle read-models einheitlich mit `read_` starten — egal ob
-    // featureName gesetzt ist oder nicht. Beispiel:
+    // The featureName prefix is inserted between read_ and the base name so
+    // all read models consistently start with `read_`, whether or not
+    // featureName is set. Examples:
     //   featureName="shop", base="read_orders"  →  "read_shop_orders"
     //   featureName=undef,  base="read_orders"  →  "read_orders"
     //   featureName="shop", base="orders" (no read_)  →  "shop_orders"
@@ -349,7 +349,7 @@ export function buildEntityTable(entityName, entity, options) {
                 indexes[`${tableName}_${toSnakeCase(fieldName)}_idx`] = index(`${tableName}_${toSnakeCase(fieldName)}_idx`).on(column);
             }
         }
-        // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
+        // lookupable fields: index the bidx column (kept in lockstep with
         // deriveEntityTableMeta).
         const bidxFieldByField = new Map();
         for (const [name, field] of Object.entries(entity.fields)) {
@@ -362,10 +362,10 @@ export function buildEntityTable(entityName, entity, options) {
                 indexes[idxName] = index(idxName).on(column);
             }
         }
-        // entity.indexes = composite/unique-Indices die der Author explizit
-        // deklariert hat. Spalten werden via field-name (camelCase) angesprochen,
-        // der Index-Name folgt der Convention <table>_<col1>_<col2>_<unique|idx>
-        // — Override via index.name möglich.
+        // entity.indexes contains composite/unique indexes explicitly declared by
+        // the author. Columns are addressed by field name (camelCase), and the
+        // index name follows <table>_<col1>_<col2>_<unique|idx>; index.name can
+        // override the convention.
         for (const def of entity.indexes ?? []) {
             const cols = def.columns
                 .map((fieldName) => tHandle[fieldName])
@@ -388,12 +388,12 @@ export function buildEntityTable(entityName, entity, options) {
             }
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would
-                // permanently block reuse; kept in lock-step with entity-table-meta.ts (framework#2593).
+                // permanently block reuse; kept in lock-step with entity-table-meta.ts.
                 chain = chain.where(sql.raw(SOFT_DELETE_LIVE_ROW_PREDICATE));
             }
             indexes[indexName] = chain;
-            // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
-            // (lock-step mit deriveEntityTableMeta).
+            // Partial bidx counterpart for unique indexes over lookupable fields
+            // (kept in lockstep with deriveEntityTableMeta).
             if (def.unique === true && def.where === undefined) {
                 const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
                 if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {
@@ -406,7 +406,7 @@ export function buildEntityTable(entityName, entity, options) {
                             .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`);
                         // Soft-deleted rows keep their bidx hash — without this, a
                         // restored row can't reuse a value a soft-deleted sibling still
-                        // holds (framework#2464).
+                        // holds.
                         const whereText = (entity.softDelete === true
                             ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE]
                             : notNullParts).join(" AND ");

package/dist/db/tenant-db.d.ts

@@ -16,7 +16,7 @@ export declare function withExecutorManagedWrites(runner: DbRunner): ExecutorMan
 export declare function withoutExecutorManagedWrites(runner: DbRunner): DbRunner;
 export declare function assertPersonalDataWrite(db: TenantDb, tableName: string, keys: readonly string[], entity: EntityDefinition): void;
 export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSystemDb, reason: string): DbRunner;
-export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): UncheckedSystemDb;
+export declare function withSystemDbUnsafeRawGrant<T extends object>(systemDb: T, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): T | UncheckedSystemDb;
 export declare function createUncheckedSystemDb(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
@@ -34,7 +34,7 @@ export type TenantDbGrants = {
     readonly writesDeniedReason?: string;
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
-export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;
+export declare function withUnsafeRawGrant<T extends object>(tenantDb: T, grant: EscapeHatchDeclaration | undefined): T | TenantDb;
 export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string, options?: {
     readonly deferReport?: boolean;
 }): TenantDb;

package/dist/db/tenant-db.js

@@ -26,6 +26,9 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
     const proxy = new Proxy(runner, {
         // Tagged-template calls need the real driver object as `this`.
         apply(target, _thisArg, args) {
+            if (typeof target !== "function") {
+                throw new TypeError("tenant-db runner proxy applied on a non-callable runner");
+            }
             return Reflect.apply(target, target, args);
         },
         get(target, prop, _receiver) {
@@ -51,7 +54,11 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
                     }
                     const gatedArgs = [
                         ...args.slice(0, -1),
-                        (tx) => callback(boundRunner(tx, gate, projectionRegistry, executorManagedWrites)),
+                        (tx) => {
+                            // @cast-boundary db-runner — driver callback hands over the tx handle untyped
+                            const txRunner = tx;
+                            return callback(boundRunner(txRunner, gate, projectionRegistry, executorManagedWrites));
+                        },
                     ];
                     return Reflect.apply(value, target, gatedArgs);
                 };
@@ -179,7 +186,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         // Reference rows (tenantId === SYSTEM_TENANT_ID) are allowed, mirroring
         // "tenant"-mode readWhere's own [tenantId, SYSTEM_TENANT_ID] allowlist.
         assertRowsTenant(rows, tenantField) {
-            const hasOffender = rows.some((row) => !allowedTenantIds.includes(row[tenantField]));
+            const hasOffender = rows.some((row) => !allowedTenantIds.some((allowed) => allowed === row[tenantField]));
             if (hasOffender) {
                 throw new AccessDeniedError({
                     message: `systemScope() row tenant self-check failed on field "${String(tenantField)}"`,

package/dist/derivatives/delete-stored-file.js

@@ -12,6 +12,7 @@
 // Used by both the user-data-rights-defaults forget hook and the
 // data-retention hardDelete cleanup — moved here so neither copies the logic.
 import { assertSafeStorageKey } from "../files/types.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { derivativeListPrefix, isDerivativeKeyOf } from "./variant-key.js";
 // Wrap rather than let a raw provider error (e.g. S3 AccessDenied) surface
 // unexplained — list() is a requirement on top of delete(); a bucket policy
@@ -62,8 +63,10 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         }
         catch (err) {
             failedKeys.push(key);
-            // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
-            console.warn(`[${errorContext}] storage delete failed key=${key} err=${err instanceof Error ? err.message : String(err)}`);
+            createFallbackLogger(errorContext).warn("storage delete failed", {
+                key,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
     return failedKeys;

package/dist/derivatives/derivatives-context.js

@@ -116,7 +116,7 @@ async function resolveOverlaySpec(spec, row, registry, tenantId) {
 // allowlisted before it becomes a response Content-Type or storage-provider
 // metadata. Otherwise an app whose renderer wildcard is broad enough (e.g.
 // `image/*`) would let a client-declared `image/svg+xml` ride straight
-// through as an honestly-declared (non-sniffed) active-content type (#2021).
+// through as an honestly-declared (non-sniffed) active-content type.
 const KNOWN_SAFE_VARIANT_MIME_TYPES = new Set([
     "image/jpeg",
     "image/png",

package/dist/engine/boot-validator/access-roles.js

@@ -1,4 +1,6 @@
+import { createFallbackLogger } from "../../logging/utils.js";
 import { normalizeAccessEntry } from "../ownership.js";
+const log = createFallbackLogger("kumiko:boot");
 const BUILTIN_ROLES = new Set(["all", "system"]);
 function addRole(roleHandlers, role, identifier) {
     let handlers = roleHandlers.get(role);
@@ -50,7 +52,7 @@ function addEntityFieldRoles(roleHandlers, f) {
 // purpose) are the normal case, not a typo — and until every access
 // surface is scanned, a role can look unique here while it's really used
 // elsewhere (configKeys / entity+field access), a false positive in the
-// other direction. Both is why this stays opt-in (#1711) rather than a
+// other direction. This is why this stays opt-in rather than a
 // default-on prod warning.
 export function warnOnUniqueAccessRoles(features) {
     // role → set of distinct identifiers using it, across every access
@@ -68,8 +70,7 @@ export function warnOnUniqueAccessRoles(features) {
         if (handlers.size !== 1)
             continue;
         const [identifier] = handlers;
-        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn(`[kumiko:boot] Access role "${role}" is only used by one handler (${identifier}). ` +
+        log.warn(`Access role "${role}" is only used by one handler (${identifier}). ` +
             `This is often a typo — the role is unknown to every other handler in the boot scan. ` +
             `If this is intentional, ignore this warning.`);
     }

package/dist/engine/boot-validator/api-ext.js

@@ -1,16 +1,17 @@
+import { createFallbackLogger } from "../../logging/utils.js";
+const log = createFallbackLogger("kumiko:boot");
 // --- Cross-feature API exposure / usage matching ---
 //
 // `r.exposesApi(name, impl)` registers a callable; `r.usesApi(name)`
-// declares a caller. Boot-Validator prüft drei Invarianten:
-//   1. Jeder usesApi(name) findet einen exposesApi(name) in irgendeinem
-//      Feature.
-//   2. Das exposing-Feature ist in requires/optionalRequires des callers
-//      gelisted (sonst klappt die Cross-Feature-Aufruf-Reihenfolge nicht).
-//   3. Self-exposure ist erlaubt (Feature ruft eigene API), wird aber
-//      mit Warning markiert weil es typisch ein Refactor-Restbestand ist.
+// declares a caller. Boot validation checks three invariants:
+//   1. Every usesApi(name) finds an exposesApi(name) in some feature.
+//   2. The exposing feature is listed in the caller's
+//      requires/optionalRequires so cross-feature call ordering works.
+//   3. Self-exposure is allowed (a feature calling its own API), but is
+//      warned about because it is typically a refactoring leftover.
 //
-// Globale Eindeutigkeit der apiNames (kein Dublicate über Features)
-// wird in validateBoot() vor dem Per-Feature-Walk geprüft.
+// apiNames must be globally unique across features; validateBoot() checks
+// this before the per-feature walk.
 export function validateApiExposureMatching(feature, allExposedApis, featureMap) {
     for (const apiName of feature.usedApis) {
         const providerFeature = allExposedApis.get(apiName);
@@ -19,17 +20,16 @@ export function validateApiExposureMatching(feature, allExposedApis, featureMap)
             throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") but no feature exposes that API. Known exposed APIs: ${known}`);
         }
         if (providerFeature === feature.name) {
-            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-            console.warn(`[kumiko:boot] [Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`);
+            log.warn(`[Feature ${feature.name}] r.usesApi("${apiName}") on its own r.exposesApi — typically a refactor leftover. Call the impl directly instead.`);
             continue;
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
             throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires({ features: ["${providerFeature}"] }).`);
         }
-        // Sanity: provider feature actually exists in this app's feature set.
-        // Should always be true if allExposedApis was built from `features`,
-        // aber defensiv für unklare Constructor-Pfade.
+        // Sanity: the provider feature must exist in this app's feature set.
+        // This should always hold when allExposedApis was built from `features`,
+        // but remains defensive for unclear constructor paths.
         if (!featureMap.has(providerFeature)) {
             throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map. Register the provider feature in the app's feature list.`);
         }

package/dist/engine/boot-validator/config-deps.js

@@ -1,5 +1,7 @@
 import { optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
+import { createFallbackLogger } from "../../logging/utils.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
+const log = createFallbackLogger("kumiko:boot");
 // --- Toggleable-dependency warnings ---
 //
 // When feature A declares r.requires({ features: ["B"] }) and B is toggleable with
@@ -15,8 +17,7 @@ export function warnOnToggleableDependencies(features, featureMap) {
             if (!depFeature)
                 continue; // requires-target-missing is handled elsewhere
             if (depFeature.toggleableDefault === false) {
-                // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                console.warn(`[kumiko:boot] Feature "${f.name}" requires "${dep}", which is toggleable(default=false). ` +
+                log.warn(`Feature "${f.name}" requires "${dep}", which is toggleable(default=false). ` +
                     `"${f.name}" will be effectively disabled until "${dep}" is enabled globally via the feature-toggles feature. ` +
                     `If this is intentional, ignore this warning; otherwise consider r.optionalRequires() or default=true.`);
             }
@@ -70,9 +71,9 @@ export function validateConfigKeyRequired(feature) {
     for (const [keyName, keyDef] of Object.entries(feature.configKeys ?? {})) {
         if (keyDef.required !== true)
             continue;
-        // required heißt "Tenant MUSS konfigurieren" — ein non-empty default
-        // oder ein computed-Resolver macht den Key nie unset, readiness könnte
-        // die Lücke nie melden: der required-Flag wäre eine stille Lüge.
+        // `required` means the tenant must configure the key. A non-empty default
+        // or computed resolver means the key can never be unset, so readiness could
+        // never report the omission and the flag would be misleading.
         if (keyDef.computed !== undefined) {
             throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has required=true AND a computed resolver — a computed key can never be missing; drop one of the two`);
         }
@@ -160,7 +161,7 @@ export function validateConfigKeyBacking(feature) {
         // read/write without it throws loud at request time, not silently.
     }
 }
-// --- Config key piiEncrypted compatibility (kumiko-platform#231/#459) ---
+// --- Config key piiEncrypted compatibility ---
 export function validateConfigKeyPiiEncrypted(feature) {
     for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
         if (!keyDef.piiEncrypted)

package/dist/engine/boot-validator/detail-screens.js

@@ -2,9 +2,9 @@ import { qualifyEntityName } from "../qualified-name.js";
 import { findEntityFeature } from "./screens.js";
 // Entity name → the one screen that declares detailFor: "<entity>". Built
 // once, up front (before the per-feature validateScreens loop) so both this
-// module's own uniqueness check AND rowAction entity-targets (fw#2228,
-// screens.ts) resolve against the same map instead of re-walking every
-// feature's screens twice.
+// module's own uniqueness check AND rowAction entity-targets (in screens.ts)
+// resolve against the same map instead of re-walking every feature's
+// screens twice.
 export function collectDetailForScreens(features, featureMap) {
     const screenQnByEntity = new Map();
     const result = new Map();