@cosmicdrift/kumiko-framework 0.365.0 → 0.366.0

package/dist/engine/define-feature.js

@@ -2,7 +2,7 @@ import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
-import { unwrapArrayForm } from "./object-form.js";
+import { isObjectArgument, throwPositionalFormRemoved, unwrapArrayForm } from "./object-form.js";
 // `TExports` lets the setup callback hand back a typed object that
 // downstream features can import (e.g. `tenantFeature.exports.config`). The
 // runtime always packs whatever setup returns into `featureDef.exports` —
@@ -15,10 +15,8 @@ import { unwrapArrayForm } from "./object-form.js";
 // for `ctx.appendEvent({ type: eventDef.name, ... })` lights up. Apps
 // that don't care can keep the default-string and use the wrapper-based
 // strict-mode (string-literal types per call-site) like before.
-// requires/optionalRequires accept either variadic strings (hand-written
-// call sites) or a single `{ features }` object (the feature-ast renderer's
-// canonical Object-Form for Designer/AI-generated code) — see the matching
-// overloads on RequiresApi / FeatureRegistrar['optionalRequires'].
+// optionalRequires accepts either variadic strings or a single `{ features }` object; requires
+// takes only the object (see RequiresApi).
 function resolveFeatureNamesArgs(args) {
     return unwrapArrayForm(args, "features");
 }
@@ -50,6 +48,8 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
+                if (!args.every(isObjectArgument))
+                    throwPositionalFormRemoved(name, "requires");
                 state.requires.push(...resolveFeatureNamesArgs(args));
             };
             fn.projection = (tableName) => {

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

@@ -63,5 +63,5 @@ export declare function defineProjectionQueryHandler(name: string, projectionQua
     };
     escapeHatch?: EscapeHatchDeclaration;
 }): QueryHandlerDef;
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export declare function registerEntityCrud(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export declare function registerCrudHandlers(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;

package/dist/engine/entity-handlers.js

@@ -551,21 +551,21 @@ function defaultCrudVerbs(entity) {
         detail: true,
     };
 }
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export function registerEntityCrud(r, entityName, entity, options) {
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export function registerCrudHandlers(r, entityName, entity, options) {
     const verbs = { ...defaultCrudVerbs(entity), ...options?.verbs };
     if (verbs.restore && entity.softDelete !== true) {
         throw new Error(`restore requested but entity "${entityName}" has no softDelete: true`);
     }
     if (options?.registerEntity !== false) {
-        r.entity(entityName, entity);
+        r.entity({ name: entityName, ...entity });
     }
     const writeOpts = options?.write;
     const readOpts = options?.read;
     const requireAccess = (verb, access) => {
         if (!access) {
-            throw new Error(`registerEntityCrud("${entityName}", verb: "${verb}"): no access rule resolved. ` +
-                `Set write.access/read.access on registerEntityCrud's options, or verbAccess.${verb}.`);
+            throw new Error(`r.crud("${entityName}", …): no access rule resolved for verb "${verb}". ` +
+                `Set write.access/read.access in r.crud's options, or verbAccess.${verb}.`);
         }
         return access;
     };

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,7 @@ 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[];
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -37,6 +38,7 @@ 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[];
     }): 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,9 @@ export function buildConfigEventsJobsMethods(state, name) {
                 ...(resolvedDefinition.localizedTemplate !== undefined
                     ? { localizedTemplate: resolvedDefinition.localizedTemplate }
                     : {}),
+                ...(resolvedDefinition.renamedFrom !== undefined
+                    ? { renamedFrom: resolvedDefinition.renamedFrom }
+                    : {}),
             };
         },
         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;