@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/observability/metrics-handle.d.ts

@@ -1,6 +1,5 @@
 import type { Meter, MetricsHandle } from "./types/index.ts";
 export declare function createMetricsHandle(meter: Meter, featureName: string): MetricsHandle;
 export declare function createSafeMetricsHandle(meter: Meter, featureName: string): MetricsHandle;
-export declare function createUnboundMetricsHandle(meter: Meter): MetricsHandle;
 export declare function createNoopMetricsHandle(): MetricsHandle;
 export declare function createMetricsForFactory(meter: Meter | undefined): (featureName: string) => MetricsHandle;

package/dist/observability/metrics-handle.js

@@ -26,7 +26,7 @@ export function createMetricsHandle(meter, featureName) {
 // Same feature-bound resolution as createMetricsHandle, but for an
 // explicit `featureName` chosen by the caller rather than the dispatching
 // handler's own feature. Meant for shared/library code
-// invoked from many features' HandlerContext (ctx.metricsFor) — the
+// invoked from many features' HandlerContext (ctx.obs.metricsFor) — the
 // library owns one stable metric name instead of splintering into
 // kumiko_<caller>_x per consumer.
 //
@@ -77,19 +77,6 @@ export function createSafeMetricsHandle(meter, featureName) {
 // Fallback for contexts where the feature is unknown (e.g. system-hooks,
 // internal pipeline code). Short names are used verbatim — useful for
 // framework-level usage, but rejected by the Meter unless pre-registered.
-export function createUnboundMetricsHandle(meter) {
-    return {
-        inc(name, labels, value) {
-            meter.counter(name).inc(value, labels);
-        },
-        observe(name, value, labels) {
-            meter.histogram(name).observe(value, labels);
-        },
-        set(name, value, labels) {
-            meter.gauge(name).set(value, labels);
-        },
-    };
-}
 // Noop fallback used when no provider is configured and for safety in
 // contexts where we can't determine the feature. Every call is a no-op —
 // tests and non-observability-aware features never crash.
@@ -100,7 +87,7 @@ export function createNoopMetricsHandle() {
         set(_name, _value, _labels) { },
     };
 }
-// Shared factory behind ctx.metricsFor for handler and job contexts, so both
+// Shared factory behind ctx.obs.metricsFor for handler and job contexts, so both
 // keep the same no-op-on-unregistered contract.
 export function createMetricsForFactory(meter) {
     return meter

package/dist/observability/recording-tracer.d.ts

@@ -1,4 +1,4 @@
-import type { SensitiveFilterConfig, SerializedTraceContext, Span, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer } from "./types/index.ts";
+import type { SensitiveFilterConfig, Span, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer } from "./types/index.ts";
 export type RecordedSpan = {
     readonly traceId: string;
     readonly spanId: string;
@@ -28,5 +28,4 @@ export declare class RecordingTracer implements Tracer {
     withSpan<T>(name: string, optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>), fn?: (span: Span) => Promise<T>): Promise<T>;
     getActiveSpan(): Span | undefined;
 }
-export declare function serializeSpanContext(span: Span): SerializedTraceContext;
 export {};

package/dist/observability/recording-tracer.js

@@ -127,9 +127,3 @@ export class RecordingTracer {
     }
 }
 // Helper to serialize an active Span into the cross-process format.
-export function serializeSpanContext(span) {
-    return {
-        traceId: span.traceId,
-        spanId: span.spanId,
-    };
-}

package/dist/observability/sensitive-filter.d.ts

@@ -2,8 +2,6 @@ import type { SensitiveFilterConfig, SpanAttributeValue } from "./types/index.ts
 export declare const REDACTED = "[REDACTED]";
 export declare const DEFAULT_SENSITIVE_CONFIG: SensitiveFilterConfig;
 export declare function mergeSensitiveConfig(override: Partial<SensitiveFilterConfig> | undefined): SensitiveFilterConfig;
-export declare function redactHeaders(headers: Readonly<Record<string, string>>, config: SensitiveFilterConfig): Record<string, string>;
-export declare function redactQueryString(input: string, config: SensitiveFilterConfig): string;
 export declare function shouldRedactAttribute(key: string, config: SensitiveFilterConfig): boolean;
 export declare function redactValue(value: SpanAttributeValue): SpanAttributeValue;
 export declare function redactAttributes(attrs: Readonly<Record<string, SpanAttributeValue>>, config: SensitiveFilterConfig): Record<string, SpanAttributeValue>;

package/dist/observability/sensitive-filter.js

@@ -32,35 +32,6 @@ export function mergeSensitiveConfig(override) {
             DEFAULT_SENSITIVE_CONFIG.redactedAttributeKeyPatterns,
     };
 }
-function lowercaseSet(names) {
-    return new Set(names.map((n) => n.toLowerCase()));
-}
-export function redactHeaders(headers, config) {
-    const redacted = lowercaseSet(config.redactedHeaders);
-    const out = {};
-    for (const [key, value] of Object.entries(headers)) {
-        out[key] = redacted.has(key.toLowerCase()) ? REDACTED : value;
-    }
-    return out;
-}
-// Redact sensitive query params in a URL or query string. Returns a new URL
-// string with the same shape — path, fragment, and ordering preserved.
-export function redactQueryString(input, config) {
-    const redacted = lowercaseSet(config.redactedQueryParams);
-    // URL wants absolute; handle both absolute and path-only forms.
-    const hasScheme = /^[a-z][a-z0-9+\-.]*:/i.test(input);
-    const base = hasScheme ? undefined : "http://_internal";
-    const url = base ? new URL(input, base) : new URL(input);
-    for (const key of Array.from(url.searchParams.keys())) {
-        if (redacted.has(key.toLowerCase())) {
-            url.searchParams.set(key, REDACTED);
-        }
-    }
-    if (!hasScheme) {
-        return `${url.pathname}${url.search}${url.hash}`;
-    }
-    return url.toString();
-}
 // Check a single attribute key against the redaction patterns.
 // Used by the Span implementation when setAttribute is called.
 export function shouldRedactAttribute(key, config) {

package/dist/pipeline/active-membership.d.ts

@@ -1,6 +1,7 @@
+import type { ActiveMembershipResult } from "@cosmicdrift/kumiko-types/handlers";
 import { type PrincipalStatusPlugin, type TenantLifecycleStatusPlugin } from "../engine/active-membership.ts";
 import type { TenantId } from "../engine/types/identifiers.ts";
-import type { ActiveMembershipResult, Registry } from "../engine/types/index.ts";
+import type { Registry } from "../engine/types/index.ts";
 import { type DispatchContext } from "./dispatch-shared.ts";
 export type ActiveMembershipPolicy = {
     readonly allowPendingDestruction: boolean;

package/dist/pipeline/active-membership.js

@@ -1,5 +1,6 @@
 // One framework-owned composition of membership / principal-status /
 // tenant-lifecycle checks so login, switch-tenant and MFA completion can't independently drift.
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
 import { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN_STATUSES, } from "../engine/active-membership.js";
 import { EXT_PRINCIPAL_STATUS, EXT_TENANT_LIFECYCLE_STATUS } from "../engine/extension-names.js";
 import { createSystemUser } from "../engine/system-user.js";
@@ -41,7 +42,7 @@ async function findMembership(ctx, userId, tenantId) {
     }
     return rawMemberships.find((m) => m.tenantId === tenantId);
 }
-// Exported so member-reader.ts (ctx.queryAsMember) can reach the registered
+// Exported so member-reader.ts (ctx.dispatch.queryAsMember) can reach the registered
 // PrincipalStatusPlugin's resolveProfile without duplicating this lookup.
 export function resolvePrincipalPlugin(registry) {
     const usages = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS);
@@ -84,7 +85,10 @@ function isTeardownRejected(status, policy) {
 }
 // Order is load-bearing: a non-member must never learn a foreign tenant's
 // lifecycle/blocked state, so membership is resolved and checked FIRST.
-export async function resolveActiveMembershipFn(ctx, userId, tenantId, policy) {
+export function resolveActiveMembershipFn(ctx, userId, tenantId, policy) {
+    return runInSystemRowLevelSecurityScope("active membership lookup runs before the request tenant is established", () => resolveActiveMembershipInScope(ctx, userId, tenantId, policy));
+}
+async function resolveActiveMembershipInScope(ctx, userId, tenantId, policy) {
     const { registry } = ctx;
     const membership = await findMembership(ctx, userId, tenantId);
     if (!membership) {

package/dist/pipeline/after-rollback-sink.d.ts

@@ -0,0 +1,6 @@
+import type { createFallbackLogger } from "../logging/utils.ts";
+import type { AfterCommitHook } from "./dispatcher-utils.ts";
+export type AfterRollbackHook = () => Promise<void>;
+export declare function afterRollbackHooksOf(commitSink: AfterCommitHook[]): AfterRollbackHook[];
+export declare function carrySavepointRollbackHooks(innerCommitSink: AfterCommitHook[], outerCommitSink: AfterCommitHook[], savepointRolledBack: boolean): void;
+export declare function flushAfterRollback(commitSink: AfterCommitHook[], logError: Pick<ReturnType<typeof createFallbackLogger>, "error">): Promise<void>;

package/dist/pipeline/after-rollback-sink.js

@@ -0,0 +1,32 @@
+// Side channel keyed by the afterCommit sink array, so executeWrite and friends keep their signatures.
+// Invariant: every registration runs at most once, and only if the work it compensates was discarded.
+const rollbackSinks = new WeakMap();
+export function afterRollbackHooksOf(commitSink) {
+    const existing = rollbackSinks.get(commitSink);
+    if (existing)
+        return existing;
+    const created = [];
+    rollbackSinks.set(commitSink, created);
+    return created;
+}
+// A rolled-back savepoint is not compensated immediately: the compensation could wait on locks of
+// the still-open outer transaction. It runs once after that transaction ends, via the commit sink
+// on commit or the rollback sink on rollback.
+export function carrySavepointRollbackHooks(innerCommitSink, outerCommitSink, savepointRolledBack) {
+    const innerHooks = rollbackSinks.get(innerCommitSink) ?? [];
+    if (innerHooks.length > 0) {
+        if (savepointRolledBack)
+            outerCommitSink.push(...innerHooks);
+        afterRollbackHooksOf(outerCommitSink).push(...innerHooks);
+    }
+}
+export async function flushAfterRollback(commitSink, logError) {
+    const hooks = rollbackSinks.get(commitSink) ?? [];
+    const outcomes = await Promise.allSettled(hooks.map((hook) => hook()));
+    for (const outcome of outcomes) {
+        if (outcome.status === "rejected") {
+            const detail = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            logError.error("afterRollback hook failed", { error: detail });
+        }
+    }
+}

package/dist/pipeline/append-event-core.d.ts

@@ -1,5 +1,6 @@
+import type { AppendEventArgs } from "@cosmicdrift/kumiko-types/handlers";
 import type { DbRunner } from "../db/connection.ts";
-import type { AppendEventArgs, Registry, TenantId } from "../engine/types/index.ts";
+import type { Registry, TenantId } from "../engine/types/index.ts";
 import { type StoredEvent } from "../event-store/event-store.ts";
 export type AppendDomainEventCoreDeps = {
     readonly registry: Registry;

package/dist/pipeline/append-event-core.js

@@ -63,7 +63,7 @@ export async function appendDomainEventCore(deps, args) {
         throw new ArchivedStreamError(deps.tenantId, args.aggregateId);
     }
     // Stream-version authoritative. See Block 0 / getStreamVersion doc for
-    // why row.version isn't sufficient once ctx.appendEvent enters the picture.
+    // why row.version isn't sufficient once ctx.events.append enters the picture.
     // A caller-pinned version (fetchForWriting handles) must reach append() so a
     // write landing between fetch and append conflicts instead of being re-read.
     const expectedVersion = args.expectedVersion ?? (await getStreamVersion(deps.db, args.aggregateId, deps.tenantId));
@@ -91,7 +91,7 @@ export async function appendDomainEventCore(deps, args) {
     });
     // Inline projections fire in the same tx — a throw rolls everything back
     // together. Same semantics regardless of which call-site triggered the
-    // append (write-handler ctx.appendEvent vs. MSP-apply ctx.appendEvent).
+    // append (write-handler ctx.events.append vs. MSP-apply ctx.appendEvent).
     await runProjectionsForEvent(stored, deps.registry, deps.db);
     return stored;
 }

package/dist/pipeline/attach-outside-transaction.d.ts

@@ -0,0 +1,3 @@
+export declare function attachOutsideTransaction<T extends object, O extends object | undefined>(db: T, outsideTransaction: O): T & {
+    readonly outsideTransaction: O;
+};

package/dist/pipeline/attach-outside-transaction.js

@@ -0,0 +1,13 @@
+// TenantDb identity keys WeakMaps (rebinders, personal-data gates), so the exposed db is never
+// wrapped or spread; the non-enumerable property keeps spreads and logging of the db unchanged.
+function defineOutsideTransaction(db, outsideTransaction) {
+    Object.defineProperty(db, "outsideTransaction", {
+        value: outsideTransaction,
+        enumerable: false,
+        configurable: true,
+    });
+}
+export function attachOutsideTransaction(db, outsideTransaction) {
+    defineOutsideTransaction(db, outsideTransaction);
+    return db;
+}

package/dist/pipeline/auth-claims-resolver.d.ts

@@ -1,4 +1,5 @@
-import type { AuthClaimsContext, AuthClaimsHookDef, SessionUser } from "../engine/types/index.ts";
+import type { AuthClaimsContext, AuthClaimsHookDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { SessionUser } from "../engine/types/index.ts";
 import type { Logger } from "../logging/types.ts";
 export type ResolveAuthClaimsArgs = {
     readonly user: SessionUser;

package/dist/pipeline/cascade-handler.d.ts

@@ -1,5 +1,6 @@
+import type { PreDeleteHookFn } from "@cosmicdrift/kumiko-types/hooks";
 import type { TableColumns } from "../db/dialect.ts";
-import type { PreDeleteHookFn, Registry } from "../engine/types/index.ts";
+import type { Registry } from "../engine/types/index.ts";
 import type { SystemHookDef } from "./lifecycle-pipeline.ts";
 type TableMap = ReadonlyMap<string, TableColumns>;
 export declare function createCascadeDeleteHook(registry: Registry, tables: TableMap): SystemHookDef<PreDeleteHookFn>;

package/dist/pipeline/cascade-handler.js

@@ -4,7 +4,8 @@ import { isBoundTenantDb } from "../db/tenant-db-runner.js";
 import { OnDeleteStrategies, SystemHookNames, SystemHookPriorities } from "../engine/constants.js";
 import { isRecordLocked } from "../engine/screen-helpers.js";
 import { createSystemUser } from "../engine/system-user.js";
-import { ConflictError, FrameworkReasons, InternalError, RecordLockedError, reraiseAsKumikoError, } from "../errors/index.js";
+import { RecordLockedError } from "../errors/classes.js";
+import { ConflictError, FrameworkReasons, InternalError, reraiseAsKumikoError, } from "../errors/index.js";
 // The cascade is a consequence of the parent delete the caller was already authorized for, so the
 // children are written as the framework system user and the lock decision is taken once, up front.
 const CASCADE_CHILD_WRITE_OPTIONS = { unsafeSkipLockGuard: true };
@@ -18,7 +19,7 @@ export function createCascadeDeleteHook(registry, tables) {
                 ? ctx.systemDb.acknowledgeCrossTenant(`cascade delete for r.systemScope() write handler (${entityName ?? "unknown"})`)
                 : ctx.db;
             if (!entityName || !db) {
-                ctx.log?.debug(`cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`);
+                ctx.obs.log?.debug(`cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`);
                 return;
             }
             const writeDb = isBoundTenantDb(db) ? db : undefined;

package/dist/pipeline/config-accessor-factory.d.ts

@@ -1,3 +1,3 @@
 import type { ConfigAccessorFactory } from "@cosmicdrift/kumiko-types/config";
 import type { AppContext } from "@cosmicdrift/kumiko-types/handlers";
-export declare function configAccessorFactoryOf(context: Pick<AppContext, "configAccessorFactory" | "_configAccessorFactory">): ConfigAccessorFactory | undefined;
+export declare function configAccessorFactoryOf(context: Pick<AppContext, "configAccessorFactory">): ConfigAccessorFactory | undefined;

package/dist/pipeline/config-accessor-factory.js

@@ -1,3 +1,3 @@
 export function configAccessorFactoryOf(context) {
-    return context.configAccessorFactory ?? context._configAccessorFactory;
+    return context.configAccessorFactory;
 }

package/dist/pipeline/context-services.d.ts

@@ -0,0 +1,56 @@
+import type { AppContext, ContextServices } from "../engine/types/index.ts";
+type ServiceKey = Exclude<keyof ContextServices, "extensions">;
+export declare const APP_CONTEXT_KEY_ROLES: {
+    readonly redis: "service";
+    readonly cacheSync: "service";
+    readonly jobRunner: "service";
+    readonly searchAdapter: "service";
+    readonly entityCache: "service";
+    readonly secrets: "service";
+    readonly kms: "service";
+    readonly files: "service";
+    readonly derivatives: "service";
+    readonly configResolver: "service";
+    readonly configEncryption: "service";
+    readonly rateLimit: "service";
+    readonly effectiveFeatures: "service";
+    readonly masterKeyProvider: "service";
+    readonly _fileProviderResolver: "service";
+    readonly _notifyFactory: "service";
+    readonly _notifyInTransactionFactory: "service";
+    readonly _notifyAfterCommitFactory: "service";
+    readonly _escapeHatchAuditSink: "service";
+    readonly db: "wiring";
+    readonly systemDb: "wiring";
+    readonly registry: "wiring";
+    readonly systemUser: "wiring";
+    readonly log: "wiring";
+    readonly triggeredBy: "wiring";
+    readonly triggerName: "wiring";
+    readonly geoTzProvider: "wiring";
+    readonly clock: "wiring";
+    readonly _tenantId: "wiring";
+    readonly defaultLocale: "wiring";
+    readonly configAccessorFactory: "wiring";
+    readonly _rateLimitPayloadDigest: "wiring";
+    readonly tracer: "wiring";
+    readonly meter: "wiring";
+    readonly config: "wiring";
+    readonly configFor: "wiring";
+    readonly forTenant: "wiring";
+    readonly notify: "wiring";
+    readonly signal: "wiring";
+    readonly scheduleAfterCommit: "wiring";
+    readonly scheduleAfterRollback: "wiring";
+};
+type ServiceRoleKey = {
+    [Key in keyof typeof APP_CONTEXT_KEY_ROLES]: (typeof APP_CONTEXT_KEY_ROLES)[Key] extends "service" ? Key : never;
+}[keyof typeof APP_CONTEXT_KEY_ROLES];
+type IsSame<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
+type MustBeTrue<Value extends true> = Value;
+export type ServiceRolesMatchContextServices = MustBeTrue<IsSame<ServiceRoleKey, ServiceKey>>;
+export type ContextServiceOverrides = {
+    -readonly [Key in ServiceKey]?: ContextServices[Key];
+};
+export declare function buildContextServices(context: AppContext, overrides?: ContextServiceOverrides): ContextServices;
+export {};

package/dist/pipeline/context-services.js

@@ -0,0 +1,73 @@
+// Every AppContext key is either a service a handler or job may use, or boot wiring the framework
+// consumes itself. The satisfies clause makes a new AppContext key a compile error until it is classified.
+export const APP_CONTEXT_KEY_ROLES = {
+    redis: "service",
+    cacheSync: "service",
+    jobRunner: "service",
+    searchAdapter: "service",
+    entityCache: "service",
+    secrets: "service",
+    kms: "service",
+    files: "service",
+    derivatives: "service",
+    configResolver: "service",
+    configEncryption: "service",
+    rateLimit: "service",
+    effectiveFeatures: "service",
+    masterKeyProvider: "service",
+    _fileProviderResolver: "service",
+    _notifyFactory: "service",
+    _notifyInTransactionFactory: "service",
+    _notifyAfterCommitFactory: "service",
+    _escapeHatchAuditSink: "service",
+    db: "wiring",
+    systemDb: "wiring",
+    registry: "wiring",
+    systemUser: "wiring",
+    log: "wiring",
+    triggeredBy: "wiring",
+    triggerName: "wiring",
+    geoTzProvider: "wiring",
+    clock: "wiring",
+    _tenantId: "wiring",
+    defaultLocale: "wiring",
+    configAccessorFactory: "wiring",
+    _rateLimitPayloadDigest: "wiring",
+    tracer: "wiring",
+    meter: "wiring",
+    config: "wiring",
+    configFor: "wiring",
+    forTenant: "wiring",
+    notify: "wiring",
+    signal: "wiring",
+    scheduleAfterCommit: "wiring",
+    scheduleAfterRollback: "wiring",
+};
+function isAppContextKey(key) {
+    return Object.hasOwn(APP_CONTEXT_KEY_ROLES, key);
+}
+function isServiceKey(key) {
+    return isAppContextKey(key) && APP_CONTEXT_KEY_ROLES[key] === "service";
+}
+// The dispatcher binds these two to one call's transaction; a factory inherited from an outer
+// context must not leak into a context that has none of its own.
+const PER_CALL_FACTORY_KEYS = new Set([
+    "_notifyInTransactionFactory",
+    "_notifyAfterCommitFactory",
+]);
+function copyService(target, source, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}
+const SERVICE_KEYS = Object.keys(APP_CONTEXT_KEY_ROLES).filter(isServiceKey);
+export function buildContextServices(context, overrides = {}) {
+    const services = {};
+    for (const key of SERVICE_KEYS) {
+        if (!PER_CALL_FACTORY_KEYS.has(key))
+            copyService(services, context, key);
+        copyService(services, overrides, key);
+    }
+    const extensions = Object.fromEntries(Object.entries(context).filter(([key]) => key !== "services" && !isAppContextKey(key)));
+    return { ...services, extensions };
+}

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

@@ -1,5 +1,6 @@
 import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
-import type { SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
+import type { SessionUser } from "../engine/types/index.ts";
 import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.ts";
 export declare function runBatch(ctx: DispatchContext, commands: readonly BatchCommand[], user: SessionUser, requestId?: string, inheritedOrigin?: WriteOrigin): Promise<BatchResult>;
 export declare function unwrapSingle(batchResult: BatchResult): WriteResult;

package/dist/pipeline/dispatch-batch.js

@@ -1,9 +1,13 @@
-import { requestContext, runWithWriteOrigin } from "../api/request-context.js";
+import { requestContext } from "../api/request-context.js";
+import { runWithWriteOrigin } from "../api/request-context-scopes.js";
 import { transaction } from "../db/query.js";
-import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { toWriteErrorInfo } from "../errors/write-error-info.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
-import { resolveAppPoolDb } from "./dispatch-shared.js";
+import { flushAfterRollback } from "./after-rollback-sink.js";
+import { runInDispatchScope } from "./dispatch-scope.js";
+import { buildHandlerContext, resolveAppPoolDb } from "./dispatch-shared.js";
 import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
@@ -32,10 +36,13 @@ async function runReservedCommand(scope, cmd, index, tx) {
     const hookStart = afterCommitHooks.length;
     // 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)));
+    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => runInDispatchScope(ctx.registry, [cmd.type], user, () => execute(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks))));
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }
+function rollbackLogger(scope) {
+    return createFallbackLogger("dispatcher", scope.ctx.appContext.log);
+}
 // 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) {
@@ -50,12 +57,14 @@ async function runCommandsWithoutTransaction(scope, commands, results) {
                 // No tx means no rollback — but we still drop afterCommit hooks,
                 // matching the semantic "failure = side-effects don't fire".
                 await scope.reservations.releaseAll();
+                await flushAfterRollback(scope.afterCommitHooks, rollbackLogger(scope));
                 return { index: i, error: res.error };
             }
         }
     }
     catch (e) {
         await scope.reservations.releaseAll();
+        await flushAfterRollback(scope.afterCommitHooks, rollbackLogger(scope));
         throw e;
     }
     return undefined;
@@ -63,14 +72,16 @@ async function runCommandsWithoutTransaction(scope, commands, results) {
 // 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) {
-    const current = requestContext.get();
-    if (!current?.signal) {
-        return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
-    }
-    // Strip the signal: a client disconnect must not roll back a write whose
-    // afterCommit effects would then be lost.
-    const { signal: _signal, ...withoutSignal } = current;
-    return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
+    return runInDispatchScope(ctx.registry, commands.map((command) => command.type), user, () => {
+        const current = requestContext.get();
+        if (!current?.signal) {
+            return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
+        }
+        // Strip the signal: a client disconnect must not roll back a write whose
+        // afterCommit effects would then be lost.
+        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));
@@ -96,6 +107,7 @@ async function checkBatchIdempotency(ctx, user, requestId) {
     // corrupted cache entry — treat as miss, let the request re-run
     return parsed ? { cached: parsed } : {};
 }
+const BATCH_HOOKS_CONTEXT_TYPE = "dispatcher:batch-hooks";
 async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     const { idempotency, lifecycle, appContext: context } = ctx;
     if (commands.length === 0) {
@@ -157,7 +169,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // Fires the batch-level system hooks with every successful save/delete
     // context from this run. Called after flushAfterCommit so per-save hooks
     // have all completed first; errors are isolated inside lifecycleHooks.
-    const flushBatchHooksInner = async () => {
+    const flushBatchHooksInner = async (origin) => {
         try {
             const saves = [];
             const deletes = [];
@@ -171,10 +183,17 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
                 else if (r.data.kind === "delete")
                     deletes.push(r.data);
             }
-            if (saves.length > 0 && lifecycle)
-                await lifecycle.runPostSaveBatch(saves, context);
-            if (deletes.length > 0 && lifecycle)
-                await lifecycle.runPostDeleteBatch(deletes, context);
+            // skip: nothing to flush when there are no lifecycle hooks or no successful save/delete
+            if (!lifecycle || (saves.length === 0 && deletes.length === 0))
+                return;
+            // Post-commit context: batch hooks may write, but nothing is left to roll back.
+            const hookContext = await buildHandlerContext(ctx, BATCH_HOOKS_CONTEXT_TYPE, user, origin, {
+                transactionScope: "postCommit",
+            });
+            if (saves.length > 0)
+                await lifecycle.runPostSaveBatch(saves, hookContext);
+            if (deletes.length > 0)
+                await lifecycle.runPostDeleteBatch(deletes, hookContext);
         }
         catch (e) {
             // Batch hooks must never fail the batch — the commit already happened.
@@ -190,7 +209,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         // skip: no command ran, so batch hooks have no saves or deletes to see
         if (!strictest)
             return;
-        await runWithWriteOrigin(strictest, flushBatchHooksInner);
+        await runWithWriteOrigin(strictest, () => flushBatchHooksInner(strictest));
     };
     const perCommandRejection = perCommandBatchRejection(ctx, commands);
     if (perCommandRejection)
@@ -208,7 +227,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         }, reservations.error.httpStatus >= 500);
     }
     // batch() opens its own outer transaction — needs the top-level
-    // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+    // connection's `.begin()` (a transaction handle cannot begin another one).
     const db = resolveAppPoolDb(ctx);
     if (!db || runsWithoutTransaction) {
         // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
@@ -250,6 +269,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         // 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();
+        await flushAfterRollback(afterCommitHooks, createFallbackLogger("dispatcher", context.log));
         if (e instanceof BatchRollback) {
             // Thrown inside the callback, so the tx rolled back. A 4xx is
             // deterministic and stays cached; a 5xx may be transient.

package/dist/pipeline/dispatch-query.js

@@ -4,15 +4,16 @@ import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
-import { assertNoSecretLeak } from "../secrets/index.js";
+import { assertNoSecretLeak } from "../secrets/leak-guard.js";
+import { runInDispatchScope } from "./dispatch-scope.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
 import { handlerAccessError } from "./handler-access-error.js";
 import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
 // Standalone query execution — used by the public dispatcher.query() and
-// by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
+// by ctx.dispatch.query/ctx.dispatch.queryAs inside handlers. Runs the handler, applies
 // field-level read filters for the given user, logs the event.
 export async function executeQuery(ctx, type, payload, user, origin, tx, outerNotifySink) {
-    return runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink));
+    return runInDispatchScope(ctx.registry, [type], user, () => runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink)));
 }
 async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink) {
     const { registry } = ctx;
@@ -52,7 +53,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNoti
     // so other handlers never see the flag. Visibility filters still apply
     // downstream (see HandlerContext.includeDeleted) — safe from raw input.
     const includeDeleted = propertyOf(parsed.data, "includeDeleted") === true;
-    // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
+    // A resolved member (ctx.dispatch.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
     return isMemberResolutionPrincipal(user)
         ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))
         : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx, outerNotifySink);

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

@@ -0,0 +1,6 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-types/handlers";
+import { type RowLevelSecurityScope } from "../db/row-level-security-scope.ts";
+import type { Registry } from "../engine/types/index.ts";
+export declare function dispatchRowLevelSecurityScope(registry: Registry, types: readonly string[], user: SessionUser): RowLevelSecurityScope;
+export declare function runInDispatchScope<T>(registry: Registry, types: readonly string[], user: SessionUser, fn: () => T): T;
+export declare function streamInDispatchScope<T>(scope: RowLevelSecurityScope, source: AsyncGenerator<T>): AsyncGenerator<T>;