@cosmicdrift/kumiko-framework 0.353.0 → 0.354.1

package/dist/db/table-builder.js

@@ -253,17 +253,17 @@ const ROW_META_WITH_SOFT_DELETE = new Set(Object.keys(buildBaseColumns(true)));
 export function rowMetaFieldNames(softDelete) {
     return softDelete ? ROW_META_WITH_SOFT_DELETE : ROW_META_BASE;
 }
-function stampGlobalTenancyMeta(table, entity) {
-    // skip: non-global entities keep pgTable's default tenancy meta
-    if (entity.tenancy !== "global")
-        return;
+// pgTable's own meta stamp sees neither entity.tenancy nor that this table is an executor-managed projection;
+// patch both so db.global()'s runtime guards match the type brands.
+function stampEntityTableMeta(table, entity) {
     const meta = table[KUMIKO_META_SYMBOL];
     // skip: no meta stamp present — nothing to patch
     if (!meta)
         return;
     table[KUMIKO_META_SYMBOL] = {
         ...meta,
-        tenancy: "global",
+        source: "managed",
+        ...(entity.tenancy === "global" && { tenancy: "global" }),
     };
 }
 /**
@@ -416,7 +416,6 @@ export function buildEntityTable(entityName, entity, options) {
         }
         return indexes;
     });
-    // pgTable's own meta stamp doesn't see entity.tenancy — patch it so db.global()'s runtime guard matches the type brand.
-    stampGlobalTenancyMeta(built, entity);
+    stampEntityTableMeta(built, entity);
     return built;
 }

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

@@ -1,5 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
-import type { EscapeHatchDeclaration, EscapeHatchReporter } from "@cosmicdrift/kumiko-types/handlers";
+import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 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";
@@ -28,7 +28,10 @@ export type TenantDbGrants = {
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;
-export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string): TenantDb;
+export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string, options?: {
+    readonly deferReport?: boolean;
+}): TenantDb;
+export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -27,7 +27,17 @@ function boundRunner(runner, gate, projectionRegistry) {
             const value = Reflect.get(target, prop, target);
             if (typeof value !== "function")
                 return value;
-            if (prop === "begin" || prop === "savepoint") {
+            if (prop === "reserve") {
+                // Bun.SQL and postgres.js hand back a raw connection; re-wrap it so the gate survives.
+                return async (...args) => {
+                    const reserved = await Reflect.apply(value, target, args);
+                    return boundRunner(reserved, gate, projectionRegistry);
+                };
+            }
+            if (prop === "begin" ||
+                prop === "transaction" ||
+                prop === "beginDistributed" ||
+                prop === "savepoint") {
                 // createTenantDb(tx, ...) inside the callback must inherit the gate too.
                 return (...args) => {
                     const callback = args[args.length - 1];
@@ -247,8 +257,11 @@ export function withUnsafeRawGrant(tenantDb, grant) {
     return rebind ? rebind(grant) : tenantDb;
 }
 const crossTenantRebinders = new WeakMap();
+const crossTenantUseReporters = new WeakMap();
 // Framework-private (not re-exported from db/index.ts): lifting the tenant filter needs a registered declaration.
-export function acknowledgeConventionCrossTenant(tenantDb, reason) {
+// `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");
     }
@@ -259,7 +272,19 @@ export function acknowledgeConventionCrossTenant(tenantDb, reason) {
                 "no cross-tenant rebinder bound.",
         });
     }
-    return rebind(reason);
+    return rebind(reason, options?.deferReport === true);
+}
+// The report that acknowledgeConventionCrossTenant(..., { deferReport: true }) held back; the
+// target keeps the 60s audit dedup from collapsing touches of different rows into one entry.
+export function reportConventionCrossTenantUse(acknowledged, target) {
+    const reporter = crossTenantUseReporters.get(acknowledged);
+    if (!reporter) {
+        throw new InternalError({
+            message: "reportConventionCrossTenantUse received a TenantDb not returned by " +
+                "acknowledgeConventionCrossTenant.",
+        });
+    }
+    reporter(target);
 }
 const ownTransactionRebinders = new WeakMap();
 export async function runInOwnTransaction(tenantDb, fn) {
@@ -363,6 +388,14 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 "writes through db.global().",
         });
     }
+    // The ExecutorOnly brand is type-only; a type-erased table must still not reach the read model without an event.
+    function executorManagedWriteDenied(table) {
+        if (asEntityTableMeta(table)?.source === "unmanaged")
+            return undefined;
+        return new AccessDeniedError({
+            message: `db.global(${tableNameOf(table)}): writes on executor-managed entity tables must go through the entity executor`,
+        });
+    }
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
@@ -411,6 +444,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             },
             insertOne(values) {
                 const denied = missingEscapeHatch(table) ??
+                    executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
                     personalDataDenied(table, Object.keys(values));
                 if (denied)
@@ -420,6 +454,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             },
             updateMany(set, where) {
                 const denied = missingEscapeHatch(table) ??
+                    executorManagedWriteDenied(table) ??
                     foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
                     personalDataDenied(table, Object.keys(set));
                 if (denied)
@@ -431,7 +466,7 @@ 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);
+                const denied = missingEscapeHatch(table) ?? executorManagedWriteDenied(table);
                 if (denied)
                     return Promise.reject(denied);
                 if (!where || Object.keys(where).length === 0) {
@@ -522,10 +557,15 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
     unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, {
         ...rebindGrants,
         unsafeRaw: grant,
+        // db.global() writes are write-handler-only: a rebind (a hook's own grant) must not inherit them.
+        globalWrites: undefined,
     }));
-    crossTenantRebinders.set(tenantDb, (reason) => {
-        report("acknowledge-cross-tenant", reason);
-        return createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
+    crossTenantRebinders.set(tenantDb, (reason, deferReport) => {
+        if (!deferReport)
+            report("acknowledge-cross-tenant", reason);
+        const acknowledged = createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
+        crossTenantUseReporters.set(acknowledged, (target) => report("acknowledge-cross-tenant", reason, target));
+        return acknowledged;
     });
     ownTransactionRebinders.set(tenantDb, async (fn) => {
         if (grants?.memberReadOnly) {

package/dist/derivatives/variant-key.d.ts

@@ -3,6 +3,7 @@ export declare function canonicalJson(value: unknown): string;
 export declare function specHash(spec: VariantSpec): string;
 export declare const VARIANT_NAME_PATTERN: RegExp;
 export declare function variantSuffix(name: string, spec: VariantSpec): string;
+export declare function isDerivativeSuffix(suffix: string): boolean;
 export declare function derivativeListPrefix(originalKey: string): string;
 export declare function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean;
 export declare function parseDerivativeKey(candidateKey: string): {

package/dist/derivatives/variant-key.js

@@ -37,6 +37,9 @@ export function variantSuffix(name, spec) {
 // The hash part stays case-sensitive (specHash emits lowercase hex only), so
 // the erasure sweep never matches a differently-cased sibling file.
 const DERIVATIVE_SUFFIX_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}-[0-9a-f]{16}$/;
+export function isDerivativeSuffix(suffix) {
+    return DERIVATIVE_SUFFIX_PATTERN.test(suffix);
+}
 // Mirrors deriveKey's own split so callers get the exact same base/ext this
 // key's derivatives were built from.
 function splitKey(key) {

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

@@ -1,4 +1,5 @@
 import { escapeHatchGrantsProblem, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
+import { codemodPlaceholderReasonProblem } 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";
@@ -60,6 +61,10 @@ function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
                 "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}`);
+        }
     }
 }
 function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {

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

@@ -106,6 +106,9 @@ export function validateConfigKeyAllowPerRequest(feature) {
 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)`);
+        }
         if (keyDef.optionsQuery === undefined) {
             if (keyDef.optionsQueryPayload !== undefined) {
                 throw new Error(`${prefix} has optionsQueryPayload without optionsQuery`);

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

@@ -20,6 +20,7 @@ export declare function validateReferenceFields(feature: FeatureDefinition, feat
 export declare function validateEmbeddedFields(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
 export declare function validateEntitySelectOptionsQuery(feature: FeatureDefinition): void;
 export declare function validateEntitySelectAvailabilityQuery(feature: FeatureDefinition, queryHandlers: ReadonlyMap<string, QueryHandlerDef>): void;
+export declare function validateEntitySelectConditionalOptions(feature: FeatureDefinition): void;
 export declare function validateMultiSelectFields(feature: FeatureDefinition): void;
 export declare function validateImageVariants(feature: FeatureDefinition): void;
 export declare function validateTransitions(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -722,6 +722,46 @@ export function validateEntitySelectAvailabilityQuery(feature, queryHandlers) {
         }
     }
 }
+export function validateEntitySelectConditionalOptions(feature) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        for (const [fieldName, field] of Object.entries(entity.fields)) {
+            if (field.type !== "select" || field.conditionalOptions === undefined)
+                continue;
+            const where = `[Feature ${feature.name}] Select field "${fieldName}" on entity "${entityName}"`;
+            if (field.optionsQuery !== undefined) {
+                throw new Error(`${where} combines conditionalOptions with optionsQuery — conditionalOptions filters the static options only.`);
+            }
+            const knownOptions = new Set(field.options);
+            const ruleOfOption = new Map();
+            field.conditionalOptions.forEach((rule, ruleIndex) => {
+                const ruleLabel = `conditionalOptions[${ruleIndex}]`;
+                if (rule.options.length === 0) {
+                    throw new Error(`${where} has an empty ${ruleLabel}.options — drop the rule.`);
+                }
+                for (const option of rule.options) {
+                    if (!knownOptions.has(option)) {
+                        throw new Error(`${where} lists "${option}" in ${ruleLabel} which is not in options (${field.options.join(", ")}).`);
+                    }
+                    const otherRule = ruleOfOption.get(option);
+                    if (otherRule !== undefined) {
+                        throw new Error(`${where} lists "${option}" in conditionalOptions[${otherRule}] and ${ruleLabel} — an option may belong to one rule only.`);
+                    }
+                    ruleOfOption.set(option, ruleIndex);
+                    if (option === field.default) {
+                        throw new Error(`${where} has default "${option}" inside ${ruleLabel} — the default must be available unconditionally.`);
+                    }
+                }
+                const conditionField = rule.when.field;
+                if (conditionField === fieldName) {
+                    throw new Error(`${where} has ${ruleLabel}.when on its own field.`);
+                }
+                if (!(conditionField in entity.fields)) {
+                    throw new Error(`${where} has ${ruleLabel}.when.field "${conditionField}" which is not a field of the entity.`);
+                }
+            });
+        }
+    }
+}
 export function validateMultiSelectFields(feature) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
         for (const [fieldName, field] of Object.entries(entity.fields)) {

package/dist/engine/boot-validator/handler-field-references.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateHandlerFieldReferences(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/handler-field-references.js

@@ -0,0 +1,25 @@
+import { handlerFieldReference } from "../handler-field-references.js";
+import { parseRefTarget } from "../parse-ref-target.js";
+import { getZodObjectShape } from "./zod-shape.js";
+function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
+    for (const [handlerName, def] of Object.entries(handlers)) {
+        const shape = getZodObjectShape(def.schema);
+        if (shape === undefined)
+            continue;
+        for (const fieldName of Object.keys(shape)) {
+            const reference = handlerFieldReference(def.schema, fieldName);
+            if (reference === undefined)
+                continue;
+            const target = parseRefTarget(reference, feature.name);
+            const targetEntities = featureMap.get(target.featureName)?.entities;
+            if (targetEntities?.[target.entityName] !== undefined)
+                continue;
+            throw new Error(`[Feature ${feature.name}] Input field "${fieldName}" of ${handlerNoun} "${handlerName}" has meta references: "${reference}", ` +
+                `which is not a registered entity. Use "<entity>" for this feature or "<feature>:<entity>" for another one.`);
+        }
+    }
+}
+export function validateHandlerFieldReferences(feature, featureMap) {
+    validateHandlerGroup(feature, featureMap, feature.writeHandlers ?? {}, "write handler");
+    validateHandlerGroup(feature, featureMap, feature.queryHandlers ?? {}, "query handler");
+}

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

@@ -9,10 +9,11 @@ import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext.
 import { validateFeatureBootChecks } from "./boot-check.js";
 import { validateCircularDeps, validateConfigKeyAllowPerRequest, validateConfigKeyBacking, validateConfigKeyBounds, validateConfigKeyComputed, validateConfigKeyOptionsQuery, validateConfigKeyPiiEncrypted, validateConfigKeyRequired, validateConfigReads, warnOnToggleableDependencies, } from "./config-deps.js";
 import { collectDetailForScreens } from "./detail-screens.js";
-import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
+import { validateDerivedFieldCollisions, validateEmbeddedFields, validateEncryptedFields, validateEntityIndexes, validateEntitySelectAvailabilityQuery, validateEntitySelectConditionalOptions, validateEntitySelectOptionsQuery, validateExtendSchemaCollisions, validateExtensionPreSaveWiring, validateFileFields, validateHandlerAccess, validateImageVariants, validateLocatedTimestamps, validateMultiSelectFields, validateMultiStreamProjections, validateReferenceFields, validateSearchableFieldReadAccess, validateTransitions, } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
 import { validateGlobalTenancyEntities } from "./global-tenancy.js";
+import { validateHandlerFieldReferences } from "./handler-field-references.js";
 import { validateI18nSurfaceKeys } from "./i18n-keys.js";
 import { collectKnownRoles, collectNavQns, collectWriteHandlerQns, validateNavCycles, validateNavs, warnOnNavAccessInversion, warnOnUnreachableNavScreens, } from "./nav.js";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership.js";
@@ -26,6 +27,7 @@ import { collectScreenQns, collectScreensByShortId, validateScreenShortIdCollisi
 import { warnOnMissingSecurityBaseline } from "./security-baseline.js";
 import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
 import { validateTransferGraph } from "./transfer-graph.js";
+import { validateSubmitPrefilledHiddenFields } from "./url-prefill-fields.js";
 import { collectWorkspaceQns, resolveNavAllowlist, validateDefaultWorkspaceUniqueness, validateWorkspaces, } from "./workspaces.js";
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 // Re-export: wird von run-dev-app.ts benötigt um Write-Handler-QNs
@@ -170,10 +172,12 @@ export function validateBoot(rawFeatures, options) {
         validateApiExposureMatching(feature, allExposedApis, featureMap);
         validateEntitySelectOptionsQuery(feature);
         validateEntitySelectAvailabilityQuery(feature, queryHandlerQns);
+        validateEntitySelectConditionalOptions(feature);
         validateEmbeddedFields(feature, featureMap, queryHandlerQns);
         validateMultiSelectFields(feature);
         validateImageVariants(feature);
         validateReferenceFields(feature, featureMap, queryHandlerQns);
+        validateHandlerFieldReferences(feature, featureMap);
         validateTransitions(feature);
         validateExtensionUsages(feature, extensionProviders);
         validateExtendSchemaCollisions(feature);
@@ -212,6 +216,7 @@ export function validateBoot(rawFeatures, options) {
     validateDefaultWorkspaceUniqueness(allWorkspaceQns);
     validateI18nSurfaceKeys(features);
     validateEntityListScreens(features);
+    validateSubmitPrefilledHiddenFields(features);
     // Must run before validateProjectionListScreens: an unresolvable query
     // there is silently treated as "capability absent" and surfaces as a
     // misleading "no search parameter in its Zod schema" error instead of

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

@@ -59,7 +59,9 @@ export function validateNavs(feature, allScreenQns, allNavQns, allWorkspaceQns)
 // `screen`/`target`. Without this check an action with neither is a
 // Hover-Icon that does nothing; one with both is ambiguous about which
 // click-mode wins.
-function validateTreeAction(featureName, navId, actionPath, action, allScreenQns) {
+function validateTreeAction(featureName, navId, actionPath, action, 
+// Loose on purpose: this is the runtime guard for untyped input.
+allScreenQns) {
     const { screen, target } = action;
     const hasScreen = screen !== undefined;
     const hasTarget = target !== undefined;

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

@@ -5,7 +5,7 @@ export type WhereRuleProbe = {
     readonly tableName: string;
     readonly columns: ReadonlySet<string>;
 };
-export type AccessPath = "read" | "write";
+export type AccessPath = "read" | "fieldRead" | "write";
 export declare function collectClaimKeys(features: readonly FeatureDefinition[]): Map<string, ClaimKeyDefinition>;
 export declare function validateOwnershipBoot(features: readonly FeatureDefinition[]): void;
 export declare function validateOwnershipRules(feature: FeatureDefinition, allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined, knownRoles: ReadonlySet<string> | undefined): void;
@@ -32,5 +32,6 @@ export declare function checkOwnershipMap(args: {
     readonly path: AccessPath;
 }): void;
 export declare function probeWhereRule(rule: WhereRule, roleName: string, probe: WhereRuleProbe | undefined, scope: string, featureName: string): void;
+export declare function buildWhereOnFieldReadMessage(roleName: string, scope: string, featureName: string): string;
 export declare function buildWhereOnWritePathMessage(roleName: string, scope: string, featureName: string): string;
 export declare function buildUnknownRoleMessage(roleName: string, knownRoles: ReadonlySet<string>, scope: string, featureName: string): string;

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

@@ -14,6 +14,9 @@ import { assertQualifiedWhereFragment, tableColumnSqlNames } from "../where-rule
 // lint (see ../where-rule-lint.ts) so a fail-open unqualified-column bug
 // fails the boot instead of waiting for a request from the right role.
 //
+// Field-level `access.read` rejects where-rules too: filterFieldsForRead
+// evaluates it in memory and userCanReadFieldRow fails closed on a where-rule.
+//
 // fw#2626: `access.write` maps reject `{ kind: "where" }` outright. A
 // where-rule is raw SQL and the write path never reaches SQL — it evaluates
 // rules in memory against the concrete row (userCanCreateFieldRow /
@@ -114,8 +117,11 @@ export function validateOwnershipRules(feature, allClaimKeys, knownRoles) {
                 scope: `${entityName}.${fieldName}.access.read`,
                 featureName: feature.name,
                 probe,
-                path: "read",
+                path: "fieldRead",
             });
+            if (field.type === "embedded") {
+                rejectWhereInEmbeddedRead(field.schema, `${entityName}.${fieldName}`, feature.name);
+            }
             checkFieldAccess({
                 access: field.access?.write,
                 columnNames,
@@ -193,6 +199,9 @@ export function checkOwnershipMap(args) {
             if (args.path === "write") {
                 throw new Error(buildWhereOnWritePathMessage(roleName, args.scope, args.featureName));
             }
+            if (args.path === "fieldRead") {
+                throw new Error(buildWhereOnFieldReadMessage(roleName, args.scope, args.featureName));
+            }
             probeWhereRule(rule, roleName, args.probe, args.scope, args.featureName);
             continue; // escape hatch — feature author owns the SQL
         }
@@ -249,6 +258,28 @@ export function probeWhereRule(rule, roleName, probe, scope, featureName) {
         return;
     assertQualifiedWhereFragment(fragment.sqlText, probe.columns, `${scope} (role "${roleName}", feature: "${featureName}")`);
 }
+// Embedded sub-fields are filtered in memory too (filterFieldsForRead), so a
+// where-rule there is just as unevaluable as on a top-level field.
+function rejectWhereInEmbeddedRead(schema, parentScope, featureName) {
+    for (const [subName, sub] of Object.entries(schema)) {
+        const map = sub.access?.read;
+        if (!map || Array.isArray(map))
+            continue;
+        for (const [roleName, rule] of Object.entries(map)) {
+            if (rule !== "all" && rule.kind === "where") {
+                throw new Error(buildWhereOnFieldReadMessage(roleName, `${parentScope}.${subName}.access.read`, featureName));
+            }
+        }
+    }
+}
+export function buildWhereOnFieldReadMessage(roleName, scope, featureName) {
+    return (`[Kumiko Ownership] ${scope} uses a \`{ kind: "where" }\` rule for role ` +
+        `"${roleName}" (feature: "${featureName}"). Field-level read access is decided ` +
+        `in memory against the concrete row (userCanReadFieldRow), which cannot run ` +
+        `raw SQL — the rule could only ever hide the field from this role. Use a ` +
+        `from()-rule (e.g. from("user:id", "ownerId")) on the field, or move the ` +
+        `where-rule to entity access.read.`);
+}
 export function buildWhereOnWritePathMessage(roleName, scope, featureName) {
     return (`[Kumiko Ownership] ${scope} uses a \`{ kind: "where" }\` rule for role ` +
         `"${roleName}" (feature: "${featureName}"). where-rules are raw SQL and only ` +

package/dist/engine/boot-validator/pii-retention.js

@@ -1,4 +1,6 @@
+import { createFallbackLogger } from "../../logging/utils.js";
 import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./entity-handler.js";
+const log = createFallbackLogger("kumiko:boot");
 // Framework-managed Timestamp-Spalten — dürfen als retention.reference
 // genutzt werden auch wenn nicht in entity.fields deklariert.
 const FRAMEWORK_TIMESTAMP_FIELDS = new Set([
@@ -238,6 +240,11 @@ export function validatePiiAndRetention(feature) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
                     console.warn(`[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`);
                 }
+                else if (!annot.subjectRef && (field.type === "text" || field.type === "longText")) {
+                    // The factories refuse a missing stance, but a raw literal such as
+                    // { type: "text" } still compiles and reaches the entity unchecked.
+                    log.warn(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" (type "${field.type}") declares no personal stance. Declare { personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false } via createTextField / createLongTextField; "false" additionally needs { reason: "..." } stating why the value is not personal data.`);
+                }
             }
         }
         // --- Entity-level retention ---
@@ -266,7 +273,7 @@ export function validatePiiAndRetention(feature) {
                 });
                 if (entityHasAnonymizableField && !hasAnonymize) {
                     // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                    console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`);
+                    console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. Once keepFor expires, the data-retention cron anonymizes nothing and the row keeps its PII. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`);
                 }
             }
         }

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

@@ -10,13 +10,13 @@ function checkFieldExists(shape, field, buildMessage) {
         return;
     throw new Error(buildMessage());
 }
-// Mirrors entity-list-screens.ts's "unlabeled unknown column" convention: a
-// column with its own `label` is a virtual/computed cell drawn by a
-// renderer, not a row field — exempt from the shape check.
+// Unlike entity-list-screens.ts, `label` does not exempt a column here: query
+// screens label nearly every column, so that exemption would leave the check
+// validating nothing. Only an explicit `virtual: true` skips the shape check.
 function checkColumnField(rowShape, column, buildMessage) {
     const normalized = normalizeListColumn(column);
-    // skip: labeled column is a virtual/computed cell drawn by a renderer, not a row field
-    if (normalized.label !== undefined)
+    // skip: virtual column is a computed cell drawn by a renderer, not a row field
+    if (normalized.virtual === true)
         return;
     checkFieldExists(rowShape, normalized.field, () => buildMessage(normalized.field));
 }
@@ -55,7 +55,7 @@ function resolveListRowShape(queryHandlers, queryQn, usage) {
 function checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen) {
     const rowShape = resolveListRowShape(queryHandlers, screen.query, `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
     for (const column of screen.columns) {
-        checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (projectionList) column "${field}" is not present in query "${screen.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
+        checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (projectionList) column "${field}" is not present in query "${screen.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
     }
 }
 function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, screenType, layout) {
@@ -64,7 +64,7 @@ function checkEditLayoutOutputColumns(queryHandlers, featureName, screenId, scre
             continue;
         const rowShape = resolveListRowShape(queryHandlers, section.query, `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}"`);
         for (const column of section.columns) {
-            checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" column "${field}" is not present in query "${section.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
+            checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}" column "${field}" is not present in query "${section.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
         }
     }
 }
@@ -189,7 +189,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
         else if (panel.kind === "list") {
             const rowShape = resolveListRowShape(queryHandlers, panel.query, `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
             for (const column of panel.columns) {
-                checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" column "${field}" is not present in query "${panel.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
+                checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" column "${field}" is not present in query "${panel.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
             }
         }
         // chart/feed/progress-list/custom panels have a fixed query-result
@@ -205,7 +205,7 @@ function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen)
         if (screen.expandableRow !== undefined) {
             const rowShape = resolveListRowShape(queryHandlers, screen.expandableRow.query, `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow.title}"`);
             for (const column of screen.expandableRow.columns) {
-                checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}" column "${field}" is not present in query "${screen.expandableRow?.query}"'s outputSchema — check for a typo, or add a "label" to mark it a virtual/computed column.`);
+                checkColumnField(rowShape, column, (field) => `[Feature ${featureName}] Screen "${screenId}" (entityList) expandableRow "${screen.expandableRow?.title}" column "${field}" is not present in query "${screen.expandableRow?.query}"'s outputSchema — check for a typo, or set virtual: true on it to mark it a virtual/computed column.`);
             }
         }
     }