@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/dist/db/tenant-db.js

@@ -1,11 +1,12 @@
 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 { 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 { hasFieldProperty, tableNameOf } from "./table-introspection.js";
-import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.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
@@ -220,6 +221,12 @@ 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;
@@ -229,6 +236,19 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids a where.tenantId filter asks for; undefined for operator forms
+// that cannot narrow to a tenant list (ne, like, ...).
+export function requestedTenantIds(requested) {
+    if (Array.isArray(requested))
+        return requested;
+    if (!isPlainObject(requested))
+        return [requested];
+    if (Array.isArray(requested["in"]))
+        return requested["in"];
+    if ("eq" in requested)
+        return [requested["eq"]];
+    return undefined;
+}
 function isForeignTenantId(tenantIdValue) {
     return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
 }
@@ -354,7 +374,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = Array.isArray(requested) ? requested : [requested];
+            const requestedList = requestedTenantIds(requested) ?? [];
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -390,6 +410,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 ?? "";
     }
@@ -437,7 +461,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));
@@ -447,7 +472,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));
@@ -460,7 +486,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) {
@@ -509,6 +537,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") {
@@ -524,6 +555,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."));
             }
@@ -537,6 +571,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."));
             }
@@ -573,10 +610,18 @@ 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)
         bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
+// Tenant-mode TenantDb whose writes reach the registry's custom projections. The positional
+// undefineds of createTenantDb would hide a moved grants parameter from the type checker.
+export function createProjectingTenantDb(db, tenantId, projectionRegistry) {
+    return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionRegistry ? { projectionRegistry } : undefined);
+}
 export { asRawClient };

package/dist/derivatives/delete-stored-file.d.ts

@@ -1,6 +1,10 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
 export type StoredFileStore = {
     list(prefix: string): Promise<readonly string[]>;
     delete(key: string): Promise<void>;
 };
 export declare function listDerivativeKeys(originalKey: string, store: Pick<StoredFileStore, "list">, errorContext: string): Promise<readonly string[]>;
 export declare function deleteStoredFileAndDerivatives(originalKey: string, store: StoredFileStore, errorContext: string): Promise<readonly string[]>;
+export declare function deleteFileRefBytes(files: FileContext, row: {
+    readonly storageKey: string;
+}, errorContext: string): Promise<readonly string[]>;

package/dist/derivatives/delete-stored-file.js

@@ -68,3 +68,12 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
     }
     return failedKeys;
 }
+// deleteStoredFileAndDerivatives through ctx.files for a key read from a tenant-filtered fileRef
+// row. After a tenant handover the key keeps the previous tenant's prefix, which ref() and list()
+// reject; every key the helper deletes is the original or one of its derivatives.
+export function deleteFileRefBytes(files, row, errorContext) {
+    return deleteStoredFileAndDerivatives(row.storageKey, {
+        list: () => files.listFromFileRef(row),
+        delete: (key) => files.refFromFileRef({ storageKey: key }).delete(),
+    }, errorContext);
+}

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/index.d.ts

@@ -1,5 +1,5 @@
 export type { StoredFileStore } from "./delete-stored-file.js";
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export type { DerivativesContextDeps } from "./derivatives-context.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";

package/dist/derivatives/index.js

@@ -1,4 +1,4 @@
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";
 export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";

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;