@cosmicdrift/kumiko-framework 0.365.1 → 0.367.0

package/dist/engine/factories.d.ts

@@ -133,34 +133,34 @@ export declare function createTzField<R extends true | false = false>(overrides?
     required: R;
 };
 /**
- * Wall-Clock-Termin an einem Ort als ATOMARES Field. Empfohlene Form für
- * jeden Date-Wert mit Location-Bezug (Pickup, Delivery, Meeting, Schedule).
+ * Wall-clock time at a place as one atomic field. Use it for every date
+ * value tied to a location (pickup, delivery, meeting, schedule).
  *
- * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
- * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ * One schema field maps to two DB columns (`<name>_utc TIMESTAMPTZ` +
+ * `<name>_tz TEXT`) and to three API fields on read (`{ at, tz, utc }`).
  *
  * ```ts
- * r.entity("order", {
+ * r.entity({
+ *   name: "order",
  *   fields: {
  *     pickup: createLocatedTimestampField(),
  *     delivery: createLocatedTimestampField(),
  *   },
  * });
  *
- * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * // Write: the caller sends at+tz, the framework computes utc
  * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
  *
- * // Read — Framework liefert alle drei Felder zurück
+ * // Read: the framework returns all three fields
  * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
  *
- * // Sort/Filter über die UTC-Spalte
+ * // Sort/filter on the UTC column
  * orderBy(asc(orderTable.pickupUtc))
  * where(between(orderTable.pickupUtc, start, end))
  * ```
  *
- * Default-Sicht für `at` ist Pickup-Ort-lokal (was eingegeben wurde, kommt
- * mit demselben Tag zurück). User-lokale Sicht kommt aus `utc` per
- * separater Berechnung.
+ * `at` is local to the place (what was entered comes back on the same day).
+ * A user-local view is computed separately from `utc`.
  */
 export declare function createLocatedTimestampField<R extends true | false = false>(overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;

package/dist/engine/factories.js

@@ -324,34 +324,34 @@ export function createTzField(overrides) {
     }; // @cast-boundary engine-payload
 }
 /**
- * Wall-Clock-Termin an einem Ort als ATOMARES Field. Empfohlene Form für
- * jeden Date-Wert mit Location-Bezug (Pickup, Delivery, Meeting, Schedule).
+ * Wall-clock time at a place as one atomic field. Use it for every date
+ * value tied to a location (pickup, delivery, meeting, schedule).
  *
- * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
- * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ * One schema field maps to two DB columns (`<name>_utc TIMESTAMPTZ` +
+ * `<name>_tz TEXT`) and to three API fields on read (`{ at, tz, utc }`).
  *
  * ```ts
- * r.entity("order", {
+ * r.entity({
+ *   name: "order",
  *   fields: {
  *     pickup: createLocatedTimestampField(),
  *     delivery: createLocatedTimestampField(),
  *   },
  * });
  *
- * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * // Write: the caller sends at+tz, the framework computes utc
  * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
  *
- * // Read — Framework liefert alle drei Felder zurück
+ * // Read: the framework returns all three fields
  * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
  *
- * // Sort/Filter über die UTC-Spalte
+ * // Sort/filter on the UTC column
  * orderBy(asc(orderTable.pickupUtc))
  * where(between(orderTable.pickupUtc, start, end))
  * ```
  *
- * Default-Sicht für `at` ist Pickup-Ort-lokal (was eingegeben wurde, kommt
- * mit demselben Tag zurück). User-lokale Sicht kommt aus `utc` per
- * separater Berechnung.
+ * `at` is local to the place (what was entered comes back on the same day).
+ * A user-local view is computed separately from `utc`.
  */
 export function createLocatedTimestampField(overrides) {
     return {

package/dist/engine/feature-ast/extractors/round2.js

@@ -1,7 +1,21 @@
 import { SyntaxKind } from "ts-morph";
 import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "../entity-field-types.js";
 import { sourceLocationFromNode } from "../source-location.js";
-import { fail, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+import { fail, isPlainObject, isRawRefSentinel, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+// `{ name: "x", ...xEntity }` — the definition is a reference the parser cannot
+// inline, so it is kept as a raw-ref sentinel and re-rendered as the same spread.
+// `backingTable` is runtime wiring (a table identifier), not part of the
+// definition data, so it does not take part in the shape check.
+function readSpreadOnlyDefinition(obj) {
+    const properties = obj
+        .getProperties()
+        .filter((property) => property.asKind(SyntaxKind.PropertyAssignment)?.getName() !== "backingTable");
+    const spread = properties.length === 2 ? properties[1]?.asKind(SyntaxKind.SpreadAssignment) : undefined;
+    if (!spread)
+        return undefined;
+    const reference = readDataLiteralNode(spread.getExpression());
+    return isRawRefSentinel(reference) ? reference : undefined;
+}
 export function extractEntity(call, sourceFile) {
     const args = call.getArguments();
     const first = args[0];
@@ -18,7 +32,7 @@ export function extractEntity(call, sourceFile) {
         if (!nameInit) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const definition = readDataLiteralNode(obj);
+        const definition = readSpreadOnlyDefinition(obj) ?? readDataLiteralNode(obj);
         if (!isPlainObject(definition)) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "definition could not be read as a plain object (contains functions or identifiers)");
         }

package/dist/engine/feature-ast/render.js

@@ -202,15 +202,12 @@ function renderDescribe(p) {
     return `r.describe(${JSON.stringify(p.text)});`;
 }
 function renderEntity(p) {
-    // A whole-value raw-ref (`r.entity("x", eventEntity)`) can't be spread
-    // into the merged Object-Form without losing `name` to the sentinel
-    // shortcut in renderValue — fall back to the classic positional form,
-    // which keeps the reference verbatim alongside the name.
+    // A whole-value raw-ref (`eventEntity`) can't go through renderValue without
+    // losing `name` to the sentinel shortcut — spread the reference verbatim
+    // next to the name instead.
     if (isRawRefSentinel(p.definition)) {
-        return `r.entity(${JSON.stringify(p.entityName)}, ${p.definition.__raw});`;
+        return `r.entity({ name: ${JSON.stringify(p.entityName)}, ...${p.definition.__raw} });`;
     }
-    // Inline `name` into the definition object — canonical Object-Form
-    // is a single arg with name-as-property.
     const merged = { name: p.entityName, ...p.definition };
     return `r.entity(${renderValue(merged)});`;
 }

package/dist/engine/feature-config-events-jobs.d.ts

@@ -25,6 +25,9 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -37,6 +40,9 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {

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

@@ -217,6 +217,11 @@ export function buildConfigEventsJobsMethods(state, name) {
                 ...(resolvedDefinition.localizedTemplate !== undefined
                     ? { localizedTemplate: resolvedDefinition.localizedTemplate }
                     : {}),
+                ...(resolvedDefinition.renamedFrom !== undefined
+                    ? { renamedFrom: resolvedDefinition.renamedFrom }
+                    : {}),
+                ...(resolvedDefinition.systemOnly === true ? { systemOnly: true } : {}),
+                ...(resolvedDefinition.unsubscribe === true ? { unsubscribe: true } : {}),
             };
         },
         translations(def) {

package/dist/engine/feature-entity-handlers.d.ts

@@ -3,34 +3,15 @@ import type { ZodType } from "zod";
 import { type QueryHandlerDefinition, type StreamHandlerDefinition, type WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
-import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, KumikoEventTypeMap, NameOrRef, PayloadRateLimitOption, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
+import type { AccessRule, EntityDefinition, EntityObjectDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, KumikoEventTypeMap, NameOrRef, RateLimitDeclaration, RelationDefinition, StreamHandlerFn } from "./types/index.js";
 export declare function buildEntityHandlerMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
-    entity(nameOrDefinition: string | ({
-        readonly name: string;
-    } & EntityDefinition), definition?: EntityDefinition, options?: {
-        readonly table?: unknown;
-    }): EntityRef;
+    entity(definition: EntityObjectDefinition): EntityRef;
     relation(entityRefOrDefinition: NameOrRef | ({
         readonly entity: NameOrRef;
         readonly name: string;
     } & RelationDefinition), relationName?: string, definition?: RelationDefinition): void;
-    writeHandler<TName_1 extends string, TSchema extends ZodType, TPrepared = undefined>(nameOrDef: string | WriteHandlerDefinition<TName_1, TSchema, unknown, KumikoEventTypeMap, TPrepared>, schema?: TSchema, handler?: WriteHandlerFn<z.infer<TSchema>>, options?: {
-        access: AccessRule;
-        rateLimit?: RateLimitDeclaration;
-        additionalRateLimits?: readonly PayloadRateLimitOption[];
-        description?: string;
-        agent?: AgentHandlerHints;
-        escapeHatch?: EscapeHatchDeclaration;
-    }): HandlerRef;
-    queryHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | QueryHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: QueryHandlerFn<z.infer<TSchema>>, options?: {
-        access: AccessRule;
-        rateLimit?: RateLimitDeclaration;
-        outputSchema?: ZodType;
-        liveEntities?: readonly string[];
-        description?: string;
-        agent?: AgentHandlerHints;
-        escapeHatch?: EscapeHatchDeclaration;
-    }): HandlerRef;
+    writeHandler<TName_1 extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName_1, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
+    queryHandler<TName_1 extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName_1, TSchema>): HandlerRef;
     streamHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | StreamHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: StreamHandlerFn<z.infer<TSchema>>, options?: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;

package/dist/engine/feature-entity-handlers.js

@@ -1,9 +1,9 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { toTableName } from "../db/table-builder.js";
 import { isEntityConventionQueryHandler, isPagedQueryHandler, PAGED_QUERY_HANDLER_BRAND, } from "./define-handler.js";
-import { registerEntityCrud } from "./entity-handlers.js";
+import { registerCrudHandlers } from "./entity-handlers.js";
 import { resolveName } from "./handler-helpers.js";
-import { splitNamedDefinition } from "./object-form.js";
+import { isObjectArgument, throwPositionalFormRemoved } from "./object-form.js";
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
 const CRUD_REGISTERED_VERBS = new Set([...CRUD_VERBS, "restore", "list", "detail"]);
 // A silent overwrite would drop framework behaviour that rides on the r.crud
@@ -65,6 +65,13 @@ function transactionPhaseSlots(def) {
         ...(def.transaction && { transaction: def.transaction }),
     };
 }
+// Typed callers cannot omit `access`; untyped ones (JS, designer output) must not get a
+// handler that silently falls through to the boot-time default-deny.
+function assertHandlerHasAccess(featureName, method, handlerName, access) {
+    if (access === undefined || access === null) {
+        throw new Error(`[Feature ${featureName}] r.${method}({ name: "${handlerName}" }) requires an access rule (access: { roles: [...] } or { openToAll: { reason } })`);
+    }
+}
 function requireInlineHandlerArgs(kind, schema, handler, options) {
     if (!schema || !handler || !options?.access) {
         throw new Error(`${kind} inline form requires schema + handler + options.access`);
@@ -75,13 +82,13 @@ function requireInlineHandlerArgs(kind, schema, handler, options) {
 // methods that create or reference entities.
 export function buildEntityHandlerMethods(state, name) {
     const methods = {
-        entity(nameOrDefinition, definition, options) {
-            const [entityName, entityDefinition] = typeof nameOrDefinition === "string"
-                ? [nameOrDefinition, definition]
-                : splitNamedDefinition(nameOrDefinition);
+        entity(definition) {
+            if (!isObjectArgument(definition))
+                throwPositionalFormRemoved(name, "entity");
+            const { name: entityName, backingTable, ...entityDefinition } = definition;
             state.entities[entityName] = entityDefinition;
-            if (options?.table !== undefined)
-                state.entityTables[entityName] = options.table;
+            if (backingTable !== undefined)
+                state.entityTables[entityName] = backingTable;
             return { name: entityName, table: entityDefinition.table ?? toTableName(entityName) };
         },
         relation(entityRefOrDefinition, relationName, definition) {
@@ -96,105 +103,75 @@ export function buildEntityHandlerMethods(state, name) {
                 state.relations[entityName] = {};
             state.relations[entityName][resolvedRelationName] = resolvedDefinition;
         },
-        writeHandler(nameOrDef, schema, handler, options) {
-            if (typeof nameOrDef === "object") {
-                const def = nameOrDef;
-                assertHandlerNameFree(state, name, "write", def.name);
-                state.writeHandlers[def.name] = {
-                    name: def.name,
-                    schema: def.schema,
-                    // @cast-boundary engine-bridge — typed Dev-API's handler is
-                    // generic over the schema's parsed payload (`WriteEvent<output<TSchema>>`),
-                    // the storage form WriteHandlerFn carries `WriteEvent<unknown>`.
-                    // Function-arg variance: TS sees the typed handler as stricter
-                    // than the loose storage shape and rejects direct assignment.
-                    // The runtime value is identical — the cast crosses that boundary.
-                    // `satisfies` does not work here (it asserts assignability, which
-                    // is what fails). Explicit cast is the right tool.
-                    handler: def.handler,
-                    access: def.access,
-                    ...agentSlots(def),
-                    ...(def.excludedFields && { excludedFields: def.excludedFields }),
-                    ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
-                    ...(def.rateLimit && { rateLimit: def.rateLimit }),
-                    ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
-                    ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
-                    ...transactionPhaseSlots(def),
-                    ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
-                    // Forward the pipeline-build closure so boot-validators and
-                    // Designer/AI tooling can inspect the step list. Absent on
-                    // free-form handlers — defineWriteHandler only sets `perform`
-                    // when the author used the pipeline form. Variance cast
-                    // mirrors the handler-cast above: PipelineDef<output<TSchema>>
-                    // is stricter than PipelineDef<unknown> for the same reason.
-                    ...(def.perform !== undefined && {
-                        perform: def.perform,
-                    }),
-                };
-                tryMapEntity(state, name, def.name);
-                return { name: def.name };
-            }
-            const inline = requireInlineHandlerArgs("writeHandler", schema, handler, options);
-            assertHandlerNameFree(state, name, "write", nameOrDef);
-            state.writeHandlers[nameOrDef] = {
-                name: nameOrDef,
-                schema: inline.schema,
-                handler: inline.handler, // @cast-boundary engine-bridge
-                access: inline.options.access,
-                ...agentSlots(inline.options),
-                ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
-                ...(inline.options.additionalRateLimits && {
-                    additionalRateLimits: inline.options.additionalRateLimits,
+        writeHandler(def) {
+            if (!isObjectArgument(def))
+                throwPositionalFormRemoved(name, "writeHandler");
+            assertHandlerHasAccess(name, "writeHandler", def.name, def.access);
+            assertHandlerNameFree(state, name, "write", def.name);
+            state.writeHandlers[def.name] = {
+                name: def.name,
+                schema: def.schema,
+                // @cast-boundary engine-bridge — typed Dev-API's handler is
+                // generic over the schema's parsed payload (`WriteEvent<output<TSchema>>`),
+                // the storage form WriteHandlerFn carries `WriteEvent<unknown>`.
+                // Function-arg variance: TS sees the typed handler as stricter
+                // than the loose storage shape and rejects direct assignment.
+                // The runtime value is identical — the cast crosses that boundary.
+                // `satisfies` does not work here (it asserts assignability, which
+                // is what fails). Explicit cast is the right tool.
+                handler: def.handler,
+                access: def.access,
+                ...agentSlots(def),
+                ...(def.excludedFields && { excludedFields: def.excludedFields }),
+                ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
+                ...(def.rateLimit && { rateLimit: def.rateLimit }),
+                ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
+                ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+                ...transactionPhaseSlots(def),
+                ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
+                // Forward the pipeline-build closure so boot-validators and
+                // Designer/AI tooling can inspect the step list. Absent on
+                // free-form handlers — defineWriteHandler only sets `perform`
+                // when the author used the pipeline form. Variance cast
+                // mirrors the handler-cast above: PipelineDef<output<TSchema>>
+                // is stricter than PipelineDef<unknown> for the same reason.
+                ...(def.perform !== undefined && {
+                    perform: def.perform,
                 }),
-                ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
             };
-            tryMapEntity(state, name, nameOrDef);
-            return { name: nameOrDef };
+            tryMapEntity(state, name, def.name);
+            return { name: def.name };
         },
-        queryHandler(nameOrDef, schema, handler, options) {
-            if (typeof nameOrDef === "object") {
-                const def = nameOrDef;
-                assertHandlerNameFree(state, name, "query", def.name);
-                state.queryHandlers[def.name] = {
-                    name: def.name,
-                    schema: def.schema,
-                    // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
-                    handler: def.handler, // @cast-boundary engine-bridge
-                    access: def.access,
-                    ...agentSlots(def),
-                    ...(def.rateLimit && { rateLimit: def.rateLimit }),
-                    ...(def.outputSchema && { outputSchema: def.outputSchema }),
-                    ...(def.liveEntities && { liveEntities: def.liveEntities }),
-                    ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
-                    // Carry the definePagedQueryHandler brand through — this rebuild
-                    // drops any field not explicitly listed.
-                    ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
-                    ...(isEntityConventionQueryHandler(def) && {
-                        [ENTITY_CONVENTION_QUERY_BRAND]: true,
-                    }),
-                };
-                tryMapEntity(state, name, def.name);
-                return { name: def.name };
-            }
-            const inline = requireInlineHandlerArgs("queryHandler", schema, handler, options);
-            assertHandlerNameFree(state, name, "query", nameOrDef);
-            state.queryHandlers[nameOrDef] = {
-                name: nameOrDef,
-                schema: inline.schema,
-                handler: inline.handler, // @cast-boundary engine-bridge
-                access: inline.options.access,
-                ...agentSlots(inline.options),
-                ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
-                ...(inline.options.outputSchema && { outputSchema: inline.options.outputSchema }),
-                ...(inline.options.liveEntities && { liveEntities: inline.options.liveEntities }),
-                ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
+        queryHandler(def) {
+            if (!isObjectArgument(def))
+                throwPositionalFormRemoved(name, "queryHandler");
+            assertHandlerHasAccess(name, "queryHandler", def.name, def.access);
+            assertHandlerNameFree(state, name, "query", def.name);
+            state.queryHandlers[def.name] = {
+                name: def.name,
+                schema: def.schema,
+                // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
+                handler: def.handler, // @cast-boundary engine-bridge
+                access: def.access,
+                ...agentSlots(def),
+                ...(def.rateLimit && { rateLimit: def.rateLimit }),
+                ...(def.outputSchema && { outputSchema: def.outputSchema }),
+                ...(def.liveEntities && { liveEntities: def.liveEntities }),
+                ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+                // Carry the definePagedQueryHandler brand through — this rebuild
+                // drops any field not explicitly listed.
+                ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
+                ...(isEntityConventionQueryHandler(def) && {
+                    [ENTITY_CONVENTION_QUERY_BRAND]: true,
+                }),
             };
-            tryMapEntity(state, name, nameOrDef);
-            return { name: nameOrDef };
+            tryMapEntity(state, name, def.name);
+            return { name: def.name };
         },
         streamHandler(nameOrDef, schema, handler, options) {
             if (typeof nameOrDef === "object") {
                 const def = nameOrDef;
+                assertHandlerHasAccess(name, "streamHandler", def.name, def.access);
                 state.streamHandlers[def.name] = {
                     name: def.name,
                     schema: def.schema,
@@ -221,7 +198,7 @@ export function buildEntityHandlerMethods(state, name) {
     return {
         ...methods,
         crud(entityName, entity, options) {
-            registerEntityCrud(methods, entityName, entity, options);
+            registerCrudHandlers(methods, entityName, entity, options);
         },
     };
 }

package/dist/engine/feature-ui-extensions.d.ts

@@ -2,17 +2,12 @@ import { type WebSocketRouteDefinition } from "@cosmicdrift/kumiko-types/websock
 import type { EntityTableMeta } from "../db/entity-table-meta.js";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
 import type { HttpRouteDefinition } from "./types/http-route.js";
-import type { BootCheckFn, EntityProjectionExtension, EscapeHatchDeclaration, ExtensionSelectorPanel, HookPhase, LifecycleHookFn, LifecycleHookType, MultiStreamProjectionDefinition, NameOrRef, ProjectionDefinition, RegistrarExtensionDef, SearchPayloadContributorFn, StoreTableOptions, TreeActionDef, TreeActionsHandle, ValidationHookFn } from "./types/index.js";
+import type { BootCheckFn, EntityProjectionExtension, ExtensionSelectorPanel, HookDefinition, MultiStreamProjectionDefinition, NameOrRef, ProjectionDefinition, RegistrarExtensionDef, SearchPayloadContributorFn, StoreTableOptions, TreeActionDef, TreeActionsHandle } from "./types/index.js";
 import type { ContentCollectionDefinition, NavDefinition } from "./types/nav.js";
 import type { ScreenDefinition } from "./types/screen.js";
 import type { WorkspaceDefinition } from "./types/workspace.js";
 export declare function buildUiExtensionsMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
-    hook(type: LifecycleHookType | "validation", target: NameOrRef | readonly NameOrRef[] | {
-        readonly allOf: NameOrRef;
-    }, fn: LifecycleHookFn | ValidationHookFn, options?: {
-        phase?: HookPhase;
-        escapeHatch?: EscapeHatchDeclaration;
-    }): void;
+    hook(definition: HookDefinition): void;
     searchPayloadExtension(entityRef: NameOrRef, fn: SearchPayloadContributorFn): void;
     extendsRegistrar(extensionName: string, def: RegistrarExtensionDef): void;
     useExtension(extensionNameOrDefinition: string | ({
@@ -25,20 +20,20 @@ export declare function buildUiExtensionsMethods<TName extends string>(state: Fe
         readonly panels?: readonly ExtensionSelectorPanel[];
     }): void;
     /**
-     * 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.
+     * Marker declaration: this feature provides a cross-feature API under
+     * the given name. The implementation is registered separately as a query
+     * or write handler under the QN pattern; r.exposesApi only feeds the
+     * boot check.
      *
-     * Beispiel:
+     * Example:
      *   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.requires({ features: ["compliance-profiles"] });
      *     r.usesApi("compliance.forTenant");
-     *     // ruft im Handler: ctx.callQuery("compliance:query:for-tenant", ...)
+     *     // in a handler: ctx.callQuery("compliance:query:for-tenant", ...)
      *   });
      */
     exposesApi(apiName: string): void;

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

@@ -4,6 +4,7 @@ import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES,
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
 import { resolveName } from "./handler-helpers.js";
+import { isObjectArgument, throwPositionalFormRemoved } from "./object-form.js";
 import { isKebabSegment, isValidQn, qualifyEntityName, toKebab } from "./qualified-name.js";
 import { HookPhases } from "./types/index.js";
 // Builds hooks/extensions/projections/screens/nav/workspace/tables/tree-actions
@@ -43,8 +44,8 @@ function isEntityWideHookType(type) {
         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
+// r.hook({ type, target: { allOf: entity }, handler }) — "all write/query handlers of
+// this entity". Hook-fn casts
 // below: @cast-boundary engine-bridge — typed Dev-API (LifecycleHookFn) →
 // erased Map<entityName, fn>.
 function registerEntityWideHook(state, featureName, type, entityName, fn, options) {
@@ -107,21 +108,28 @@ export function buildUiExtensionsMethods(state, name) {
         state.navs[navDefinition.id] = Object.fromEntries(Object.entries(navDefinition).filter(([, value]) => value !== undefined));
     }
     return {
-        hook(type, target, fn, options) {
+        hook(definition) {
+            if (!isObjectArgument(definition))
+                throwPositionalFormRemoved(name, "hook");
+            const { type, target, handler: fn } = definition;
+            const options = {
+                ...(definition.phase !== undefined && { phase: definition.phase }),
+                ...(definition.escapeHatch !== undefined && { escapeHatch: definition.escapeHatch }),
+            };
             if (type === "validation") {
                 if (options?.escapeHatch !== undefined) {
-                    throw new Error(`[Feature ${name}] r.hook("validation", ...) does not accept { escapeHatch } — ` +
+                    throw new Error(`[Feature ${name}] r.hook({ type: "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: "" } } — ` +
+                throw new Error(`[Feature ${name}] r.hook({ type: "${type}", … }) declares escapeHatch: { reason: "" } — ` +
                     "the reason must be a non-empty string explaining why this hook switches identity to SYSTEM.");
             }
             const hookGrantsProblem = options?.escapeHatch && escapeHatchGrantsProblem(options.escapeHatch);
             if (hookGrantsProblem) {
-                throw new Error(`[Feature ${name}] r.hook("${type}", ...) declares an invalid escapeHatch — ${hookGrantsProblem}`);
+                throw new Error(`[Feature ${name}] r.hook({ type: "${type}", … }) declares an invalid escapeHatch — ${hookGrantsProblem}`);
             }
             // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
             const hookLabel = `${type} hook of feature "${name}"`;
@@ -135,7 +143,7 @@ export function buildUiExtensionsMethods(state, name) {
                 !Array.isArray(target) &&
                 "allOf" in target) {
                 if (!isEntityWideHookType(type)) {
-                    throw new Error(`[Feature ${name}] r.hook("${type}", { allOf }, ...) only supports ` +
+                    throw new Error(`[Feature ${name}] r.hook({ type: "${type}", target: { allOf }, … }) only supports ` +
                         `postSave/preDelete/postDelete/postQuery, not "${type}".`);
                 }
                 registerEntityWideHook(state, name, type, resolveName(target.allOf), wrapped, // @cast-boundary engine-bridge
@@ -241,20 +249,20 @@ export function buildUiExtensionsMethods(state, name) {
             });
         },
         /**
-         * 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.
+         * Marker declaration: this feature provides a cross-feature API under
+         * the given name. The implementation is registered separately as a query
+         * or write handler under the QN pattern; r.exposesApi only feeds the
+         * boot check.
          *
-         * Beispiel:
+         * Example:
          *   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.requires({ features: ["compliance-profiles"] });
          *     r.usesApi("compliance.forTenant");
-         *     // ruft im Handler: ctx.callQuery("compliance:query:for-tenant", ...)
+         *     // in a handler: ctx.callQuery("compliance:query:for-tenant", ...)
          *   });
          */
         exposesApi(apiName) {

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

@@ -18,5 +18,30 @@ export type HandlerFieldReferenceReading = {
     readonly kind: "ok";
     readonly reference: HandlerFieldReference;
 };
+export type HandlerFieldPathSegment = {
+    readonly kind: "field";
+    readonly name: string;
+} | {
+    readonly kind: "element";
+} | {
+    readonly kind: "recordKey";
+} | {
+    readonly kind: "recordValue";
+};
+export type HandlerFieldReferenceAtPath = {
+    readonly path: string;
+    readonly segments: readonly HandlerFieldPathSegment[];
+    readonly reading: Exclude<HandlerFieldReferenceReading, {
+        kind: "none";
+    }>;
+};
 export declare function readHandlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReferenceReading;
+/** All reference metas of a handler input schema, including fields nested in arrays,
+ *  objects and records. `z.lazy()` is not followed. */
+export declare function readHandlerFieldReferences(schema: z.ZodType): readonly HandlerFieldReferenceAtPath[];
+export declare function handlerFieldReferences(schema: z.ZodType): readonly {
+    readonly path: string;
+    readonly segments: readonly HandlerFieldPathSegment[];
+    readonly reference: HandlerFieldReference;
+}[];
 export declare function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;