@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/dist/files/purge-expired-file-ref-bytes.js

@@ -1,34 +1,60 @@
 import { deleteMany, selectMany } from "../db/query.js";
 import { deleteStoredFileAndDerivatives } from "../derivatives/delete-stored-file.js";
 export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
+const PAGE_ORDER = [
+    { col: "deletedAt", direction: "asc" },
+    { col: "id", direction: "asc" },
+];
+// Keyset page over (deletedAt, id): rows at the cursor's instant with a larger id first, then
+// strictly later instants. `where` already bounds deletedAt by the cutoff; the later-instants
+// query repeats that bound next to the cursor.
+async function selectNextPage(args) {
+    const { db, table, where, expiredBefore, cursor, pageSize } = args;
+    const options = { orderBy: PAGE_ORDER, limit: pageSize };
+    if (cursor === undefined)
+        return selectMany(db, table, where, options);
+    const sameInstant = await selectMany(db, table, { ...where, deletedAt: cursor.deletedAt, id: { gt: cursor.id } }, options);
+    if (sameInstant.length >= pageSize)
+        return sameInstant;
+    const later = await selectMany(db, table, { ...where, deletedAt: { gt: cursor.deletedAt, lt: expiredBefore } }, { ...options, limit: pageSize - sameInstant.length });
+    return [...sameInstant, ...later];
+}
 // Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
 // rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
-// row whose bytes could not be removed stays and the next run retries it.
+// row whose bytes could not be removed stays and the next run retries it. A run walks the
+// expired rows page by page along (deletedAt, id), so rows that keep failing cannot hide the
+// rows behind them; the run ends on the first empty page.
 export async function purgeExpiredFileRefsWithBytes(args) {
-    const { db, table, where, files, log } = args;
+    const { db, table, where, expiredBefore, files, log } = args;
+    const pageSize = args.pageSize ?? EXPIRED_FILE_REF_PURGE_BATCH;
     if (!files) {
         log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
         return;
     }
-    const rows = await selectMany(db, table, where, {
-        orderBy: [{ col: "deletedAt", direction: "asc" }],
-        limit: EXPIRED_FILE_REF_PURGE_BATCH,
-    });
-    const purgedIds = [];
     const store = { list: files.list, delete: (key) => files.ref(key).delete() };
-    for (const row of rows) {
-        try {
-            const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
-            if (failedKeys.length === 0) {
-                purgedIds.push(row.id);
-                continue;
+    let cursor;
+    for (;;) {
+        const rows = await selectNextPage({ db, table, where, expiredBefore, cursor, pageSize });
+        const lastRow = rows[rows.length - 1];
+        // skip: an empty page means every expired row has been visited
+        if (lastRow === undefined)
+            return;
+        cursor = lastRow;
+        const purgedIds = [];
+        for (const row of rows) {
+            try {
+                const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
+                if (failedKeys.length === 0) {
+                    purgedIds.push(row.id);
+                    continue;
+                }
+                log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
+            }
+            catch (err) {
+                log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
             }
-            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not fully deleted, row kept`);
-        }
-        catch (err) {
-            log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
         }
+        if (purgedIds.length > 0)
+            await deleteMany(db, table, { ...where, id: { in: purgedIds } });
     }
-    if (purgedIds.length > 0)
-        await deleteMany(db, table, { ...where, id: { in: purgedIds } });
 }

package/dist/jobs/index.d.ts

@@ -1,2 +1,2 @@
-export type { JobLogEntry, JobMeta, JobOutcomeMeta, JobQueuedMeta, JobRunner, JobRunnerOptions, JobSubjectValue, } from "./job-runner.js";
+export type { JobDroppedMeta, JobLogEntry, JobMeta, JobOutcomeMeta, JobQueuedMeta, JobRunner, JobRunnerOptions, JobSubjectValue, } from "./job-runner.js";
 export { createJobRunner, serializeJobSubject } from "./job-runner.js";

package/dist/jobs/job-runner.d.ts

@@ -29,6 +29,9 @@ export type JobQueuedMeta = {
     readonly tenantId: string;
     readonly subject: string | null;
 };
+export type JobDroppedMeta = {
+    readonly tenantId: string;
+};
 export type JobOutcomeMeta = {
     readonly tenantId: string;
     readonly finalAttempt: boolean;
@@ -66,6 +69,6 @@ export type JobRunnerOptions = {
     onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
     onJobFailed?: (jobName: string, jobId: string, error: string, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
     onJobQueued?: (jobName: string, jobId: string, meta: JobQueuedMeta) => void;
-    onJobDropped?: (jobName: string, jobId: string) => void;
+    onJobDropped?: (jobName: string, jobId: string, meta: JobDroppedMeta) => void;
 };
 export declare function createJobRunner(options: JobRunnerOptions): JobRunner;

package/dist/jobs/job-runner.js

@@ -611,12 +611,16 @@ export function createJobRunner(options) {
             });
         }
     }
-    async function announceDropped(jobName, jobDef, bullJobId) {
+    async function announceDropped(jobName, jobDef, bullJobId, data) {
         // skip: job did not opt in or no logger wired
         if (!jobDef.tenantVisibleRun || !options.onJobDropped)
             return;
+        const tenantId = tenantIdOfJobData(data);
+        // skip: tenant-less run — announceQueued never recorded a row for it
+        if (tenantId === SYSTEM_TENANT_ID)
+            return;
         try {
-            await options.onJobDropped(jobName, bullJobId);
+            await options.onJobDropped(jobName, bullJobId, { tenantId });
         }
         catch (err) {
             errorLogger.warn("tenant-visible queued state not cleared", {
@@ -732,7 +736,7 @@ export function createJobRunner(options) {
                     ...buildRetryBullOpts(jobDef, priorAttempts),
                 });
                 if (bullJob.id !== undefined && bullJob.id !== requeued.id) {
-                    await announceDropped(jobName, jobDef, bullJob.id);
+                    await announceDropped(jobName, jobDef, bullJob.id, bullJob.data);
                 }
                 await announceQueued(jobName, jobDef, requeued.id, requeuedData);
                 // skip: lock taken, work re-enqueued with delay, current invocation done
@@ -1298,7 +1302,7 @@ export function createJobRunner(options) {
                     for (const j of waiting) {
                         if (j.name === jobName && j.id) {
                             await j.remove();
-                            await announceDropped(jobName, jobDef, j.id);
+                            await announceDropped(jobName, jobDef, j.id, j.data);
                         }
                     }
                     break;

package/dist/observability/escape-hatch-report.d.ts

@@ -11,7 +11,7 @@ export declare function createEscapeHatchReportWindow(opts?: {
 }): EscapeHatchReportWindow;
 export type EscapeHatchProcessDedup = {
     readonly kinds: ReadonlySet<EscapeHatchKind>;
-    readonly seen: Set<string>;
+    readonly lastAuditedAt: Map<string, number>;
 };
 export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function withEscapeHatchAuditScope<T>(run: () => Promise<T>): Promise<T>;

package/dist/observability/escape-hatch-report.js

@@ -27,8 +27,11 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+// A long-lived worker must leave an audit event inside every retention window
+// (90 days), or its crons vanish from the log once the first event is pruned.
+const PROCESS_REAUDIT_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export function createEscapeHatchProcessDedup(kinds) {
-    return { kinds: new Set(kinds), seen: new Set() };
+    return { kinds: new Set(kinds), lastAuditedAt: new Map() };
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
@@ -105,11 +108,20 @@ export function createEscapeHatchReporter(opts) {
             emitEscapeHatchUse(opts.meter, opts.handler, kind);
         const { processDedup } = opts;
         if (processDedup?.kinds.has(kind)) {
-            const processKey = JSON.stringify([opts.handler, kind, opts.tenantId]);
-            // skip: this (handler, kind, tenant) was already audited by this process
-            if (processDedup.seen.has(processKey))
+            const processKey = JSON.stringify([
+                opts.handler,
+                kind,
+                opts.tenantId,
+                target?.id ?? null,
+                target?.tenantId ?? null,
+            ]);
+            const nowMs = now();
+            const lastAuditedAt = processDedup.lastAuditedAt.get(processKey);
+            // skip: audited by this process within the re-audit interval
+            if (lastAuditedAt !== undefined && nowMs - lastAuditedAt < PROCESS_REAUDIT_INTERVAL_MS) {
                 return;
-            processDedup.seen.add(processKey);
+            }
+            processDedup.lastAuditedAt.set(processKey, nowMs);
             reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds
             return;

package/dist/pipeline/cascade-handler.js

@@ -52,10 +52,13 @@ export function createCascadeDeleteHook(registry, tables) {
                     // block the parent delete here instead of changing with it. The error names
                     // the parent only: the caller may delete the parent without reading the child.
                     if (strategy === OnDeleteStrategies.cascade || strategy === OnDeleteStrategies.setNull) {
-                        const childLock = registry.getEntity(relation.target)?.lockedWhen;
-                        if (childLock !== undefined) {
+                        const childEntity = registry.getEntity(relation.target);
+                        const childLock = childEntity?.lockedWhen;
+                        if (childLock !== undefined && payload.lockGuardBypassed !== true) {
+                            // A soft-deleted child is invisible to the caller and must not block.
                             const children = await selectMany(db, targetTable, {
                                 [relation.foreignKey]: payload.id,
+                                ...(childEntity?.softDelete === true && { isDeleted: false }),
                             });
                             if (children.some((child) => isRecordLocked(childLock, child))) {
                                 throw new RecordLockedError({ entityName, entityId: payload.id });

package/dist/pipeline/dispatch-batch.js

@@ -1,10 +1,10 @@
 import { requestContext, runWithWriteOrigin } from "../api/request-context.js";
 import { transaction } from "../db/query.js";
-import { InternalError, toWriteErrorInfo, writeFailure } from "../errors/index.js";
+import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { resolveDbSource } from "./dispatch-shared.js";
-import { executeNestedWrite } from "./dispatch-write.js";
+import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
@@ -22,15 +22,44 @@ function toReservedScope(reservations, index, cmd) {
     const reservation = reservations.reservedCommands.get(index);
     return reservation && { type: cmd.type, reservation };
 }
+function isPerCommandHandler(ctx, type) {
+    return ctx.registry.getWriteHandler(type)?.transaction === "perCommand";
+}
 async function runReservedCommand(scope, cmd, index, tx) {
     const { ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks } = scope;
     const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
     origins.push(origin);
     const hookStart = afterCommitHooks.length;
-    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
+    // Nested-write children would run inline with the in-transaction scope, so a perCommand command skips the expansion.
+    const execute = isPerCommandHandler(ctx, cmd.type) ? executeWrite : executeNestedWrite;
+    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => execute(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }
+// Sequential fallback without an outer transaction. A failure result and a throw both end the
+// batch, so both give the reserved capacity back.
+async function runCommandsWithoutTransaction(scope, commands, results) {
+    try {
+        for (let i = 0; i < commands.length; i++) {
+            const cmd = commands[i];
+            if (!cmd)
+                continue;
+            const res = await runReservedCommand(scope, cmd, i, undefined);
+            results.push(res);
+            if (!res.isSuccess) {
+                // No tx means no rollback — but we still drop afterCommit hooks,
+                // matching the semantic "failure = side-effects don't fire".
+                await scope.reservations.releaseAll();
+                return { index: i, error: res.error };
+            }
+        }
+    }
+    catch (e) {
+        await scope.reservations.releaseAll();
+        throw e;
+    }
+    return undefined;
+}
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
 export async function runBatch(ctx, commands, user, requestId, inheritedOrigin) {
@@ -43,6 +72,30 @@ export async function runBatch(ctx, commands, user, requestId, inheritedOrigin)
     const { signal: _signal, ...withoutSignal } = current;
     return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
 }
+function perCommandBatchRejection(ctx, commands) {
+    const index = commands.findIndex((cmd) => isPerCommandHandler(ctx, cmd.type));
+    const command = commands[index];
+    if (!command || commands.length < 2)
+        return undefined;
+    return {
+        isSuccess: false,
+        error: toWriteErrorInfo(new UnprocessableError("per_command_handler_in_batch", {
+            message: `handler "${command.type}" runs without a transaction (transaction: "perCommand") and cannot be part of a multi-command batch`,
+        })),
+        failedIndex: index,
+        results: [],
+    };
+}
+async function checkBatchIdempotency(ctx, user, requestId) {
+    if (!requestId || !ctx.idempotency)
+        return {};
+    const checked = await ctx.idempotency.check(user.tenantId, user.id, requestId);
+    if (checked.status !== "cached")
+        return { token: checked.token };
+    const parsed = parseJsonSafe(checked.result, null);
+    // corrupted cache entry — treat as miss, let the request re-run
+    return parsed ? { cached: parsed } : {};
+}
 async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     const { idempotency, lifecycle, appContext: context } = ctx;
     if (commands.length === 0) {
@@ -53,19 +106,10 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // idempotencyToken is only set when we actually acquired the lock — the
     // corrupted-cache fallthrough below leaves it unset, so finalize() skips
     // store() rather than writing over an entry it never owned.
-    let idempotencyToken;
-    if (requestId && idempotency) {
-        const checked = await idempotency.check(user.tenantId, user.id, requestId);
-        if (checked.status === "cached") {
-            const parsed = parseJsonSafe(checked.result, null);
-            if (parsed)
-                return parsed;
-            // corrupted cache entry — treat as miss, let the request re-run
-        }
-        else {
-            idempotencyToken = checked.token;
-        }
-    }
+    const idempotencyCheck = await checkBatchIdempotency(ctx, user, requestId);
+    if (idempotencyCheck.cached)
+        return idempotencyCheck.cached;
+    const idempotencyToken = idempotencyCheck.token;
     // Hooks already ran on the plaintext results; what is returned and cached
     // for retries must not carry writeOnly values.
     const maskForClient = (result) => maskBatchResultForClient(ctx.registry, commands, result);
@@ -148,6 +192,10 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             return;
         await runWithWriteOrigin(strictest, flushBatchHooksInner);
     };
+    const perCommandRejection = perCommandBatchRejection(ctx, commands);
+    if (perCommandRejection)
+        return releaseOrFinalize(perCommandRejection, false);
+    const runsWithoutTransaction = commands.some((cmd) => isPerCommandHandler(ctx, cmd.type));
     // Reserve before the transaction opens so no extra connection is held while the handler tx is
     // open; the release below runs only after that tx has ended without committing.
     const reservations = await reserveBeforeTransaction(ctx, commands, user, inheritedOrigin);
@@ -162,25 +210,24 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // batch() opens its own outer transaction — needs the top-level
     // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
     const db = resolveDbSource(ctx, undefined);
-    if (!db) {
-        // Without a DB connection there is no transaction to open. Fall back to
+    if (!db || runsWithoutTransaction) {
+        // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
+        // there is no transaction to open. Fall back to
         // sequential execution — useful for unit tests that don't touch the DB.
         // Each command runs independently; a failure stops the batch.
-        for (let i = 0; i < commands.length; i++) {
-            const cmd = commands[i];
-            if (!cmd)
-                continue;
-            const res = await runReservedCommand({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, cmd, i, undefined);
-            results.push(res);
-            if (!res.isSuccess) {
-                // No tx means no rollback — but we still drop afterCommit hooks,
-                // matching the semantic "failure = side-effects don't fire".
-                await reservations.releaseAll();
-                return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
-            }
+        const failed = await runCommandsWithoutTransaction({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, commands, results);
+        if (failed) {
+            return finalize({
+                isSuccess: false,
+                error: failed.error,
+                failedIndex: failed.index,
+                results,
+            });
         }
         await flushAfterCommit();
-        await flushBatchHooks();
+        // The inner commands of a perCommand handler already fired their own batch hooks.
+        if (!runsWithoutTransaction)
+            await flushBatchHooks();
         return finalize({ isSuccess: true, results });
     }
     let transactionCallbackCompleted = false;
@@ -201,6 +248,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     }
     catch (e) {
         // Rollback or failed COMMIT: the transaction is over, so the reserved capacity goes back.
+        // The release is outcome-safe: it only gives back a reservation row the handler tx did not delete.
         await reservations.releaseAll();
         if (e instanceof BatchRollback) {
             // Thrown inside the callback, so the tx rolled back. A 4xx is

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

@@ -6,7 +6,7 @@ import type { defineTransitions } from "../engine/state-machine.js";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.js";
 import type { TenantId } from "../engine/types/identifiers.js";
 import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
-import { type WriteErrorInfo } from "../errors/index.js";
+import { InternalError, type WriteErrorInfo } from "../errors/index.js";
 import { type EscapeHatchReportWindow, type getFallbackMeter, getFallbackTracer } from "../observability/index.js";
 import { type AfterCommitHook } from "./dispatcher-utils.js";
 import type { IdempotencyGuard } from "./idempotency.js";
@@ -53,7 +53,12 @@ export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
-export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, isPostCommit?: boolean): Promise<HandlerContext>;
+export declare function perCommandNestedDenied(targetType: string): InternalError;
+export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
+export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;
+export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, transactionScope?: HandlerTransactionScope): Promise<HandlerContext>;
+export declare function createHandlerBoundDigest(digest: (value: string) => string, handlerName: string): (value: string) => string;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;
 export declare function runStreamInstrumented<T>(ctx: DispatchContext, type: string, user: SessionUser, inner: () => AsyncGenerator<T>): AsyncGenerator<T>;
 export declare function checkFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<import("../errors/index.js").FeatureDisabledError | undefined>;

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";
@@ -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,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;
@@ -214,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;
@@ -231,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"),
@@ -240,11 +298,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 +347,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);
     };
@@ -354,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({
@@ -362,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,
             };
         }
@@ -400,6 +465,9 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // 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 = [];
@@ -420,13 +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);
+    // 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.
@@ -761,11 +829,12 @@ 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;
     const handlerContext = {
         ...contextForHandler,
+        ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
         ...(notifyInTransactionFactory && { _notifyInTransactionFactory: notifyInTransactionFactory }),
         registry,
         db: exposedDb,
@@ -816,10 +885,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 +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)
@@ -1117,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 });
     }
 }