@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/pipeline/dispatch-stream.d.ts

@@ -0,0 +1,3 @@
+import type { SessionUser } from "../engine/types/index.js";
+import { type DispatchContext, type WriteOrigin } from "./dispatch-shared.js";
+export declare function executeStream(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin): AsyncGenerator<unknown>;

package/dist/pipeline/dispatch-stream.js

@@ -0,0 +1,89 @@
+import { hasAccess } from "../engine/access.js";
+import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
+import { assertNoSecretLeak } from "../secrets/index.js";
+import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runStreamInstrumented, } from "./dispatch-shared.js";
+// Standalone stream execution — used by the public dispatcher.stream().
+// Chunk-by-chunk analog of executeQuery: same gate order (feature → rate-
+// limit → access → validation → handler), but yields incrementally instead
+// of returning a single response. streamHandler never entity-maps (unlike
+// write/queryHandler — see feature-entity-handlers.ts), so there's no
+// field-access filter or postQuery-hook stage to run here.
+export async function* executeStream(ctx, type, payload, user, origin) {
+    yield* runStreamInstrumented(ctx, type, user, () => executeStreamInner(ctx, type, payload, user, origin));
+}
+async function* executeStreamInner(ctx, type, payload, user, origin) {
+    const { registry } = ctx;
+    const handler = registry.getStreamHandler(type);
+    if (!handler)
+        throw new NotFoundError("handler", type);
+    // A resolved member principal (ctx.queryAsMember) is read-only — streams
+    // are excluded the same way executeWriteInner excludes writes.
+    if (isMemberResolutionPrincipal(user)) {
+        throw memberResolutionReadOnlyDenied();
+    }
+    await ensureFeatureEnabled(ctx, type, user.tenantId);
+    await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
+    if (!hasAccess(user, handler.access)) {
+        throw new AccessDeniedError({
+            message: `access denied for ${type}`,
+            details: { handler: type },
+        });
+    }
+    const parsed = handler.schema.safeParse(payload);
+    if (!parsed.success) {
+        throw validationErrorFromZod(parsed.error);
+    }
+    // Idle (heartbeat-only) streams must also cut on access revoke — race each
+    // pull against an invalidated Deferred instead of a post-chunk boolean.
+    let resolveInvalidated;
+    const invalidated = new Promise((resolve) => {
+        resolveInvalidated = resolve;
+    });
+    const streamCredential = {
+        ...(user.sid !== undefined && { sid: user.sid }),
+        ...(user.pat?.tokenId !== undefined && { patTokenId: user.pat.tokenId }),
+    };
+    const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(user.id, () => {
+        resolveInvalidated?.();
+    }, streamCredential);
+    let iterator;
+    // When access is revoked mid-pull, `iterator.next()` is still in flight.
+    // Awaiting `iterator.return()` in that state deadlocks async generators in
+    // Bun (overlapping next+return). Track abandonment so finally skips the
+    // await; close is fire-and-forget instead (#1563).
+    let abandonedForInvalidation = false;
+    try {
+        const handlerContext = await buildHandlerContext(ctx, type, user, origin);
+        const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
+        iterator = chunks[Symbol.asyncIterator]();
+        while (true) {
+            const nextPull = iterator.next();
+            const outcome = await Promise.race([
+                nextPull.then((result) => ({ kind: "chunk", result })),
+                invalidated.then(() => ({ kind: "invalidated" })),
+            ]);
+            if (outcome.kind === "invalidated") {
+                abandonedForInvalidation = true;
+                void nextPull.catch(() => { });
+                void iterator.return?.(undefined)?.then(undefined, () => { });
+                throw new AccessDeniedError({
+                    message: `access revoked mid-stream for ${type}`,
+                    details: { handler: type },
+                });
+            }
+            if (outcome.result.done)
+                break;
+            await ensureFeatureEnabled(ctx, type, user.tenantId);
+            assertNoSecretLeak(outcome.result.value);
+            yield outcome.result.value;
+        }
+    }
+    finally {
+        unsubscribeAccessInvalidation?.();
+        // Close the generator so cleanup runs; skip awaiting return() after
+        // access-revoke abandonment — overlapping next()+return() can deadlock.
+        if (iterator !== undefined && !abandonedForInvalidation) {
+            await iterator.return?.(undefined);
+        }
+    }
+}

package/dist/pipeline/dispatch-write.d.ts

@@ -0,0 +1,6 @@
+import type { DbTx } from "../db/connection.js";
+import type { SessionUser, WriteResult } from "../engine/types/index.js";
+import type { DispatchContext, WriteOrigin } from "./dispatch-shared.js";
+import { type AfterCommitHook } from "./dispatcher-utils.js";
+export declare function executeWrite(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx: DbTx | undefined, afterCommitHooks: AfterCommitHook[]): Promise<WriteResult>;
+export declare function executeNestedWrite(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx: DbTx | undefined, afterCommitHooks: AfterCommitHook[]): Promise<WriteResult>;

package/dist/pipeline/dispatch-write.js

@@ -0,0 +1,428 @@
+import { selectRowForUpdateById } from "../db/queries/entity-read.js";
+import { asEntityTableMeta, selectMany } from "../db/query.js";
+import { buildEntityTable, toSnakeCase } from "../db/table-builder.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { hasAccess } from "../engine/access.js";
+import { ConfigScopes } from "../engine/constants.js";
+import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access.js";
+import { defineTransitions, guardTransition } from "../engine/state-machine.js";
+import { HookPhases } from "../engine/types/index.js";
+import { runValidation } from "../engine/validation.js";
+import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
+import { assertNoSecretLeak } from "../secrets/index.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
+import { runProjections } from "./projections-runner.js";
+function getTable(ctx, entityName) {
+    const { registry, tableCache } = ctx;
+    if (tableCache.has(entityName))
+        return tableCache.get(entityName);
+    const entity = registry.getEntity(entityName);
+    if (!entity)
+        return undefined;
+    const table = buildEntityTable(entityName, entity, {
+        relations: registry.getRelations(entityName),
+    });
+    tableCache.set(entityName, table);
+    return table;
+}
+function getTransitions(ctx, args) {
+    const { transitionCache } = ctx;
+    // Scope by entity — `fieldName` alone collides across entities (e.g. both
+    // `invoice.status` and `driverOrder.status` exist with different maps),
+    // which would apply the wrong transition rules to whichever entity arrives
+    // second.
+    const key = `${args.entityName}:${args.fieldName}`;
+    const cached = transitionCache.get(key);
+    if (cached)
+        return cached;
+    const transitions = defineTransitions(args.map);
+    transitionCache.set(key, transitions);
+    return transitions;
+}
+// A successful config:write:set/reset returns { key, scope, ... } — see
+// bundled-features/src/config/handlers/{set,reset}.write.ts. Narrows the
+// otherwise-`unknown` WriteResult.data so invalidateTenantTimezoneCache
+// below can check `key` without an unchecked cast.
+function isConfigWriteResultForKey(data, key) {
+    if (typeof data !== "object" || data === null || !("key" in data))
+        return false;
+    return data.key === key; // @cast-boundary engine-payload
+}
+// fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
+// value per tenant. A successful write to that key must drop the stale
+// entry — tenant/user scope only affects the writing tenant, system scope
+// changes the fallback every tenant without an override reads, so the
+// whole cache is dropped instead of just one entry.
+function invalidateTenantTimezoneCache(ctx, type, user, result) {
+    // skip: failed write, nothing to invalidate
+    if (!result.isSuccess)
+        return;
+    // skip: not a config:write:set/reset dispatch
+    if (type !== CONFIG_WRITE_SET_TYPE && type !== CONFIG_WRITE_RESET_TYPE)
+        return;
+    // skip: write was for a different config key
+    if (!isConfigWriteResultForKey(result.data, TENANT_TIMEZONE_CONFIG_KEY))
+        return;
+    if (result.data.scope === ConfigScopes.system) {
+        ctx.tenantTimezoneCache.clear();
+    }
+    else {
+        ctx.tenantTimezoneCache.invalidate(user.tenantId);
+    }
+}
+// Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
+// (they see the tx via ctx.db when batch/write opens a transaction).
+// afterCommit hooks are queued into `afterCommitHooks` for the caller to
+// flush after commit. Their context is built lazily, without `tx`: by the
+// time they fire the transaction has already committed, so `handlerContext`
+// (built around it) would hand them a dead handle.
+async function runLifecycle(ctx, type, data, handlerContext, user, origin, afterCommitHooks, runner) {
+    const { lifecycle } = ctx;
+    if (!lifecycle) {
+        handlerContext.log?.debug(`runLifecycle: skipping ${type} — no lifecycle pipeline`);
+        return;
+    }
+    if (!isLifecycleResult(data)) {
+        handlerContext.log?.debug(`runLifecycle: skipping ${type} — result is not a lifecycle kind`);
+        return;
+    }
+    const result = data;
+    // Projections run FIRST, inside the tx, before any user postSave/postDelete
+    // hooks. If a projection apply() throws, the whole tx rolls back — the
+    // event and the auto-projection row go with it. Running before the hooks
+    // keeps projection state consistent with what the hooks observe.
+    await runProjections(result, handlerContext.registry, runner);
+    if (result.kind === "save") {
+        await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
+        afterCommitHooks.push(async () => {
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, afterCommitHooks);
+            await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
+        });
+    }
+    else if (result.kind === "delete") {
+        await lifecycle.runPreDelete(type, result, handlerContext);
+        await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
+        afterCommitHooks.push(async () => {
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, afterCommitHooks);
+            await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
+        });
+    }
+}
+// Shared write pipeline: validates, executes handler, runs lifecycle + side effects.
+// Used by runBatch (which opens a transaction and flushes afterCommitHooks on commit).
+//
+// Contract:
+//   - `tx` is the active Drizzle transaction handle, or undefined for "no
+//     surrounding transaction" — either no Postgres is configured, or the
+//     transaction already committed (afterCommit phase).
+//   - `afterCommitHooks` collects deferred side-effects that must only fire
+//     after the transaction commits. The caller flushes them on commit, drops
+//     them on rollback. executeWrite never fires them directly.
+export async function executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks) {
+    return runHandlerInstrumented(ctx, type, "write", user, () => executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks));
+}
+function isForeignTenantParentRow(parentRow, user) {
+    const rowTenantId = parentRow["tenantId"];
+    return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
+}
+// Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
+//
+// When a parent `:create` handler's payload carries values under keys
+// declared as `hasMany` relations with `nestedWrite: true`, those values
+// are expanded into child writes: parent first (so its new id exists),
+// then each nested entry as a separate `<target>:create` write with the
+// foreign key set by the framework — never taken from the client. All of
+// this runs inside the caller's transaction, so a child failure rolls the
+// parent (and any earlier children) back together.
+//
+// This wrapper is what runBatch calls, not executeWrite. Single writes
+// (`dispatcher.write`) flow through runBatch as batch-of-one, so they get
+// nested-expansion too for free. A batch with N heterogeneous commands
+// can each independently carry nested-children — all still one TX.
+export async function executeNestedWrite(ctx, type, payload, user, origin, tx, afterCommitHooks) {
+    const { registry } = ctx;
+    const nested = extractNestedSpecs(type, payload, registry);
+    if (!nested)
+        return executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks);
+    // Pre-flight client-shape checks. Merge non-array issues (collected up
+    // front by extractNestedSpecs) with fk-injection issues into one error
+    // so the client sees every problem in a single round-trip.
+    //
+    // Security rail: the client MUST NOT supply the foreign key on nested
+    // items. The framework binds it from the parent's new id. Silent-overwrite
+    // would mask an attempt to attach children to a different parent — fail
+    // loud with a ValidationError carrying a client-mappable path.
+    const issues = [...nested.typeIssues];
+    for (const spec of nested.specs) {
+        for (let i = 0; i < spec.items.length; i++) {
+            const item = spec.items[i];
+            if (item && typeof item === "object" && spec.foreignKey in item) {
+                issues.push({
+                    path: `${spec.key}.${i}.${spec.foreignKey}`,
+                    code: "unexpected_field",
+                    i18nKey: "errors.validation.unexpected_field",
+                });
+            }
+        }
+    }
+    if (issues.length > 0) {
+        return writeFailure(new ValidationError({ fields: issues }));
+    }
+    const parentResult = await executeWrite(ctx, type, nested.cleanPayload, user, origin, tx, afterCommitHooks);
+    if (!parentResult.isSuccess)
+        return parentResult;
+    // Handlers built on the CRUD executor return a SaveContext wrapper —
+    // `{ kind: "save", id, data: <row>, changes, previous, event, ... }`.
+    // The wrapper is load-bearing for batch-level hooks downstream (see
+    // flushBatchHooks), so we mutate in place: nested children land on the
+    // inner `data` (which mirrors the entity shape the client expects) while
+    // the wrapper keeps its SaveContext semantics intact for the lifecycle
+    // pipeline. For handlers that return a bare row (no wrapper), children
+    // land directly on that object.
+    //
+    // Hook-ordering note: per-entity postSave hooks already ran inside the
+    // parent's executeWrite call above — they never saw `tasks`, which is
+    // the right semantic (postSave gets the entity's own columns, not
+    // synthetic relation keys). A future postSaveBatch subscriber that
+    // enumerates columns generically WOULD see `tasks`; no such subscriber
+    // exists today. If you add one that iterates `Object.keys(save.data)`,
+    // filter by `entity.fields` membership to stay correct.
+    // handler-Result.data ist generic über alle Entity-Handler; nested-
+    // write inspiziert die shape strukturell.
+    const parentWrapper = parentResult.data; // @cast-boundary engine-payload
+    const parentRow = (parentWrapper["data"] ?? parentWrapper); // @cast-boundary engine-payload
+    const parentId = parentRow["id"];
+    if (typeof parentId !== "string") {
+        return writeFailure(new InternalError({
+            message: `nested-write: parent handler "${type}" returned no string "id" — cannot attach children`,
+        }));
+    }
+    // A custom create handler may return an existing foreign row; verify it before attaching children.
+    if (!registry.isHandlerSystemScoped(type) && isForeignTenantParentRow(parentRow, user)) {
+        return writeFailure(new AccessDeniedError({
+            message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
+            details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
+        }));
+    }
+    const parentEntityName = registry.getHandlerEntity(type);
+    if (parentEntityName) {
+        const parentEntity = registry.getEntity(parentEntityName);
+        if (parentEntity) {
+            const deniedField = checkWriteFieldOwnership(parentEntity, parentRow, user);
+            if (deniedField) {
+                return writeFailure(new AccessDeniedError({
+                    message: `nested-write: parent row ownership check failed on field "${deniedField}" of "${type}" — refusing to attach children to a parent row the caller does not own`,
+                    i18nKey: "errors.access.fieldDenied",
+                    details: {
+                        reason: FrameworkReasons.fieldAccessDenied,
+                        field: deniedField,
+                        handler: type,
+                    },
+                }));
+            }
+        }
+    }
+    for (const spec of nested.specs) {
+        const subRows = [];
+        for (let i = 0; i < spec.items.length; i++) {
+            const rawItem = spec.items[i];
+            const itemObj = (rawItem ?? {}); // @cast-boundary engine-payload
+            const subPayload = { ...itemObj, [spec.foreignKey]: parentId };
+            const subResult = await executeWrite(ctx, spec.subType, subPayload, user, origin, tx, afterCommitHooks);
+            if (!subResult.isSuccess) {
+                return {
+                    isSuccess: false,
+                    error: prefixValidationPath(subResult.error, `${spec.key}.${i}`),
+                };
+            }
+            const subWrapper = subResult.data; // @cast-boundary engine-payload
+            const subRow = (subWrapper["data"] ?? subWrapper); // @cast-boundary engine-payload
+            subRows.push(subRow);
+        }
+        parentRow[spec.key] = subRows;
+    }
+    return parentResult;
+}
+async function executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks) {
+    const { registry, jobRunner } = ctx;
+    const handler = registry.getWriteHandler(type);
+    if (!handler)
+        return writeFailure(new NotFoundError("handler", type));
+    // Defense in depth — covers runBatch and a spread-copied user that kept
+    // `origin`, beyond buildHandlerContext's own ctx.write replacement.
+    if (isMemberResolutionPrincipal(user)) {
+        return writeFailure(memberResolutionReadOnlyDenied());
+    }
+    // Feature-toggle gate: disabled handlers must short-circuit before any
+    // rate-limit/access/validation work — see executeQueryInner comment.
+    const disabledErr = await checkFeatureEnabled(ctx, type, user.tenantId);
+    if (disabledErr)
+        return writeFailure(disabledErr);
+    // Rate-limit gate before access (same reasoning as in executeQueryInner).
+    // Throws RateLimitError; the outer wrapper turns it into a 429
+    // WriteFailure via toWriteErrorInfo. Apps that don't use L3 pay zero cost
+    // for non-systemScope handlers with no rateLimit declared; systemScope
+    // handlers pay one isHandlerSystemScoped lookup to check whether the
+    // default per-tenant limit applies.
+    try {
+        await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
+    }
+    catch (e) {
+        if (isKumikoError(e))
+            return writeFailure(e);
+        throw e;
+    }
+    // Default-deny: missing access rule is treated as "no one has access".
+    // The registry boot-validator refuses to register handlers without one,
+    // so in normal boots this branch shouldn't fire — the guard is belt-and-
+    // suspenders in case a handler sneaks through (e.g. runtime injection).
+    if (!hasAccess(user, handler.access)) {
+        return writeFailure(new AccessDeniedError({
+            message: `access denied for ${type}`,
+            details: { handler: type },
+        }));
+    }
+    const parsed = handler.schema.safeParse(payload);
+    if (!parsed.success) {
+        return writeFailure(validationErrorFromZod(parsed.error));
+    }
+    const hookErrors = runValidation(registry, type, parsed.data); // @cast-boundary engine-payload
+    if (hookErrors) {
+        return writeFailure(new ValidationError({
+            fields: hookErrors.map((e) => ({
+                path: e.field,
+                code: e.error,
+                i18nKey: `errors.validation.${e.error}`,
+            })),
+        }));
+    }
+    // Field-level write access check
+    const entityName = registry.getHandlerEntity(type);
+    if (entityName) {
+        const entity = registry.getEntity(entityName);
+        if (entity) {
+            const fieldsToCheck = parsed.data["changes"]; // @cast-boundary engine-payload
+            const writePayload = fieldsToCheck ?? parsed.data; // @cast-boundary engine-payload
+            // Pre-handler check: role-only gate. Ownership-level row-match runs
+            // later in the executor where oldRow is loaded — that split lets
+            // updates with partial changes still pass the pre-handler check and
+            // get their full evaluation at save time.
+            const deniedField = checkWriteFieldRoles(entity, writePayload, user);
+            if (deniedField) {
+                return writeFailure(new AccessDeniedError({
+                    message: `field access denied: ${deniedField}`,
+                    i18nKey: "errors.access.fieldDenied",
+                    details: {
+                        reason: FrameworkReasons.fieldAccessDenied,
+                        field: deniedField,
+                        handler: type,
+                    },
+                }));
+            }
+        }
+    }
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
+    // Auto transition guard: if entity has transitions and handler doesn't skip it.
+    // Reads via the guard's own db handle — for r.systemScope() handlers
+    // handlerContext.db is fail-closed, so this reaches for
+    // systemDb.acknowledgeCrossTenant like any other framework-internal
+    // mechanism that touches a system-scoped handler's data.
+    const transitionGuardDb = handlerContext.systemDb
+        ? handlerContext.systemDb.acknowledgeCrossTenant(`auto transition guard for r.systemScope() write handler (${type})`)
+        : handlerContext.db;
+    if (entityName && !handler.unsafeSkipTransitionGuard) {
+        const entity = registry.getEntity(entityName);
+        if (entity?.transitions && transitionGuardDb) {
+            const parsedData = parsed.data; // @cast-boundary engine-payload
+            const changes = parsedData["changes"] ?? parsedData; // @cast-boundary engine-payload
+            const id = parsedData["id"] ?? undefined; // @cast-boundary engine-payload
+            for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
+                const newValue = changes[fieldName]; // @cast-boundary engine-bridge
+                if (!newValue || !id)
+                    continue;
+                const table = getTable(ctx, entityName);
+                if (!table)
+                    continue;
+                // SELECT FOR UPDATE inside the surrounding transaction — locks the
+                // row so a concurrent handler can't mutate `status` between our
+                // guard check and the handler's UPDATE. Without this lock the guard
+                // can false-pass; optimistic locking would catch it later, but with
+                // a less specific error. Falls back to a plain SELECT if no tx is
+                // active (tests without a DB connection).
+                const tableName = asEntityTableMeta(table)?.tableName ?? "";
+                const rows = tx
+                    ? await selectRowForUpdateById(tenantDbRunner(transitionGuardDb), tableName, id)
+                    : await selectMany(transitionGuardDb, table, { id });
+                const row = rows[0];
+                if (!row)
+                    continue;
+                // Skip guard for soft-deleted rows — they shouldn't be transitioning
+                // at all; a handler that wants to move a deleted row should use
+                // unsafeSkipTransitionGuard or restore first.
+                const rowAsRow = row; // @cast-boundary engine-payload
+                const isDeleted = rowAsRow["isDeleted"] ?? rowAsRow["is_deleted"];
+                if (entity.softDelete && isDeleted === true) {
+                    continue;
+                }
+                const currentValue = row[fieldName] ??
+                    row[toSnakeCase(fieldName)]; // @cast-boundary engine-bridge
+                guardTransition(getTransitions(ctx, { entityName, fieldName, map: transitionMap }), currentValue, newValue);
+            }
+        }
+    }
+    // The handler itself plus the lifecycle pipeline run under the same
+    // try-wrapper: any KumikoError bubbles up as a typed WriteErrorInfo, any
+    // other throw gets wrapped in InternalError so the Prod contract holds
+    // ("unexpected throw → 500 with sanitized body"). We intentionally do NOT
+    // catch further out (runBatch still sees these as exceptions via
+    // writeFailure, not via a rethrow) so batches roll back naturally.
+    let result;
+    try {
+        result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
+    }
+    catch (e) {
+        return writeFailure(wrapToKumiko(e));
+    }
+    // Runtime shape-guard. The compile-time type WriteHandlerFn already
+    // requires `Promise<WriteResult>`, but custom handlers wired through
+    // r.writeHandler(name, schema, fn, opts) sometimes slip through with
+    // `Promise<{id: string}>` — TypeScript misses it under structural-
+    // widening, the dispatcher then reads .isSuccess on undefined and
+    // crashes obscure. Surface a clear actionable message instead.
+    if (!isWriteResultShape(result)) {
+        return writeFailure(new InternalError({
+            message: `Write handler "${type}" returned an invalid shape. Expected WriteResult ` +
+                `({ isSuccess: true, data: ... } or writeFailure(err)), got ${describeShape(result)}. ` +
+                `Use defineWriteHandler() or wrap the return as { isSuccess: true as const, data: ... }.`,
+        }));
+    }
+    if (result.isSuccess) {
+        try {
+            const runner = resolveDbSource(ctx, tx);
+            await runLifecycle(ctx, type, result.data, handlerContext, user, origin, afterCommitHooks, runner);
+        }
+        catch (e) {
+            return writeFailure(wrapToKumiko(e));
+        }
+        // jobRunner has external side-effects (BullMQ enqueue) — must NOT
+        // fire for rolled-back writes. Defer to afterCommit.
+        if (jobRunner) {
+            const eventData = (parsed.data ?? {}); // @cast-boundary engine-payload
+            afterCommitHooks.push(() => jobRunner.handleEvent(type, eventData, user));
+        }
+        invalidateTenantTimezoneCache(ctx, type, user, result);
+        // Again after commit: a query landing between the drop above and the
+        // commit would read the pre-write row (tx not yet visible) and
+        // repopulate the cache with the stale value for a full TTL.
+        afterCommitHooks.push(async () => {
+            invalidateTenantTimezoneCache(ctx, type, user, result);
+        });
+    }
+    // Response-guard: block Secret<> leaks in write responses (SaveContext
+    // data / previous / changes). Feature code that fed a plaintext through
+    // to the return payload fails here instead of hitting the client.
+    if (result.isSuccess)
+        assertNoSecretLeak(result.data);
+    return result;
+}

package/dist/pipeline/dispatcher-utils.d.ts

@@ -0,0 +1,36 @@
+import type { HandlerRef, LifecycleResult, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
+import { type KumikoError, type WriteErrorInfo } from "../errors/index.js";
+export type FailedWriteResult = Extract<WriteResult, {
+    isSuccess: false;
+}>;
+export declare function isFailedWriteResult(result: unknown): result is FailedWriteResult;
+export declare function isLifecycleResult(data: unknown): data is LifecycleResult;
+export declare function isWriteResultShape(result: unknown): boolean;
+export declare function describeShape(result: unknown): string;
+export declare function dispatcherSpanAttributes(type: string, operation: "query" | "write" | "stream", user: SessionUser, feature: string | undefined): Record<string, string | number | boolean>;
+export type AfterCommitHook = () => Promise<void>;
+export type NestedSpec = {
+    readonly key: string;
+    readonly subType: string;
+    readonly foreignKey: string;
+    readonly items: readonly unknown[];
+};
+export type NestedTypeIssue = {
+    readonly path: string;
+    readonly code: string;
+    readonly i18nKey: string;
+};
+export declare function extractNestedSpecs(parentType: string, payload: unknown, registry: Registry): {
+    cleanPayload: Record<string, unknown>;
+    specs: readonly NestedSpec[];
+    typeIssues: readonly NestedTypeIssue[];
+} | null;
+export declare function prefixValidationPath(info: WriteErrorInfo, prefix: string): WriteErrorInfo;
+export declare class BatchRollback extends Error {
+    readonly failedIndex: number;
+    readonly failureError: WriteErrorInfo;
+    constructor(failedIndex: number, failureError: WriteErrorInfo);
+}
+export type HandlerType = string | HandlerRef;
+export declare function resolveType(type: HandlerType): string;
+export declare function wrapToKumiko(e: unknown): KumikoError;