@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/pipeline/dispatch-shared.js

@@ -6,7 +6,7 @@ import { createDerivativesContext } from "../derivatives/derivatives-context.js"
 import { mayOverrideTenant } from "../engine/cross-tenant.js";
 import { createSystemUser } from "../engine/system-user.js";
 import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index.js";
-import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, } from "../errors/index.js";
+import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, writeFailure, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
 import { getStreamVersion, loadAggregate, loadAggregateAsOf, } from "../event-store/event-store.js";
@@ -27,6 +27,7 @@ import { executeQuery } from "./dispatch-query.js";
 import { executeWrite } from "./dispatch-write.js";
 import { dispatcherSpanAttributes, isFailedWriteResult, NestedWriteRollback, } from "./dispatcher-utils.js";
 import { createMemberReaderFn } from "./member-reader.js";
+import { createDeferringNotify } from "./notify-scope.js";
 import { createGatedIdentitySwitch, createGatedMemberReader, createGatedProjectionReader, isSystemIdentity, systemIdentitySwitchDenied, } from "./system-identity-switch.js";
 import { buildPersonalDataGate, rootWriteOrigin } from "./write-origin.js";
 // Framework/pipeline stays bundled-features-free, so this can't import the
@@ -47,8 +48,10 @@ export const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10_000;
 // dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
 // appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
 export function resolveDbSource(ctx, tx) {
-    const { appContext: context } = ctx;
-    return tx ?? context.db; // @cast-boundary db-operator
+    return tx ?? resolveAppPoolDb(ctx);
+}
+function resolveAppPoolDb(ctx) {
+    return ctx.appContext.db; // @cast-boundary db-operator
 }
 // ctx.appendEvent — append a domain event onto a specific aggregate stream
 // in the current tx, then fire matching inline projections. Core logic
@@ -109,10 +112,10 @@ async function denyMemberResolutionWrite() {
 }
 // JobRunnerRef's declared type only carries handleEvent, but callers
 // routinely bracket-access a fuller runner — a Proxy denies ANY property read.
-function denyingJobRunnerProxy() {
+function denyingJobRunnerProxy(denied = memberResolutionReadOnlyDenied) {
     return new Proxy({}, {
         get() {
-            throw memberResolutionReadOnlyDenied();
+            throw denied();
         },
     });
 }
@@ -202,7 +205,62 @@ export function applyMemberResolutionReadOnly(handlerContext) {
         }),
     };
 }
-export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, isPostCommit) {
+function beforeTransactionDenied(surface) {
+    return new InternalError({
+        message: `ctx.${surface} is not available before the transaction; move it into the handler`,
+    });
+}
+function withoutTransactionDenied(surface) {
+    return new InternalError({
+        message: `ctx.${surface} is not available without an open transaction; run the write through ctx.write so it gets its own transaction`,
+    });
+}
+export function perCommandNestedDenied(targetType) {
+    return new InternalError({
+        message: `handler "${targetType}" runs without a transaction (transaction: "perCommand") and cannot run as a nested write inside an open transaction`,
+    });
+}
+function denySurface(buildError, surface) {
+    return () => {
+        throw buildError(surface);
+    };
+}
+function denyEventStoreSurfaces(handlerContext, buildError) {
+    return {
+        ...handlerContext,
+        appendEvent: denySurface(buildError, "appendEvent"),
+        unsafeAppendEvent: denySurface(buildError, "unsafeAppendEvent"),
+        tryAppendEvent: denySurface(buildError, "tryAppendEvent"),
+        fetchForWriting: denySurface(buildError, "fetchForWriting"),
+        archiveStream: denySurface(buildError, "archiveStream"),
+        restoreStream: denySurface(buildError, "restoreStream"),
+        snapshotAggregate: denySurface(buildError, "snapshotAggregate"),
+    };
+}
+// Reservations write on purpose through the outside-transaction handles, so they keep those but
+// lose every surface bound to the not-yet-open transaction.
+export function denyTransactionBoundSurfaces(handlerContext) {
+    return {
+        ...denyEventStoreSurfaces(handlerContext, beforeTransactionDenied),
+        write: denySurface(beforeTransactionDenied, "write"),
+        writeAs: denySurface(beforeTransactionDenied, "writeAs"),
+        scheduleAfterCommit: denySurface(beforeTransactionDenied, "scheduleAfterCommit"),
+        ...(handlerContext.notify && { notify: denySurface(beforeTransactionDenied, "notify") }),
+        ...(handlerContext.jobRunner && {
+            jobRunner: denyingJobRunnerProxy(() => beforeTransactionDenied("jobRunner")),
+        }),
+    };
+}
+// The beforeTransaction phase has no write need at all, so it also loses the outside-transaction handles.
+export function applyBeforeTransactionReadOnly(handlerContext) {
+    return {
+        ...denyTransactionBoundSurfaces(handlerContext),
+        dbOutsideTransaction: undefined,
+        outsideTransaction: undefined,
+        forTenant: undefined,
+    };
+}
+export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, transactionScope = tx ? "inTransaction" : "withoutTransaction") {
     const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -211,7 +269,10 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const dbSource = resolveDbSource(ctx, tx);
     const reqCtx = requestContext.get();
     // global() writes are write-handler-only; SYSTEM identity switch and unsafeRaw accept write, query or stream escapeHatch.
-    const writeEscapeHatch = registry.getWriteHandler(type)?.escapeHatch;
+    const writeHandler = registry.getWriteHandler(type);
+    const writeEscapeHatch = writeHandler?.escapeHatch;
+    const isPerCommand = writeHandler?.transaction === "perCommand";
+    const denyDbWrites = transactionScope === "withoutTransaction";
     const handlerEscapeHatch = writeEscapeHatch ??
         registry.getQueryHandler(type)?.escapeHatch ??
         registry.getStreamHandler(type)?.escapeHatch;
@@ -228,7 +289,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     });
     const identitySwitchGrantReason = identitySwitchEscapeHatch?.reason ??
         (isSystem ? `r.systemScope() feature "${featureName ?? "unknown"}"` : undefined);
-    const buildTenantScopedDb = (source, signal, foreignTenantId) => createTenantDb(source, foreignTenantId ?? user.tenantId, isSystem && foreignTenantId === undefined ? "system" : "tenant", context.tracer, context.meter, signal, {
+    const buildTenantScopedDb = (source, signal, foreignTenantId, denyWrites = false) => createTenantDb(source, foreignTenantId ?? user.tenantId, isSystem && foreignTenantId === undefined ? "system" : "tenant", context.tracer, context.meter, signal, {
         ...(foreignTenantId === undefined && {
             globalWrites: escapeHatchFor(writeEscapeHatch, "globalWrites"),
             unsafeRaw: escapeHatchFor(handlerEscapeHatch, "unsafeRaw"),
@@ -237,18 +298,21 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         memberReadOnly: isMemberResolutionPrincipal(user),
         personalDataGate: buildPersonalDataGate(registry, origin),
         projectionRegistry: registry,
+        ...(denyWrites && { writesDeniedReason: "without an open transaction" }),
     });
     // Propagate the request's AbortSignal so every TenantDb query throws when
     // the client has disconnected — handlers with many sequential queries skip
     // the rest of the chain instead of burning DB-CPU for results no one reads.
-    const db = dbSource ? buildTenantScopedDb(dbSource, reqCtx?.signal) : undefined;
+    const db = dbSource
+        ? buildTenantScopedDb(dbSource, reqCtx?.signal, undefined, denyDbWrites)
+        : undefined;
     // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
     // through it survive a rollback of the handler's own transaction. No
     // AbortSignal here: a client disconnect must not abort a durability write
     // that is meant to outlive the request. Computed before `systemDb` below
     // so its guarded escape hatch (ctx.systemDb.outsideTransaction) can wrap
     // this same TenantDb instead of a second, independently-built one.
-    const outsideTxSource = ctx.outsideTransactionDb ?? resolveDbSource(ctx, undefined);
+    const outsideTxSource = ctx.outsideTransactionDb ?? resolveAppPoolDb(ctx);
     const rawDbOutsideTransaction = outsideTxSource
         ? buildTenantScopedDb(outsideTxSource, undefined)
         : undefined;
@@ -279,9 +343,40 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         userId: user.id,
         ...(reqCtx && { requestId: reqCtx.requestId }),
     });
-    const notify = context._notifyFactory
-        ? context._notifyFactory(user, user.tenantId, isNotifyJobDispatcher(jobRunner) ? jobRunner : undefined)
+    // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
+    // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
+    const bridgeSink = afterCommitHooks ?? [];
+    // Query bridges and post-commit contexts get a throwaway sink: hooks pushed there never run.
+    const hasLiveCommitSink = afterCommitHooks !== undefined && transactionScope !== "postCommit";
+    const scheduleAfterCommit = (hook) => {
+        bridgeSink.push(hook);
+    };
+    const notifyFactory = context._notifyFactory;
+    const notifyJobDispatcher = isNotifyJobDispatcher(jobRunner) ? jobRunner : undefined;
+    // Inside the write tx the app pool's slots can all be held by waiting write txs, so the
+    // delivery's own DB work (broadcast lookup, attempt log, channel sends) runs on the outside-tx pool.
+    const notifyInTransactionFactory = notifyFactory && tx !== undefined
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, outsideTxSource, context._fileProviderResolver)
         : undefined;
+    const notify = buildNotify();
+    function buildNotify() {
+        if (!notifyFactory)
+            return undefined;
+        const notifyAfterCommit = notifyFactory(user, user.tenantId, notifyJobDispatcher, undefined, context._fileProviderResolver);
+        if (!notifyInTransactionFactory)
+            return notifyAfterCommit;
+        const notifyInTransaction = notifyInTransactionFactory(user, user.tenantId);
+        // A rolled-back write must leave no notification behind.
+        if (!hasLiveCommitSink)
+            return notifyInTransaction;
+        return createDeferringNotify({
+            registry,
+            tenantId: user.tenantId,
+            notifyAfterCommit,
+            notifyNow: notifyInTransaction,
+            scheduleAfterCommit,
+        });
+    }
     // Mirror notify: only built when the config feature wired its factory.
     const config = context._configAccessorFactory && db
         ? context._configAccessorFactory({
@@ -320,7 +415,11 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const forTenant = !isSystem && dbSource && registry.getWriteHandler(type) !== undefined
         ? (targetTenantId) => {
             if (targetTenantId === user.tenantId && exposedDb) {
-                return { db: exposedDb, streamTenantId: undefined };
+                // Only perCommand handlers lose forTenant writes; reservations keep their pre-transaction contract.
+                const ownTenantDb = denyDbWrites && !isPerCommand
+                    ? buildTenantScopedDb(dbSource, reqCtx?.signal)
+                    : exposedDb;
+                return { db: ownTenantDb, streamTenantId: undefined };
             }
             if (!mayOverrideTenant(user)) {
                 throw new AccessDeniedError({
@@ -328,7 +427,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                 });
             }
             return {
-                db: buildTenantScopedDb(dbSource, reqCtx?.signal, targetTenantId),
+                db: buildTenantScopedDb(dbSource, reqCtx?.signal, targetTenantId, denyDbWrites && isPerCommand),
                 streamTenantId: targetTenantId,
             };
         }
@@ -361,20 +460,20 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const metricsFor = meter
         ? (targetFeatureName) => createSafeMetricsHandle(meter, targetFeatureName)
         : () => createNoopMetricsHandle();
-    // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
-    // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
-    const bridgeSink = afterCommitHooks ?? [];
     // A failed inner write has already appended its event and projections when a later
     // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
     // failure result. The savepoint makes the failure undo exactly the inner write; the
     // inner afterCommit hooks only reach the outer sink if it succeeded.
     const executeNestedWriteInSavepoint = async (asUser, targetType, payload) => {
+        if (registry.getWriteHandler(targetType)?.transaction === "perCommand") {
+            return writeFailure(perCommandNestedDenied(targetType));
+        }
         if (!tx)
             return executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink);
         const innerAfterCommitHooks = [];
         try {
             const result = await runInSavepoint(tx, async (savepointTx) => {
-                const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary driver savepoint handle is a transaction handle
+                const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary db-runner savepoint handle is a transaction handle
                 innerAfterCommitHooks);
                 if (isFailedWriteResult(innerResult))
                     throw new NestedWriteRollback(innerResult);
@@ -389,16 +488,13 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             throw e;
         }
     };
-    // Post-commit hooks have no transaction left, so a bare executeWrite would
-    // auto-commit event append, projections and inTransaction hooks separately
-    // and its afterCommit hooks would land in an already-flushed sink. A
-    // batch-of-one gives the write its own transaction and its own flush.
-    const writeAsUser = async (asUser, targetType, payload) => isPostCommit
-        ? unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin))
-        : executeNestedWriteInSavepoint(asUser, targetType, payload);
-    const scheduleAfterCommit = (hook) => {
-        bridgeSink.push(hook);
-    };
+    // Without an open transaction (post-commit hooks, stream/query handlers, perCommand handlers) a bare
+    // executeWrite would auto-commit event append, projections and inTransaction hooks separately and its
+    // afterCommit hooks would land in a sink nobody flushes. A batch-of-one gives the write its own
+    // transaction and its own flush.
+    const writeAsUser = async (asUser, targetType, payload) => transactionScope === "inTransaction"
+        ? executeNestedWriteInSavepoint(asUser, targetType, payload)
+        : unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin));
     const identitySwitchAudit = { reason: identitySwitchGrantReason, report: reportEscapeHatch };
     const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
         // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
@@ -733,9 +829,13 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const locale = reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
     // The payload-bucket digest is dispatcher-internal; handlers must not be
     // able to compute bucket keys.
-    const { _rateLimitPayloadDigest: _omitPayloadDigest, ...contextForHandler } = context;
+    const { _rateLimitPayloadDigest: payloadDigest, 
+    // Bound to this call's tx: an outer context's factory must not leak into a tx-less one.
+    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, ...contextForHandler } = context;
     const handlerContext = {
         ...contextForHandler,
+        ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
+        ...(notifyInTransactionFactory && { _notifyInTransactionFactory: notifyInTransactionFactory }),
         registry,
         db: exposedDb,
         dbOutsideTransaction,
@@ -781,14 +881,22 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         _userId: user.id,
         _tenantId: user.tenantId,
         _handlerType: type,
-        scheduleAfterCommit,
+        ...(hasLiveCommitSink && { scheduleAfterCommit }),
         ...(includeDeleted && { includeDeleted: true }),
         ...bridge,
     }; // @cast-boundary engine-bridge
+    const scopedContext = transactionScope === "withoutTransaction"
+        ? denyEventStoreSurfaces(handlerContext, withoutTransactionDenied)
+        : handlerContext;
     // A resolved member principal is read-only by construction.
     return isMemberResolutionPrincipal(user)
-        ? applyMemberResolutionReadOnly(handlerContext)
-        : handlerContext;
+        ? applyMemberResolutionReadOnly(scopedContext)
+        : scopedContext;
+}
+// The handler-name prefix keeps a handler from reproducing the digests the
+// dispatcher uses for payload buckets (those hash the bare normalized value).
+export function createHandlerBoundDigest(digest, handlerName) {
+    return (value) => digest(`handler:${handlerName}:${value}`);
 }
 // Resolves the agent risk the irreversible-operation gate should attribute to
 // `type` when it becomes the request's entry handler — same defaulting rule
@@ -1076,7 +1184,7 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
             message: `Handler "${handlerName}" declares additionalRateLimits but its payload is not an object.`,
         });
     }
-    for (const { per, limit, windowSeconds, cost } of limits) {
+    for (const { per, limit, windowSeconds, cost, normalize } of limits) {
         const value = data[per.payloadField];
         // skip: optional field not sent — nothing to bucket on
         if (value === undefined)
@@ -1086,7 +1194,7 @@ export async function enforcePayloadRateLimits(ctx, limits, handlerName, user, d
                 message: `Handler "${handlerName}" additionalRateLimits payloadField "${per.payloadField}" is not a string.`,
             });
         }
-        const key = buildPayloadBucketKey(handlerName, per.payloadField, digest(normalizePayloadBucketValue(value)));
+        const key = buildPayloadBucketKey(user.tenantId, handlerName, per.payloadField, digest(normalizePayloadBucketValue(value, normalize)));
         await context.rateLimit.enforce(key, { limit, windowSeconds, cost });
     }
 }

package/dist/pipeline/dispatch-write.js

@@ -11,12 +11,13 @@ import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionRea
 import { assertFileRefsBelongToTenant } from "../files/assert-file-refs-belong-to-tenant.js";
 import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
 import { disposeRemovedFileRefs } from "../files/dispose-removed-file-refs.js";
+import { loadSaveFileRefs } from "../files/load-save-file-refs.js";
 import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
-import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, perCommandNestedDenied, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
-import { consumeReservation } from "./pre-transaction-reservations.js";
+import { consumeReservation, hasPreTransactionPhase, } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -115,12 +116,13 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     await runProjections(result, handlerContext.registry, runner);
     if (result.kind === "save") {
         const fileRefArgs = { registry: handlerContext.registry, result, user, db: handlerContext.db };
-        await assertFileRefsBelongToTenant(fileRefArgs);
-        await bindPendingFileRefs(fileRefArgs);
+        const fileRefRows = await loadSaveFileRefs(fileRefArgs);
+        assertFileRefsBelongToTenant({ ...fileRefArgs, fileRefRows });
+        await bindPendingFileRefs({ ...fileRefArgs, fileRefRows });
         await disposeRemovedFileRefs(fileRefArgs);
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, "postCommit");
             await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -128,7 +130,7 @@ 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, true);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, "postCommit");
             await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -337,23 +339,29 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     if (isMemberResolutionPrincipal(user)) {
         return writeFailure(memberResolutionReadOnlyDenied());
     }
-    // A command the dispatcher reserved for was already billed against the rate limits; the
-    // gates only run again against the in-transaction state.
-    const reservation = handler.reserveBeforeTransaction ? consumeReservation(type) : undefined;
+    const isPerCommand = handler.transaction === "perCommand";
+    if (isPerCommand && tx !== undefined) {
+        return writeFailure(perCommandNestedDenied(type));
+    }
+    // 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;
-    // A handler that reserves before the transaction cannot do so from inside an open one; running
-    // it unreserved would skip the check entirely, so a nested ctx.write of a different capped
-    // handler is rejected instead.
-    if (handler.reserveBeforeTransaction && !reservation) {
+    // 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({
-            message: `handler "${type}" reserves before the transaction and cannot run as a nested write unless the top-level command reserved it`,
+            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);
-    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks);
+    // 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
@@ -410,7 +418,8 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     // writeFailure, not via a rethrow) so batches roll back naturally.
     let result;
     try {
-        result = await handler.handler({ type, payload: parsedPayload, user }, handlerContext);
+        const event = { type, payload: parsedPayload, user, prepared: reservation?.prepared };
+        result = await handler.handler(event, handlerContext);
     }
     catch (e) {
         return writeFailure(wrapToKumiko(e));
@@ -434,12 +443,15 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
             return confirmFailure;
     }
     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));
+        // 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.

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

@@ -57,8 +57,7 @@ export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs
         const cooldownElapsed = Temporal.Instant.compare(state.updatedAt, cooldownDeadline) <= 0;
         if (cooldownElapsed && state.rearmCount < maxRearmCount) {
             const rearmed = await rearmDeadConsumer(tx, name, instanceId);
-            const rearmedState = rearmed &&
-                coerceRow(rearmed, extractTableInfo(eventConsumerStateTable));
+            const rearmedState = rearmed && coerceRow(rearmed, extractTableInfo(eventConsumerStateTable));
             if (rearmedState)
                 return { state: rearmedState, skip: null };
         }
@@ -149,7 +148,7 @@ export async function markProcessing(tx, name, instanceId) {
 export async function fetchPendingEvents(tx, cursor, batchSize, pendingRanges = []) {
     const rawRows = await selectPendingAndNewEventRows(tx, cursor, pendingRanges, batchSize);
     const info = extractTableInfo(eventsTable);
-    return rawRows.map((row) => coerceRow(row, info)); // @cast-boundary db-row
+    return rawRows.map((row) => coerceRow(row, info));
 }
 // Deliver events to the consumer's handler in events.id order, or — when
 // the consumer wires a batchHandler — through it in one call first. Halt-

package/dist/pipeline/index.d.ts

@@ -1,5 +1,6 @@
 export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.js";
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
+export { normalizePayloadBucketValue } from "../rate-limit/bucket.js";
 export type { AppendDomainEventCoreDeps } from "./append-event-core.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.js";
@@ -30,6 +31,7 @@ export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pip
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export type { MspRebuildDeps } from "./msp-rebuild.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export type { ProjectionProgress, RebuildResult } from "./projection-rebuild.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export type { ProjectionStatus } from "./projection-state.js";

package/dist/pipeline/index.js

@@ -1,4 +1,5 @@
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
+export { normalizePayloadBucketValue } from "../rate-limit/bucket.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
@@ -15,6 +16,7 @@ export { createIdempotencyGuard } from "./idempotency.js";
 export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";
 export { runProjectionsForEvent } from "./projections-runner.js";

package/dist/pipeline/member-read-only-transaction.js

@@ -34,7 +34,7 @@ async function runInDiscardedReadOnlySavepoint(tx, timeoutMs, bindIdleTimeout, f
         await runInSavepoint(tx, async (sp) => {
             // kumiko-lint-ignore raw-sql transaction characteristic, no query helper
             await asRawClient(sp).unsafe(memberReadSessionSettingsSql(timeoutMs, bindIdleTimeout));
-            // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
+            // @cast-boundary db-runner savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
             settled.outcome = { value: await fn(sp) };
             // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
             throw new SavepointDiscard();

package/dist/pipeline/notify-scope.d.ts

@@ -0,0 +1,13 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+import type { NotifyFn, NotifyOptions, Registry } from "../engine/types/index.js";
+import type { AfterCommitHook } from "./dispatcher-utils.js";
+export declare function assertNotifyTargetsOwnTenant(options: NotifyOptions, tenantId: TenantId): void;
+type DeferringNotifyDeps = {
+    readonly registry: Pick<Registry, "getAllNotifications"> | undefined;
+    readonly tenantId: TenantId;
+    readonly notifyAfterCommit: NotifyFn;
+    readonly notifyNow: NotifyFn;
+    readonly scheduleAfterCommit: (hook: AfterCommitHook) => void;
+};
+export declare function createDeferringNotify(deps: DeferringNotifyDeps): NotifyFn;
+export {};

package/dist/pipeline/notify-scope.js

@@ -0,0 +1,32 @@
+import { assertNotificationVariables } from "../engine/template-variables.js";
+import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+function isTenantBroadcast(to) {
+    return typeof to === "object" && to !== null && !Array.isArray(to) && "tenant" in to;
+}
+export function assertNotifyTargetsOwnTenant(options, tenantId) {
+    const { to } = options;
+    if (isTenantBroadcast(to) && to.tenant !== tenantId) {
+        throw new AccessDeniedError({
+            message: "ctx.notify can only broadcast to the caller's own tenant",
+            details: { reason: FrameworkReasons.notifyForeignTenantBroadcast },
+        });
+    }
+}
+// Without `immediate`, a notify inside a write transaction waits for the commit so a
+// rolled-back write leaves no notification behind.
+export function createDeferringNotify(deps) {
+    const { registry, tenantId, notifyAfterCommit, notifyNow, scheduleAfterCommit } = deps;
+    async function notifyDeferringUntilCommit(notificationType, options) {
+        assertNotifyTargetsOwnTenant(options, tenantId);
+        // Fail the write now: after the commit the problem would only surface in the render job.
+        if (registry)
+            assertNotificationVariables(registry, notificationType, options.data);
+        if (options.immediate === true)
+            return notifyNow(notificationType, options);
+        scheduleAfterCommit(async () => {
+            await notifyAfterCommit(notificationType, options);
+        });
+        return { kind: "deferred" };
+    }
+    return notifyDeferringUntilCommit;
+}

package/dist/pipeline/pre-transaction-reservations.d.ts

@@ -1,12 +1,14 @@
 import type { ReservationHandle } from "@cosmicdrift/kumiko-types/handlers";
-import type { SessionUser } from "../engine/types/index.js";
+import type { SessionUser, WriteHandlerDef } from "../engine/types/index.js";
 import { type WriteErrorInfo } from "../errors/index.js";
 import type { BatchCommand, DispatchContext } from "./dispatch-shared.js";
 import type { WriteOrigin } from "./write-origin.js";
 type ReservationConfirm = ReservationHandle["confirmInTransaction"];
 export type ConsumedReservation = {
     readonly confirmInTransaction: ReservationConfirm | undefined;
+    readonly prepared: unknown;
 };
+export declare function hasPreTransactionPhase(handler: WriteHandlerDef): boolean;
 export declare function runAsCommand<T>(reserved: {
     readonly type: string;
     readonly reservation: ConsumedReservation;

package/dist/pipeline/pre-transaction-reservations.js

@@ -1,10 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { toWriteErrorInfo } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { buildHandlerContext, isMemberResolutionPrincipal } from "./dispatch-shared.js";
+import { applyBeforeTransactionReadOnly, buildHandlerContext, denyTransactionBoundSurfaces, isMemberResolutionPrincipal, } from "./dispatch-shared.js";
 import { wrapToKumiko } from "./dispatcher-utils.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
 import { effectiveWriteOrigin, rootWriteOrigin } from "./write-origin.js";
+export function hasPreTransactionPhase(handler) {
+    return handler.reserveBeforeTransaction !== undefined || handler.beforeTransaction !== undefined;
+}
 // One-shot permission per top-level command: the handler that reserved before the transaction
 // consumes it on entry. A capped handler reached any other way (nested ctx.write, writeAs, a
 // second execution of the same type) finds it spent and is rejected instead of running unreserved.
@@ -36,13 +39,13 @@ async function releaseAll(ctx, releases) {
             await release();
         }
         catch (error) {
-            log.error("releasing a pre-transaction reservation failed", { error });
+            log.error("releasing a pre-transaction phase failed", { error });
         }
     }
 }
 // Same gates as the in-transaction run, but before any transaction: a caller who is rate limited,
-// denied or sends an invalid payload never reserves anything, so a rejected request cannot consume
-// capacity or trigger the reservation's side effects.
+// denied or sends an invalid payload never reserves or prepares anything, so a rejected request
+// cannot consume capacity or trigger external calls.
 export async function reserveBeforeTransaction(ctx, commands, user, inheritedOrigin) {
     const releases = [];
     const reservedCommands = new Map();
@@ -51,7 +54,7 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
     for (const [index, command] of commands.entries()) {
         try {
             const handler = ctx.registry.getWriteHandler(command.type);
-            if (!handler?.reserveBeforeTransaction)
+            if (!handler || !hasPreTransactionPhase(handler))
                 continue;
             const gates = await runPreHandlerGates(ctx, handler, command.type, command.payload, user, "charge");
             if (!gates.isSuccess) {
@@ -60,10 +63,26 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
             }
             const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, command.type, user), inheritedOrigin);
             const handlerContext = await buildHandlerContext(ctx, command.type, user, origin);
-            const handle = toReservationHandle(await handler.reserveBeforeTransaction({ type: command.type, payload: gates.payload, user }, handlerContext));
-            if (handle)
-                releases.push(handle.release);
-            reservedCommands.set(index, { confirmInTransaction: handle?.confirmInTransaction });
+            const event = { type: command.type, payload: gates.payload, user };
+            let confirmInTransaction;
+            if (handler.reserveBeforeTransaction) {
+                const handle = toReservationHandle(await handler.reserveBeforeTransaction(event, denyTransactionBoundSurfaces(handlerContext)));
+                if (handle)
+                    releases.push(handle.release);
+                confirmInTransaction = handle?.confirmInTransaction;
+            }
+            let prepared;
+            if (handler.beforeTransaction) {
+                const phase = await handler.beforeTransaction(event, applyBeforeTransactionReadOnly(handlerContext));
+                if (!phase.isSuccess) {
+                    await releaseAll(ctx, releases);
+                    return { isSuccess: false, error: phase.error, failedIndex: index };
+                }
+                if (phase.release)
+                    releases.push(phase.release);
+                prepared = phase.data;
+            }
+            reservedCommands.set(index, { confirmInTransaction, prepared });
         }
         catch (error) {
             await releaseAll(ctx, releases);