@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/engine/feature-ui-extensions.js

@@ -0,0 +1,488 @@
+import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
+import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
+import { LifecycleHookTypes } from "./constants.js";
+import { resolveName } from "./handler-helpers.js";
+import { isKebabSegment, toKebab } from "./qualified-name.js";
+import { HookPhases } from "./types/index.js";
+function isEntityWideHookType(type) {
+    return (type === LifecycleHookTypes.postSave ||
+        type === LifecycleHookTypes.preDelete ||
+        type === LifecycleHookTypes.postDelete ||
+        type === LifecycleHookTypes.postQuery);
+}
+// r.hook(type, { allOf: entity }, fn) — "all write/query handlers of this
+// entity", replacing the old r.entityHook(type, entity, fn). Hook-fn casts
+// below: @cast-boundary engine-bridge — typed Dev-API (LifecycleHookFn) →
+// erased Map<entityName, fn>.
+function registerEntityWideHook(state, featureName, type, entityName, fn, options) {
+    if (type === LifecycleHookTypes.postSave) {
+        const phase = options?.phase ?? HookPhases.afterCommit;
+        if (!state.entityPostSave[entityName])
+            state.entityPostSave[entityName] = [];
+        state.entityPostSave[entityName].push({
+            fn: fn,
+            phase,
+            featureName,
+        }); // @cast-boundary engine-bridge
+    }
+    else if (type === LifecycleHookTypes.preDelete) {
+        if (!state.entityPreDelete[entityName])
+            state.entityPreDelete[entityName] = [];
+        state.entityPreDelete[entityName].push({
+            fn: fn, // @cast-boundary engine-bridge
+            phase: HookPhases.inTransaction,
+            featureName,
+        });
+    }
+    else if (type === LifecycleHookTypes.postDelete) {
+        const phase = options?.phase ?? HookPhases.afterCommit;
+        if (!state.entityPostDelete[entityName])
+            state.entityPostDelete[entityName] = [];
+        state.entityPostDelete[entityName].push({
+            fn: fn,
+            phase,
+            featureName,
+        }); // @cast-boundary engine-bridge
+    }
+    else {
+        // postQuery is unphased (no inTransaction/afterCommit semantics — fires
+        // synchronously after query-handler-execute, before field-access-filter)
+        if (!state.entityPostQuery[entityName])
+            state.entityPostQuery[entityName] = [];
+        state.entityPostQuery[entityName].push({ fn: fn, featureName }); // @cast-boundary engine-bridge
+    }
+}
+export function buildUiExtensionsMethods(state, name) {
+    // Shared by r.nav() and r.screen()'s inline nav-sugar path — one place
+    // for id-validation + collision checks so future registration-time
+    // checks (e.g. parent-format, reserved ids) apply to both call sites
+    // instead of only the standalone r.nav() one.
+    function registerNav(navDefinition) {
+        if (!isKebabSegment(navDefinition.id)) {
+            throw new Error(`[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
+                `(lowercase letters, digits, dashes; start with a letter). ` +
+                `Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`);
+        }
+        if (state.navs[navDefinition.id]) {
+            throw new Error(`[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
+                `Nav ids must be unique per feature — remove the standalone ` +
+                `r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`);
+        }
+        state.navs[navDefinition.id] = navDefinition;
+    }
+    return {
+        hook(type, target, fn, options) {
+            if (type === "validation") {
+                if (options?.escapeHatch !== undefined) {
+                    throw new Error(`[Feature ${name}] r.hook("validation", ...) does not accept { escapeHatch } — ` +
+                        "validation hooks receive no context to switch identity with.");
+                }
+            }
+            else if (options?.escapeHatch !== undefined &&
+                options.escapeHatch.reason.trim().length === 0) {
+                throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares { escapeHatch: { reason: "" } } — ` +
+                    "the reason must be a non-empty string explaining why this hook switches identity to SYSTEM.");
+            }
+            // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
+            const hookLabel = `${type} hook of feature "${name}"`;
+            const wrapped = type === "validation"
+                ? fn
+                : bindHookEscapeHatchGrant(fn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
+            // Entity-wide target ("all write/query handlers of this entity") —
+            // replaces the old r.entityHook(type, entity, fn).
+            if (typeof target === "object" &&
+                target !== null &&
+                !Array.isArray(target) &&
+                "allOf" in target) {
+                if (!isEntityWideHookType(type)) {
+                    throw new Error(`[Feature ${name}] r.hook("${type}", { allOf }, ...) only supports ` +
+                        `postSave/preDelete/postDelete/postQuery, not "${type}".`);
+                }
+                registerEntityWideHook(state, name, type, resolveName(target.allOf), wrapped, // @cast-boundary engine-bridge
+                options);
+                // skip: entity-wide target fully handled above, nothing more to do
+                return;
+            }
+            const targets = Array.isArray(target) ? target : [target];
+            const names = targets.map(resolveName);
+            // Hook-fn casts unten alle: @cast-boundary engine-bridge
+            // — typed Dev-API (LifecycleHookFn|ValidationHookFn) → erased Map<name, fn>.
+            if (type === "validation") {
+                for (const n of names) {
+                    state.validationHooks[n] = wrapped; // @cast-boundary engine-bridge
+                }
+                // skip: validation hooks have no phase, stored and done
+                return;
+            }
+            if (type === LifecycleHookTypes.preSave ||
+                type === LifecycleHookTypes.preQuery ||
+                type === LifecycleHookTypes.postQuery) {
+                if (!state.lifecycleHooks[type])
+                    state.lifecycleHooks[type] = {};
+                for (const n of names) {
+                    if (!state.lifecycleHooks[type][n])
+                        state.lifecycleHooks[type][n] = [];
+                    state.lifecycleHooks[type][n].push({
+                        fn: wrapped, // @cast-boundary engine-bridge
+                        featureName: name,
+                    });
+                }
+                // skip: pre/post-hooks without phase semantics, stored and done
+                return;
+            }
+            // Phased storage. preDelete has no phase option (always inTransaction);
+            // postSave/postDelete default to afterCommit.
+            const phase = type === LifecycleHookTypes.preDelete
+                ? HookPhases.inTransaction
+                : (options?.phase ?? HookPhases.afterCommit);
+            const bucket = state.phasedLifecycleHooks[type];
+            for (const n of names) {
+                if (!bucket[n])
+                    bucket[n] = [];
+                bucket[n].push({
+                    fn: wrapped, // @cast-boundary engine-bridge
+                    phase,
+                    featureName: name,
+                });
+            }
+        },
+        searchPayloadExtension(entityRef, fn) {
+            const entityName = resolveName(entityRef);
+            if (!state.searchPayloadExtensions[entityName])
+                state.searchPayloadExtensions[entityName] = [];
+            state.searchPayloadExtensions[entityName].push({ fn, featureName: name });
+        },
+        extendsRegistrar(extensionName, def) {
+            state.registrarExtensions[extensionName] = def;
+        },
+        useExtension(extensionNameOrDefinition, entityRef, options) {
+            const [extensionName, resolvedEntityRef, resolvedOptions] = typeof extensionNameOrDefinition === "string"
+                ? [extensionNameOrDefinition, entityRef, options]
+                : (() => {
+                    const { name, entity, ...rest } = extensionNameOrDefinition;
+                    return [name, entity, rest];
+                })();
+            const resolvedEntityName = resolveName(resolvedEntityRef);
+            // @cast-boundary engine-bridge — typed per-extension options → erased registration bag
+            const optionsBag = resolvedOptions;
+            // fw#2914 — cross-cutting escapeHatch convention for hook-context db
+            // access (mirrors r.hook's validation above). Validated the same way
+            // for every extension regardless of its typed hook shape.
+            const escapeHatch = optionsBag?.["escapeHatch"];
+            if (escapeHatch !== undefined) {
+                const reason = typeof escapeHatch === "object" && escapeHatch !== null
+                    ? escapeHatch.reason
+                    : undefined;
+                if (typeof reason !== "string" || reason.trim().length === 0) {
+                    throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
+                        `must be { reason: "<non-empty string>" } explaining why this usage needs unfiltered db access.`);
+                }
+            }
+            state.extensionUsages.push({
+                extensionName,
+                entityName: resolvedEntityName,
+                options: optionsBag,
+            });
+        },
+        extensionSelector(extensionName, key) {
+            if (state.extensionSelectors.some((s) => s.extensionName === extensionName)) {
+                throw new Error(`[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
+                    `one selector key per extension point.`);
+            }
+            const qualifiedKey = typeof key === "string" ? key : key.name;
+            state.extensionSelectors.push({ extensionName, qualifiedKey });
+        },
+        /**
+         * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
+         * unter dem genannten Namen bereit. Die eigentliche Implementation
+         * wird separat als Query- oder Write-Handler unter dem QN-Pattern
+         * registriert; r.exposesApi ist reine Boot-Check-Surface.
+         *
+         * Beispiel:
+         *   defineFeature("compliance-profiles", (r) => {
+         *     r.exposesApi("compliance.forTenant");
+         *     r.queryHandler({ name: "compliance:query:for-tenant", ... });
+         *   });
+         *   defineFeature("user-data-rights", (r) => {
+         *     r.requires("compliance-profiles");
+         *     r.usesApi("compliance.forTenant");
+         *     // ruft im Handler: ctx.callQuery("compliance:query:for-tenant", ...)
+         *   });
+         */
+        exposesApi(apiName) {
+            if (state.exposedApis.has(apiName)) {
+                throw new Error(`[Feature ${name}] r.exposesApi("${apiName}") called twice — API names must be unique within a feature.`);
+            }
+            state.exposedApis.add(apiName);
+        },
+        /**
+         * Declares that this feature calls a cross-feature API. Boot-Validator
+         * checkt dass irgendein anderes Feature `r.exposesApi(name)` macht und
+         * dass dieses Feature `r.requires` darauf hat.
+         */
+        usesApi(apiName) {
+            state.usedApis.add(apiName);
+        },
+        bootCheck(fn) {
+            state.bootChecks.push(fn);
+        },
+        projection(definition) {
+            // Reject names that would blow up at registry-boot when we qualify them.
+            // Catch it at the registration site so the stack trace points at the
+            // feature file, not at framework internals.
+            if (!isKebabSegment(definition.name)) {
+                throw new Error(`[Feature ${name}] Projection name "${definition.name}" must be kebab-case ` +
+                    `(lowercase letters, digits, dashes; start with a letter). ` +
+                    `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`);
+            }
+            if (state.projections[definition.name]) {
+                throw new Error(`[Feature ${name}] Projection "${definition.name}" already registered. ` +
+                    `Projection names must be unique per feature.`);
+            }
+            state.projections[definition.name] = definition;
+        },
+        multiStreamProjection(definition) {
+            if (!isKebabSegment(definition.name)) {
+                throw new Error(`[Feature ${name}] MultiStreamProjection name "${definition.name}" must be kebab-case ` +
+                    `(lowercase letters, digits, dashes; start with a letter). ` +
+                    `Got "${definition.name}" — try "${toKebab(definition.name).replace(/_/g, "-")}".`);
+            }
+            if (state.multiStreamProjections[definition.name] || state.projections[definition.name]) {
+                throw new Error(`[Feature ${name}] Projection name "${definition.name}" already registered. ` +
+                    `r.projection and r.multiStreamProjection share a namespace — pick a unique short name.`);
+            }
+            if (Object.keys(definition.apply).length === 0) {
+                throw new Error(`[Feature ${name}] MultiStreamProjection "${definition.name}" has no apply handlers. ` +
+                    `Declare at least one event type it reacts to, otherwise the dispatcher has nothing to route.`);
+            }
+            state.multiStreamProjections[definition.name] = definition;
+        },
+        extendEntityProjection(entityName, extension) {
+            if (Object.keys(extension.apply).length === 0) {
+                throw new Error(`[Feature ${name}] extendEntityProjection("${entityName}") has no apply handlers. ` +
+                    `Declare at least one event type, otherwise the rebuild replay has nothing to do.`);
+            }
+            // Entity existence + apply-key collisions are validated at registry
+            // build — r.entity may legally be called after this in the same feature.
+            const list = state.entityProjectionExtensions[entityName] ?? [];
+            list.push(extension);
+            state.entityProjectionExtensions[entityName] = list;
+        },
+        referenceData(entityRefOrDefinition, data, options) {
+            const [entityRef, resolvedData, upsertKey] = typeof entityRefOrDefinition === "object" && "entity" in entityRefOrDefinition
+                ? [
+                    entityRefOrDefinition.entity,
+                    entityRefOrDefinition.data,
+                    entityRefOrDefinition.upsertKey,
+                ]
+                : [entityRefOrDefinition, data, options?.upsertKey];
+            state.referenceData.push({
+                entityName: resolveName(entityRef),
+                data: resolvedData,
+                upsertKey,
+            });
+        },
+        screen(definition) {
+            // Reject kebab-drift at registration-time so the stack trace points at
+            // the feature file, not at registry-boot. Same guard pattern as
+            // r.projection / r.multiStreamProjection.
+            if (!isKebabSegment(definition.id)) {
+                throw new Error(`[Feature ${name}] Screen id "${definition.id}" must be kebab-case ` +
+                    `(lowercase letters, digits, dashes; start with a letter). ` +
+                    `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`);
+            }
+            if (state.screens[definition.id]) {
+                throw new Error(`[Feature ${name}] Screen "${definition.id}" already registered. ` +
+                    `Screen ids must be unique per feature.`);
+            }
+            state.screens[definition.id] = definition;
+            if (definition.nav) {
+                // Sugar for the common "one nav entry pointing at this screen"
+                // case — synthesizes id/screen from the screen's own id. Beyond
+                // label/icon/parent/order, declare a standalone r.nav() instead.
+                // Optional fields stay absent rather than explicitly undefined —
+                // buildAppSchema's JSON-safety check flags undefined values. Same
+                // pattern as r.contentCollection() below.
+                registerNav({
+                    id: definition.id,
+                    label: definition.nav.label,
+                    ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+                    ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+                    ...(definition.nav.order !== undefined && { order: definition.nav.order }),
+                    screen: `${name}:screen:${definition.id}`,
+                });
+            }
+        },
+        nav(definition) {
+            registerNav(definition);
+        },
+        contentCollection(definition) {
+            if (state.contentCollections[definition.id]) {
+                throw new Error(`[Feature ${name}] Content collection "${definition.id}" already registered. ` +
+                    `Collection ids must be unique per feature.`);
+            }
+            // registerNav owns the kebab + collision checks, including collisions
+            // with a plain r.nav() of the same id. Optional fields stay absent
+            // rather than explicitly undefined — buildAppSchema's JSON-safety check
+            // flags undefined values.
+            registerNav({
+                id: definition.id,
+                label: definition.nav.label,
+                ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+                ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+                ...(definition.nav.order !== undefined && { order: definition.nav.order }),
+                // Nav visibility follows the collection's access unless the caller
+                // overrode it — a node the handler would refuse has no business in
+                // the sidebar.
+                ...((definition.nav.access ?? definition.access) !== undefined && {
+                    access: definition.nav.access ?? definition.access,
+                }),
+                ...(definition.nav.workspaces !== undefined && { workspaces: definition.nav.workspaces }),
+                ...(definition.nav.createAction !== undefined && {
+                    createAction: definition.nav.createAction,
+                }),
+                ...(definition.nav.actions !== undefined && { actions: definition.nav.actions }),
+                // The tree children come from a runtime provider keyed on this QN —
+                // a collection without it would render as an empty leaf.
+                provider: true,
+            });
+            state.contentCollections[definition.id] = definition;
+            return `${name}:nav:${definition.id}`;
+        },
+        workspace(definition) {
+            // Same kebab guard as r.screen / r.nav so authoring-time mistakes
+            // surface at the feature file, not deep in registry boot.
+            if (!isKebabSegment(definition.id)) {
+                throw new Error(`[Feature ${name}] Workspace id "${definition.id}" must be kebab-case ` +
+                    `(lowercase letters, digits, dashes; start with a letter). ` +
+                    `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`);
+            }
+            if (state.workspaces[definition.id]) {
+                throw new Error(`[Feature ${name}] Workspace "${definition.id}" already registered. ` +
+                    `Workspace ids must be unique per feature.`);
+            }
+            state.workspaces[definition.id] = definition;
+        },
+        httpRoute(definition) {
+            // Path-Validation: muss mit "/" beginnen, keine /api/-Routes (die
+            // sind dem Dispatcher reserviert; eine HTTP-Route die /api/foo
+            // belegt, würde die Auth-Middleware umgehen ohne dass der Author
+            // das ausgesprochen hat — bewusster Block).
+            if (!definition.path.startsWith("/")) {
+                throw new Error(`[Feature ${name}] httpRoute path "${definition.path}" must start with "/". ` +
+                    `Got "${definition.path}".`);
+            }
+            if (definition.path === "/api" || definition.path.startsWith("/api/")) {
+                throw new Error(`[Feature ${name}] httpRoute path "${definition.path}" is in the /api/* namespace ` +
+                    `which is reserved for the dispatcher (write/query/batch/auth/sse). ` +
+                    `Pick a different path or use r.queryHandler / r.writeHandler.`);
+            }
+            if (typeof definition.anonymous !== "boolean") {
+                throw new Error(`[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
+                    `anonymous: true | false — true mounts it public, false behind the session auth chain.`);
+            }
+            const key = `${definition.method} ${definition.path}`;
+            if (state.httpRoutes[key]) {
+                throw new Error(`[Feature ${name}] HTTP-Route "${key}" already registered. ` +
+                    `method + path must be unique per feature.`);
+            }
+            state.httpRoutes[key] = definition;
+        },
+        webSocketRoute(definition) {
+            if (!definition.path.startsWith(WEBSOCKET_ROUTE_PATH_PREFIX)) {
+                throw new Error(`[Feature ${name}] webSocketRoute path "${definition.path}" must start with ` +
+                    `"${WEBSOCKET_ROUTE_PATH_PREFIX}" — only that namespace rides the /api/* auth chain ` +
+                    "the upgrade relies on.");
+            }
+            if (definition.path.includes("*")) {
+                throw new Error(`[Feature ${name}] webSocketRoute path "${definition.path}" must not contain "*" — ` +
+                    "wildcards would let one route swallow unrelated /api/ws/* paths.");
+            }
+            const { maxMessageBytes } = definition;
+            if (maxMessageBytes !== undefined &&
+                (!Number.isInteger(maxMessageBytes) ||
+                    maxMessageBytes < 1 ||
+                    maxMessageBytes > WEBSOCKET_MAX_PAYLOAD_BYTES)) {
+                throw new Error(`[Feature ${name}] webSocketRoute "${definition.path}" maxMessageBytes must be an ` +
+                    `integer between 1 and ${WEBSOCKET_MAX_PAYLOAD_BYTES}, got ${maxMessageBytes}.`);
+            }
+            const { maxConnectionsPerUser } = definition;
+            if (maxConnectionsPerUser !== undefined &&
+                (!Number.isInteger(maxConnectionsPerUser) ||
+                    maxConnectionsPerUser < 1 ||
+                    maxConnectionsPerUser > WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT)) {
+                throw new Error(`[Feature ${name}] webSocketRoute "${definition.path}" maxConnectionsPerUser must be an ` +
+                    `integer between 1 and ${WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT}, got ${maxConnectionsPerUser}.`);
+            }
+            if (state.webSocketRoutes[definition.path]) {
+                throw new Error(`[Feature ${name}] WebSocket route "${definition.path}" already registered. ` +
+                    "path must be unique per feature.");
+            }
+            state.webSocketRoutes[definition.path] = definition;
+        },
+        storeTable(meta, options) {
+            // Name comes from the meta itself — apps already give the table a
+            // name when calling defineUnmanagedTable, no need to repeat it.
+            const tableName = meta.tableName;
+            if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
+                // EntityTableMeta uses snake_case for tableName (matches Postgres
+                // convention); we just guard against truly broken input.
+                throw new Error(`[Feature ${name}] Store-table name "${tableName}" must be a ` +
+                    `valid identifier (lowercase letters, digits, underscores; start with a letter).`);
+            }
+            if (state.storeTables[tableName]) {
+                throw new Error(`[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
+                    `Store-table names must be unique per feature.`);
+            }
+            // `read_` is reserved for r.entity()/r.projection() (managed,
+            // event-sourced, rebuildable). storeTable is the unmanaged
+            // direct-write escape hatch — the prefix must say so (#1220).
+            if (tableName.startsWith("read_")) {
+                throw new Error(`[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
+                    `for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
+                    `distinct prefix (e.g. "store_${tableName.slice("read_".length)}").`);
+            }
+            // meta.source must agree with the r.storeTable() escape hatch, or the
+            // migrate-generator treats schema drift on this table as safe to
+            // DROP+rebuild-from-events — wiping direct-write data with no events
+            // to replay it from (#1209).
+            if (meta.source !== "unmanaged") {
+                throw new Error(`[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
+                    `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
+                    `defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
+                    `otherwise the migration generator will treat schema drift on this table as safe ` +
+                    `to DROP+rebuild, wiping any direct-write data.`);
+            }
+            // The `reason` is the marker that justifies the bypass — empty
+            // strings would defeat the audit trail. Reject early so the
+            // failure points at the feature file.
+            if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+                throw new Error(`[Feature ${name}] r.storeTable("${tableName}"): options.reason must be a ` +
+                    `non-empty string. The reason justifies the audit-trail bypass — ` +
+                    `if you can't write one, declare data via r.entity() instead.`);
+            }
+            state.storeTables[tableName] = {
+                name: tableName,
+                meta,
+                reason: options.reason,
+                ...(options.piiEncryptedOnWrite && { piiEncryptedOnWrite: true }),
+            };
+        },
+        treeActions(actions) {
+            // Only-once-guard: zweiter Aufruf ist Author-Bug, soll am
+            // Feature-File aufschlagen (gleicher Stil wie r.toggleable).
+            if (state.treeActions !== undefined) {
+                throw new Error(`[Feature ${name}] r.treeActions() already called. ` +
+                    `Each feature may declare a single tree-actions schema.`);
+            }
+            state.treeActions = actions;
+            // Return typed handle für setup-export. Frozen damit Caller die
+            // Map nicht nachträglich mutieren (würde Pattern-AST + Runtime-
+            // Lookup divergieren lassen).
+            return Object.freeze({
+                id: name,
+                treeActions: actions,
+            });
+        },
+    };
+}

package/dist/engine/field-access.d.ts

@@ -0,0 +1,4 @@
+import type { EntityDefinition, SessionUser } from "./types/index.js";
+export declare function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
+export declare function checkWriteFieldRoles(entity: EntityDefinition, changes: Readonly<Record<string, unknown>>, user: SessionUser): string | null;
+export declare function checkWriteFieldOwnership(entity: EntityDefinition, submittedChanges: Readonly<Record<string, unknown>>, user: SessionUser, oldRow?: Readonly<Record<string, unknown>>, rowContext?: Readonly<Record<string, unknown>>): string | null;

package/dist/engine/field-access.js

@@ -0,0 +1,119 @@
+import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership.js";
+// Field-level read filtering. Returns a copy of `data` with fields stripped
+// if the user's roles don't grant read access OR the ownership-rule for the
+// matching role doesn't accept this concrete row. Fields without access
+// config are visible to everyone.
+//
+// Removal is silent (field simply not present in the output) — this is the
+// one place in the ownership system where silence is the right default:
+// reporting "you tried to read X but can't" leaks the field's existence.
+// Writes do the opposite (loud error) because a silent drop there masks
+// save-bugs.
+export function filterReadFields(entity, data, user) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const field = entity.fields[key];
+        if (!field) {
+            // Base columns (id, tenantId, version, etc.) — always visible
+            result[key] = value;
+            continue;
+        }
+        const accessMap = normalizeAccessEntry(field.access?.read);
+        if (!userCanReadFieldRow(user, accessMap, data)) {
+            continue; // entire field stripped
+        }
+        // For embedded fields: filter sub-fields with access restrictions.
+        // A list-embedded value is an array of rows — each row is filtered on its
+        // own, so a sub-field rule can reference the row it sits in. Filtering the
+        // array as if it were one object would turn it into `{0: …, 1: …}`.
+        if (field.type === "embedded" && value && typeof value === "object") {
+            const filterRow = (row) => {
+                const filtered = {};
+                for (const [subKey, subValue] of Object.entries(row)) {
+                    const subField = field.schema[subKey];
+                    const subAccess = normalizeAccessEntry(subField?.access?.read);
+                    if (!userCanReadFieldRow(user, subAccess, row))
+                        continue;
+                    filtered[subKey] = subValue;
+                }
+                return filtered;
+            };
+            result[key] = Array.isArray(value)
+                ? value.map((row) => (row && typeof row === "object" ? filterRow(row) : row))
+                : filterRow(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// Role-only field-write check. Evaluates ONLY whether the user has at
+// least one role mapped to the field's write-access — does NOT evaluate
+// ownership rules against a row. The dispatcher calls this before the
+// handler runs to catch clear-cut role denials (the common case), without
+// needing to load old-row state.
+//
+// Ownership-level row-match for updates happens in the executor, where
+// the pre-update row is already loaded. See checkWriteFieldOwnership.
+//
+// Returns the denied field name, or null if all fields pass the role gate.
+export function checkWriteFieldRoles(entity, changes, user) {
+    for (const key of Object.keys(changes)) {
+        const field = entity.fields[key];
+        if (!field)
+            continue;
+        const accessMap = normalizeAccessEntry(field.access?.write);
+        if (!accessMap)
+            continue; // public write
+        // Pure role-in-map check — ownership-rule evaluation is deferred.
+        const hasRole = user.roles.some((role) => accessMap[role] !== undefined);
+        if (!hasRole)
+            return key;
+    }
+    return null;
+}
+// Full ownership-aware field-write check. Called from the executor after
+// oldRow is loaded. Enforces Straddle-safe per-role atomicity: at least one
+// of the user's roles must accept BOTH the old row AND the new (post-change)
+// row. For creates, pass oldRow = undefined; the check degenerates to a
+// newRow-only evaluation.
+//
+// `submittedChanges` and `rowContext` are deliberately separate (fw#1685):
+// - `submittedChanges` drives WHICH fields get checked — only what the user
+//   actually wrote in the request. A preSave-hook-derived field the user
+//   never touched (e.g. a system hook setting `assignedTo`) must not be
+//   field-ownership-checked against the user at all.
+// - `rowContext` drives what a checked field's rule is evaluated AGAINST —
+//   this needs the full post-hook row, because an ownership rule can
+//   reference a DIFFERENT column that only a hook populates (kumiko-
+//   framework#1672: a hook derives `authorId`, a user-submitted `secretNote`
+//   field's rule is `from("user:id", "authorId")` — the check needs the
+//   hook-derived `authorId` in scope even though the user only wrote
+//   `secretNote`). Defaults to `submittedChanges` when omitted.
+//
+// Returns the denied field name for the caller to wrap into an
+// `ownership_denied` error with scope: "field", or null if all fields pass.
+export function checkWriteFieldOwnership(entity, submittedChanges, user, oldRow, rowContext = submittedChanges) {
+    for (const key of Object.keys(submittedChanges)) {
+        const field = entity.fields[key];
+        if (!field)
+            continue;
+        const accessMap = normalizeAccessEntry(field.access?.write);
+        if (!accessMap)
+            continue;
+        // Only run the ownership eval when the map actually has at least one
+        // ownership-typed rule (i.e. at least one entry is NOT "all"). Pure
+        // "all" maps are just role-in-map checks — already verified by the
+        // dispatcher, no row-eval needed.
+        const hasOwnershipRule = Object.values(accessMap).some((r) => r !== "all");
+        if (!hasOwnershipRule)
+            continue;
+        const newRow = { ...(oldRow ?? {}), ...rowContext };
+        const effectiveOld = oldRow ?? newRow; // create: compare against newRow
+        if (!userCanWriteFieldRow(user, accessMap, effectiveOld, newRow)) {
+            return key;
+        }
+    }
+    return null;
+}

package/dist/engine/field-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { AnyFileFieldDef, FieldDefinition } from "./types/fields.js";
+export declare const DEFAULT_CURRENCIES: readonly ["EUR", "USD", "GBP", "CHF", "JPY", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "NZD", "CNY", "INR"];
+export declare const DEFAULT_LOCALES: readonly ["de", "en", "es"];
+export declare function isFileField(field: FieldDefinition | undefined): field is AnyFileFieldDef;

package/dist/engine/field-helpers.js

@@ -0,0 +1,28 @@
+// --- Currency ---
+export const DEFAULT_CURRENCIES = [
+    "EUR",
+    "USD",
+    "GBP",
+    "CHF",
+    "JPY",
+    "SEK",
+    "NOK",
+    "DKK",
+    "PLN",
+    "CZK",
+    "CAD",
+    "AUD",
+    "NZD",
+    "CNY",
+    "INR",
+];
+// --- Locale ---
+export const DEFAULT_LOCALES = ["de", "en", "es"];
+export function isFileField(field) {
+    if (!field)
+        return false;
+    return (field.type === "file" ||
+        field.type === "image" ||
+        field.type === "files" ||
+        field.type === "images");
+}