@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/engine/entity-handlers.js

@@ -0,0 +1,567 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import * as z from "zod";
+import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { buildEntityTable } from "../db/table-builder.js";
+import { acknowledgeConventionCrossTenant } from "../db/tenant-db.js";
+import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
+import { assertUnreachable } from "../utils/index.js";
+import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { instructionFieldNames } from "./instruction-fields.js";
+import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
+// Convention-based handler factories for event-sourced aggregates.
+//
+// You register one handler per call (no auto-generation of a whole CRUD set),
+// but the Schema and the executor body are inferred from the entity + verb.
+// Pick the verbs you need — leave out the ones you don't.
+//
+// Two API shapes — pick one per project, don't mix:
+//
+//   PREFERRED — full standard CRUD set in one call:
+//     r.crud("note", noteEntity, { write: { access }, read: { access } })
+//
+//   PREFERRED — one function per verb, type-safe, no magic strings:
+//     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
+//     r.writeHandler(defineEntityUpdateHandler("note", noteEntity, { access }))
+//     r.writeHandler(defineEntityDeleteHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityListHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }))
+//
+//   LEGACY — single function with verb in the name-string. Kept for
+//   backwards-compat; existing apps work as before. New code should use
+//   the verb-specific factories above:
+//     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }))
+//
+// For custom logic (default values, business rules, side effects, custom
+// executors with ctx.searchAdapter, ...) write the handler explicitly with
+// r.writeHandler / r.queryHandler — these helpers cover the standard path only.
+//
+// Note on the `as` casts in the handler bodies: WriteHandlerDef.handler's
+// payload type is `unknown` because the dispatcher hands the parsed payload
+// through a runtime-only boundary. Each verb knows its post-parse shape (the
+// schema we just built two lines up enforces it), so the casts are a
+// localised re-declaration of that shape rather than a narrowing escape.
+const WRITE_VERBS = ["create", "update", "delete", "restore"];
+const QUERY_VERBS = ["list", "detail"];
+const idSchema = z.object({ id: z.uuid() });
+// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
+const deprecatedCrossTenantHandlers = new WeakSet();
+export function isDeprecatedCrossTenantHandler(handler) {
+    return deprecatedCrossTenantHandlers.has(handler);
+}
+export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
+function resolveCrossTenantReason(name, options) {
+    if (options.escapeHatch !== undefined && options.crossTenant === true) {
+        throw new Error(`"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`);
+    }
+    if (options.escapeHatch !== undefined) {
+        if (options.escapeHatch.reason.trim().length === 0) {
+            throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
+        }
+        return options.escapeHatch.reason;
+    }
+    if (options.crossTenant === true) {
+        return `deprecated crossTenant: true on entity convention handler ${name}`;
+    }
+    return undefined;
+}
+// Upper bound on entity-list `limit`: unbounded/fractional values ran
+// straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
+// read.ts), letting a client demand a full-table materialisation or trip a
+// Postgres syntax error on a non-integer literal.
+export const MAX_LIST_LIMIT = 200;
+export const entityListSchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
+    search: z.string().optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+    offset: z.number().int().nonnegative().optional(),
+    totalCount: z.boolean().optional(),
+    // Trash query: include soft-deleted rows. Honoured only for softDelete
+    // entities; the dispatcher mirrors it onto ctx.includeDeleted. Tenant +
+    // ownership filters still apply.
+    includeDeleted: z.boolean().optional(),
+    filter: z
+        .object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
+        // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
+        // lässt alles durch; Type-Check kommt im executor.list.
+        value: z.unknown(),
+    })
+        .optional(),
+    // User-gewählte Faceted-Filter (dynamisch). Additiv zum statischen
+    // `filter` — executor.list verknüpft alle mit AND.
+    filters: z
+        .array(z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        value: z.unknown(),
+    }))
+        .optional(),
+});
+function parseHandlerName(name, validVerbs) {
+    const colonIdx = name.indexOf(":");
+    if (colonIdx < 0) {
+        throw new Error(`Handler name "${name}" must use the "<entity>:<verb>" pattern (e.g. "note:create").`);
+    }
+    const entityName = name.slice(0, colonIdx);
+    const verbCandidate = name.slice(colonIdx + 1);
+    if (!entityName) {
+        throw new Error(`Handler name "${name}" is missing the entity part before the colon.`);
+    }
+    const verbs = validVerbs; // @cast-boundary engine-bridge
+    if (!verbs.includes(verbCandidate)) {
+        throw new Error(`Unknown verb "${verbCandidate}" in handler name "${name}". Standard verbs: ${validVerbs.join("/")}. For custom verbs use the explicit r.writeHandler / r.queryHandler form.`);
+    }
+    return { entityName, verb: verbCandidate }; // @cast-boundary engine-bridge
+}
+function isInTotalsMatchPair(entity, fieldName) {
+    return Object.entries(entity.fields).some(([name, field]) => field.type === "embedded" &&
+        field.totalsMatch !== undefined &&
+        (name === fieldName || Object.values(field.totalsMatch).includes(fieldName)));
+}
+// A create/update handler can write a field flagged readAsInstruction: true if:
+// update — the field isn't in excludeFields; create — the field isn't excluded,
+// or is excluded but has a default (applyDefaults writes it regardless, so the
+// define-time floor must match what the executor gate will see at runtime).
+function writableInstructionFields(verb, entity, excludedFields) {
+    return instructionFieldNames(entity).filter((fieldName) => {
+        if (!excludedFields.includes(fieldName))
+            return true;
+        if (verb !== "create")
+            return false;
+        const field = entity.fields[fieldName];
+        return field !== undefined && "default" in field && field.default !== undefined;
+    });
+}
+// delete on an entity without softDelete hard-purges the row, and create/update
+// handlers writing a readAsInstruction field are irreversible in effect (a
+// revert doesn't undo a run that already read the value) — the agent risk gate
+// only protects either case if this handler resolves to "high".
+function resolveEntityWriteAgentHints(name, verb, entity, agent, excludedFields) {
+    const isIrreversibleDelete = verb === "delete" && !entity.softDelete;
+    const instructionFields = verb === "create" || verb === "update"
+        ? writableInstructionFields(verb, entity, excludedFields)
+        : [];
+    if (!isIrreversibleDelete && instructionFields.length === 0)
+        return agent;
+    if (agent?.risk !== undefined && agent.risk !== "high") {
+        const reason = isIrreversibleDelete
+            ? "delete on an entity without softDelete is irreversible"
+            : `it writes field(s) ${instructionFields.join(", ")} flagged readAsInstruction: true`;
+        throw new Error(`"${name}": ${reason} — agent.risk must be "high" (got "${agent.risk}").`);
+    }
+    return { ...agent, risk: "high" };
+}
+function assertExcludableFields(name, verb, entity, excludedFields) {
+    if (excludedFields.length > 0 && verb !== "create" && verb !== "update") {
+        throw new Error(`"${name}": excludeFields only applies to create and update handlers.`);
+    }
+    for (const fieldName of excludedFields) {
+        const field = entity.fields[fieldName];
+        if (!field) {
+            throw new Error(`"${name}": excludeFields names unknown field "${fieldName}".`);
+        }
+        if (isInTotalsMatchPair(entity, fieldName)) {
+            throw new Error(`"${name}": excludeFields cannot name "${fieldName}" — it is part of a totalsMatch pair, which must be written together.`);
+        }
+        const isRequired = "required" in field && field.required === true;
+        const hasDefault = "default" in field && field.default !== undefined;
+        if (verb === "create" && isRequired && !hasDefault) {
+            throw new Error(`"${name}": excludeFields cannot name "${fieldName}" — it is required without a default, so no row could ever be created.`);
+        }
+    }
+}
+export function defineEntityWriteHandler(name, entity, options) {
+    const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
+    if (verb === "restore" && !entity.softDelete) {
+        throw new Error(`"${name}": restore is only valid for entities declared with softDelete: true.`);
+    }
+    const excludedFields = options.excludeFields ?? [];
+    assertExcludableFields(name, verb, entity, excludedFields);
+    const agentHints = resolveEntityWriteAgentHints(name, verb, entity, options.agent, excludedFields);
+    const table = buildEntityTable(entityName, entity);
+    const executor = createEventStoreExecutor(table, entity, { entityName });
+    // r.systemScope() features (tenant, config, secrets, ...) hand their
+    // entity-convention handlers a fail-closed ctx.db — this generic layer
+    // has no per-call business reason to give assertTenantMatch, so it
+    // acknowledges cross-tenant access on the feature's behalf. This is
+    // behavior-preserving: ctx.db was already an unfiltered "system"-mode
+    // TenantDb for these handlers before the ctx.db cutover.
+    //
+    // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+    // query-handler branch below: this ONE write handler reads/writes across
+    // every tenant without making the whole feature r.systemScope().
+    const crossTenantReason = resolveCrossTenantReason(name, options);
+    const dbFor = (ctx) => {
+        if (ctx.systemDb) {
+            return ctx.systemDb.acknowledgeCrossTenant(`entity convention handler for r.systemScope() feature (${name})`);
+        }
+        return crossTenantReason !== undefined
+            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+            : ctx.db;
+    };
+    // The event stream is keyed by the acting user's tenantId (streamTenantFor in
+    // event-store-executor-context.ts), not by the db handed to the executor — an
+    // unfiltered "system"-mode db alone reads the foreign row but appends to an
+    // empty stream in the operator's own tenant, surfacing as a bogus
+    // version_conflict. Rewriting the acting tenant also keeps PII envelope keys
+    // derived from the row's tenant rather than the operator's.
+    const actingUserFor = async (user, id, db) => {
+        if (crossTenantReason === undefined || entity.systemStream)
+            return user;
+        const row = await db.fetchOne(table, { id });
+        const rowTenantId = row?.["tenantId"];
+        if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
+            return user;
+        return { ...user, tenantId: rowTenantId };
+    };
+    let schema;
+    let handler;
+    switch (verb) {
+        case "create":
+            schema = buildInsertSchema(entity, undefined, excludedFields);
+            handler = async (event, ctx) => {
+                const { runPreSave } = ctx;
+                // A caller-chosen id (deterministic-id idempotent creates) is only
+                // honored for a system-identity caller (jobs/hooks via
+                // createSystemUser) — an HTTP-authenticated end user can never
+                // present that identity, so their payload.id is dropped exactly as
+                // before this field became part of the schema.
+                const { id: _callerId, ...payloadWithoutId } = event.payload;
+                const payload = isSystemIdentity(event.user) ? event.payload : payloadWithoutId;
+                return executor.create(payload, event.user, dbFor(ctx), {
+                    preSave: runPreSave &&
+                        ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
+                });
+            };
+            break;
+        case "update":
+            schema = z.object({
+                id: z.uuid(),
+                version: z.number(),
+                changes: buildUpdateSchema(entity, undefined, excludedFields),
+            });
+            handler = async (event, ctx) => {
+                const { runPreSave } = ctx;
+                const db = dbFor(ctx);
+                const payload = event.payload; // @cast-boundary engine-payload
+                const user = await actingUserFor(event.user, payload.id, db);
+                // skipUnchanged (#464): API-driven updates diff against the stored
+                // row so a resubmitted-but-identical field doesn't force a fresh
+                // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
+                // KEK-rotation, the user-data-rights #494 backfill) don't go through
+                // this handler and keep today's always-re-encrypt behavior, which
+                // they rely on to intentionally force a fresh event/ciphertext.
+                return executor.update(payload, user, db, {
+                    skipUnchanged: true,
+                    preSave: runPreSave &&
+                        ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
+                });
+            };
+            break;
+        case "delete":
+            schema = idSchema;
+            handler = async (event, ctx) => {
+                const db = dbFor(ctx);
+                const payload = event.payload; // @cast-boundary engine-payload
+                const user = await actingUserFor(event.user, payload.id, db);
+                return executor.delete(payload, user, db);
+            };
+            break;
+        case "restore":
+            schema = idSchema;
+            handler = async (event, ctx) => {
+                const db = dbFor(ctx);
+                const payload = event.payload; // @cast-boundary engine-payload
+                const user = await actingUserFor(event.user, payload.id, db);
+                return executor.restore(payload, user, db);
+            };
+            break;
+        default:
+            assertUnreachable(verb, "write verb");
+    }
+    if (options.crossTenant === true)
+        deprecatedCrossTenantHandlers.add(handler);
+    // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
+    return {
+        name,
+        schema,
+        handler,
+        access: options.access,
+        ...(options.description !== undefined && { description: options.description }),
+        ...(agentHints !== undefined && { agent: agentHints }),
+    };
+}
+// Append read-time derived-field values (EntityDefinition.derivedFields) to
+// each row, after the SQL fetch + reference eagerload — i.e. on the row shape
+// the view-model will see. The clock is the read instant; derive bodies must
+// read it from ctx.asOf, never their own Date/Temporal.Now. No-op (returns the
+// rows untouched) when the entity declares no derived fields.
+function augmentDerivedFields(rows, entity) {
+    const derived = entity.derivedFields;
+    if (derived === undefined)
+        return rows;
+    const entries = Object.entries(derived);
+    if (entries.length === 0)
+        return rows;
+    const ctx = { asOf: Temporal.Now.instant() };
+    return rows.map((row) => {
+        const out = { ...row };
+        for (const [fieldName, def] of entries) {
+            out[fieldName] = def.derive(row, ctx);
+        }
+        return out;
+    });
+}
+export function defineEntityQueryHandler(name, entity, options) {
+    const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
+    const table = buildEntityTable(entityName, entity);
+    const executor = createEventStoreExecutor(table, entity, { entityName });
+    let schema;
+    let handler;
+    // Tier 2.7e server-eagerload: when the entity has reference fields, the
+    // handler resolves the UUIDs against the referenced entities after the
+    // main query. The `_refs` property lands on every row; the renderer-side
+    // useReferenceLookup stays as a fallback (for apps that write custom
+    // handlers by hand without this wrapper).
+    const hasRefFields = collectReferenceFields(entity).length > 0;
+    const crossTenantReason = resolveCrossTenantReason(name, options);
+    // Preference order:
+    //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
+    //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
+    //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
+    //     TenantDb for these handlers before that cutover.
+    //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+    //     ONE handler reads across every tenant (e.g. a SystemAdmin-only
+    //     operator inspector) without making the whole feature r.systemScope()
+    //     — that would drop tenant isolation from every OTHER handler the
+    //     feature registers too. The executor's list()/detail() only add a
+    //     tenant filter when db.mode === "tenant" (see event-store-executor.ts),
+    //     so handing them a "system"-mode TenantDb built from the same raw
+    //     connection is enough to skip it — access-control (who may call this
+    //     handler at all) is unaffected, still gated by `options.access`.
+    //  3. plain ctx.db — the common case, tenant-filtered.
+    const dbFor = (ctx) => {
+        if (ctx.systemDb) {
+            return ctx.systemDb.acknowledgeCrossTenant(`entity convention handler for r.systemScope() feature (${entityName}:${verb})`);
+        }
+        return crossTenantReason !== undefined
+            ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+            : ctx.db;
+    };
+    switch (verb) {
+        case "list":
+            schema = entityListSchema;
+            handler = async (query, ctx) => {
+                // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
+                // damit payload.search zur Laufzeit gegen Meilisearch/InMem
+                // läuft (Remote-Combobox-Search). Der executor wird beim
+                // Definition-Time gebaut, kennt den Adapter also nicht —
+                // Runtime-Override holt das.
+                const listPayload = query.payload; // @cast-boundary engine-payload
+                const db = dbFor(ctx);
+                const result = await executor.list(listPayload, query.user, db, {
+                    ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+                    ...(ctx.includeDeleted === true && { includeDeleted: true }),
+                    // fw#2660 — registry access only exists at request time, so the
+                    // searchable-reference cache + entity resolver travel through the
+                    // same runtime-override extension point as searchAdapter above.
+                    referenceSearch: {
+                        fields: ctx.registry.getSearchableReferences(entityName),
+                        resolveEntity: (name) => ctx.registry.getEntity(name),
+                    },
+                    referenceSort: {
+                        fields: ctx.registry.getSortableReferences(entityName),
+                        resolveEntity: (name) => ctx.registry.getEntity(name),
+                    },
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                });
+                const enrichedRows = hasRefFields
+                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db)
+                    : result.rows;
+                return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
+            };
+            break;
+        case "detail":
+            schema = idSchema;
+            handler = async (query, ctx) => {
+                const db = dbFor(ctx);
+                const row = await executor.detail(query.payload, query.user, db, {
+                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                }); // @cast-boundary engine-payload
+                if (row === null || !hasRefFields)
+                    return row;
+                return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db);
+            };
+            break;
+        default:
+            assertUnreachable(verb, "query verb");
+    }
+    if (options.crossTenant === true)
+        deprecatedCrossTenantHandlers.add(handler);
+    // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
+    return {
+        name,
+        schema,
+        handler,
+        access: options.access,
+        ...(options.description !== undefined && { description: options.description }),
+        ...(options.agent !== undefined && { agent: options.agent }),
+        // The "list" verb's executor.list() always returns { rows, nextCursor,
+        // total? } (see the handler body above) — brand it so the definition
+        // site documents the PagedRows contract without needing
+        // definePagedQueryHandler on top. The "detail" verb returns a single
+        // row/null, never this shape.
+        ...(verb === "list" && { [PAGED_QUERY_HANDLER_BRAND]: true }),
+        [ENTITY_CONVENTION_QUERY_BRAND]: true,
+    };
+}
+// ─── Verb-specific factories (preferred) ──────────────────────────────
+//
+// One function per verb — verb is the function name, no magic-string
+// parsing. Each delegates to the legacy `defineEntityWriteHandler` /
+// `defineEntityQueryHandler` with a fixed verb-suffix; the schema +
+// handler-body logic is unchanged. Migration from the legacy API is a
+// 1:1 rename — same arguments minus the verb-prefix in the name-string.
+//
+// Why prefer these over the legacy form:
+//   - Verb is checked at compile-time (no runtime "Unknown verb" throw)
+//   - IDE auto-completes the four/two verbs after typing `defineEntity`
+//   - Function name is self-documenting; no comment needed to explain
+//   - Entity-name appears once (used to be doubled: once in the string,
+//     once as the entity-arg)
+//
+// Restore-specific note: defineEntityRestoreHandler still validates at
+// runtime that entity.softDelete === true. A compile-time-only check
+// would need a Branded-EntityDefinition with `softDelete: true` literal
+// — feasible but not yet wired; the runtime guard catches misuse.
+// @wrapper-known semantic-alias
+export function defineEntityCreateHandler(entityName, entity, options) {
+    return defineEntityWriteHandler(`${entityName}:create`, entity, options);
+}
+// @wrapper-known semantic-alias
+export function defineEntityUpdateHandler(entityName, entity, options) {
+    return defineEntityWriteHandler(`${entityName}:update`, entity, options);
+}
+// @wrapper-known semantic-alias
+export function defineEntityDeleteHandler(entityName, entity, options) {
+    return defineEntityWriteHandler(`${entityName}:delete`, entity, options);
+}
+// @wrapper-known semantic-alias
+export function defineEntityRestoreHandler(entityName, entity, options) {
+    return defineEntityWriteHandler(`${entityName}:restore`, entity, options);
+}
+// @wrapper-known semantic-alias
+export function defineEntityListHandler(entityName, entity, options) {
+    return defineEntityQueryHandler(`${entityName}:list`, entity, options);
+}
+// @wrapper-known semantic-alias
+export function defineEntityDetailHandler(entityName, entity, options) {
+    return defineEntityQueryHandler(`${entityName}:detail`, entity, options);
+}
+// Bundle the two calls every custom write-handler opens with: build the
+// Drizzle table from the entity, then wire an event-store executor onto it.
+// The pair is identical in every sample that hand-writes handlers, so the
+// helper collapses 3-4 lines + the { entityName } bookkeeping into one.
+//
+//   const { table, executor } = createEntityExecutor("counter", counterEntity);
+//
+// Keep using the explicit buildEntityTable / createEventStoreExecutor duo
+// when you need search-adapter / entity-cache options on the executor — this
+// helper covers the zero-config case.
+export function createEntityExecutor(entityName, entity) {
+    const table = buildEntityTable(entityName, entity);
+    const executor = createEventStoreExecutor(table, entity, { entityName });
+    return { table, executor };
+}
+// Wrap a projection read into a zero-argument query handler. Use when the
+// read is "give me all rows from projection X, tenant-scoped" — the common
+// shape for list-views backed by an MSP/projection table.
+//
+//   r.queryHandler(
+//     defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue", {
+//       access: { openToAll: { reason: "any signed-in user reviews aggregate revenue" } },
+//     }),
+//   );
+//
+// For anything more involved (filters, joins, custom shaping), write the
+// query-handler explicitly with ctx.queryProjection or a raw select.
+export function defineProjectionQueryHandler(name, projectionQualifiedName, options) {
+    return {
+        name,
+        schema: z.object({}),
+        // Returns the raw row array — matches ctx.queryProjection's shape so the
+        // helper is a drop-in for the inline `async (_q, ctx) => ctx.queryProjection(...)`
+        // handler. Wrap the result in the caller's handler when you need
+        // pagination envelopes or added metadata.
+        handler: async (_query, ctx) => ctx.queryProjection(projectionQualifiedName, options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined), // @wrapper-known semantic-alias
+        access: options.access,
+        ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
+    };
+}
+function defaultCrudVerbs(entity) {
+    return {
+        create: true,
+        update: true,
+        delete: true,
+        restore: entity.softDelete === true,
+        list: true,
+        detail: true,
+    };
+}
+/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
+export function registerEntityCrud(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);
+    }
+    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}.`);
+        }
+        return access;
+    };
+    const resolveWriteOpts = (verb) => {
+        const excludeFields = verb === "create" || verb === "update" ? options?.excludeFields?.[verb] : undefined;
+        return {
+            ...writeOpts,
+            access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
+            description: options?.descriptions?.[verb] ?? writeOpts?.description,
+            ...(excludeFields !== undefined && { excludeFields }),
+        };
+    };
+    const resolveReadOpts = (verb) => ({
+        ...readOpts,
+        access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
+        description: options?.descriptions?.[verb] ?? readOpts?.description,
+    });
+    if (verbs.create) {
+        r.writeHandler(defineEntityCreateHandler(entityName, entity, resolveWriteOpts("create")));
+    }
+    if (verbs.update) {
+        r.writeHandler(defineEntityUpdateHandler(entityName, entity, resolveWriteOpts("update")));
+    }
+    if (verbs.delete) {
+        r.writeHandler(defineEntityDeleteHandler(entityName, entity, resolveWriteOpts("delete")));
+    }
+    if (verbs.restore) {
+        r.writeHandler(defineEntityRestoreHandler(entityName, entity, resolveWriteOpts("restore")));
+    }
+    if (verbs.list) {
+        r.queryHandler(defineEntityListHandler(entityName, entity, resolveReadOpts("list")));
+    }
+    if (verbs.detail) {
+        r.queryHandler(defineEntityDetailHandler(entityName, entity, resolveReadOpts("detail")));
+    }
+}

package/dist/engine/escape-hatch-declaration.d.ts

@@ -0,0 +1,2 @@
+import type { EscapeHatchDeclaration } from "@cosmicdrift/kumiko-types/handlers";
+export declare function declareEscapeHatch(_declaration: EscapeHatchDeclaration): void;

package/dist/engine/escape-hatch-declaration.js

@@ -0,0 +1,5 @@
+// Marks a standalone helper that escalates on a HandlerContext handed to it
+// by its caller. The caller's registration carries the escapeHatch that
+// authorizes it; this call makes the escalation visible at the site where it
+// happens, where the guard and a reviewer both see it.
+export function declareEscapeHatch(_declaration) { }

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

@@ -0,0 +1,11 @@
+import type { EventDef, HandlerContext } from "./types/handlers.js";
+export type EmitCtx = Pick<HandlerContext, "unsafeAppendEvent">;
+export declare function emitEvent<TPayload>(ctx: EmitCtx, eventDef: EventDef<TPayload>, args: {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly payload: TPayload;
+}): Promise<void>;
+export declare function typedPayload<TPayload>(event: {
+    readonly type: string;
+    readonly payload: Record<string, unknown>;
+}, eventDef: EventDef<TPayload>): TPayload;

package/dist/engine/event-helpers.js

@@ -0,0 +1,47 @@
+// Typed wrapper around ctx.appendEvent. Two wins over the raw call:
+//
+//   1. The payload is checked against the EventDef's inferred TPayload,
+//      so a Zod-schema mismatch becomes a compile error at the emit site
+//      rather than a runtime reject from the event-store append.
+//   2. The event name is carried by the def — no hand-typed
+//      "<feature>:event:<short>" string, no typos.
+//
+//   await emitEvent(ctx, orderPlaced, {
+//     aggregateId: String(result.data.id),
+//     aggregateType: "pubsub-order",
+//     payload: { id, customer, product },
+//   });
+//
+// aggregateType stays explicit on purpose — the EventDef doesn't know which
+// aggregate owns an event (cross-feature reuse is legal). Use the raw
+// ctx.appendEvent when the event name is computed at runtime.
+export async function emitEvent(ctx, eventDef, args) {
+    const appendArgs = {
+        aggregateId: args.aggregateId,
+        aggregateType: args.aggregateType,
+        type: eventDef.name,
+        payload: args.payload,
+    };
+    await ctx.unsafeAppendEvent(appendArgs);
+}
+// Read-side counterpart: narrow a StoredEvent's `payload` (declared as
+// `Record<string, unknown>` because a stream carries many event types) to
+// the EventDef's inferred TPayload. Replaces the scattered
+// `event.payload as { ... }` casts inside projection-apply handlers and
+// reducers — the cast is named, the shape comes from a single source
+// (the defineEvent() schema), and a mismatched event-type throws loudly.
+//
+//   const p = typedPayload(event, approved);
+//   // p is typed as { amountCents: number; approvedBy: string }
+//
+// The runtime type-check guards against projection-apply maps that hand-
+// build their key → handler mapping and accidentally route events to the
+// wrong typedPayload call. No Zod-parse — validation happened at
+// appendEvent time; this is a read-path helper.
+export function typedPayload(event, eventDef) {
+    if (event.type !== eventDef.name) {
+        throw new Error(`[Kumiko] typedPayload: event type "${event.type}" does not match EventDef "${eventDef.name}". ` +
+            `Check the projection-apply / reducer mapping — the event was routed to the wrong handler.`);
+    }
+    return event.payload; // @cast-boundary engine-payload
+}