@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/tenant-db-runner.js

@@ -26,6 +26,9 @@ const writesDeniedReasons = new WeakMap();
 export function denyTenantDbWrites(tenantDb, reason) {
     writesDeniedReasons.set(tenantDb, reason);
 }
+export function tenantDbWritesDeniedReason(tenantDb) {
+    return writesDeniedReasons.get(tenantDb);
+}
 export function tenantDbWritesDeniedError(operation, reason) {
     return new InternalError({
         message: `${operation}: writes are not available ${reason}; run the write through ctx.write so it gets its own transaction`,

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

@@ -10,7 +10,7 @@ import { bindProjectionRegistry, projectionRegistryOf } from "./projection-regis
 import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { queryDatabaseNow } from "./queries/database-now.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
-import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, tenantDbWritesDeniedReason, } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
 // The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
@@ -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);
                 };
@@ -98,9 +105,7 @@ export function assertPersonalDataWrite(db, tableName, keys, entity) {
 }
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(holder, reason) {
-    if (reason.trim().length === 0) {
-        throw new Error("unsafeRawForDeclaredStep requires a non-empty reason");
-    }
+    assertReason("unsafeRawForDeclaredStep", reason);
     const runner = declaredUnsafeRawRunners.get(holder);
     if (!runner) {
         throw new InternalError({
@@ -179,7 +184,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)}"`,
@@ -250,7 +255,13 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 // same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
 // validators) without handing them a cross-tenant view.
 export function scopeTenantDbToTenant(db, tenantId) {
-    return createTenantDb({ db: tenantDbRunner(db), tenantId, mode: "tenant" });
+    const writesDeniedReason = tenantDbWritesDeniedReason(db);
+    return createTenantDb({
+        db: tenantDbRunner(db),
+        tenantId,
+        mode: "tenant",
+        ...(writesDeniedReason !== undefined && { grants: { writesDeniedReason } }),
+    });
 }
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
@@ -261,6 +272,18 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids left over when the caller excludes some via ne/notIn; undefined for other operator forms.
+function tenantIdsAfterExclusion(requested, allowed) {
+    if (!isPlainObject(requested))
+        return undefined;
+    if ("ne" in requested)
+        return allowed.filter((t) => t !== requested["ne"]);
+    if (Array.isArray(requested["notIn"])) {
+        const excluded = requested["notIn"];
+        return allowed.filter((t) => !excluded.includes(t));
+    }
+    return undefined;
+}
 // Tenant ids a where.tenantId filter asks for; undefined for operator forms
 // that cannot narrow to a tenant list (ne, like, ...).
 export function requestedTenantIds(requested) {
@@ -422,7 +445,13 @@ function buildTenantDb(options) {
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = requestedTenantIds(requested) ?? [];
+            const requestedList = requestedTenantIds(requested);
+            // An explicit exclusion or empty list must keep excluding, never widen to the full scope.
+            if (requestedList === undefined) {
+                return { ...where, tenantId: tenantIdsAfterExclusion(requested, allowed) ?? allowed };
+            }
+            if (requestedList.length === 0)
+                return { ...where, tenantId: [] };
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -457,6 +486,14 @@ function buildTenantDb(options) {
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
+    // The table is the audit target: process-level dedup would otherwise collapse a cron's
+    // writes to several global tables into one audit entry.
+    function reportGlobalWrite(table) {
+        report("global-write", globalWriteReason(), {
+            id: tableNameOf(table),
+            tenantId: tenantId ?? SYSTEM_TENANT_ID,
+        });
+    }
     function personalDataDenied(table, keys) {
         if (!personalDataGate)
             return undefined;
@@ -528,7 +565,7 @@ function buildTenantDb(options) {
                     personalDataDenied(table, Object.keys(values));
                 if (denied)
                     return Promise.reject(denied);
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("insert", table, async () => insertRow(table, values));
             },
             updateMany(set, where) {
@@ -542,7 +579,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     return Promise.reject(new Error("db.global().updateMany without where would mass-update every tenant's rows. Pass at least one where condition."));
                 }
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("update", table, async () => updateRows(table, set, where));
             },
             deleteMany(where) {
@@ -554,7 +591,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
                 }
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("delete", table, async () => {
                     await deleteRows(table, where);
                 });

package/dist/db/where-clause.d.ts

@@ -0,0 +1,6 @@
+import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { TableInfo } from "./table-info.ts";
+export declare function buildWhereClause(info: TableInfo, where: WhereObject, startIndex: number, qualifier?: string): {
+    sqlText: string;
+    values: unknown[];
+};

package/dist/db/where-clause.js

@@ -0,0 +1,236 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+import { prepareJsonbValue, prepareValue } from "./driver-value-preparation.js";
+function isJsonTextMatchList(value) {
+    return Array.isArray(value);
+}
+function isWhereOperator(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    // Don't false-positive on Date / Temporal / other domain-objects.
+    // WhereOperator is plain object literal with at most these keys.
+    const keys = Object.keys(v);
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => Object.hasOwn(OPERATOR_EMITTERS, key));
+}
+function isJsonbScalar(value) {
+    return value !== null && typeof value !== "object";
+}
+function valueList(target, values) {
+    return values
+        .map((v) => {
+        const p = prepareValue(v, target.pgType);
+        return p.kind === "literal" ? p.literal : `${target.bind(p.bound)}${p.sql}`;
+    })
+        .join(", ");
+}
+// multiSelect (and any other jsonb-array-of-scalars column) stores an
+// array — a filter value is one option, not the whole array, so eq/ne/in
+// must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
+// against the jsonb column, which Postgres rejects outright.
+// Mirrors applyMultiSelectFilter in event-store-executor-read-filter.ts — keep in lock-step.
+function jsonbContainsAny(target, candidates) {
+    const { column, ref, bind } = target;
+    if (candidates.length === 0)
+        return "FALSE";
+    const parts = [];
+    for (const v of candidates) {
+        const p = prepareJsonbValue([v]);
+        // prepareJsonbValue never returns kind:"literal" (only prepareValue's
+        // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
+        if (p && p.kind === "param") {
+            parts.push(`${ref(column)} @> ${bind(p.bound)}${p.sql}`);
+        }
+        // A jsonb column holding the scalar itself is never `@>` an array of it.
+        if (isJsonbScalar(v)) {
+            parts.push(`${ref(column)} = ${bind(JSON.stringify(v))}::text::jsonb`);
+        }
+    }
+    return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
+}
+function isValidJsonTextMatch(match) {
+    if (match === null || typeof match !== "object")
+        return false;
+    const keys = propertyOf(match, "keys");
+    return (Array.isArray(keys) &&
+        keys.length > 0 &&
+        keys.every((k) => typeof k === "string") &&
+        typeof propertyOf(match, "eq") === "string");
+}
+function jsonTextMatchCondition(target, match) {
+    const { column, ref, bind } = target;
+    if (!isValidJsonTextMatch(match)) {
+        throw new Error(`where: jsonText on column "${column}" needs non-empty string keys and a string eq`);
+    }
+    const lookups = match.keys.map((key) => `${ref(column)}->>${bind(key)}::text`);
+    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
+    return `(${lhs} = ${bind(match.eq)})`;
+}
+function emitJsonText(target, operator) {
+    const { column, pgType } = target;
+    const operand = operator.jsonText;
+    if (operand === undefined)
+        return undefined;
+    if (Object.keys(operator).length > 1) {
+        throw new Error(`where: jsonText on column "${column}" cannot be combined with other operators`);
+    }
+    if (pgType !== "jsonb") {
+        throw new Error(`where: jsonText requires a jsonb column, "${column}" is ${pgType}`);
+    }
+    const matches = isJsonTextMatchList(operand) ? operand : [operand];
+    if (matches.length === 0)
+        return "FALSE";
+    return matches.map((match) => jsonTextMatchCondition(target, match)).join(" AND ");
+}
+function comparisonCondition(target, symbol, operand) {
+    const { column, pgType, ref, bind } = target;
+    const p = prepareValue(operand, pgType);
+    return p.kind === "literal"
+        ? `${ref(column)} ${symbol} ${p.literal}`
+        : `${ref(column)} ${symbol} ${bind(p.bound)}${p.sql}`;
+}
+function comparisonEmitter(key, symbol) {
+    return (target, operator) => {
+        const operand = operator[key];
+        if (operand === undefined)
+            return undefined;
+        // Mirrors applyMultiSelectFilter: ordering/pattern ops have no meaning on a jsonb
+        // option array (`like` would crash as `jsonb ~~ jsonb`), so match nothing.
+        if (target.pgType === "jsonb")
+            return "FALSE";
+        return comparisonCondition(target, symbol, operand);
+    };
+}
+// Mirrors applyMultiSelectFilter: an array `ne` means "does not contain all of these".
+function jsonbNotEqualCondition(target, operand) {
+    const { column, ref, bind } = target;
+    if (Array.isArray(operand)) {
+        if (operand.length === 0)
+            return "FALSE";
+        const p = prepareJsonbValue(operand);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql}))`;
+        }
+    }
+    if (isJsonbScalar(operand)) {
+        const p = prepareJsonbValue([operand]);
+        if (p && p.kind === "param") {
+            return `(${ref(column)} IS NULL OR NOT (${ref(column)} @> ${bind(p.bound)}${p.sql} OR ${ref(column)} = ${bind(JSON.stringify(operand))}::text::jsonb))`;
+        }
+    }
+    return undefined;
+}
+function emitNotEqual(target, operator) {
+    const operand = operator.ne;
+    if (operand === undefined)
+        return undefined;
+    if (operand === null && Object.keys(operator).length === 1) {
+        return `${target.ref(target.column)} IS NOT NULL`;
+    }
+    if (target.pgType === "jsonb") {
+        const jsonbCondition = jsonbNotEqualCondition(target, operand);
+        if (jsonbCondition !== undefined)
+            return jsonbCondition;
+    }
+    return comparisonCondition(target, "<>", operand);
+}
+function emitIn(target, operator) {
+    const operand = operator.in;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, operand);
+    if (operand.length === 0)
+        return "FALSE";
+    return `${target.ref(target.column)} IN (${valueList(target, operand)})`;
+}
+function emitNotIn(target, operator) {
+    const operand = operator.notIn;
+    if (!Array.isArray(operand))
+        return undefined;
+    if (target.pgType === "jsonb") {
+        throw new Error(`where: notIn is not supported on jsonb column "${target.column}"`);
+    }
+    if (operand.length === 0)
+        return "TRUE";
+    return `${target.ref(target.column)} NOT IN (${valueList(target, operand)})`;
+}
+// Insertion order is the SQL emission order. jsonText comes first so its "cannot be combined" error wins over any other
+// operator's error; the rest keep the historical order gt, gte, lt, lte, ne, like, in, notIn.
+const OPERATOR_EMITTERS = {
+    jsonText: emitJsonText,
+    gt: comparisonEmitter("gt", ">"),
+    gte: comparisonEmitter("gte", ">="),
+    lt: comparisonEmitter("lt", "<"),
+    lte: comparisonEmitter("lte", "<="),
+    ne: emitNotEqual,
+    like: comparisonEmitter("like", "LIKE"),
+    in: emitIn,
+    notIn: emitNotIn,
+};
+function operatorConditions(target, operator) {
+    const conditions = [];
+    for (const emit of Object.values(OPERATOR_EMITTERS)) {
+        const condition = emit(target, operator);
+        if (condition !== undefined)
+            conditions.push(condition);
+    }
+    return conditions;
+}
+// Blind-index OR rewrite: if the column has a bidx
+// counterpart (suffix convention `<col>_bidx`, framework-reserved)
+// and a key is configured, equality matches both arms —
+// plaintext legacy rows via the plaintext arm, encrypted rows
+// via the HMAC. The `kumiko-pii:` prefix on ciphertexts makes
+// a random match on the plaintext arm practically impossible.
+function equalityCondition(target, value) {
+    const { info, column, pgType, ref, bind } = target;
+    const p = prepareValue(value, pgType);
+    if (p.kind === "literal")
+        return `${ref(column)} = ${p.literal}`;
+    const bidxKey = configuredBlindIndexKey();
+    const bidxCol = `${column}_bidx`;
+    if (bidxKey !== undefined &&
+        typeof value === "string" &&
+        !column.endsWith("_bidx") &&
+        info.hasColumn(bidxCol)) {
+        return `(${ref(column)} = ${bind(p.bound)} OR ${ref(bidxCol)} = ${bind(computeBlindIndex(bidxKey, value))})`;
+    }
+    return `${ref(column)} = ${bind(p.bound)}${p.sql}`;
+}
+function arrayCondition(target, values) {
+    if (values.length === 0)
+        return "FALSE";
+    if (target.pgType === "jsonb")
+        return jsonbContainsAny(target, values);
+    return `${target.ref(target.column)} IN (${valueList(target, values)})`;
+}
+function conditionsForValue(target, value) {
+    if (value === null)
+        return [`${target.ref(target.column)} IS NULL`];
+    if (Array.isArray(value))
+        return [arrayCondition(target, value)];
+    if (isWhereOperator(value))
+        return operatorConditions(target, value);
+    if (target.pgType === "jsonb" && isJsonbScalar(value)) {
+        return [jsonbContainsAny(target, [value])];
+    }
+    return [equalityCondition(target, value)];
+}
+export function buildWhereClause(info, where, startIndex, qualifier) {
+    const values = [];
+    // Single place that renders a column reference, so a join qualifier reaches
+    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
+    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
+    const bind = (value) => {
+        values.push(value);
+        return `$${startIndex + values.length - 1}`;
+    };
+    const conditions = Object.entries(where).flatMap(([field, value]) => {
+        const column = info.columnOf(field);
+        return conditionsForValue({ info, column, pgType: info.pgTypeOf(column), ref, bind }, value);
+    });
+    return { sqlText: conditions.join(" AND "), values };
+}

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
@@ -55,6 +56,7 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
         ...(await listDerivativeKeys(originalKey, store, errorContext)),
     ];
     const failedKeys = [];
+    const log = createFallbackLogger(errorContext);
     for (const key of keysToDelete) {
         try {
             assertSafeStorageKey(key);
@@ -62,8 +64,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)}`);
+            log.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/boot-check.js

@@ -13,7 +13,7 @@ export function validateFeatureBootChecks(features) {
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}. Fix the condition this check reports.`);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
             }
         }
     }

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

@@ -1,10 +1,10 @@
 import { qualifyEntityName } from "../qualified-name.js";
-import { findEntityFeature } from "./screens.js";
+import { findEntityFeature } from "./screens-kind-shared.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-actions.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.d.ts

@@ -9,6 +9,7 @@ export declare function validateHandlerAccess(feature: FeatureDefinition): void;
 export declare function validateAdditionalRateLimits(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
+export declare function validateRateLimitCost(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateRateLimitBucketList(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;