@cosmicdrift/kumiko-framework 0.382.0 → 0.383.1

package/dist/db/connection.js

@@ -4,6 +4,13 @@ import { readPositiveIntEnv } from "../utils/env-parse.js";
 // so a plain end() (no timeout = wait for queries to finish) hangs forever —
 // close() must always bound how long shutdown waits.
 export const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+// Keyed by the pool so withoutStatementTimeout can open a sibling with identical connect options.
+const unboundedSiblingFactories = new WeakMap();
+export function openUnboundedSiblingPool(db) {
+    if (typeof db !== "function" && (typeof db !== "object" || db === null))
+        return undefined;
+    return unboundedSiblingFactories.get(db)?.();
+}
 export function createDbConnection({ url, ...options }) {
     const pgOptions = {};
     if (options.maxConnections !== undefined)
@@ -18,13 +25,51 @@ export function createDbConnection({ url, ...options }) {
         pgOptions.ssl = options.ssl;
     if (options.onNotice !== undefined)
         pgOptions.onnotice = options.onNotice;
+    const serverParameters = {};
+    if (options.statementTimeoutMs !== undefined) {
+        serverParameters["statement_timeout"] = options.statementTimeoutMs;
+    }
+    if (options.idleInTransactionSessionTimeoutMs !== undefined) {
+        serverParameters["idle_in_transaction_session_timeout"] =
+            options.idleInTransactionSessionTimeoutMs;
+    }
+    if (options.lockTimeoutMs !== undefined)
+        serverParameters["lock_timeout"] = options.lockTimeoutMs;
+    if (Object.keys(serverParameters).length > 0)
+        pgOptions.connection = serverParameters;
     const client = postgres(url, pgOptions);
+    // A run that never settles (a caller gave up on it via its own timeout) never reaches the
+    // sibling's own close; close() ends it so shutdown and DROP DATABASE are not blocked by it.
+    const openSiblings = new Set();
+    unboundedSiblingFactories.set(client, () => {
+        // Two connections are enough for lock-in-tx plus DDL; the cap keeps parallel rebuilds from exhausting max_connections.
+        const sibling = postgres(url, {
+            ...pgOptions,
+            max: 4,
+            connection: { ...pgOptions.connection, statement_timeout: 0 },
+        });
+        openSiblings.add(sibling);
+        return {
+            client: sibling,
+            close: async (timeoutSeconds) => {
+                openSiblings.delete(sibling);
+                await sibling.end({ timeout: timeoutSeconds });
+            },
+        };
+    });
     return {
         db: client,
         client,
-        close: () => client.end({
-            timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
-        }),
+        close: async () => {
+            const timeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
+            unboundedSiblingFactories.delete(client);
+            const pools = [client, ...openSiblings];
+            openSiblings.clear();
+            const results = await Promise.allSettled(pools.map((pool) => pool.end({ timeout })));
+            const failure = results.find((result) => result.status === "rejected");
+            if (failure !== undefined)
+                throw failure.reason;
+        },
     };
 }
 // DB_PROVIDER=bun selected the removed Bun.SQL driver; ignoring it would boot
@@ -49,6 +94,21 @@ export function dbConnectionOptionsFromEnv(env = process.env) {
         opts.connectTimeoutSeconds = connect;
     return opts;
 }
+export const DEFAULT_SERVER_STATEMENT_TIMEOUT_MS = 60_000;
+// Handlers that await external calls inside a tx must not be killed; five minutes still ends leaked transactions.
+export const DEFAULT_SERVER_IDLE_IN_TRANSACTION_TIMEOUT_MS = 300_000;
+// Long-running servers (prod app, worker) bound runaway statements and tx held
+// open by a stuck handler; one-shot CLIs keep the unbounded driver default.
+export function serverTimeoutOptionsFromEnv(env = process.env) {
+    const lockTimeoutMs = readPositiveIntEnv(env, "DATABASE_LOCK_TIMEOUT_MS");
+    return {
+        statementTimeoutMs: readPositiveIntEnv(env, "DATABASE_STATEMENT_TIMEOUT_MS") ??
+            DEFAULT_SERVER_STATEMENT_TIMEOUT_MS,
+        idleInTransactionSessionTimeoutMs: readPositiveIntEnv(env, "DATABASE_IDLE_IN_TRANSACTION_TIMEOUT_MS") ??
+            DEFAULT_SERVER_IDLE_IN_TRANSACTION_TIMEOUT_MS,
+        ...(lockTimeoutMs !== undefined && { lockTimeoutMs }),
+    };
+}
 // Outside-tx access runs on its own pool: sharing the write pool deadlocks once
 // pool-max concurrent writes each hold a tx and then wait for a second connection.
 export const DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX = 3;

package/dist/db/index.d.ts

@@ -5,7 +5,7 @@ export { collectTableMetas } from "./collect-table-metas.ts";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.ts";
 export { seedConfigValues } from "./config-seed.ts";
 export type { CreateDbConnectionOptions, DbConnection, DbConnectionHandle, DbConnectionOptions, DbRow, DbRunner, DbTx, } from "./connection.ts";
-export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "./connection.ts";
+export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "./connection.ts";
 export type { CursorQueryOptions, CursorResult, DecodedKeysetCursor } from "./cursor.ts";
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.ts";
 export type { SchemaTable, SelectQuery, TableColumns } from "./dialect.ts";
@@ -36,6 +36,7 @@ export { renderTableDdl, renderTablesDdl } from "./render-ddl.ts";
 export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.ts";
 export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.ts";
 export { tableExists } from "./schema-inspection.ts";
+export { withoutStatementTimeout } from "./statement-timeout.ts";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, type ExecutorManagedRunner, type ExecutorManagedWriteCapability, physicalColumnName, toSnakeCase, toTableName, type Writable, type WritableSchemaTable, type WritableTable, } from "./table-builder.ts";
 export type { CreateTenantDbOptions, ExecutorManagedTenantDb, OutsideTransactionContext, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
 export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";

package/dist/db/index.js

@@ -4,7 +4,7 @@ export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recor
 export { collectTableMetas } from "./collect-table-metas.js";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 export { seedConfigValues } from "./config-seed.js";
-export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "./connection.js";
+export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, serverTimeoutOptionsFromEnv, } from "./connection.js";
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
 export { bigint, bigserial, boolean, extractTableName, index, instant, instantToDriver, integer, jsonb, moneyAmount, numeric, primaryKey, serial, sql, table, text, timestamp, uniqueIndex, uuid, } from "./dialect.js";
 export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "./eagerload.js";
@@ -29,5 +29,6 @@ export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
 export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migration-sql.js";
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
+export { withoutStatementTimeout } from "./statement-timeout.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/migrate-runner.js

@@ -239,6 +239,8 @@ export async function runMigrations(db, migrations) {
     // which would leave the lock held on a session nobody unlocks.
     const conn = await reserveConnection(db);
     try {
+        // Server pools cap statement_timeout; a migration (backfill, index build) must not hit it.
+        await conn.unsafe("SET statement_timeout = 0");
         await conn.unsafe(MIGRATIONS_TABLE_DDL);
         await conn.unsafe(`SELECT pg_advisory_lock(${MIGRATION_ADVISORY_LOCK_KEY})`);
         try {
@@ -282,6 +284,8 @@ export async function runMigrations(db, migrations) {
         }
     }
     finally {
+        // A dead connection fails RESET; the pool drops it, so the migration's own outcome wins.
+        await conn.unsafe("RESET statement_timeout").catch(() => undefined);
         await conn.release();
     }
 }

package/dist/db/queries/backfill-pii.js

@@ -67,6 +67,7 @@ import { collectPiiEncryptedFields, nonEmptyString, resolveEventSubject, resolve
 import { resolveTableName } from "../entity-table-meta.js";
 import { asRawClient } from "../query.js";
 import { tableExists } from "../schema-inspection.js";
+import { withoutStatementTimeout } from "../statement-timeout.js";
 import { toSnakeCase } from "../table-builder.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"];
@@ -90,7 +91,10 @@ function requireLocalKeySubjectKms(caller) {
     }
     return kms;
 }
-export async function backfillEventPiiEncryption(db, registry, options = {}) {
+export function backfillEventPiiEncryption(db, registry, options = {}) {
+    return withoutStatementTimeout(db, (unboundedDb) => backfillAllEventBatches(unboundedDb, registry, options));
+}
+async function backfillAllEventBatches(db, registry, options) {
     requireLocalKeySubjectKms("backfillEventPiiEncryption");
     const total = {
         scannedEvents: 0,

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

@@ -1,5 +1,6 @@
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
 import { asRawClient, runInNewTransaction, runnerCanBeginTransaction, unsafeReadRetrying, } from "../query.js";
+import { withoutStatementTimeout } from "../statement-timeout.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 // Gap-finality (event-dispatcher pending_gaps) needs every holder of an
 // event id to already have a *real* xact id by the time it inserts — Postgres
@@ -48,7 +49,10 @@ async function indexValidity(client, indexName = IDEMPOTENCY_INDEX_NAME) {
         `WHERE c.relname = $1 AND i.indrelid = '"kumiko_events"'::regclass`, [indexName]);
     return rows[0]?.indisvalid;
 }
-export async function ensureIdempotencyKeyIndex(db) {
+export function ensureIdempotencyKeyIndex(db) {
+    return withoutStatementTimeout(db, buildIdempotencyKeyIndex);
+}
+async function buildIdempotencyKeyIndex(db) {
     const client = asRawClient(db);
     try {
         // 1) A prior CONCURRENTLY build that got killed mid-flight (crash, deploy
@@ -89,7 +93,10 @@ export async function ensureIdempotencyKeyIndex(db) {
 // tenant_id column — cross-tenant SystemAdmin adds land under the actor's
 // tenant), which no other index covers: without this it scans every event.
 // Same CONCURRENTLY + INVALID-rebuild handling as the idempotency index.
-export async function ensureMembershipPayloadTenantIndex(db) {
+export function ensureMembershipPayloadTenantIndex(db) {
+    return withoutStatementTimeout(db, buildMembershipPayloadTenantIndex);
+}
+async function buildMembershipPayloadTenantIndex(db) {
     const client = asRawClient(db);
     try {
         if ((await indexValidity(client, MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME)) === false) {

package/dist/db/statement-timeout.d.ts

@@ -0,0 +1,2 @@
+import { type PgClient } from "./connection.ts";
+export declare function withoutStatementTimeout<R, T>(db: R, run: (db: R | PgClient) => Promise<T>): Promise<T>;

package/dist/db/statement-timeout.js

@@ -0,0 +1,18 @@
+import { openUnboundedSiblingPool } from "./connection.js";
+const UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS = 5;
+// Server pools cap statement_timeout (see serverTimeoutOptionsFromEnv); index builds, reindex,
+// PII backfill and projection rebuilds legitimately run longer. The cap is a connect-time session
+// setting, so the run gets its own short-lived pool with the same options minus the cap: one shared
+// connection would deadlock code that holds a lock in a tx while its DDL runs on another connection.
+// Handles not created by createDbConnection (tx, savepoint, siblings) are passed through.
+export async function withoutStatementTimeout(db, run) {
+    const unbounded = openUnboundedSiblingPool(db);
+    if (unbounded === undefined)
+        return run(db);
+    try {
+        return await run(unbounded.client);
+    }
+    finally {
+        await unbounded.close(UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS);
+    }
+}

package/dist/db/tenant-db.js

@@ -1,6 +1,7 @@
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
+import { assertReason } from "../engine/escape-hatch-reason.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
@@ -152,9 +153,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             }
             return sourceRunner(forwardedDeclaredStep ? reason : undefined);
         }
-        if (reason.trim().length === 0) {
-            throw new Error("unsafeRaw requires a non-empty reason");
-        }
+        assertReason("ctx.systemDb.unsafeRaw(reason)", reason);
         if (gate && !hasGrant(gate.grant)) {
             throw new AccessDeniedError({
                 message: 'ctx.systemDb.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
@@ -189,9 +188,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             return rows;
         },
         acknowledgeCrossTenant(reason) {
-            if (reason.trim().length === 0) {
-                throw new Error("acknowledgeCrossTenant requires a non-empty reason");
-            }
+            assertReason("acknowledgeCrossTenant(reason)", reason);
             report("acknowledge-cross-tenant", reason);
             return db;
         },
@@ -206,9 +203,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                 return requireSystemOutsideTransactionDb();
             },
             acknowledgeCrossTenant(reason) {
-                if (reason.trim().length === 0) {
-                    throw new Error("acknowledgeCrossTenant requires a non-empty reason");
-                }
+                assertReason("acknowledgeCrossTenant(reason)", reason);
                 const result = requireSystemOutsideTransactionDb();
                 report("acknowledge-cross-tenant", reason);
                 return result;
@@ -306,9 +301,7 @@ const crossTenantUseReporters = new WeakMap();
 // `deferReport` leaves the audit entry to reportConventionCrossTenantUse, so a caller that learns
 // which foreign row it touches can attach that row as the entry's target.
 export function acknowledgeConventionCrossTenant(tenantDb, reason, options) {
-    if (reason.trim().length === 0) {
-        throw new Error("acknowledgeConventionCrossTenant requires a non-empty reason");
-    }
+    assertReason("acknowledgeConventionCrossTenant", reason);
     const rebind = crossTenantRebinders.get(tenantDb);
     if (!rebind) {
         throw new InternalError({

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

@@ -1,5 +1,5 @@
 import { escapeHatchGrantsProblem, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
-import { codemodPlaceholderReasonProblem } from "../escape-hatch-reason.js";
+import { reasonProblem } from "../escape-hatch-reason.js";
 import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../personal-data-fields.js";
 import { ANONYMOUS_ROLE } from "../system-user.js";
 import { collectZodObjectKeys } from "./zod-shape.js";
@@ -24,16 +24,16 @@ function candidatePersonalFieldNames(feature, handlerName, handler, honorOwnerBi
     }
     return names;
 }
-// Not an object with a non-empty string `reason` (incl. deprecated `openToAll: true`) counts as "empty".
-function openToAllReasonIsEmpty(access) {
+// Not an object with a string `reason` (incl. deprecated `openToAll: true`) counts as malformed.
+function openToAllReasonOf(access) {
     if (!("openToAll" in access))
-        return false;
+        return undefined;
     const openToAll = access.openToAll;
     if (typeof openToAll !== "object" || openToAll === null)
-        return true;
+        return "";
     if (!("reason" in openToAll) || typeof openToAll.reason !== "string")
-        return true;
-    return openToAll.reason.trim().length === 0;
+        return "";
+    return openToAll.reason;
 }
 function hasOpenToAll(access) {
     return "openToAll" in access;
@@ -42,11 +42,16 @@ function declaresTenantMembersPersonalData(access) {
     return declaredPersonalData(access) === "tenant-members";
 }
 function validateOpenToAllReason(feature, kind, handlerName, access) {
+    const reason = openToAllReasonOf(access);
+    // skip: no openToAll declared
+    if (reason === undefined)
+        return;
+    const problem = reasonProblem(reason);
     // skip: reason is well-formed, nothing to validate
-    if (!openToAllReasonIsEmpty(access))
+    if (problem === undefined)
         return;
     throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
-        '{ openToAll: ... } — must be { reason: "<non-empty explanation>" } for why any ' +
+        `{ openToAll: ... } — ${problem}. Must be { reason: "<explanation>" } for why any ` +
         "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.");
 }
 function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
@@ -55,15 +60,9 @@ function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
         if (grantsProblem !== undefined) {
             throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${grantsProblem}`);
         }
-        if (escapeHatch.reason.trim().length === 0) {
-            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
-                `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
-                "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
-                "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
-        }
-        const placeholderProblem = codemodPlaceholderReasonProblem(escapeHatch.reason);
-        if (placeholderProblem !== undefined) {
-            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${placeholderProblem}`);
+        const problem = reasonProblem(escapeHatch.reason);
+        if (problem !== undefined) {
+            throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid escapeHatch — ${problem}`);
         }
     }
 }

package/dist/engine/boot-validator/query-output-columns.js

@@ -1,6 +1,5 @@
 import { isPagedQueryHandler } from "../define-handler.js";
 import { normalizeListColumn, sectionFieldSpecs } from "../screen-helpers.js";
-import { metricField } from "../types/index.js";
 import { buildQueryHandlerMap } from "./projection-list-screens.js";
 import { validateActionFieldRefs } from "./screens.js";
 import { getZodObjectShape, getZodRowShape } from "./zod-shape.js";
@@ -106,7 +105,7 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
         checkFieldExists(recordShape, field, () => `${prefix} recordTitleField references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     for (const metric of screen.metrics ?? []) {
-        const field = metricField(metric);
+        const field = metric.field;
         checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     checkDetailSectionFields(recordShape, prefix, screen);

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

@@ -16,7 +16,6 @@ import { parseRefTarget } from "../parse-ref-target.js";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
 import { explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../screen-helpers.js";
-import { metricField } from "../types/index.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
 import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
@@ -719,11 +718,11 @@ function validateFormMoneyCurrency(featureName, screenId, context, fieldName, fd
 // `fields`/`groups` are mutually exclusive on a fields-kind section; shared by
 // every EditLayout-walking screen type instead of four hand-rolled copies.
 function validateFieldsXorGroups(errorPrefix, section) {
-    if (section.fields.length > 0 && section.groups !== undefined) {
-        throw new Error(`${errorPrefix} section "${section.title}" declares both fields and groups — pass fields: [] ` +
-            `when using groups.`);
+    if (section.fields !== undefined && section.groups !== undefined) {
+        throw new Error(`${errorPrefix} section "${section.title}" declares both fields and groups — remove ` +
+            `\`fields: []\` when using groups.`);
     }
-    if (section.fields.length === 0 && (section.groups?.length ?? 0) === 0) {
+    if ((section.fields?.length ?? 0) === 0 && (section.groups?.length ?? 0) === 0) {
         throw new Error(`${errorPrefix} has a section "${section.title}" with zero fields — drop the section or add ` +
             `fields (or groups) to it.`);
     }
@@ -1363,8 +1362,9 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             if (screen.layout.mode === "tabs") {
                 validateTabSections(feature.name, screenId, "projectionDetail", screen.layout.sections);
                 for (const section of screen.layout.sections) {
-                    const isFieldsSection = section.kind === undefined || section.kind === "fields";
-                    if (isFieldsSection && section.groups !== undefined && section.actions !== undefined) {
+                    if (isFieldsEditSection(section) &&
+                        "groups" in section &&
+                        section.actions !== undefined) {
                         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.id}" ` +
                             `declares both groups and actions in tabs mode — actions has no single group's Card to sit ` +
                             `in, and an extra title-less Card around the group cards would nest a Card inside a Card. ` +
@@ -1374,14 +1374,13 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             }
             if (screen.metrics !== undefined) {
                 for (const metric of screen.metrics) {
-                    const field = metricField(metric);
-                    const hasOwnLabel = typeof metric !== "string" && metric.label !== undefined;
-                    if (!hasOwnLabel && screen.fieldLabels?.[field] === undefined) {
+                    const field = metric.field;
+                    if (typeof metric.label !== "string" || metric.label.length === 0) {
                         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" has ` +
-                            `no entry in fieldLabels and no own "label" — every metrics field needs one of the two, ` +
+                            `no "label" — every metric needs an i18n label key, ` +
                             `there is no fallback to the raw column name.`);
                     }
-                    const navigate = typeof metric === "string" ? undefined : metric.navigate;
+                    const navigate = metric.navigate;
                     if (navigate !== undefined) {
                         if (navigate.screen === undefined && navigate.entity === undefined) {
                             if (navigate.tab !== undefined &&
@@ -1525,14 +1524,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                             `(writeForm) has zero fields — drop the section or add fields to it.`);
                     }
                     // A ref to a fieldDef the form never renders would never resolve.
-                    const writeFormFieldNames = new Set(
-                    // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
-                    section.fields.map((f) => normalizeEditField(f).field));
+                    const writeFormFieldNames = new Set(section.fields.map((f) => normalizeEditField(f).field));
                     for (const [defName, fdef] of Object.entries(section.fieldDefs)) {
                         validateFormSelectOptions(feature.name, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef, writeFormFieldNames);
                         rejectWriteOnlyFormField(feature.name, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef);
                     }
-                    // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
                     for (const f of section.fields) {
                         const fieldName = normalizeEditField(f).field;
                         if (section.fieldDefs[fieldName] === undefined) {

package/dist/engine/boot-validator/url-prefill-fields.js

@@ -29,9 +29,7 @@ function projectionDetailNavigateActions(screen) {
                     pick: [relatedListParentParamField(section)],
                 }),
             ]),
-        ...(screen.metrics ?? []).flatMap((metric) => typeof metric === "string" || metric.navigate === undefined
-            ? []
-            : scopeActions([metric.navigate], undefined)),
+        ...(screen.metrics ?? []).flatMap((metric) => metric.navigate === undefined ? [] : scopeActions([metric.navigate], undefined)),
         ...subtitlePartNavigates(screen).flatMap((navigate) => scopeActions([navigate], undefined)),
     ];
 }

package/dist/engine/build-config-feature-schema.js

@@ -20,7 +20,7 @@ import { isEncryptedAtRest } from "./config-helpers.js";
 import { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
 import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
 import { isKebabSegment, toKebab } from "./qualified-name.js";
-import { isFieldsEditSection, sectionFieldSpecs } from "./screen-helpers.js";
+import { isFieldsEditSection, sectionFieldSpecs, } from "./screen-helpers.js";
 import { isOpenToAllGranted } from "./types/handlers.js";
 // Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
 // (find-or-create FeatureSchema). MUSS gleich CONFIG_FEATURE aus dem config
@@ -349,9 +349,10 @@ class ProviderFormBuilder {
         const section = pluginScreen.layout.sections.find(isFieldsEditSection);
         if (section === undefined)
             return undefined;
-        const { groups: _groups, ...flatSection } = section;
+        const widened = section;
+        const { groups: _groups, fields: _fields, ...sectionBase } = widened;
         const gated = {
-            ...flatSection,
+            ...sectionBase,
             fields: gateFields(sectionFieldSpecs(section), visible),
         };
         this.sections.push(gated);
@@ -374,7 +375,6 @@ class ProviderFormBuilder {
         this.requiredFields.push(...(secretsScreen.requiredFields ?? []));
         const secretsTitleKey = `${feature}.settings.secrets`;
         for (const section of secretsScreen.sections) {
-            // kumiko-lint-ignore section-fields-raw a secretsEdit section is a flat key list without groups
             const fields = gateFields(section.fields, visible);
             const ownSection = section.title === secretsTitleKey || pluginSection === undefined;
             if (ownSection) {

package/dist/engine/entity-handlers.js

@@ -8,7 +8,7 @@ import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
-import { codemodPlaceholderReasonProblem } from "./escape-hatch-reason.js";
+import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
@@ -60,12 +60,7 @@ function isSystemAdminOnly(access) {
 function resolveCrossTenantReason(name, options, kind) {
     if (options.escapeHatch === undefined)
         return undefined;
-    if (options.escapeHatch.reason.trim().length === 0) {
-        throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
-    }
-    const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
-    if (placeholderProblem !== undefined)
-        throw new Error(`"${name}": ${placeholderProblem}`);
+    assertReason(`"${name}": escapeHatch`, options.escapeHatch.reason);
     assertEscapeHatchAccessIsSystemAdminOnly(name, kind, options.access);
     return options.escapeHatch.reason;
 }
@@ -528,6 +523,9 @@ export function createEntityExecutor(entityName, entity) {
 // For anything more involved (filters, joins, custom shaping), write the
 // query-handler explicitly with ctx.queryProjection or a raw select.
 export function defineProjectionQueryHandler(name, projectionQualifiedName, options) {
+    if (typeof options.unsafeAllTenants === "object") {
+        assertReason(`"${name}": unsafeAllTenants`, options.unsafeAllTenants.reason);
+    }
     const escapeHatch = options.escapeHatch ??
         (typeof options.unsafeAllTenants === "object"
             ? { reason: options.unsafeAllTenants.reason }

package/dist/engine/escape-hatch-declaration.d.ts

@@ -1,2 +1,2 @@
 import type { EscapeHatchDeclaration } from "@cosmicdrift/kumiko-types/handlers";
-export declare function declareEscapeHatch(_declaration: EscapeHatchDeclaration): void;
+export declare function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;

package/dist/engine/escape-hatch-declaration.js

@@ -1,5 +1,8 @@
+import { assertReason } from "./escape-hatch-reason.js";
 // Marks a standalone helper that escalates on a HandlerContext handed to it
 // by its caller. The caller's registration carries the escapeHatch that
 // authorizes it; this call makes the escalation visible at the site where it
-// happens, where the guard and a reviewer both see it.
-export function declareEscapeHatch(_declaration) { }
+// happens and rejects an empty or placeholder reason.
+export function declareEscapeHatch(declaration) {
+    assertReason("declareEscapeHatch", declaration.reason);
+}

package/dist/engine/escape-hatch-reason.d.ts

@@ -1,2 +1,4 @@
 export declare const CODEMOD_PLACEHOLDER_REASON_MARKER = "state the operator use case here";
 export declare function codemodPlaceholderReasonProblem(reason: string): string | undefined;
+export declare function reasonProblem(reason: string): string | undefined;
+export declare function assertReason(callerLabel: string, reason: string): void;

package/dist/engine/escape-hatch-reason.js

@@ -6,3 +6,38 @@ export function codemodPlaceholderReasonProblem(reason) {
         return undefined;
     return `the reason still contains the migrate-cross-tenant codemod placeholder ("${CODEMOD_PLACEHOLDER_REASON_MARKER}") — replace the codemod placeholder with the real operator use case`;
 }
+// Compared after trim, lowercase and stripping trailing punctuation.
+const PLACEHOLDER_REASONS = new Set([
+    "todo",
+    "tbd",
+    "fixme",
+    "legacy",
+    "temp",
+    "temporary",
+    "hack",
+    "wip",
+    "n/a",
+    "na",
+    "none",
+    "-",
+    "?",
+    "reason",
+    "xxx",
+]);
+const PLACEHOLDER_REASON_PREFIXES = ["todo:", "fixme:", "tbd:"];
+export function reasonProblem(reason) {
+    const lowered = reason.trim().toLowerCase();
+    if (lowered.length === 0)
+        return "the reason must be a non-empty explanation";
+    const stripped = lowered.replace(/[.!:;,]+$/, "").trim();
+    if (PLACEHOLDER_REASON_PREFIXES.some((prefix) => lowered.startsWith(prefix)) ||
+        PLACEHOLDER_REASONS.has(stripped)) {
+        return `the reason "${reason.trim()}" is a placeholder — state why this access is needed`;
+    }
+    return codemodPlaceholderReasonProblem(reason);
+}
+export function assertReason(callerLabel, reason) {
+    const problem = reasonProblem(reason);
+    if (problem !== undefined)
+        throw new Error(`${callerLabel}: ${problem}`);
+}

package/dist/engine/extensions/escape-hatch-usage.js

@@ -4,6 +4,7 @@
 // empty reason, but options stays `Record<string, unknown>`, so orchestrators
 // re-narrow at read time instead of trusting the shape.
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { reasonProblem } from "../escape-hatch-reason.js";
 export function extensionUsageEscapeHatchReason(usage) {
     const escapeHatch = usage.options?.["escapeHatch"];
     if (!isPlainObject(escapeHatch))
@@ -11,5 +12,5 @@ export function extensionUsageEscapeHatchReason(usage) {
     const { reason, grants } = escapeHatch;
     if (Array.isArray(grants) && !grants.includes("unsafeRaw"))
         return undefined;
-    return typeof reason === "string" && reason.trim().length > 0 ? reason : undefined;
+    return typeof reason === "string" && reasonProblem(reason) === undefined ? reason : undefined;
 }

package/dist/engine/feature-config-events-jobs.js

@@ -1,6 +1,7 @@
 import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { isValidIanaTimeZone } from "../time/iana.js";
+import { reasonProblem } from "./escape-hatch-reason.js";
 import { createEventDef } from "./event-def.js";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
@@ -79,10 +80,11 @@ export function buildConfigEventsJobsMethods(state, name) {
                     const { name: definedJobName, handler: h, ...rest } = jobNameOrDefinition;
                     return [definedJobName, rest, h];
                 })();
-            if (jobOptions.escapeHatch !== undefined &&
-                jobOptions.escapeHatch.reason.trim().length === 0) {
-                throw new Error(`[Feature ${name}] r.job("${jobName}") declares { escapeHatch: { reason: "" } } — ` +
-                    "the reason must be a non-empty string explaining why this job needs unfiltered database access.");
+            const jobReasonProblem = jobOptions.escapeHatch !== undefined
+                ? reasonProblem(jobOptions.escapeHatch.reason)
+                : undefined;
+            if (jobReasonProblem !== undefined) {
+                throw new Error(`[Feature ${name}] r.job("${jobName}") declares an invalid escapeHatch — ${jobReasonProblem}`);
             }
             const jobGrantsProblem = jobOptions.escapeHatch && escapeHatchGrantsProblem(jobOptions.escapeHatch);
             if (jobGrantsProblem) {