@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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",
@@ -141,6 +139,7 @@ export function validateHandlerAccess(feature) {
     for (const [name, handler] of Object.entries(feature.writeHandlers)) {
         validateTenantlessAnonymous(feature.name, name, handler);
         validateAdditionalRateLimits(feature.name, name, handler);
+        validateRateLimitCost(feature.name, name, handler);
         validatePerCommandTransaction(feature.name, name, handler);
     }
 }
@@ -237,6 +236,22 @@ export function validateTenantlessAnonymous(featureName, handlerName, handler) {
             `tenant/user bucket, so one caller could exhaust it for all. Use ${IP_SCOPED_RATE_LIMIT_PER.map((allowed) => `"${allowed}"`).join(" or ")}.`);
     }
 }
+export function validateRateLimitCost(featureName, handlerName, handler) {
+    // skip: no payload-derived cost declared
+    if (!handler.rateLimitCost)
+        return;
+    if (handler.rateLimit === undefined || isRateLimitDisabled(handler.rateLimit)) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost without an active rateLimit — ` +
+            `the cost is booked on the rateLimit buckets, so declare rateLimit or drop rateLimitCost.`);
+    }
+    const isAnonymous = "roles" in handler.access && handler.access.roles.includes("anonymous");
+    const hasIpBucket = declaredRateLimitOptions(handler.rateLimit).some(({ per }) => IP_SCOPED_RATE_LIMIT_PER.includes(per));
+    if (isAnonymous || hasIpBucket) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares rateLimitCost on an anonymous or ip-limited handler — ` +
+            `rateLimitCost books after the parse, so such a handler would lose its pre-parse protection against junk floods. ` +
+            `Bulk handlers are authenticated: use a user/tenant bucket and drop "anonymous", or drop rateLimitCost.`);
+    }
+}
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required
     if (!isRateLimitDisabled(rateLimit))
@@ -305,18 +320,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 +341,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 +375,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 +413,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 +452,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 +507,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 +568,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 +587,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 +721,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/form-derivations.js

@@ -3,15 +3,46 @@ import { parseQn } from "../qualified-name.js";
 import { formDerivationsOfSchema } from "../with-form-derivations.js";
 const NUMERIC_FORM_FIELD_TYPES = ["money", "number", "decimal"];
 const NUMERIC_SUB_FIELD_TYPES = ["money", "number", "decimal"];
+function isMoneyType(type) {
+    return type === "money";
+}
+// Money operands are computed in minor units, number/decimal in major units: mixing them
+// silently scales the result by 100 or 10000.
+function validateUnitCompatibility({ prefix, screen, target }, derivation) {
+    const targetIsMoney = isMoneyType(screen.fields[target]?.type);
+    const moneyFlags = derivation.from.map((source) => isMoneyType(screen.fields[source]?.type));
+    const moneyCount = moneyFlags.filter(Boolean).length;
+    if (derivation.op === "sum" || derivation.op === "subtract") {
+        if (moneyCount !== 0 && moneyCount !== moneyFlags.length) {
+            throw new Error(`${prefix}.${target}: "${derivation.op}" sources must be all money or all number/decimal.`);
+        }
+        if (moneyCount > 0 !== targetIsMoney) {
+            throw new Error(`${prefix}.${target}: a "${derivation.op}" over ${moneyCount > 0 ? "money" : "number/decimal"} sources needs a ${moneyCount > 0 ? "money" : "number/decimal"} target.`);
+        }
+        // skip: sum/subtract fully validated above.
+        return;
+    }
+    if (moneyCount > 1 || (derivation.op === "percent" && moneyFlags[1] === true)) {
+        throw new Error(`${prefix}.${target}: "${derivation.op}" takes at most one money source${derivation.op === "percent" ? " (the base, not the rate)" : ""}.`);
+    }
+    if ((moneyCount === 1) !== targetIsMoney) {
+        throw new Error(`${prefix}.${target}: the target must be money exactly when a "${derivation.op}" source is money.`);
+    }
+}
 function validateFromList({ prefix, screen, target }, derivation) {
     if (derivation.op === "percent" && derivation.from.length !== 2) {
         throw new Error(`${prefix}.${target}: "percent" needs exactly two sources (base, rate).`);
     }
     for (const source of derivation.from) {
-        if (!(source in screen.fields)) {
+        const sourceField = screen.fields[source];
+        if (sourceField === undefined) {
             throw new Error(`${prefix}.${target}: unknown source field "${source}". Name a field of this screen.`);
         }
+        if (!NUMERIC_FORM_FIELD_TYPES.includes(sourceField.type)) {
+            throw new Error(`${prefix}.${target}: source "${source}" must be money, number or decimal, not "${sourceField.type}".`);
+        }
     }
+    validateUnitCompatibility({ prefix, screen, target }, derivation);
 }
 function validateListSum(check, derivation) {
     const { prefix, screen, target } = check;
@@ -26,6 +57,9 @@ function validateListSum(check, derivation) {
     if (cellType === undefined || !NUMERIC_SUB_FIELD_TYPES.includes(cellType)) {
         throw new Error(`${prefix}.${target}: "${derivation.cell}" must be a money, number or decimal sub-field of "${derivation.list}".`);
     }
+    if (isMoneyType(cellType) !== isMoneyType(screen.fields[target]?.type)) {
+        throw new Error(`${prefix}.${target}: a listSum of a ${isMoneyType(cellType) ? "money" : "number/decimal"} cell needs a ${isMoneyType(cellType) ? "money" : "number/decimal"} target.`);
+    }
     const { whenEmpty } = derivation;
     // skip: whenEmpty is optional
     if (whenEmpty === undefined)

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,
@@ -94,9 +94,11 @@ export function validateTranslationLocaleConsistency(features) {
     }
 }
 export function validateRequiredLocales(features, requiredLocales) {
-    const gaps = findRequiredLocaleGaps(features, requiredLocales ?? []);
-    if (gaps.length > 0) {
+    const gaps = requiredLocales === undefined || requiredLocales.length === 0
+        ? []
+        : findRequiredLocaleGaps(features, requiredLocales);
+    if (requiredLocales !== undefined && gaps.length > 0) {
         const lines = gaps.map((gap) => `[i18n] Feature "${gap.featureName}": translation key "${gap.key}" is missing required locale(s) ${gap.missingLocales.join(", ")}.`);
-        throw new Error(`${lines.join("\n")}\nThe app requires locales [${(requiredLocales ?? []).join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
+        throw new Error(`${lines.join("\n")}\nThe app requires locales [${requiredLocales.join(", ")}] for every translation key; load the matching locale package or add the missing translations.`);
     }
 }

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

@@ -2,6 +2,7 @@ import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-en
 import { dedupeFeatures } from "../dedupe-features.js";
 import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
 import { validateAccessDeclarations } from "./access-declarations.js";
 import { warnOnUniqueAccessRoles } from "./access-roles.js";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring.js";
@@ -30,9 +31,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 +102,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 +139,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 +201,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);
@@ -238,6 +239,7 @@ export function validateBoot(rawFeatures, options) {
     validateGdprStoragePersistence(features);
     validateGlobalTenancyEntities(features);
     validateFeatureBootChecks(features);
+    validateProjectionAllowlist(features);
     if (hasEncryptedFields) {
         // Availability check, not env-presence: eagerly building the keyring
         // catches malformed keys (wrong length, bad base64) at boot instead of

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}.`);

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

@@ -3,23 +3,23 @@ import { tableNameOf, } from "../ownership.js";
 import { SYSTEM_USER_ID } from "../system-user.js";
 import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 import { assertQualifiedWhereFragment, tableColumnSqlNames } from "../where-rule-lint.js";
-// --- Ownership rule validation (H.2) ---
+// --- Ownership rule validation ---
 //
 // Walks every entity.access and every field.access map, resolves each
 // FromRule against the cross-feature claim registry, and confirms the
 // referenced column exists on the entity. Catches typos, renames, and
 // cross-feature-claim-removal scenarios at boot instead of at request time.
 //
-// fw#2639: also probes every `{ kind: "where" }` rule against the where-rule
+// Also probes every `{ kind: "where" }` rule against the where-rule
 // lint (see ../where-rule-lint.ts) so a fail-open unqualified-column bug
 // fails the boot instead of waiting for a request from the right role.
 //
 // Field-level `access.read` rejects where-rules too: filterFieldsForRead
 // evaluates it in memory and userCanReadFieldRow fails closed on a where-rule.
 //
-// fw#2626: `access.write` maps reject `{ kind: "where" }` outright. A
-// where-rule is raw SQL and the write path never reaches SQL — it evaluates
-// rules in memory against the concrete row (userCanCreateFieldRow /
+// `access.write` maps reject `{ kind: "where" }` outright. A where-rule is
+// raw SQL and the write path never reaches SQL — it evaluates rules in memory
+// against the concrete row (userCanCreateFieldRow /
 // userCanWriteFieldRow), and a create has no row to run a predicate against
 // at all. Such a rule can therefore only ever deny, so the boot fails instead
 // of shipping an access map that silently locks the role out.
@@ -49,9 +49,8 @@ export function collectClaimKeys(features) {
 // corpora go in as undefined — a three-feature stack genuinely does not know
 // which roles and claims the whole app declares, and answering that question
 // from a slice produces false "unknown role"/"unknown claim" errors. The
-// subset-invariant checks (#2639 where-lint, #2626 where-on-write, unknown
-// column) run in full: those hold or fail per feature, whatever else is
-// mounted.
+// subset-invariant checks (where-lint, where-on-write, unknown column) run in
+// full: those hold or fail per feature, whatever else is mounted.
 export function validateOwnershipBoot(features) {
     for (const feature of features) {
         validateOwnershipRules(feature, undefined, undefined);
@@ -258,12 +257,16 @@ export function probeWhereRule(rule, roleName, probe, scope, featureName) {
         return;
     assertQualifiedWhereFragment(fragment.sqlText, probe.columns, `${scope} (role "${roleName}", feature: "${featureName}")`);
 }
+// Array.isArray does not narrow a readonly array out of a union.
+function isRoleList(access) {
+    return Array.isArray(access);
+}
 // Embedded sub-fields are filtered in memory too (filterFieldsForRead), so a
 // where-rule there is just as unevaluable as on a top-level field.
 function rejectWhereInEmbeddedRead(schema, parentScope, featureName) {
     for (const [subName, sub] of Object.entries(schema)) {
         const map = sub.access?.read;
-        if (!map || Array.isArray(map))
+        if (!map || isRoleList(map))
             continue;
         for (const [roleName, rule] of Object.entries(map)) {
             if (rule !== "all" && rule.kind === "where") {

package/dist/engine/boot-validator/parent-ref.js

@@ -1,5 +1,5 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
-// --- Parent-ref boot validation (fw#2766) ---
+// --- Parent-ref boot validation ---
 //
 // Join-row entities (EntityDefinition.parentRef) derive both the write-path
 // deny and the read-path SQL gate from one declaration. This is the boot-time