@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

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();

package/dist/engine/boot-validator/entity-handler.js

@@ -6,16 +6,14 @@ import { access as accessPresets } from "../config-helpers.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
 export const FILE_FIELD_TYPES = new Set(["file", "image", "files", "images"]);
-// Field-Namen die typischerweise PII enthalten. Ohne `pii: true` /
-// `userOwned` / `tenantOwned` / `allowPlaintext`-Marker → Boot-Warning.
-// Lower-case compare für case-insensitive Match (displayName vs displayname).
+// Field names that typically contain PII. Without a `pii: true` /
+// `userOwned` / `tenantOwned` / `allowPlaintext` marker → boot warning.
+// Compare in lower case for case-insensitive matching (displayName vs displayname).
 //
-// Bewusst NICHT in der Liste:
-//   - `name` allein — zu viele Geschäfts-Kontexte (product.name,
-//     tenant.name, role.name) sind kein PII. Personen-Namen werden
-//     ueber displayName / firstName / lastName / fullName erfasst.
-//
-// Quelle: docs/plans/datenschutz/crypto-shredding.md Boot-Validation-Sektion.
+// Deliberately NOT included:
+//   - `name` alone — too many business contexts (product.name,
+//     tenant.name, role.name) are not PII. Personal names are detected
+//     through displayName / firstName / lastName / fullName.
 export const PII_DIRECT_NAME_HINTS = new Set([
     "email",
     "phone",
@@ -42,8 +40,8 @@ export const PII_DIRECT_NAME_HINTS = new Set([
     "iban",
     "bic",
 ]);
-// Field-Namen die typischerweise User-Generated-Content enthalten —
-// User-Forget muss diese mit Author-Subject-Key encrypten.
+// Field names that typically contain user-generated content —
+// User-Forget must encrypt these with the author subject key.
 export const PII_USER_OWNED_NAME_HINTS = new Set([
     "body",
     "text",
@@ -305,18 +303,18 @@ export function validateAnonymousRateLimit(featureName, kind, handlerName, acces
             `Use rateLimit.per="ip" or "ip+handler" for anonymous endpoints.`);
     }
 }
-// --- MultiStreamProjection delivery-invariant ---
+// --- MultiStreamProjection delivery invariant ---
 //
-// `delivery: "per-instance"` mit einer `table` ist eine semantische Falle:
-// N Dispatcher-Instanzen würden parallel die gleichen INSERT/UPDATE-Zeilen
-// schreiben (Race / Duplicates), und ein Rebuild würde nur eine Zeile in
-// kumiko_event_consumers anfassen (die SHARED_INSTANCE_SENTINEL-Zeile),
-// während Live-Cursor in per-instance-Zeilen liegen → Cursor-Divergenz.
+// `delivery: "per-instance"` with a `table` is a semantic trap:
+// N dispatcher instances would write the same INSERT/UPDATE rows in parallel
+// (races / duplicates), and a rebuild would affect only one row in
+// kumiko_event_consumers (the SHARED_INSTANCE_SENTINEL row),
+// while live cursors reside in per-instance rows → cursor divergence.
 //
-// Die Invariante ist: per-instance-Consumer sind rein side-effect (SSE,
-// in-memory cache invalidation). Wer eine Tabelle materialisiert, braucht
-// shared delivery — das ist exactly-once globally und gibt dem Rebuild
-// einen einzigen Cursor zum zurücksetzen.
+// The invariant is: per-instance consumers are side-effect-only (SSE,
+// in-memory cache invalidation). Materializing a table requires
+// shared delivery — it is exactly-once globally and gives the rebuild
+// a single cursor to reset.
 export function validateMultiStreamProjections(feature) {
     for (const [name, msp] of Object.entries(feature.multiStreamProjections)) {
         if (msp.delivery === "per-instance" && msp.table !== undefined) {
@@ -326,18 +324,19 @@ export function validateMultiStreamProjections(feature) {
         }
     }
 }
-// --- Located-Timestamp validation ---
+// --- Located-timestamp validation ---
 //
-// Wenn ein Feld `type: "timestamp"` einen `locatedBy`-Marker trägt, muss das
-// referenzierte Feld in derselben Entity existieren UND vom Typ `tz` sein.
-// Sonst weiß weder DB-Wrapper noch JSON-Serializer welche TZ zur Wall-Clock
-// gehört → silent data loss bei Reads in anderer Server-TZ.
+// When a field with `type: "timestamp"` has a `locatedBy` marker, the
+// referenced field must exist in the same entity AND have type `tz`.
+// Otherwise neither the DB wrapper nor the JSON serializer knows which TZ
+// belongs to the wall clock → silent data loss when reading in another
+// server TZ.
 //
-// Die häufigste Quelle von Konflikten ist Hand-Konstruktion:
+// Manual construction is the most common source of conflicts:
 //   { foo: { type: "timestamp", locatedBy: "fooTz" } }
-// ohne das `fooTz`-Feld zu deklarieren. `createLocatedTimestampField()`
-// erzeugt stattdessen EIN Feld vom Typ "locatedTimestamp" — wer den nutzt,
-// fliegt nicht durch diesen Validator.
+// without declaring the `fooTz` field. `createLocatedTimestampField()`
+// instead creates ONE field of type "locatedTimestamp" — using it avoids
+// this validator.
 export function validateLocatedTimestamps(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         const fields = entity.fields;
@@ -359,18 +358,18 @@ export function validateLocatedTimestamps(feature) {
         }
     }
 }
-// --- Entity-Index validation ---
+// --- Entity-index validation ---
 //
-// entity.indexes deklariert Composite-/Unique-Indices über mehrere Feld-
-// Spalten. Häufige Fehler: Tippfehler im Feld-Namen, leere column-Liste,
-// Index auf einem Field das die DB-Spalte gar nicht existiert (file/image
-// in der multi-Variante). Catched at boot, lange bevor drizzle-kit beim
-// generate-Run zickt.
+// entity.indexes declares composite/unique indexes over multiple field
+// columns. Common errors include misspelled field names, an empty column
+// list, and an index on a field for which the DB has no column (file/image
+// in the multi-value variant). Catch these at boot, long before drizzle-kit
+// fails during the generate run.
 //
-// `tenantId` als einzige Spalte ist redundant — buildEntityTable legt
-// den Index sowieso automatisch an. Wir lassen die Composite-Form erlaubt
-// (`["tenantId", "key"]` ist sinnvoll), nur die rein-tenantId-Single-
-// column-Form blockieren wir.
+// A `tenantId`-only index is redundant because buildEntityTable creates
+// that index automatically. Composite forms remain allowed
+// (`["tenantId", "key"]` is useful); only the tenantId-only single-column
+// form is rejected.
 export function validateEntityIndexes(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         if (!entity.indexes)
@@ -397,21 +396,21 @@ export function validateEntityIndexes(feature) {
                         `a jsonb array cannot be indexed as a column. Use a single-value field or remove from the index.`);
                 }
                 if (field && field.type === "longText") {
-                    // longText ist semantisch "potentially-megabytes content" — ein
-                    // BTREE-Index auf einer 1-MB-Spalte ist Performance-Disaster
-                    // (PG würde in TOAST-pages dereferenzieren müssen für jeden
-                    // Index-Lookup). Konsistent mit der type-level-decision dass
-                    // longText kein sortable/searchable/filterable hat. Wer
-                    // wirklich indexieren will, nimmt `text` mit den
-                    // entsprechenden Skalierungs-Trade-offs.
+                    // longText semantically means "potentially-megabytes content" — a
+                    // BTREE index on a 1-MB column is a performance disaster
+                    // (PG would need to dereference TOAST pages for every
+                    // index lookup). This is consistent with the type-level decision
+                    // that longText has no sortable/searchable/filterable flags. Anyone
+                    // who truly needs indexing should use `text` with the
+                    // corresponding scaling trade-offs.
                     throw new Error(`${where}: column "${col}" is a longText field — these cannot be indexed. ` +
                         `Use \`text\` if you need indexing, or rely on the SearchAdapter (Meilisearch) for full-text search on long content.`);
                 }
             }
-            // UNIQUE-constraint auf tenantId ist semantisch (1:1 tenant→entity)
-            // und NICHT redundant — buildEntityTable's auto-Index ist nur ein
-            // Performance-Hint, kein constraint. Nur die rein-tenantId-Single-
-            // column-non-unique-Form blockieren.
+            // A UNIQUE constraint on tenantId is semantically meaningful (1:1 tenant→entity)
+            // and NOT redundant — buildEntityTable's automatic index is only a
+            // performance hint, not a constraint. Only the tenantId-only,
+            // single-column, non-unique form is rejected.
             if (def.columns.length === 1 && def.columns[0] === "tenantId" && !def.unique) {
                 throw new Error(`${where}: single-column index on "tenantId" is redundant — ` +
                     `buildEntityTable always creates one automatically. Remove this entry.`);
@@ -436,9 +435,9 @@ export function validateEncryptedFields(feature) {
     let found = false;
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {
-            // Beide string-typed fields können encrypted sein. Die
-            // searchable/sortable-Konflikt-Checks gelten nur für `text`
-            // (longText hat diese flags type-level nicht).
+            // Both string-typed fields can be encrypted. The
+            // searchable/sortable conflict checks apply only to `text`
+            // (`longText` does not have these flags at the type level).
             if (field.type !== "text" && field.type !== "longText")
                 continue;
             if (!field.encrypted)
@@ -491,7 +490,7 @@ const NUMERIC_EMBEDDED_SUB_TYPES = new Set(["number", "money", "decimal"]);
 function isValidEmbeddedDecimalScale(scale) {
     return Number.isInteger(scale) && scale >= 0 && scale <= 15;
 }
-// Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation, shared by
+// ReferenceFieldDef validation, shared by
 // top-level reference fields and reference sub-fields of an embedded field
 // (only the field-path in error messages differs, e.g. "accountId" vs
 // "lines.accountId", so a failure is locatable either way).
@@ -552,7 +551,7 @@ function validateReferenceTarget(entityName, fieldPath, refString, labelField, o
     // (use-reference-lookup).
     validateReferenceOptionsQuery(entityName, fieldPath, optionsQuery, feature, queryHandlers);
 }
-// fw#2780: the picker may source its options from a query handler instead of
+// The picker may source its options from a query handler instead of
 // the referenced entity's table. A typo'd QN would only surface as a 404 on
 // first Combobox open, so it is pinned at boot — same treatment as
 // `DashboardFilterDefinition.optionsQuery` (boot-validator/query-refs.ts).
@@ -571,7 +570,7 @@ function validateReferenceOptionsQuery(entityName, fieldPath, optionsQuery, feat
             `is declared via r.queryHandler(...).`);
     }
 }
-// Tier 2.7e-3 + Cross-Feature: ReferenceFieldDef validation for top-level
+// ReferenceFieldDef validation for top-level
 // reference fields (self-reference, entity → entity, is allowed). The actual
 // checks run in validateReferenceTarget — shared with the reference
 // sub-fields of an embedded field (validateEmbeddedFields).
@@ -705,10 +704,10 @@ function validateEmbeddedListMetadata(fieldName, entityName, field, entity) {
 }
 // --- MultiSelect field validation ---
 //
-// options muss non-empty sein (sonst wäre das Feld nicht benutzbar) und
-// default — wenn gesetzt — ist eine Teilmenge der options. Beides würde
-// auch im Zod-Schema bei runtime fehlschlagen, der Boot-Catch ist nur
-// die früheste Stelle für klare Fehlermeldungen.
+// options must be non-empty (otherwise the field cannot be used), and
+// default — when set — must be a subset of options. Both conditions would
+// also fail at runtime in the Zod schema; boot validation only provides
+// the earliest clear error messages.
 // Exhaustive over MultiSelectFieldDef["columns"] (the compiler flags a union
 // change); the TS union is gone at runtime for JS/JSON-sourced definitions.
 const CHECKBOX_COLUMN_COUNTS = {

package/dist/engine/boot-validator/gdpr-storage.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../../logging/utils.js";
+const log = createFallbackLogger("kumiko:boot");
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
 const EPHEMERAL_PROVIDERS = new Set(["inmemory"]);
@@ -30,8 +32,7 @@ export function validateGdprStoragePersistence(features) {
     }
     const persistent = [...registeredProviders].filter((p) => !EPHEMERAL_PROVIDERS.has(p));
     if (persistent.length === 0) {
-        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn("[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount createFileProviderS3Feature() or createFileProviderS3Feature({ fromEnv: true }) and select it via the file-foundation provider config.");
+        log.warn("user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount createFileProviderS3Feature() or createFileProviderS3Feature({ fromEnv: true }) and select it via the file-foundation provider config.");
         // skip: ephemeral store already warned; the s3-env env-var check below is moot
         return;
     }
@@ -41,8 +42,7 @@ export function validateGdprStoragePersistence(features) {
     if (persistent.length === 1 && persistent[0] === "s3-env") {
         const missing = S3_ENV_REQUIRED.filter((v) => !process.env[v]);
         if (missing.length > 0) {
-            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-            console.warn(`[kumiko:boot] createFileProviderS3Feature({ fromEnv: true }) (provider "s3-env") is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
+            log.warn(`createFileProviderS3Feature({ fromEnv: true }) (provider "s3-env") is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
         }
     }
 }

package/dist/engine/boot-validator/i18n-keys.js

@@ -11,7 +11,7 @@ function requiredKeysFromGeneratedConfigHub(schema) {
     const out = new Set();
     // The generator's section titles + mask-title field-label overrides are
     // dot-form i18n references (`${feature}.settings`), never literal display
-    // text, so treatDotFormAsKey bypasses isI18nKey's colon-only check (fw#2260).
+    // text, so treatDotFormAsKey bypasses isI18nKey's colon-only check.
     for (const screen of schema.screens) {
         for (const key of requiredKeysFromScreen(SETTINGS_HUB_FEATURE, screen, {
             treatDotFormAsKey: true,

package/dist/engine/boot-validator/index.d.ts

@@ -9,14 +9,14 @@ export type ValidateBootOptions = {
     /** Warn when an access role is used by exactly one handler/config-key/
      *  field across the whole boot scan — often a typo, but also the normal
      *  shape of a legitimate fine-grained role (one role scoped to one admin
-     *  endpoint on purpose). Opt-in (default false, #1711): a default-on
+     *  endpoint on purpose). Opt-in (default false): a default-on
      *  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
+     *  unreachable via the sidebar. 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>;

package/dist/engine/boot-validator/index.js

@@ -30,9 +30,9 @@ import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
 import { validateTransferGraph } from "./transfer-graph.js";
 import { validateSubmitPrefilledHiddenFields } from "./url-prefill-fields.js";
 import { collectWorkspaceQns, resolveNavAllowlist, validateDefaultWorkspaceUniqueness, validateWorkspaces, } from "./workspaces.js";
-// Re-export: wird von run-dev-app.ts benötigt um Write-Handler-QNs
-// an den Codegen zu übergeben. Nicht Teil von validateBoot, aber
-// dieselbe Extraktionslogik.
+// Re-export: run-dev-app.ts needs this to pass write-handler QNs
+// to codegen. It is not part of validateBoot, but uses the same
+// extraction logic.
 export { collectCardMetaOverflow } from "./card-meta-overflow.js";
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 export { collectWriteHandlerQns } from "./nav.js";
@@ -101,13 +101,13 @@ export function validateBoot(rawFeatures, options) {
     }
     // Collect all config keys across features (for cross-feature reference validation)
     const allConfigKeys = new Set();
-    // Qualified config-key set für ConfigEditScreen-Validation. MUSS via
-    // qualifyEntityName kanonisiert werden (toKebab auf Feature + Key) — exakt
-    // wie define-feature/registry den QN bildet. Der rohe f.configKeys-Key ist
-    // der camelCase-Objekt-Key (`brandingTitle`), die echte QN aber
-    // `…:config:branding-title`; ohne toKebab failt jeder configEdit-Screen mit
-    // multi-word Config-Key fälschlich. allConfigKeys oben nutzt das ältere
-    // `feature.short`-Format für validateConfigReads.
+    // Qualified config-key set for ConfigEditScreen validation. MUST be
+    // canonicalized via qualifyEntityName (toKebab on feature + key), exactly
+    // as define-feature/registry builds the QN. The raw f.configKeys key is
+    // the camelCase object key (`brandingTitle`), but the actual QN is
+    // `…:config:branding-title`; without toKebab, every configEdit screen
+    // with a multi-word config key would fail incorrectly. allConfigKeys above
+    // uses the older `feature.short` format for validateConfigReads.
     const configKeyDefsByQn = new Map();
     for (const f of features) {
         for (const [key, def] of Object.entries(f.configKeys)) {
@@ -138,15 +138,15 @@ export function validateBoot(rawFeatures, options) {
     const screensByShortId = collectScreensByShortId(features);
     validateScreenShortIdCollisions(screensByShortId);
     // Cross-feature entity → detailFor-screen map — built (+ uniqueness-
-    // validated) up front so per-feature rowAction entity-targets (fw#2228)
+    // validated) up front so per-feature rowAction entity-targets
     // resolve against it inside the loop below, instead of at the very end
     // where this used to run.
     const detailForScreens = collectDetailForScreens(features, featureMap);
-    // Cross-feature API exposure-map — jedes Feature deklariert Marker via
-    // r.exposesApi(name). Per-feature validateApiExposureMatching walkt
-    // usedApis-Set und checkt dass jeder Eintrag hier einen Match findet.
-    // Verhindert dass typo-getroffene oder gedroppte QN-Aufrufe zu
-    // Runtime-Crash statt Boot-Fail werden.
+    // Cross-feature API exposure map — each feature declares markers via
+    // r.exposesApi(name). Per-feature validateApiExposureMatching walks the
+    // usedApis set and checks that every entry has a match here.
+    // This prevents typoed or removed QN calls from causing a runtime crash
+    // instead of a boot failure.
     const allExposedApis = new Map(); // apiName → providerFeature
     for (const f of features) {
         for (const apiName of f.exposedApis) {
@@ -200,10 +200,10 @@ export function validateBoot(rawFeatures, options) {
         validateParentRefs(feature, featureMap);
         validateTransferGraph(feature, featureMap);
         validateMultiStreamProjections(feature);
-        // Vor validateScreens: dessen visible/entityId-Feldref-Checks werfen für
-        // einen Function-Wert bereits (mit verwirrender "unknown field undefined"-
-        // Message, weil `typeof fn !== "boolean"` true ist), bevor der klare
-        // Function-Check hier überhaupt liefe.
+        // Before validateScreens: its visible/entityId field-reference checks throw
+        // for a Function value first, with the confusing "unknown field undefined"
+        // message (because `typeof fn !== "boolean"` is true), before the clear
+        // Function check here can run.
         validateActionWiring(feature);
         validateFieldWiring(feature);
         validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, configKeyDefsByQn, screensByShortId, detailForScreens);

package/dist/engine/boot-validator/nav.js

@@ -1,8 +1,10 @@
 // Nav validation + collectKnownRoles (role synthesis for ownership
 // validation in index.ts — thematically adjacent to ownership.ts, kept
 // here since this is a structural move, not a semantic reorg).
+import { createFallbackLogger } from "../../logging/utils.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { isOpenToAllGranted } from "../types/index.js";
+const log = createFallbackLogger("kumiko:boot");
 export function collectWriteHandlerQns(features) {
     const set = new Set();
     for (const f of features) {
@@ -110,7 +112,7 @@ function navViewerRoles(access) {
         return isOpenToAllGranted(access) ? undefined : [];
     return access.roles;
 }
-// fw#2640: warn (never throw — this is a real UX bug, not a broken ref)
+// Warn (never throw — this is a real UX bug, not a broken ref)
 // when a nav leaf's role gate is disjoint from its parent section's — no
 // user who can see the section could ever see this child, so the section
 // renders with zero visible children for every user who reaches it.
@@ -133,8 +135,7 @@ export function warnOnNavAccessInversion(allNavQns) {
             continue; // parent already visible to nobody — a different problem
         if (leafRoles.some((role) => parentRoles.includes(role)))
             continue;
-        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn(`[kumiko:boot] Nav entry "${qn}" requires roles [${leafRoles.join(", ")}] but its parent ` +
+        log.warn(`Nav entry "${qn}" requires roles [${leafRoles.join(", ")}] but its parent ` +
             `"${navDef.parent}" only allows [${parentRoles.join(", ")}] — no user who can see the ` +
             `parent section could ever see this entry. If this is intentional, ignore this warning; ` +
             `otherwise align the role sets.`);
@@ -158,8 +159,7 @@ export function warnOnUnreachableNavScreens(allNavQns, allowedNavQns, navAllowli
         const remedy = allowlistSource === "workspaces"
             ? "add it to a workspace's `nav` array or set `workspaces` on the nav"
             : "add it to the allowlist";
-        // 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 ` +
+        log.warn(`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 ${remedy}.`);