@cosmicdrift/kumiko-framework 0.384.0 → 0.386.0

package/dist/api/request-context.d.ts

@@ -21,6 +21,7 @@ export type RequestContextData = {
         readonly risk: AgentRisk;
     };
     readonly chargedRateLimitBuckets?: Set<string>;
+    readonly agentToolCall?: true;
 };
 export declare const requestContext: {
     run<T>(data: RequestContextData, fn: () => T): T;
@@ -41,4 +42,5 @@ export declare function runWithOrigin<T>(origin: {
     };
 }, fn: () => T): T;
 export declare function runAsDirectCallEntry<T>(fn: () => T): T;
+export declare function isAgentToolCallScope(): boolean;
 export declare function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T;

package/dist/api/request-context.js

@@ -48,15 +48,24 @@ export function runWithOrigin(origin, fn) {
             : new Set(),
     }, fn);
 }
-// Clears entryHandler so the next dispatch inside fn becomes the new entry —
-// used by dispatchToolCall so the invoked tool handler, not the surrounding
-// turn/approve handler, is what the irreversible-operation gate sees.
+// Clears entryHandler so the next dispatch inside fn becomes the new entry, letting
+// the irreversible-operation gate see the invoked tool handler instead of the
+// surrounding turn/approve handler. Reserved for dispatchToolCall, so it also marks
+// the scope as an agent tool call; it always mints a scope, because an agent loop
+// running outside any request must still carry that marker.
 export function runAsDirectCallEntry(fn) {
     const current = requestContext.get();
-    if (!current)
-        return fn();
-    const { entryHandler: _entryHandler, ...rest } = current;
-    return requestContext.run(rest, fn);
+    const requestId = current?.requestId ?? requestContext.generateId();
+    const { entryHandler: _entryHandler, ...rest } = current ?? {};
+    return requestContext.run({
+        ...rest,
+        requestId,
+        correlationId: current?.correlationId ?? requestId,
+        agentToolCall: true,
+    }, fn);
+}
+export function isAgentToolCallScope() {
+    return requestContext.get()?.agentToolCall === true;
 }
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin(origin, fn) {

package/dist/config/index.d.ts

@@ -21,7 +21,7 @@ export type AppClientConfig = {
     readonly entries: readonly string[];
 };
 /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
-export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "warnOnUniqueAccessRoles">;
+export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "warnOnUniqueAccessRoles">;
 export type AppConfig = {
     /** Features mounted in every environment: dev, tests, prod. */
     readonly features: readonly FeatureDefinition[];

package/dist/crypto/pii-ciphertext-format.js

@@ -1,4 +1,4 @@
-// Leaf module (no engine imports) so bun-db and the executors can sniff PII
+// Leaf module (no engine imports) so the query helpers and the executors can sniff PII
 // ciphertext without pulling the KMS/pipeline graph into an import cycle.
 export const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
 export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";

package/dist/db/blind-index-cleanup.js

@@ -77,7 +77,7 @@ async function existingTableNames(db, tableNames) {
 export async function subjectRowExistsInTenant(db, features, subjectId, tenantId) {
     // Prefetch which self-PII projection tables actually exist — probing a
     // missing relation used to throw (and get swallowed), which both hid
-    // real schema bugs and risked poisoning the Bun.SQL connection for the
+    // real schema bugs and risked poisoning the driver connection for the
     // rest of the forget TX (fw#2348 / framework#356).
     const candidateTables = [];
     for (const feature of features.values()) {

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

@@ -0,0 +1,8 @@
+import type { CrossTenantReads } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { EscapeHatchReporter } from "../engine/types/index.ts";
+import { type CreateTenantDbOptions, type TenantDb } from "./tenant-db.ts";
+export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): CrossTenantReads;
+export declare function createHandlerCrossTenantReads(options: Omit<CreateTenantDbOptions, "mode"> & {
+    readonly reason: string;
+    readonly report: EscapeHatchReporter;
+}): CrossTenantReads;

package/dist/db/cross-tenant-reads.js

@@ -0,0 +1,23 @@
+import { createTenantDb } from "./tenant-db.js";
+export function createCrossTenantReads(systemModeDb, reason, report) {
+    return {
+        selectMany(table, where, options) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.selectMany(table, where, options);
+        },
+        fetchOne(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.fetchOne(table, where);
+        },
+        count(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.count(table, where);
+        },
+    };
+}
+// Own system-mode TenantDb without unsafeRaw/globalWrites: the handler gets the read surface only.
+export function createHandlerCrossTenantReads(options) {
+    const { reason, report, ...dbOptions } = options;
+    const systemModeDb = createTenantDb({ ...dbOptions, mode: "system" });
+    return createCrossTenantReads(systemModeDb, reason, report);
+}

package/dist/db/dialect.js

@@ -1,7 +1,7 @@
 // Native dialect — replaces drizzle-orm/pg-core re-exports.
 //
 // Produces table objects that simultaneously expose:
-//   1. EntityTableMeta shape (source/columns/indexes) for bun-db's
+//   1. EntityTableMeta shape (source/columns/indexes) for the query helpers'
 //      extractTableInfo + the migrate-runner's renderTableDdl
 //   2. drizzle-compatible Symbol metadata so callers that introspect
 //      Symbol.for("kumiko:schema:Name") / Symbol.for("kumiko:schema:Columns") keep

package/dist/db/distinct-on.d.ts

@@ -0,0 +1,9 @@
+import type { OrderByClause } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { TableInfo } from "./query.ts";
+type DistinctOnClause = {
+    /** Physical column names, unquoted. */
+    readonly columns: readonly string[];
+    readonly orderBy: readonly OrderByClause[];
+};
+export declare function buildDistinctOnClause(info: TableInfo, distinctOn: readonly string[] | undefined, orderBy: OrderByClause | readonly OrderByClause[] | undefined): DistinctOnClause | undefined;
+export {};

package/dist/db/distinct-on.js

@@ -0,0 +1,28 @@
+// Postgres rejects DISTINCT ON unless ORDER BY starts with the same
+// expressions, so a mismatch is caught here with a readable message instead of
+// surfacing as a driver error.
+export function buildDistinctOnClause(info, distinctOn, orderBy) {
+    if (distinctOn === undefined)
+        return undefined;
+    if (distinctOn.length === 0) {
+        throw new Error(`selectMany: distinctOn must not be empty for "${info.name}"`);
+    }
+    for (const field of distinctOn) {
+        if (!info.hasColumn(field)) {
+            throw new Error(`selectMany: distinctOn entry "${field}" is not a column of "${info.name}"`);
+        }
+    }
+    const columns = distinctOn.map((field) => info.columnOf(field));
+    if (orderBy === undefined) {
+        return { columns, orderBy: distinctOn.map((col) => ({ col })) };
+    }
+    const clauses = Array.isArray(orderBy) ? orderBy : [orderBy];
+    const startsWithDistinctOn = columns.every((column, i) => {
+        const clause = clauses[i];
+        return (clause !== undefined && info.hasColumn(clause.col) && info.columnOf(clause.col) === column);
+    });
+    if (!startsWithDistinctOn) {
+        throw new Error(`selectMany: orderBy must start with the distinctOn fields [${distinctOn.join(", ")}] in the same order for "${info.name}"`);
+    }
+    return { columns, orderBy: clauses };
+}

package/dist/db/event-store-executor-write.js

@@ -290,7 +290,7 @@ export function createWriteVerbs(ctx) {
             //    selben catch (siehe line 493+).
             let event;
             try {
-                // Savepoint-scoped: postgres.js/Bun.SQL poison the WHOLE surrounding
+                // Savepoint-scoped: postgres.js poisons the WHOLE surrounding
                 // begin() once any statement inside it errors, even if the JS error
                 // is caught (kumiko-framework#1778) — a losing concurrent create's
                 // unique-violation would otherwise abort the caller's outer
@@ -336,7 +336,7 @@ export function createWriteVerbs(ctx) {
             //    UniqueViolationError 409 damit Designer/Frontend einen sauberen
             //    "duplicate" zeigen können statt cryptic "internal server error".
             // Savepoint like the append above: an unclassified DB error out of the
-            // projection INSERT would otherwise poison the enclosing tx (Bun.SQL
+            // projection INSERT would otherwise poison the enclosing tx (postgres-js
             // rejects the whole begin() once any statement in it failed), so a later
             // write sharing that tx — a sibling write after a failed nested one —
             // throws raw as a 500 instead of failing cleanly. The savepoint rolls the

package/dist/db/migrate-runner.js

@@ -188,16 +188,16 @@ function migrationClient(db) {
         if (hasBegin(client))
             return client;
     }
-    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need Bun.SQL or drizzle DbConnection)");
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (need a postgres-js Sql or drizzle DbConnection)");
 }
-// Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
+// Raw-SQL via postgres-js .unsafe().
 async function executeRaw(db, sqlText) {
     await migrationClient(db).unsafe(sqlText);
 }
 async function reserveConnection(db) {
     const client = migrationClient(db);
     if (typeof client.reserve !== "function") {
-        throw new Error("migrate-runner: db argument has no .reserve() (need Bun.SQL or postgres-js Sql)");
+        throw new Error("migrate-runner: db argument has no .reserve() (need a postgres-js Sql)");
     }
     return client.reserve();
 }
@@ -235,7 +235,7 @@ export class MigrationChecksumMismatchError extends Error {
 // Advisory-Lock verhindert concurrent-apply-races.
 export async function runMigrations(db, migrations) {
     // Session-level advisory lock and per-migration BEGIN/COMMIT must share one
-    // session. Pool calls may land on different connections (Bun.SQL round-robins),
+    // session. Pool calls may land on different connections (the pool round-robins),
     // which would leave the lock held on a session nobody unlocks.
     const conn = await reserveConnection(db);
     try {

package/dist/db/pg-error.js

@@ -20,18 +20,6 @@ export function extractPgError(e) {
         // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
         const code = layer.code;
         const constraintName = layer.constraint_name; // @cast-boundary error-details
-        // Bun.SQL carries the SQLSTATE in `errno` (string) and the constraint name
-        // in `constraint`, not in postgres-js's `code`/`constraint_name`.
-        if (code === "ERR_POSTGRES_SERVER_ERROR") {
-            const errno = layer.errno; // @cast-boundary error-details
-            const constraint = layer.constraint; // @cast-boundary error-details
-            if (typeof errno === "string") {
-                return {
-                    code: errno,
-                    constraint_name: constraintName ?? (typeof constraint === "string" ? constraint : undefined),
-                };
-            }
-        }
         if (code !== undefined || constraintName !== undefined) {
             return { code, constraint_name: constraintName };
         }

package/dist/db/queries/event-consumer.js

@@ -178,7 +178,7 @@ export async function updateConsumerDeliveryOutcome(db, name, instanceId, outcom
        "status" = $3,
        "last_error" = $4,
        "rearm_count" = CASE WHEN $5 THEN 0 ELSE "rearm_count" END,
-       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under the driver
        "pending_gaps" = $6::text::jsonb,
        "last_failed_event_id" = $9,
        "updated_at" = now()
@@ -210,7 +210,7 @@ pendingGaps) {
        "last_error" = NULL,
        "rearm_count" = 0,
        "last_failed_event_id" = NULL,
-       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under the driver
        "pending_gaps" = $4::text::jsonb,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
@@ -239,7 +239,7 @@ export async function updateConsumerRebuildCursor(db, name, instanceId, lastProc
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
-       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under the driver
        "pending_gaps" = $2::text::jsonb,
        "last_failed_event_id" = NULL,
        "updated_at" = now()

package/dist/db/queries/postgres-array-literal.js

@@ -1,5 +1,5 @@
-// Bun.SQL stringifies JS arrays via toString, so array params travel as a
-// Postgres array-literal string (`$1::text[]`) — identical on postgres-js and Bun.SQL.
+// Array params travel as a Postgres array-literal string (`$1::text[]`) so the
+// binding does not depend on how the driver infers JS array types.
 export function toPostgresArrayLiteral(values) {
     const elements = values.map((value) => value === null ? "NULL" : `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
     return `{${elements.join(",")}}`;

package/dist/db/queries/test-stack.d.ts

@@ -2,5 +2,8 @@ import type { AnyDb } from "../query.ts";
 export { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./ddl.ts";
 export declare function truncateTablesRestartIdentity(db: AnyDb, tableNames: readonly string[]): Promise<void>;
 export declare function databaseExists(db: AnyDb, dbName: string): Promise<boolean>;
-export declare function createDatabase(db: AnyDb, dbName: string): Promise<void>;
+export declare function createDatabase(db: AnyDb, dbName: string, templateDbName?: string): Promise<void>;
+export declare function renameDatabase(db: AnyDb, fromName: string, toName: string): Promise<void>;
+export declare function listDatabaseNamesWithPrefix(db: AnyDb, prefix: string): Promise<readonly string[]>;
+export declare function acquireSessionAdvisoryLock(db: AnyDb, key: string): Promise<void>;
 export declare function dropDatabaseIfExists(db: AnyDb, dbName: string): Promise<void>;

package/dist/db/queries/test-stack.js

@@ -12,8 +12,21 @@ export async function databaseExists(db, dbName) {
     const rows = await asRawClient(db).unsafe(`SELECT EXISTS (SELECT 1 FROM pg_database WHERE datname = $1) AS exists`, [dbName]);
     return rows[0]?.exists === true;
 }
-export async function createDatabase(db, dbName) {
-    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}`);
+export async function createDatabase(db, dbName, templateDbName) {
+    const template = templateDbName === undefined ? "" : ` TEMPLATE ${quoteTableIdent(templateDbName)}`;
+    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}${template}`);
+}
+export async function renameDatabase(db, fromName, toName) {
+    await asRawClient(db).unsafe(`ALTER DATABASE ${quoteTableIdent(fromName)} RENAME TO ${quoteTableIdent(toName)}`);
+}
+export async function listDatabaseNamesWithPrefix(db, prefix) {
+    const rows = await asRawClient(db).unsafe(`SELECT datname FROM pg_database WHERE starts_with(datname, $1) ORDER BY datname`, [prefix]);
+    return rows.map((row) => row.datname);
+}
+// Session-scoped: CREATE DATABASE cannot run inside a transaction, so the
+// xact-scoped variant cannot guard it. Released when the session closes.
+export async function acquireSessionAdvisoryLock(db, key) {
+    await asRawClient(db).unsafe(`SELECT pg_advisory_lock(hashtext($1))`, [key]);
 }
 export async function dropDatabaseIfExists(db, dbName) {
     await asRawClient(db).unsafe(`DROP DATABASE IF EXISTS ${quoteTableIdent(dbName)}`);

package/dist/db/query.js

@@ -24,6 +24,7 @@ import { InternalError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { SQL_EXPR_BRAND } from "./dialect.js";
+import { buildDistinctOnClause } from "./distinct-on.js";
 import { executorManagedWriteDenied } from "./executor-managed-tables.js";
 import { extractPgError } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
@@ -730,7 +731,6 @@ function buildWhereClause(info, where, startIndex, qualifier) {
 // Each failed attempt discards one, so retries are bounded by pool size.
 const CLOSED_CONNECTION_CODES = new Set([
     "CONNECTION_CLOSED", // postgres-js
-    "ERR_POSTGRES_CONNECTION_CLOSED", // Bun.SQL
     "57P01", // PG SQLSTATE: admin_shutdown / terminated backend
 ]);
 export function isClosedConnectionError(err) {
@@ -756,14 +756,10 @@ function isDriverClosedAbort(err) {
 function isHandleLike(raw) {
     return raw !== null && (typeof raw === "object" || typeof raw === "function");
 }
-// Bun.SQL is not instanceof-checkable (Bun.SQL.prototype is invalid) and its tx
-// handles are plain function objects, so discriminate by members only one driver
-// has: `flush` on Bun.SQL (pool and tx), `typed` on postgres-js (pool and tx).
+// postgres-js pool and tx handles both carry `typed`.
 function driverOf(raw) {
     if (!isHandleLike(raw))
         return "unknown";
-    if (typeof raw["flush"] === "function")
-        return "bun-sql";
     if (typeof raw["typed"] === "function")
         return "postgres-js";
     return "unknown";
@@ -771,13 +767,12 @@ function driverOf(raw) {
 function positiveNumber(v) {
     return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
 }
-// postgres-js configures timeouts in seconds, Bun.SQL in milliseconds.
-function timeoutOptionMs(options, driver, bunName, postgresJsName) {
-    if (driver === "postgres-js") {
-        const seconds = positiveNumber(options[postgresJsName]);
-        return seconds === undefined ? undefined : seconds * 1000;
-    }
-    return positiveNumber(options[bunName]);
+// postgres-js configures timeouts in seconds.
+function timeoutOptionMs(options, driver, optionName) {
+    if (driver !== "postgres-js")
+        return undefined;
+    const seconds = positiveNumber(options[optionName]);
+    return seconds === undefined ? undefined : seconds * 1000;
 }
 function errorProp(err, name) {
     return isHandleLike(err) ? err[name] : undefined;
@@ -794,9 +789,9 @@ export function describeClosedConnectionFailure(raw, err, attempts) {
         pooled: isPooledClient(raw),
         attempts,
         poolMax: positiveNumber(options["max"]),
-        idleTimeoutMs: timeoutOptionMs(options, driver, "idleTimeout", "idle_timeout"),
-        maxLifetimeMs: timeoutOptionMs(options, driver, "maxLifetime", "max_lifetime"),
-        connectionTimeoutMs: timeoutOptionMs(options, driver, "connectionTimeout", "connect_timeout"),
+        idleTimeoutMs: timeoutOptionMs(options, driver, "idle_timeout"),
+        maxLifetimeMs: timeoutOptionMs(options, driver, "max_lifetime"),
+        connectionTimeoutMs: timeoutOptionMs(options, driver, "connect_timeout"),
         errorName: errorProp(err, "name"),
         errorCode: extractPgError(err)?.code ?? errorProp(err, "code"),
         errorErrno: errorProp(err, "errno"),
@@ -889,15 +884,20 @@ export async function selectMany(db, table, where, options) {
         return scoped.selectMany(table, where, options);
     }
     const info = extractTableInfo(table);
-    let sqlText = `SELECT ${selectColumnList(info, options?.fields)} FROM ${quoteIdent(info.name)}`;
+    const distinctOn = buildDistinctOnClause(info, options?.distinctOn, options?.orderBy);
+    const distinctPrefix = distinctOn === undefined
+        ? ""
+        : `DISTINCT ON (${distinctOn.columns.map(quoteIdent).join(", ")}) `;
+    let sqlText = `SELECT ${distinctPrefix}${selectColumnList(info, options?.fields)} FROM ${quoteIdent(info.name)}`;
     let values = [];
     if (where && Object.keys(where).length > 0) {
         const w = buildWhereClause(info, where, 1);
         sqlText += ` WHERE ${w.sqlText}`;
         values = w.values;
     }
-    if (options?.orderBy) {
-        const clauses = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy];
+    const orderBy = distinctOn?.orderBy ?? options?.orderBy;
+    if (orderBy) {
+        const clauses = Array.isArray(orderBy) ? orderBy : [orderBy];
         const parts = clauses.map((c) => {
             const col = info.columnOf(c.col);
             const dir = c.direction === "desc" ? "DESC" : "ASC";

package/dist/db/tenant-db.js

@@ -33,7 +33,7 @@ function boundRunner(runner, gate, projectionRegistry, executorManagedWrites) {
             if (typeof value !== "function")
                 return value;
             if (prop === "reserve") {
-                // Bun.SQL and postgres.js hand back a raw connection; re-wrap it so the gate survives.
+                // postgres-js hands back a raw connection; re-wrap it so the gate survives.
                 return async (...args) => {
                     const reserved = await Reflect.apply(value, target, args);
                     return boundRunner(reserved, gate, projectionRegistry, executorManagedWrites);

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -1,3 +1,4 @@
 import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void;
 export declare function validateTranslationLocaleConsistency(features: readonly FeatureDefinition[]): void;
+export declare function validateRequiredLocales(features: readonly FeatureDefinition[], requiredLocales: readonly string[] | undefined): void;

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

@@ -1,4 +1,4 @@
-import { buildEffectiveTranslationKeys, featureHasI18nSurface, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
+import { buildEffectiveTranslationKeys, featureHasI18nSurface, findRequiredLocaleGaps, findTranslationLocaleGaps, requiredKeysFromFeature, requiredKeysFromNav, requiredKeysFromScreen, requiredKeysFromWorkspace, screenTitleKey, } from "../../i18n/required-surface-keys.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "../build-config-feature-schema.js";
 import { EXTENSION_SELECTOR_HINT_KEY } from "../extension-selector-plugins.js";
 import { createRegistry } from "../registry.js";
@@ -93,3 +93,10 @@ export function validateTranslationLocaleConsistency(features) {
         throw new Error(`${lines.join("\n")}\nEvery locale a feature uses must be maintained for every one of its translation keys; otherwise move that locale into a locale package.`);
     }
 }
+export function validateRequiredLocales(features, requiredLocales) {
+    const gaps = findRequiredLocaleGaps(features, requiredLocales ?? []);
+    if (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.`);
+    }
+}

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

@@ -32,6 +32,10 @@ export type ValidateBootOptions = {
      *  `masterKey` or the env keyring). Satisfies the availability check for
      *  `encrypted: true` fields without an env KEK. */
     readonly entityFieldCipher?: EnvelopeCipher;
+    /** Locales every translation key must carry across all mounted features
+     *  (locale packages count). Without it a key can ship in one language and
+     *  silently fall back at runtime for users of the others. */
+    readonly requiredLocales?: readonly string[];
 };
 /**
  * Subset-safe slice of validateBoot for test stacks: nav references (screen,

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

@@ -15,7 +15,7 @@ import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
 import { validateHandlerFieldReferences } from "./handler-field-references.js";
-import { validateI18nSurfaceKeys, validateTranslationLocaleConsistency } from "./i18n-keys.js";
+import { validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
 import { collectKnownRoles, collectNavQns, collectWriteHandlerQns, validateNavCycles, validateNavs, warnOnNavAccessInversion, warnOnUnreachableNavScreens, } from "./nav.js";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership.js";
 import { validateParentRefs } from "./parent-ref.js";
@@ -219,6 +219,7 @@ export function validateBoot(rawFeatures, options) {
     validateDefaultWorkspaceUniqueness(allWorkspaceQns);
     validateI18nSurfaceKeys(features);
     validateTranslationLocaleConsistency(features);
+    validateRequiredLocales(features, options?.requiredLocales);
     validateEntityListScreens(features);
     validateSubmitPrefilledHiddenFields(features);
     validateCardMetaOverflow(features);

package/dist/engine/boot-validator/screens-actions.d.ts

@@ -0,0 +1,67 @@
+import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
+import type { FeatureDefinition } from "../types/index.ts";
+import type { ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessLink, ProjectionDetailScreenDefinition, RelatedListToolbarAction, RowAction, RowActionNavigateBase, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
+export declare function isRowClickAction(action: RowAction): boolean;
+export declare function validateAtMostOneRowClick(featureName: string, screenId: string, screenType: "entityList" | "projectionList", rowActions: readonly RowAction[]): void;
+export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
+export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
+export type NavigateSourceScreenType = "dashboard" | "entityList" | "projectionList" | "projectionDetail" | "entityEdit" | "actionForm" | "secretMint" | "entityList expandableRow";
+export declare function validateRowActionNavigateParams(featureName: string, screenId: string, screenType: NavigateSourceScreenType, screenEntity: string | undefined, action: RowAction, target: {
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+} | undefined, actionLabel?: "rowAction" | "emptyState action"): void;
+export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList" | "dashboard", context: string, action: {
+    readonly id: string;
+    readonly icon?: IconKey;
+}): void;
+export declare function validateActionFieldRefs(featureName: string, screenId: string, actionKind: "rowAction" | "toolbarAction", actionId: string, action: RowAction | ToolbarAction | RelatedListToolbarAction, fieldNames: ReadonlySet<string>, rowMeta: ReadonlySet<string>): void;
+export declare function validateScreenShortIdCollisions(screensByShortId: ReadonlyMap<string, ReadonlyArray<{
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+}>>): void;
+export declare function resolveScreenTargetQn(featureName: string, target: string): string;
+export declare function validateScreenNavTarget(featureName: string, screenId: string, screenKind: string, fieldName: string, value: string, allScreenQns: ReadonlySet<string>, screens: FeatureDefinition["screens"]): void;
+export declare function validateDrawerTargetAction(featureName: string, screenId: string, screenKind: string, actionLabel: "toolbarAction" | "rowAction" | "emptyState action" | "action", action: {
+    readonly id: string;
+    readonly screen: string;
+    readonly params?: RowFieldExtractor;
+}, screens: FeatureDefinition["screens"]): void;
+export declare function isSensitiveOrPasswordField(field: object | undefined): boolean;
+export declare function validateDrawerPrefillKeys(where: string, targetLabel: "drawer-target" | "navigate-target", targetScreenId: string, target: ActionFormScreenDefinition | SecretMintScreenDefinition, params: RowFieldExtractor): void;
+type RowActionNavigateRuntime = RowActionNavigateBase & {
+    readonly screen?: string;
+    readonly entity?: string;
+};
+export declare function resolveRowActionNavigateTarget(featureName: string, screenId: string, screenType: NavigateSourceScreenType, actionLabel: string, action: RowActionNavigateRuntime, allScreenQns: ReadonlySet<string>, navTargetShortIds: ReadonlySet<string>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+}>>, detailForScreens: ReadonlyMap<string, {
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+}>): {
+    readonly featureName: string;
+    readonly screen: ScreenDefinition;
+} | undefined;
+export declare function validateRedirectTarget(feature: FeatureDefinition, screenId: string, screenKind: "actionForm" | "secretMint" | "entityEdit" | "projectionDetail", redirect: string | ActionFormRedirect, lookups: NavigateTargetLookups, propertyPath?: string): void;
+export declare function validateIdlessSuccessLink(feature: FeatureDefinition, screenId: string, screenKind: "actionForm", link: ActionFormSuccessLink, lookups: NavigateTargetLookups, propertyPath: string): void;
+export declare function validateClientActionName(featureName: string, screenId: string, screenKind: string, actionLabel: "rowAction" | "emptyState action" | "action", action: Extract<RowAction, {
+    readonly kind: "clientAction";
+}>): void;
+export declare function rejectRedirectOnListRowAction(featureName: string, screenId: string, screenKind: string, action: RowAction): void;
+export declare function validateRecordActionRedirect(feature: FeatureDefinition, screenId: string, screenKind: "projectionDetail" | "entityEdit", action: RowAction, lookups: NavigateTargetLookups): void;
+export declare function validatePrimaryActionTarget(featureName: string, screenId: string, screen: ProjectionDetailScreenDefinition): void;
+export declare function validateScreenVisibleWhen(feature: FeatureDefinition, screenId: string, screen: ScreenDefinition, allScreenQns: ReadonlySet<string>, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
+export type NavigateTargetLookups = {
+    readonly allScreenQns: ReadonlySet<string>;
+    readonly navTargetShortIds: ReadonlySet<string>;
+    readonly screensByShortId: ReadonlyMap<string, ReadonlyArray<{
+        readonly featureName: string;
+        readonly screen: ScreenDefinition;
+    }>>;
+    readonly detailForScreens: ReadonlyMap<string, {
+        readonly featureName: string;
+        readonly screen: ScreenDefinition;
+    }>;
+};
+export declare function validateNavigateActionTab(featureName: string, screenId: string, screenType: NavigateSourceScreenType, actionLabel: string, action: RowAction, lookups: NavigateTargetLookups): void;
+export {};