@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/dist/pipeline/dispatch-shared.js

@@ -6,16 +6,16 @@ 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";
+import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
 import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
 import { createFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { createEscapeHatchReporter, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
+import { createEscapeHatchReporter, createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
 import { buildBucketKey, buildPayloadBucketKey, normalizePayloadBucketValue, } from "../rate-limit/index.js";
 import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
 import { isPlainObject } from "../utils/is-plain-object.js";
@@ -112,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();
         },
     });
 }
@@ -205,7 +205,66 @@ 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,
+    };
+}
+export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, transactionScope = tx ? "inTransaction" : "withoutTransaction", 
+// A query bridge has no commit sink of its own, but ctx.notify inside it must still wait for
+// the outer write's commit: the outer sink is lent to notify only, not to scheduleAfterCommit.
+outerNotifySink, 
+// beforeTransaction phase: ctx.forTenant stays available but every target db denies writes.
+readOnlyForTenant = false) {
     const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -214,7 +273,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;
@@ -231,7 +293,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"),
@@ -240,11 +302,14 @@ 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
@@ -286,7 +351,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // 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 && isPostCommit !== true;
+    const hasLiveCommitSink = afterCommitHooks !== undefined && transactionScope !== "postCommit";
     const scheduleAfterCommit = (hook) => {
         bridgeSink.push(hook);
     };
@@ -297,23 +362,30 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const notifyInTransactionFactory = notifyFactory && tx !== undefined
         ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, outsideTxSource, context._fileProviderResolver)
         : undefined;
+    const notifyAfterCommitFactory = notifyFactory
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, undefined, context._fileProviderResolver)
+        : undefined;
     const notify = buildNotify();
     function buildNotify() {
-        if (!notifyFactory)
+        if (!notifyAfterCommitFactory)
             return undefined;
-        const notifyAfterCommit = notifyFactory(user, user.tenantId, notifyJobDispatcher, undefined, context._fileProviderResolver);
+        const notifyAfterCommit = notifyAfterCommitFactory(user, user.tenantId);
         if (!notifyInTransactionFactory)
             return notifyAfterCommit;
         const notifyInTransaction = notifyInTransactionFactory(user, user.tenantId);
-        // A rolled-back write must leave no notification behind.
-        if (!hasLiveCommitSink)
+        // A rolled-back write must leave no notification behind. Without any commit to wait for (a
+        // post-commit context) delivery stays immediate.
+        const notifyCommitSink = hasLiveCommitSink ? bridgeSink : outerNotifySink;
+        if (notifyCommitSink === undefined)
             return notifyInTransaction;
         return createDeferringNotify({
             registry,
             tenantId: user.tenantId,
             notifyAfterCommit,
             notifyNow: notifyInTransaction,
-            scheduleAfterCommit,
+            scheduleAfterCommit: (hook) => {
+                notifyCommitSink.push(hook);
+            },
         });
     }
     // Mirror notify: only built when the config feature wired its factory.
@@ -354,7 +426,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, undefined, readOnlyForTenant)
+                    : exposedDb;
+                return { db: ownTenantDb, streamTenantId: undefined };
             }
             if (!mayOverrideTenant(user)) {
                 throw new AccessDeniedError({
@@ -362,7 +438,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 || readOnlyForTenant)),
                 streamTenantId: targetTenantId,
             };
         }
@@ -390,16 +466,16 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const metrics = meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
     // ctx.metricsFor(featureName) — shared/library code binds to a feature
     // name of its own choosing instead of the dispatching handler's
-    // (framework#1844). Unregistered names no-op rather than throw, see
-    // createSafeMetricsHandle.
-    const metricsFor = meter
-        ? (targetFeatureName) => createSafeMetricsHandle(meter, targetFeatureName)
-        : () => createNoopMetricsHandle();
+    // (framework#1844). Unregistered names no-op rather than throw.
+    const metricsFor = createMetricsForFactory(meter);
     // 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) => {
+    const runNestedWriteInSavepoint = 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 = [];
@@ -420,17 +496,26 @@ 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);
+    // Savepoints on one connection are not serialized by the driver: two parallel nested writes would
+    // interleave their statements and a ROLLBACK TO of the first would also discard the second's rows.
+    // Writes nested one level deeper run on their own savepoint handle and therefore their own chain.
+    let nestedWriteChain = Promise.resolve();
+    const executeNestedWriteInSavepoint = (asUser, targetType, payload) => {
+        const run = nestedWriteChain.then(() => runNestedWriteInSavepoint(asUser, targetType, payload));
+        nestedWriteChain = run.catch(() => undefined);
+        return run;
+    };
+    // 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.
-        queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx), // @wrapper-known semantic-alias
+        queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx, hasLiveCommitSink ? bridgeSink : outerNotifySink), // @wrapper-known semantic-alias
         writeAs: writeAsUser,
     }, identitySwitchAudit);
     // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
@@ -474,7 +559,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         return projTable === undefined || hasTenantColumn(projTable);
     });
     const bridge = {
-        query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx), // @wrapper-known semantic-alias
+        query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx, hasLiveCommitSink ? bridgeSink : outerNotifySink), // @wrapper-known semantic-alias
         queryAs: identitySwitch.queryAs,
         write: (targetType, payload) => writeAsUser(user, targetType, payload),
         writeAs: identitySwitch.writeAs,
@@ -529,16 +614,9 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     message: `ctx.fetchForWriting("${args.aggregateId}") requires a database connection — none is configured.`,
                 });
             }
-            // Stream-version authoritative (same policy as CRUD executor + Block 0).
-            // A single SELECT MAX(version) is cheaper than loading the full stream
-            // when the caller just wants to append — but most callers also want
-            // the events (business-rule checks), so fetch both in parallel.
-            const [storedEvents, fetchedVersion] = await Promise.all([
-                loadAggregate(dbSource, args.aggregateId, user.tenantId, {
-                    aggregateType: args.aggregateType,
-                }),
-                getStreamVersion(dbSource, args.aggregateId, user.tenantId),
-            ]);
+            // Stream-version authoritative (same policy as CRUD executor + Block 0), read together
+            // with the events so the pinned version covers exactly what the handler's rules saw.
+            const { events: storedEvents, streamVersion: fetchedVersion } = await loadAggregateForWriting(dbSource, args.aggregateId, user.tenantId, { aggregateType: args.aggregateType });
             const events = await upcastStoredEvents(storedEvents, registry.getEventUpcasters(), {
                 db: dbSource,
                 tenantId: user.tenantId,
@@ -761,12 +839,14 @@ 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, 
+    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;
+    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, _notifyAfterCommitFactory: _omitOuterNotifyAfterCommitFactory, ...contextForHandler } = context;
     const handlerContext = {
         ...contextForHandler,
+        ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
         ...(notifyInTransactionFactory && { _notifyInTransactionFactory: notifyInTransactionFactory }),
+        ...(notifyAfterCommitFactory && { _notifyAfterCommitFactory: notifyAfterCommitFactory }),
         registry,
         db: exposedDb,
         dbOutsideTransaction,
@@ -816,10 +896,18 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         ...(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
@@ -1107,7 +1195,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)
@@ -1117,7 +1205,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-stream.js

@@ -2,7 +2,7 @@ import { accessInvalidationCredentialFor } from "../api/sse-broker.js";
 import { scheduleTokenExpiry } from "../api/token-expiry-timer.js";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
-import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
+import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, UnauthenticatedError, validationErrorFromZod, } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runStreamInstrumented, } from "./dispatch-shared.js";
 import { handlerAccessError } from "./handler-access-error.js";
@@ -69,10 +69,16 @@ async function* executeStreamInner(ctx, type, payload, user, origin, options) {
                 abandonedForInvalidation = true;
                 void nextPull.catch(() => { });
                 void iterator.return?.(undefined)?.then(undefined, () => { });
+                // An expired token is a lapsed session (401, so clients show the
+                // session-end hint); revocation is a permission change (403).
+                if (outcome.reason === "expired") {
+                    throw new UnauthenticatedError({
+                        message: `token expired mid-stream for ${type}`,
+                        details: { handler: type, reason: outcome.reason },
+                    });
+                }
                 throw new AccessDeniedError({
-                    message: outcome.reason === "expired"
-                        ? `token expired mid-stream for ${type}`
-                        : `access revoked mid-stream for ${type}`,
+                    message: `access revoked mid-stream for ${type}`,
                     details: { handler: type },
                 });
             }

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/dispatcher.js

@@ -1,6 +1,7 @@
 import { runWithWriteOrigin } from "../api/request-context.js";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
+import { withEscapeHatchAuditScopeStream } from "../observability/escape-hatch-report.js";
 import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
@@ -114,7 +115,8 @@ export function createDispatcher(registry, context, options = {}) {
         },
         stream: (typeOrRef, payload, user, options) => {
             const type = resolveType(typeOrRef);
-            return executeStream(ctx, type, payload, user, rootWriteOrigin(registry, type, user), options);
+            const origin = rootWriteOrigin(registry, type, user);
+            return withEscapeHatchAuditScopeStream(() => executeStream(ctx, type, payload, user, origin, options));
         },
         async command(typeOrRef, payload, user) {
             const type = resolveType(typeOrRef);

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

@@ -1,4 +1,4 @@
-import type { PgClient } from "../db/connection.js";
+import type { PgListenClient } from "../db/connection.js";
 import type { AppContext } from "../engine/types/index.js";
 import { type StoredEvent } from "../event-store/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
@@ -46,7 +46,7 @@ export type EventDispatcherOptions = {
     readonly tracer?: Tracer;
     readonly meter?: Meter;
     readonly instanceId?: string;
-    readonly pgClient?: PgClient;
+    readonly pgClient?: PgListenClient;
 };
 export declare function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher;
 export type { ConsumerProgress, ConsumerRecoveryState } from "./event-dispatcher-admin.js";

package/dist/pipeline/event-dispatcher.js

@@ -114,7 +114,7 @@ export function createEventDispatcher(options) {
     // to EVENTS_PUBSUB_CHANNEL; cleared by .stop(). The timer remains active
     // even with LISTEN attached — it's a cheap safety net against missed
     // NOTIFYs (subscription drop, crash mid-commit).
-    let pgUnlisten = null;
+    let pgSubscription = null;
     // Bounds how many consumer turns hold a DB transaction at once. Each turn's
     // db.begin() checks out one pool connection, plus any writes the handler
     // itself makes via context.db — the app db pool defaults to postgres-js's
@@ -498,15 +498,16 @@ export function createEventDispatcher(options) {
             // succeeds (onlisten callback). It drops to 0 on the initial connect
             // failure, on stop() and when the idle pre-check detects a DB outage.
             // An outage shorter than one poll tick is not detected; the gauge then
-            // stays at 1 until postgres.js's delayed re-LISTEN lands.
+            // stays at 1 until the driver's delayed re-LISTEN lands.
             emitEventDispatcherListenConnected(meter, false);
             if (options.pgClient) {
                 try {
                     const sub = await options.pgClient.listen(EVENTS_PUBSUB_CHANNEL, runBackgroundPass, () => {
-                        // Fires on initial connect and again when postgres.js's own
+                        // Fires on initial connect and again when the driver's own
                         // re-LISTEN lands after a drop; during an outage that re-LISTEN
-                        // waits in its connection backoff (measured 10-30s after the DB
-                        // returns), polling covers delivery meanwhile. Never unlisten()
+                        // waits in its connection backoff (postgres-js: measured 10-30s
+                        // after the DB returns, Bun.SQL: up to 32s), polling covers
+                        // delivery meanwhile. Never unlisten()
                         // + listen() by hand: that leaves duplicate listeners.
                         // ponytail: no own LISTEN reconnect, the backoff gap is polled;
                         // add a dedicated LISTEN connection if prod wires a pgClient
@@ -514,7 +515,7 @@ export function createEventDispatcher(options) {
                         listenSubscribed = true;
                         emitEventDispatcherListenConnected(meter, true);
                     });
-                    pgUnlisten = sub.unlisten;
+                    pgSubscription = sub;
                 }
                 catch (e) {
                     emitEventDispatcherListenConnected(meter, false);
@@ -532,12 +533,13 @@ export function createEventDispatcher(options) {
                 clearInterval(timer);
                 timer = null;
             }
-            if (pgUnlisten) {
-                await pgUnlisten().catch(() => {
+            if (pgSubscription) {
+                // Called on the subscription: Bun.SQL's unlisten is a prototype method.
+                await pgSubscription.unlisten().catch(() => {
                     // skip: unlisten failure only matters during shutdown — the
                     // subscription is being torn down anyway.
                 });
-                pgUnlisten = null;
+                pgSubscription = null;
                 listenSubscribed = false;
                 emitEventDispatcherListenConnected(meter, false);
             }

package/dist/pipeline/event-retention.d.ts

@@ -6,6 +6,7 @@ export type PruneEventsOptions = {
     readonly aggregateTypes: readonly string[];
     readonly aggregateIds?: readonly string[];
     readonly dryRun?: boolean;
+    readonly batchSize?: number;
 };
 export type PruneEventsResult = {
     readonly deletedCount: number;

package/dist/pipeline/event-retention.js

@@ -34,6 +34,10 @@ export async function pruneEvents(db, options) {
     if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
         throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
     }
+    if (options.batchSize !== undefined &&
+        (!Number.isInteger(options.batchSize) || options.batchSize < 1)) {
+        throw new Error("pruneEvents: batchSize must be a positive integer.");
+    }
     const aggregateTypes = options.aggregateTypes;
     const aggregateIds = options.aggregateIds;
     const dryRun = options.dryRun === true;
@@ -56,7 +60,9 @@ export async function pruneEvents(db, options) {
             aggregateType: [...aggregateTypes],
             ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
             createdAt: { lt: cutoff },
-        });
+        }, options.batchSize === undefined
+            ? undefined
+            : { orderBy: { col: "id", direction: "asc" }, limit: options.batchSize });
         if (candidates.length === 0) {
             return { deletedCount: 0, cutoff, aggregateTypes, dryRun };
         }

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";

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";