@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/pipeline/dispatch-write.js

@@ -92,6 +92,13 @@ function publishConfigWrite(ctx, type, user, result) {
     const message = scope === ConfigScopes.system ? { scope: "all", key } : { tenantId: user.tenantId, key };
     ctx.cacheSync?.publish(CACHE_SYNC_TOPICS.tenantConfig, message);
 }
+async function settleSaveFileRefs(handlerContext, result, user) {
+    const fileRefArgs = { registry: handlerContext.registry, result, user, db: handlerContext.db };
+    const fileRefRows = await loadSaveFileRefs(fileRefArgs);
+    assertFileRefsBelongToTenant({ ...fileRefArgs, fileRefRows });
+    await bindPendingFileRefs({ ...fileRefArgs, fileRefRows });
+    await disposeRemovedFileRefs(fileRefArgs);
+}
 // 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
@@ -115,14 +122,12 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     // keeps projection state consistent with what the hooks observe.
     await runProjections(result, handlerContext.registry, runner);
     if (result.kind === "save") {
-        const fileRefArgs = { registry: handlerContext.registry, result, user, db: handlerContext.db };
-        const fileRefRows = await loadSaveFileRefs(fileRefArgs);
-        assertFileRefsBelongToTenant({ ...fileRefArgs, fileRefRows });
-        await bindPendingFileRefs({ ...fileRefArgs, fileRefRows });
-        await disposeRemovedFileRefs(fileRefArgs);
+        await settleSaveFileRefs(handlerContext, result, user);
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, "postCommit");
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, {
+                transactionScope: "postCommit",
+            });
             await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -130,7 +135,9 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
         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, undefined, undefined, "postCommit");
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, {
+                transactionScope: "postCommit",
+            });
             await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -190,25 +197,7 @@ async function completeParentRow(ctx, parentEntityName, parentEntity, parentRow,
     });
     return stored ? { ...stored, ...parentRow } : parentRow;
 }
-// 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);
+function collectNestedForeignKeyIssues(nested) {
     // 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.
@@ -230,39 +219,33 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
             }
         }
     }
-    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 is generic across all entity handlers; nested-
-    // write inspects the shape structurally.
-    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.
+    return issues;
+}
+// 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 — 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 is generic across all entity handlers; nested-
+// write inspects the shape structurally.
+function unwrapSaveRow(data) {
+    const wrapper = data; // @cast-boundary engine-payload
+    return (wrapper["data"] ?? wrapper); // @cast-boundary engine-payload
+}
+// A custom create handler may return an existing foreign row; verify it before attaching children.
+async function rejectUnverifiedParent(ctx, type, parentRow, parentId, user, tx) {
+    const { registry } = ctx;
     const parentEntityName = registry.getHandlerEntity(type);
     const isCallerScoped = !registry.isHandlerSystemScoped(type);
     const isParentForeign = isCallerScoped &&
@@ -275,45 +258,90 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
             details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
         }));
     }
-    if (parentEntityName) {
-        const parentEntity = registry.getEntity(parentEntityName);
-        if (parentEntity) {
-            const ownershipRow = await completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx);
-            const deniedField = checkWriteFieldOwnership(parentEntity, ownershipRow, 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 {
+    if (!parentEntityName)
+        return undefined;
+    const parentEntity = registry.getEntity(parentEntityName);
+    if (!parentEntity)
+        return undefined;
+    const ownershipRow = await completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx);
+    const deniedField = checkWriteFieldOwnership(parentEntity, ownershipRow, user);
+    if (!deniedField)
+        return undefined;
+    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,
+        },
+    }));
+}
+async function writeNestedChildren(ctx, spec, parentId, user, origin, tx, afterCommitHooks) {
+    const { registry } = ctx;
+    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 {
+                kind: "failed",
+                failure: {
                     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
-            const subEntityName = registry.getHandlerEntity(spec.subType);
-            const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
-            // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
-            subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
+                },
+            };
         }
-        parentRow[spec.key] = subRows;
+        const subRow = unwrapSaveRow(subResult.data);
+        const subEntityName = registry.getHandlerEntity(spec.subType);
+        const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
+        // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
+        subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
+    }
+    return { kind: "written", rows: subRows };
+}
+// 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 nested = extractNestedSpecs(type, payload, ctx.registry);
+    if (!nested)
+        return executeWrite(ctx, type, payload, user, origin, tx, afterCommitHooks);
+    const issues = collectNestedForeignKeyIssues(nested);
+    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;
+    const parentRow = unwrapSaveRow(parentResult.data);
+    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`,
+        }));
+    }
+    const parentRejection = await rejectUnverifiedParent(ctx, type, parentRow, parentId, user, tx);
+    if (parentRejection)
+        return parentRejection;
+    for (const spec of nested.specs) {
+        const children = await writeNestedChildren(ctx, spec, parentId, user, origin, tx, afterCommitHooks);
+        if (children.kind === "failed")
+            return children.failure;
+        parentRow[spec.key] = children.rows;
     }
     return parentResult;
 }
@@ -333,96 +361,130 @@ async function confirmReservation(reservation, tx, user) {
     }
     return undefined;
 }
-async function executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks) {
-    const { registry, jobRunner } = ctx;
-    const handler = registry.getWriteHandler(type);
+function failedStep(failure) {
+    return { kind: "failed", failure };
+}
+function resolveWriteEntry(ctx, type, user, tx) {
+    const handler = ctx.registry.getWriteHandler(type);
     if (!handler)
-        return writeFailure(new NotFoundError("handler", type));
+        return failedStep(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());
+        return failedStep(writeFailure(memberResolutionReadOnlyDenied()));
     }
     const isPerCommand = handler.transaction === "perCommand";
     if (isPerCommand && tx !== undefined) {
-        return writeFailure(perCommandNestedDenied(type));
+        return failedStep(writeFailure(perCommandNestedDenied(type)));
     }
+    return { kind: "run", handler, isPerCommand };
+}
+async function runWriteGates(ctx, handler, type, payload, user) {
     // A command the dispatcher ran pre-transaction phases for was already billed against the rate
     // limits; the gates only run again against the in-transaction state.
     const needsPreTransactionPhase = hasPreTransactionPhase(handler);
     const reservation = needsPreTransactionPhase ? consumeReservation(type) : undefined;
     const gates = await runPreHandlerGates(ctx, handler, type, payload, user, reservation ? "recheck" : "charge");
     if (!gates.isSuccess)
-        return gates;
-    const parsedPayload = gates.payload;
+        return failedStep(gates);
+    const parsedPayload = reservation ? reservation.parsedPayload : gates.payload;
     // A handler with a pre-transaction phase cannot run that phase from inside an open transaction;
     // running it without would skip the reservation or the prepared data, so a nested ctx.write of
     // such a handler is rejected instead.
     if (needsPreTransactionPhase && !reservation) {
-        return writeFailure(new InternalError({
+        return failedStep(writeFailure(new InternalError({
             message: `handler "${type}" has a pre-transaction phase (reserveBeforeTransaction/beforeTransaction) and cannot run as a nested write unless the top-level command ran it`,
-        }));
+        })));
     }
-    const entityName = registry.getHandlerEntity(type);
-    // Without a database there is no transaction either, but ordinary handlers keep the in-transaction nested-write semantics.
-    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, undefined, isPerCommand ? "withoutTransaction" : "inTransaction");
-    // 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
+    return { kind: "run", parsedPayload, reservation };
+}
+// 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.
+function resolveTransitionGuardDb(handlerContext, type) {
+    return 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 = parsedPayload; // @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);
-            }
-        }
+}
+// Auto transition guard: if entity has transitions and handler doesn't skip it.
+async function guardAutoTransitions(ctx, handler, type, parsedPayload, transitionGuardDb, tx) {
+    const entityName = ctx.registry.getHandlerEntity(type);
+    // skip: handler has no entity or opted out of the transition guard
+    if (!entityName || handler.unsafeSkipTransitionGuard)
+        return;
+    const entity = ctx.registry.getEntity(entityName);
+    // skip: entity declares no transitions, or there is no db to read the current value from
+    if (!entity?.transitions || !transitionGuardDb)
+        return;
+    const parsedData = parsedPayload; // @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)) {
+        await guardFieldTransition(ctx, {
+            entityName,
+            entity,
+            fieldName,
+            transitionMap,
+            changes,
+            id,
+            transitionGuardDb,
+            tx,
+        });
     }
-    // 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.
+}
+async function guardFieldTransition(ctx, args) {
+    const { entityName, entity, fieldName, transitionMap, changes, id, transitionGuardDb, tx } = args;
+    const newValue = changes[fieldName]; // @cast-boundary engine-bridge
+    // skip: field is not part of this write
+    if (!newValue || !id)
+        return;
+    const table = getTable(ctx, entityName);
+    // skip: entity has no table to read the current value from
+    if (!table)
+        return;
+    // 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];
+    // skip: no stored row to transition from
+    if (!row)
+        return;
+    // 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"];
+    // skip: soft-deleted row
+    if (entity.softDelete && isDeleted === true) {
+        return;
+    }
+    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.
+async function invokeWriteHandler(handler, type, gated, user, handlerContext) {
     let result;
     try {
-        const event = { type, payload: parsedPayload, user, prepared: reservation?.prepared };
+        const event = {
+            type,
+            payload: gated.parsedPayload,
+            user,
+            prepared: gated.reservation?.prepared,
+        };
         result = await handler.handler(event, handlerContext);
     }
     catch (e) {
@@ -441,41 +503,86 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
                 `Use defineWriteHandler() or wrap the return as { isSuccess: true as const, data: ... }.`,
         }));
     }
-    if (result.isSuccess && reservation) {
-        const confirmFailure = await confirmReservation(reservation, tx, user);
+    return result;
+}
+async function runWriteLifecycle(ctx, args) {
+    try {
+        const runner = resolveDbSource(ctx, args.tx);
+        await runLifecycle(ctx, args.type, args.result.data, args.handlerContext, args.user, args.origin, args.afterCommitHooks, runner);
+    }
+    catch (e) {
+        return writeFailure(wrapToKumiko(e));
+    }
+    return undefined;
+}
+function scheduleWriteAfterCommit(ctx, type, user, parsedPayload, result, afterCommitHooks) {
+    const { jobRunner } = ctx;
+    // jobRunner has external side-effects (BullMQ enqueue) — must NOT
+    // fire for rolled-back writes. Defer to afterCommit.
+    if (jobRunner) {
+        const eventData = (parsedPayload ?? {}); // @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);
+        publishConfigWrite(ctx, type, user, result);
+    });
+}
+async function settleSuccessfulWrite(ctx, args) {
+    if (args.reservation) {
+        const confirmFailure = await confirmReservation(args.reservation, args.tx, args.user);
         if (confirmFailure)
             return confirmFailure;
     }
-    if (result.isSuccess) {
-        // A perCommand handler's writes ran as their own commands; its result carries no SaveContext of its own to project.
-        if (!isPerCommand) {
-            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 = (parsedPayload ?? {}); // @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);
-            publishConfigWrite(ctx, type, user, result);
-        });
+    // A perCommand handler's writes ran as their own commands; its result carries no SaveContext of its own to project.
+    if (!args.isPerCommand) {
+        const lifecycleFailure = await runWriteLifecycle(ctx, args);
+        if (lifecycleFailure)
+            return lifecycleFailure;
     }
+    scheduleWriteAfterCommit(ctx, args.type, args.user, args.parsedPayload, args.result, args.afterCommitHooks);
+    return undefined;
+}
+async function executeWriteInner(ctx, type, payload, user, origin, tx, afterCommitHooks) {
+    const entry = resolveWriteEntry(ctx, type, user, tx);
+    if (entry.kind === "failed")
+        return entry.failure;
+    const { handler, isPerCommand } = entry;
+    const gated = await runWriteGates(ctx, handler, type, payload, user);
+    if (gated.kind === "failed")
+        return gated.failure;
+    // Without a database there is no transaction either, but ordinary handlers keep the in-transaction nested-write semantics.
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, {
+        tx,
+        afterCommitHooks,
+        transactionScope: isPerCommand ? "withoutTransaction" : "inTransaction",
+    });
+    const transitionGuardDb = resolveTransitionGuardDb(handlerContext, type);
+    await guardAutoTransitions(ctx, handler, type, gated.parsedPayload, transitionGuardDb, tx);
+    const result = await invokeWriteHandler(handler, type, gated, user, handlerContext);
+    if (!result.isSuccess)
+        return result;
+    const settleFailure = await settleSuccessfulWrite(ctx, {
+        type,
+        user,
+        origin,
+        tx,
+        afterCommitHooks,
+        parsedPayload: gated.parsedPayload,
+        reservation: gated.reservation,
+        isPerCommand,
+        handlerContext,
+        result,
+    });
+    if (settleFailure)
+        return settleFailure;
     // 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);
+    assertNoSecretLeak(result.data);
     return result;
 }

package/dist/pipeline/event-dispatcher-admin.js

@@ -1,6 +1,7 @@
 import { advanceConsumerPastEventReturning, removePendingGapReturning, selectConsumerForUpdate, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
 import { selectNextEventIdAfter, selectSmallestVisibleIdInRanges, } from "../db/queries/event-store.js";
-import { coerceRow, extractTableInfo, runInNewTransaction, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, } from "../db/query.js";
+import { coerceRow, runInNewTransaction, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, } from "../db/query.js";
+import { extractTableInfo } from "../db/table-info.js";
 import { getEventsHighWaterMark } from "../event-store/index.js";
 import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 import { mergeContiguousGapRanges, rangeContainsId, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";

package/dist/pipeline/event-dispatcher-delivery.js

@@ -3,7 +3,8 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
 import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries/event-store.js";
-import { coerceRow, extractTableInfo } from "../db/query.js";
+import { coerceRow } from "../db/query.js";
+import { extractTableInfo } from "../db/table-info.js";
 import { qnScope } from "../engine/qualified-name.js";
 import { eventsTable, toStoredEvent as rowToStoredEvent, } from "../event-store/index.js";
 import { emitDispatcherError, emitEventConsumerLag, emitEventConsumerPendingGaps, getFallbackMeter, } from "../observability/index.js";
@@ -30,10 +31,6 @@ const UNPARSEABLE_STORED_WRITE_ORIGIN = {
 export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs, maxRearmCount) {
     const rawState = await selectConsumerForUpdateSkipLocked(tx, name, instanceId);
     if (!rawState) {
-        return { state: null, skip: "not_registered" };
-    }
-    const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable));
-    if (!state) {
         // Either the row never existed (no pre-reg, no ensureRegistered) or
         // another instance currently holds the lock with SKIP LOCKED filtering
         // us out. We can't distinguish here in a single query, so return
@@ -42,6 +39,7 @@ export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs
         // this path is never taken.
         return { state: null, skip: "not_registered" };
     }
+    const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable));
     if (state.status === ConsumerStatuses.disabled)
         return { state: null, skip: "disabled" };
     if (state.status === ConsumerStatuses.dead) {

package/dist/pipeline/handler-context-auth.d.ts

@@ -0,0 +1,9 @@
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { MemberReader, SessionUser } from "../engine/types/index.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildAuthFacet(scope: HandlerContextScope): {
+    resolveAuthClaims: (claimsUser: SessionUser) => Promise<Record<string, unknown>>;
+    resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<import("@cosmicdrift/kumiko-types/handlers").ActiveMembershipResult>;
+    queryAsMember: MemberReader;
+    hasFeature: (featureName: string) => Promise<boolean>;
+};