@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/db/table-introspection.js

@@ -0,0 +1,76 @@
+import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+// table() spreads column handles onto the table object as enumerable props, so
+// an entity field named `source`/`columns`/`tableName`/… shadows the matching
+// meta key. The symbol-keyed slots are the only collision-safe source; plain
+// metas (deriveEntityTableMeta / defineUnmanagedTable) carry no handle spread
+// and are unshadowable by their structural shape.
+export function isEntityTableMeta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "tableName" in value &&
+        typeof value.tableName === "string" &&
+        "columns" in value &&
+        Array.isArray(value.columns) &&
+        "indexes" in value &&
+        Array.isArray(value.indexes) &&
+        "source" in value &&
+        (value.source === "managed" || value.source === "unmanaged"));
+}
+export function asEntityTableMeta(table) {
+    if (typeof table !== "object" || table === null)
+        return undefined;
+    if (KUMIKO_META_SYMBOL in table && isEntityTableMeta(table[KUMIKO_META_SYMBOL])) {
+        return table[KUMIKO_META_SYMBOL];
+    }
+    return isEntityTableMeta(table) ? table : undefined;
+}
+export function requireEntityTableMeta(table, tableName) {
+    const meta = asEntityTableMeta(table);
+    if (!meta) {
+        throw new Error(`${tableName}: table carries no EntityTableMeta — built via table()?`);
+    }
+    return meta;
+}
+/** Physical table name from the unshadowable name symbol; undefined when absent. */
+export function schemaTableName(table) {
+    if (typeof table !== "object" || table === null || !(KUMIKO_NAME_SYMBOL in table)) {
+        return undefined;
+    }
+    const name = table[KUMIKO_NAME_SYMBOL];
+    return typeof name === "string" ? name : undefined;
+}
+/** Name symbol first, then the canonical meta; "<unknown>" when neither resolves. */
+export function tableNameOf(table) {
+    return schemaTableName(table) ?? asEntityTableMeta(table)?.tableName ?? "<unknown>";
+}
+/** Column-handle map stamped by table(); undefined for tables without one. */
+export function tableColumnsOf(table) {
+    if (typeof table !== "object" || table === null || !(KUMIKO_COLUMNS_SYMBOL in table)) {
+        return undefined;
+    }
+    const columns = table[KUMIKO_COLUMNS_SYMBOL];
+    return isPlainObject(columns) ? columns : undefined;
+}
+/** SQL name carried by the enumerable column handle `table[field]`; undefined when the field has none. */
+export function columnHandleName(table, field) {
+    if (!isPlainObject(table))
+        return undefined;
+    const handle = table[field];
+    if (!isPlainObject(handle))
+        return undefined;
+    const name = handle["name"];
+    return typeof name === "string" ? name : undefined;
+}
+/** True when `table[field]` is defined, i.e. the table exposes a column handle (or plain value) for the field. */
+export function hasFieldProperty(table, field) {
+    return isPlainObject(table) && table[field] !== undefined;
+}
+/** SQL column name of a JS field via the column-handle map; undefined when not mapped. */
+export function columnSqlNameOf(table, field) {
+    const handle = tableColumnsOf(table)?.[field];
+    if (!isPlainObject(handle))
+        return undefined;
+    const name = handle["name"];
+    return typeof name === "string" ? name : undefined;
+}

package/dist/db/tenant-db-runner.d.ts

@@ -1,4 +1,8 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../errors/index.js";
 import type { DbRunner } from "./connection.js";
 export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
+export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;
+export declare function tenantDbWritesDeniedError(operation: string, reason: string): InternalError;
+export declare function tenantDbWriteRunner(tenantDb: TenantDb, operation: string): DbRunner;

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

@@ -15,3 +15,20 @@ export function tenantDbRunner(tenantDb) {
     }
     return runner;
 }
+const writesDeniedReasons = new WeakMap();
+export function denyTenantDbWrites(tenantDb, reason) {
+    writesDeniedReasons.set(tenantDb, reason);
+}
+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`,
+    });
+}
+// For framework code that writes through the raw runner (executor verbs, event appends, projection steps):
+// the TenantDb's own write methods are denied via TenantDbGrants, this closes the runner-based door.
+export function tenantDbWriteRunner(tenantDb, operation) {
+    const reason = writesDeniedReasons.get(tenantDb);
+    if (reason !== undefined)
+        throw tenantDbWritesDeniedError(operation, reason);
+    return tenantDbRunner(tenantDb);
+}

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

@@ -1,6 +1,6 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
 import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
-import { type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asRawClient } from "../db/query.js";
 import type { EntityDefinition } from "../engine/types/fields.js";
@@ -8,6 +8,7 @@ import { type TenantId } from "../engine/types/identifiers.js";
 import type { Registry } from "../engine/types/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
 import type { DbRunner } from "./connection.js";
+import { tableNameOf } from "./table-introspection.js";
 type Table = SchemaTable;
 export { SYSTEM_SCOPE_CHECK_BRAND, type TenantDb, type TenantDbMode, type UncheckedSystemDb, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 export declare function assertPersonalDataWrite(db: TenantDb, tableName: string, keys: readonly string[], entity: EntityDefinition): void;
@@ -15,8 +16,9 @@ export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSys
 export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): 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;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
-export declare function tableNameOf(table: Table | EntityTableMeta): string;
+export { tableNameOf };
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
 export type TenantDbGrants = {
     readonly globalWrites?: EscapeHatchDeclaration;
@@ -25,6 +27,7 @@ export type TenantDbGrants = {
     readonly memberReadOnly?: boolean;
     readonly personalDataGate?: PersonalDataGate;
     readonly projectionRegistry?: Registry;
+    readonly writesDeniedReason?: string;
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;

package/dist/db/tenant-db.js

@@ -1,11 +1,11 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 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 { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
-import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
+import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } 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
@@ -53,7 +53,6 @@ function boundRunner(runner, gate, projectionRegistry) {
             }
             return value.bind(target);
         },
-        // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
     });
     if (gate)
         runnerPersonalDataGates.set(proxy, gate);
@@ -221,16 +220,17 @@ export function createUncheckedSystemDb(db, dbOutsideTransaction, report = fallb
 export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEscapeHatchReporter(db.tenantId)) {
     return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
 }
+// Narrows a (possibly "system"-mode) TenantDb to a "tenant"-mode handle for one tenant on the
+// 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(tenantDbRunner(db), tenantId, "tenant");
+}
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
     return rows;
 }
-export function tableNameOf(table) {
-    const sym = table[KUMIKO_NAME_SYMBOL];
-    if (typeof sym === "string")
-        return sym;
-    return asEntityTableMeta(table)?.tableName ?? "<unknown>";
-}
+export { tableNameOf };
 // A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
@@ -247,7 +247,7 @@ export function hasTenantColumn(table) {
     const meta = asEntityTableMeta(table);
     if (meta)
         return meta.columns.some((c) => c.name === "tenant_id");
-    return table["tenantId"] !== undefined;
+    return hasFieldProperty(table, "tenantId");
 }
 const unsafeRawRebinders = new WeakMap();
 // Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
@@ -396,6 +396,10 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             message: `db.global(${tableNameOf(table)}): writes on executor-managed entity tables must go through the entity executor`,
         });
     }
+    function writesDenied(operation) {
+        const reason = grants?.writesDeniedReason;
+        return reason === undefined ? undefined : tenantDbWritesDeniedError(operation, reason);
+    }
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
@@ -443,7 +447,8 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("select", table, async () => bunFetchOne(db, table, where));
             },
             insertOne(values) {
-                const denied = missingEscapeHatch(table) ??
+                const denied = writesDenied("ctx.db.global().insertOne") ??
+                    missingEscapeHatch(table) ??
                     executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
                     personalDataDenied(table, Object.keys(values));
@@ -453,7 +458,8 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("insert", table, async () => bunInsertOne(db, table, values));
             },
             updateMany(set, where) {
-                const denied = missingEscapeHatch(table) ??
+                const denied = writesDenied("ctx.db.global().updateMany") ??
+                    missingEscapeHatch(table) ??
                     executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
                     personalDataDenied(table, Object.keys(set));
@@ -466,7 +472,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, where));
             },
             deleteMany(where) {
-                const denied = missingEscapeHatch(table) ?? executorManagedWriteDenied(table);
+                const denied = writesDenied("ctx.db.global().deleteMany") ??
+                    missingEscapeHatch(table) ??
+                    executorManagedWriteDenied(table);
                 if (denied)
                     return Promise.reject(denied);
                 if (!where || Object.keys(where).length === 0) {
@@ -475,7 +483,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 report("global-write", globalWriteReason());
                 return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
             },
-            // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
+            // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };
     }
     function grantedUnsafeRawRunner(declaredStepReason) {
@@ -515,6 +523,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));
         },
         insertOne(table, values) {
+            const writeDenied = writesDenied("ctx.db.insertOne");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (mode === "tenant" &&
                 hasTenantColumn(table) &&
                 asEntityTableMeta(table)?.tenancy === "global") {
@@ -530,6 +541,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("insert", table, async () => bunInsertOne(db, table, data));
         },
         updateMany(table, set, where) {
+            const writeDenied = writesDenied("ctx.db.updateMany");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.updateMany without where would mass-update all tenant rows. Pass at least one where condition."));
             }
@@ -543,6 +557,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, filter));
         },
         deleteMany(table, where) {
+            const writeDenied = writesDenied("ctx.db.deleteMany");
+            if (writeDenied)
+                return Promise.reject(writeDenied);
             if (!where || Object.keys(where).length === 0) {
                 return Promise.reject(new Error("TenantDb.deleteMany without where would mass-delete all tenant rows. Pass at least one where condition."));
             }
@@ -579,6 +596,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
     });
     bindTenantDbRunner(tenantDb, db);
+    if (grants?.writesDeniedReason !== undefined) {
+        denyTenantDbWrites(tenantDb, grants.writesDeniedReason);
+    }
     if (personalDataGate)
         personalDataGates.set(tenantDb, personalDataGate);
     if (projectionRegistry)

package/dist/derivatives/derivatives-context.js

@@ -181,7 +181,7 @@ export function createDerivativesContext(deps) {
             // Resolves qr dataTokens to concrete values BEFORE the spec is hashed
             // — see resolveOverlaySpec.
             const resolvedSpec = await resolveOverlaySpec(spec, row, deps.registry, deps.tenantId);
-            const src = deps.files.ref(row.storageKey);
+            const src = deps.files.refFromFileRef(row);
             // ponytail: derived key keeps the source extension regardless of the
             // spec's format — widen deriveKey if a storage backend ever routes on
             // extension.

package/dist/derivatives/variant-key.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 // Deterministic JSON: object keys sorted (recursively), `undefined` values
 // dropped, arrays keep their order. Two specs that are semantically equal
 // (same keys, different insertion order; explicit `undefined` vs. omitted)
@@ -7,7 +8,7 @@ export function canonicalJson(value) {
     if (Array.isArray(value)) {
         return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
     }
-    if (value !== null && typeof value === "object") {
+    if (isPlainObject(value)) {
         const entries = Object.entries(value)
             .filter(([, v]) => v !== undefined)
             .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));

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

@@ -83,7 +83,7 @@ function validatePersonalDataSupportedForKind(feature, kind, handlerName, access
         ? 'only access.personalData: "public-intake" applies to query handlers, which write ' +
             "personal data through nested writes of an anonymous request."
         : "it only applies to write handlers, whose input is checked for personal-data fields.";
-    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed}`);
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed} Remove the personalData declaration from this handler.`);
 }
 function validatePersonalDataValue(feature, kind, handlerName, access) {
     const declared = declaredPersonalData(access);
@@ -107,7 +107,7 @@ function validatePersonalDataValue(feature, kind, handlerName, access) {
     throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
         'access.personalData: "public-intake" but its roles do not include ' +
         `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
-        "that allow anonymous callers.");
+        "that allow anonymous callers. Add the anonymous role to access.roles or remove personalData.");
 }
 function handlerInputKeys(feature, handlerName, handler) {
     try {

package/dist/engine/boot-validator/api-ext.js

@@ -31,7 +31,7 @@ export function validateApiExposureMatching(feature, allExposedApis, featureMap)
         // Should always be true if allExposedApis was built from `features`,
         // aber defensiv für unklare Constructor-Pfade.
         if (!featureMap.has(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] internal: r.usesApi("${apiName}") points to provider "${providerFeature}" which is not in feature map`);
+            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.`);
         }
     }
 }
@@ -40,7 +40,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
     for (const usage of feature.extensionUsages) {
         const providerFeature = extensionProviders.get(usage.extensionName);
         if (!providerFeature) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" on entity "${usage.entityName}" but no feature defines that extension. Register the feature that defines it or fix the extension name.`);
         }
         // self-extension is legitimate: requires(self) would be circular.
         if (providerFeature === feature.name) {
@@ -48,7 +48,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}")`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires("${providerFeature}").`);
         }
     }
 }

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}`);
+                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}. Fix the condition this check reports.`);
             }
         }
     }

package/dist/engine/boot-validator/config-deps.js

@@ -38,15 +38,15 @@ export function validateConfigKeyBounds(feature) {
         }
         const { min, max } = bounds;
         if (min !== undefined && max !== undefined && min > max) {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max})`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has bounds.min (${min}) > bounds.max (${max}). Set bounds.min to a value at or below bounds.max.`);
         }
         if (keyDef.default !== undefined) {
             const defaultNum = keyDef.default; // @cast-boundary engine-payload
             if (min !== undefined && defaultNum < min) {
-                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min})`);
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is below bounds.min (${min}). Raise the default or lower bounds.min.`);
             }
             if (max !== undefined && defaultNum > max) {
-                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max})`);
+                throw new Error(`[Feature ${feature.name}] Config key "${keyName}" default (${defaultNum}) is above bounds.max (${max}). Lower the default or raise bounds.max.`);
             }
         }
     }
@@ -61,7 +61,7 @@ export function validateConfigKeyComputed(feature) {
         // cascade doesn't know which one to prefer on write. Rejecting at boot
         // is cheaper than surprising behaviour at runtime.
         if (isEncryptedAtRest(keyDef)) {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms. Use either encrypted/backing="secrets" or a computed resolver on one key.`);
         }
     }
 }
@@ -92,7 +92,7 @@ export function validateConfigKeyAllowPerRequest(feature) {
         // anyway, but declaring allowPerRequest on a text key is a
         // misconfiguration that should fail loudly at boot.
         if (keyDef.type === "text") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk)`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but type="text" — text keys are permanently ineligible for per-request overrides (XSS/injection risk). Remove allowPerRequest or change the key type.`);
         }
         // encrypted + per-request would expose a cipher-text interpretation
         // to query-strings. The secret-value shouldn't be transported this
@@ -107,16 +107,16 @@ export function validateConfigKeyOptionsQuery(feature) {
     for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
         const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
         if ("conditionalOptions" in keyDef) {
-            throw new Error(`${prefix} declares conditionalOptions — conditionalOptions is only supported on entity select fields (enforced by the entity write path)`);
+            throw new Error(`${prefix} declares conditionalOptions — conditionalOptions is only supported on entity select fields (enforced by the entity write path). Remove conditionalOptions from the config key.`);
         }
         if (keyDef.optionsQuery === undefined) {
             if (keyDef.optionsQueryPayload !== undefined) {
-                throw new Error(`${prefix} has optionsQueryPayload without optionsQuery`);
+                throw new Error(`${prefix} has optionsQueryPayload without optionsQuery. Set optionsQuery or remove optionsQueryPayload.`);
             }
             continue;
         }
         if (keyDef.optionsQuery.length === 0) {
-            throw new Error(`${prefix} has an empty optionsQuery`);
+            throw new Error(`${prefix} has an empty optionsQuery. Set it to a query name or remove it.`);
         }
         if (keyDef.type !== "select") {
             throw new Error(`${prefix} has optionsQuery but type="${keyDef.type}" — optionsQuery is only valid on select keys`);
@@ -134,7 +134,7 @@ function validateOptionsQueryKeyRefs(feature, keyName, keyDef) {
     const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
     for (const ref of optionsQueryFieldRefs(keyDef.optionsQueryPayload)) {
         if (ref === keyName) {
-            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" })`);
+            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" }). Reference a different config key.`);
         }
         if (feature.configKeys[ref] === undefined) {
             throw new Error(`${prefix} optionsQueryPayload references unknown config key "${ref}" of feature "${feature.name}"`);
@@ -166,12 +166,12 @@ export function validateConfigKeyPiiEncrypted(feature) {
         if (!keyDef.piiEncrypted)
             continue;
         if (keyDef.type !== "text") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but type="${keyDef.type}" — piiEncrypted only applies to text keys. Use type="text" or remove piiEncrypted.`);
         }
         // system scope has no subject (no tenant, no user) for the subject-KMS
         // to encrypt under.
         if (keyDef.scope === "system") {
-            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under`);
+            throw new Error(`[Feature ${feature.name}] Config key "${keyName}" has piiEncrypted=true but scope="system" — system-scope has no subject (tenant/user) for the subject-KMS to encrypt under. Use scope="tenant" or "user", or remove piiEncrypted.`);
         }
         // Mutually exclusive with the shared-cipher path: a config value is
         // either subject-keyed (piiEncrypted) or master-key-keyed (encrypted/
@@ -190,7 +190,7 @@ export function validateConfigReads(features, allConfigKeys) {
     for (const feature of features) {
         for (const key of feature.configReads) {
             if (!allConfigKeys.has(key)) {
-                throw new Error(`Feature "${feature.name}" reads config "${key}" but no feature defines that key`);
+                throw new Error(`Feature "${feature.name}" reads config "${key}" but no feature defines that key. Declare the key via r.config(...) in a feature, or fix the key name.`);
             }
         }
     }
@@ -201,7 +201,7 @@ export function validateCircularDeps(featureName, featureMap) {
     const stack = new Set();
     function visit(name, path) {
         if (stack.has(name)) {
-            throw new Error(`Circular dependency: ${[...path, name].join(" → ")}`);
+            throw new Error(`Circular dependency: ${[...path, name].join(" → ")}. Break the cycle by removing one requires() link.`);
         }
         // skip: node already visited in DFS traversal
         if (visited.has(name))

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

@@ -22,7 +22,7 @@ export function collectDetailForScreens(features, featureMap) {
             screenQnByEntity.set(detailFor, qualified);
             if (findEntityFeature(detailFor, featureMap) === undefined) {
                 throw new Error(`[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
-                    `but no feature registers an entity with that name.`);
+                    `but no feature registers an entity with that name. Set detailFor to a registered entity name or remove it.`);
             }
             result.set(detailFor, { featureName: feature.name, screen });
         }

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -7,6 +7,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 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 validateRateLimitDisabledReason(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;