@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/pipeline/handler-context-events.js

@@ -0,0 +1,237 @@
+import { runInSavepoint, selectMany } from "../db/query.js";
+import { hasTenantColumn } from "../db/tenant-db.js";
+import { InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } 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 { 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 { appendDomainEventCore } from "./append-event-core.js";
+import { isMemberResolutionPrincipal, resolveDbSource, } from "./dispatch-shared.js";
+import { createGatedProjectionReader } from "./system-identity-switch.js";
+function requireDbSource(ctx, tx, surfaceCall) {
+    const dbSource = resolveDbSource(ctx, tx);
+    if (!dbSource) {
+        throw new InternalError({
+            message: `${surfaceCall} requires a database connection — none is configured.`,
+        });
+    }
+    return dbSource;
+}
+// ctx.appendEvent — append a domain event onto a specific aggregate stream
+// in the current tx, then fire matching inline projections. Core logic
+// lives in appendDomainEventCore; this wrapper just locates dbSource +
+// stringifies the SessionUser id for the shared helper.
+async function appendDomainEvent(ctx, args, user, tx, callerFeature) {
+    // Sink behind every append surface, so a resolved member stays read-only even via fetchForWriting handles.
+    if (isMemberResolutionPrincipal(user))
+        throw memberResolutionReadOnlyDenied();
+    const { registry } = ctx;
+    const dbSource = requireDbSource(ctx, tx, `ctx.appendEvent("${args.type}")`);
+    await appendDomainEventCore({
+        registry,
+        db: dbSource,
+        tenantId: user.tenantId,
+        userId: String(user.id),
+        callSiteLabel: "ctx.appendEvent",
+        callerFeature,
+    }, args);
+}
+// Savepoint-scoped append: catches a losing writer's VersionConflictError
+// without poisoning the rest of the handler's transaction. postgres.js
+// aborts the WHOLE begin() on an uncaught statement error
+// (SQLSTATE 25P02) even if the JS error is caught — runInSavepoint
+// wraps the append in a real SAVEPOINT so only that nested scope rolls
+// back on conflict, and subsequent statements in the outer tx (e.g. a
+// dedup-anchor insert) still succeed. Use when a handler must react to
+// losing a concurrent-append race instead of failing the whole write.
+function buildTryAppendEvent(scope) {
+    const { type, user, tx, registry } = scope;
+    return async (args) => {
+        if (!tx) {
+            throw new InternalError({
+                message: `ctx.tryAppendEvent("${args.type}") requires an active transaction — no tx is threaded through this call.`,
+            });
+        }
+        try {
+            const event = await runInSavepoint(tx, (sp) => appendDomainEventCore({
+                registry,
+                db: sp,
+                tenantId: user.tenantId,
+                userId: String(user.id),
+                callSiteLabel: "ctx.tryAppendEvent",
+                callerFeature: registry.getHandlerFeature(type),
+            }, args));
+            return { ok: true, event };
+        }
+        catch (e) {
+            if (e instanceof EventStoreVersionConflictError) {
+                return { ok: false, conflict: e };
+            }
+            if (e instanceof EventStoreIdempotentAppendConflictError) {
+                return { ok: false, conflict: e };
+            }
+            throw e;
+        }
+    };
+}
+function buildFetchForWriting(scope) {
+    const { ctx, type, user, tx, registry } = scope;
+    return async (args) => {
+        const dbSource = requireDbSource(ctx, tx, `ctx.fetchForWriting("${args.aggregateId}")`);
+        // 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,
+        });
+        // Optimistic concurrency: if the caller knows the version they
+        // worked against (e.g. from a prior read-model row) and the stream
+        // has moved on, fail fast before any downstream work.
+        if (args.expectedVersion !== undefined && args.expectedVersion !== fetchedVersion) {
+            throw new VersionConflictError({
+                entityId: args.aggregateId,
+                expectedVersion: args.expectedVersion,
+                currentVersion: fetchedVersion,
+            });
+        }
+        // Pinned into every append: a write landing between fetch and append
+        // fails with VersionConflictError instead of stacking on a state the
+        // caller's business rules never saw. Bumps per appendOne so consecutive
+        // appends stay in order without re-reading the DB.
+        let handleVersion = fetchedVersion;
+        const appendOne = async (appendArgs) => {
+            await appendDomainEvent(ctx, {
+                aggregateId: args.aggregateId,
+                aggregateType: args.aggregateType,
+                type: appendArgs.type,
+                payload: appendArgs.payload,
+                expectedVersion: handleVersion,
+            }, user, tx, registry.getHandlerFeature(type));
+            handleVersion += 1;
+        };
+        return {
+            events,
+            get version() {
+                return handleVersion;
+            },
+            appendOne,
+            hasEvent: (type) => events.some((e) => e.type === type),
+        };
+    };
+}
+function buildLoadAggregate(scope) {
+    const { ctx, user, tx, registry } = scope;
+    return async (aggregateId, loadOptions) => {
+        const dbSource = requireDbSource(ctx, tx, `ctx.loadAggregate("${aggregateId}")`);
+        const events = loadOptions?.asOf
+            ? await loadAggregateAsOf(dbSource, aggregateId, user.tenantId, loadOptions.asOf)
+            : await loadAggregate(dbSource, aggregateId, user.tenantId);
+        return upcastStoredEvents(events, registry.getEventUpcasters(), {
+            db: dbSource,
+            tenantId: user.tenantId,
+        });
+    };
+}
+function buildSnapshotAggregate(scope) {
+    const { ctx, user, tx, registry } = scope;
+    return async (snapshotArgs) => {
+        const dbSource = requireDbSource(ctx, tx, `ctx.snapshotAggregate("${snapshotArgs.aggregateId}")`);
+        await saveSnapshot(dbSource, {
+            aggregateId: snapshotArgs.aggregateId,
+            tenantId: user.tenantId,
+            aggregateType: snapshotArgs.aggregateType,
+            version: snapshotArgs.version,
+            state: snapshotArgs.state,
+            snapshotVersion: effectiveSnapshotGeneration(snapshotArgs.snapshotVersion ?? 1, registry.getEntity(snapshotArgs.aggregateType)?.eventVersion),
+        });
+    };
+}
+function buildLoadAggregateWithSnapshot(scope) {
+    const { ctx, user, tx, registry } = scope;
+    return async (aggregateId, reducer, initial, loadOptions) => {
+        const dbSource = requireDbSource(ctx, tx, `ctx.loadAggregateWithSnapshot("${aggregateId}")`);
+        // Upcaster-aware: pass an upcastEvent callback so loadAggregateWithSnapshot
+        // walks every delta through the registered chain before invoking the
+        // user's (sync) reducer. Async upcasters (DB-enrichment) are awaited
+        // inside loadAggregateWithSnapshot — feature authors never see legacy
+        // payload shapes regardless of which load path they chose.
+        const upcasters = registry.getEventUpcasters();
+        const upcastCtx = { db: dbSource, tenantId: user.tenantId };
+        return loadAggregateWithSnapshot(dbSource, aggregateId, user.tenantId, reducer, initial, {
+            ...loadOptions,
+            entityEventVersionOf: (aggregateType) => registry.getEntity(aggregateType)?.eventVersion,
+            upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx), // @wrapper-known semantic-alias
+        });
+    };
+}
+// queryProjection works against both single-stream and multi-stream
+// projections. MSPs without a table cannot be queried — those are
+// side-effect-only consumers (no state to read back).
+function buildHandlerProjectionReader(scope) {
+    const { ctx, type, user, tx, registry, hasIdentitySwitchGrant, identitySwitchAudit } = scope;
+    const findProjectionTable = (qualifiedName) => registry.getAllProjections().get(qualifiedName)?.table ??
+        registry.getAllMultiStreamProjections().get(qualifiedName)?.table;
+    const ungatedQueryProjection = async (qualifiedName, queryOptions) => {
+        const projTable = findProjectionTable(qualifiedName);
+        if (!projTable) {
+            const singleNames = [...registry.getAllProjections().keys()];
+            const mspNames = [...registry.getAllMultiStreamProjections().keys()].filter((n) => registry.getAllMultiStreamProjections().get(n)?.table);
+            const all = [...singleNames, ...mspNames];
+            throw new InternalError({
+                message: `ctx.queryProjection("${qualifiedName}") — projection not registered, or it is a ` +
+                    `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
+            });
+        }
+        const dbSource = requireDbSource(ctx, tx, `ctx.queryProjection("${qualifiedName}")`);
+        const where = hasTenantColumn(projTable) && queryOptions?.unsafeAllTenants !== true
+            ? { tenantId: user.tenantId }
+            : undefined;
+        const rows = await selectMany(dbSource, projTable, where);
+        return rows; // @cast-boundary engine-payload
+    };
+    return createGatedProjectionReader(`handler "${type}"`, hasIdentitySwitchGrant, ungatedQueryProjection, identitySwitchAudit, (qualifiedName) => {
+        const projTable = findProjectionTable(qualifiedName);
+        // Unknown projection: keep the grant check first, the ungated reader reports the real error.
+        return projTable === undefined || hasTenantColumn(projTable);
+    });
+}
+export function buildEventStoreFacet(scope) {
+    const { ctx, type, user, tx, registry } = scope;
+    return {
+        // Strict + unsafe share the same runtime — only the type-surface
+        // differs. The strict signature is what's exposed to typed callers;
+        // unsafe is the explicit escape-hatch for runtime-pluggable events.
+        appendEvent: (async (args) => {
+            await appendDomainEvent(ctx, args, user, tx, registry.getHandlerFeature(type));
+        }), // @cast-boundary engine-bridge
+        unsafeAppendEvent: async (args) => {
+            await appendDomainEvent(ctx, args, user, tx, registry.getHandlerFeature(type));
+        },
+        tryAppendEvent: buildTryAppendEvent(scope),
+        fetchForWriting: buildFetchForWriting(scope),
+        loadAggregate: buildLoadAggregate(scope),
+        archiveStream: async (aggregateId, archiveArgs) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.archiveStream("${aggregateId}")`);
+            await archiveStreamHelper(dbSource, {
+                tenantId: user.tenantId,
+                aggregateId,
+                aggregateType: archiveArgs.aggregateType,
+                archivedBy: user.id,
+                reason: archiveArgs.reason,
+            });
+        },
+        restoreStream: async (aggregateId) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.restoreStream("${aggregateId}")`);
+            await restoreStreamHelper(dbSource, user.tenantId, aggregateId);
+        },
+        isStreamArchived: async (aggregateId) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.isStreamArchived("${aggregateId}")`);
+            return isStreamArchived(dbSource, user.tenantId, aggregateId);
+        },
+        snapshotAggregate: buildSnapshotAggregate(scope),
+        loadAggregateWithSnapshot: buildLoadAggregateWithSnapshot(scope),
+        queryProjection: buildHandlerProjectionReader(scope),
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { DbConnection } from "../db/connection.ts";
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { NotifyFn, SessionUser } from "../engine/types/index.ts";
+import type { CommitSinks } from "./handler-context-dispatch.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildNotifyFacet(scope: HandlerContextScope, sinks: CommitSinks, outsideTxSource: DbConnection | undefined): {
+    notify: NotifyFn | undefined;
+    factoryFragment: {
+        _notifyInTransactionFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
+        _notifyAfterCommitFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
+    };
+};

package/dist/pipeline/handler-context-notify.js

@@ -0,0 +1,55 @@
+import { createDeferringNotify } from "./notify-scope.js";
+// DispatchContext.jobRunner is typed as the handleEvent-only JobRunnerRef but
+// holds the concrete runner at boot; narrow instead of casting.
+function isNotifyJobDispatcher(runner) {
+    return (typeof runner === "object" &&
+        runner !== null &&
+        "dispatch" in runner &&
+        typeof runner.dispatch === "function");
+}
+function buildNotify(scope, sinks, notifyAfterCommitFactory, notifyInTransactionFactory) {
+    const { user, registry } = scope;
+    if (!notifyAfterCommitFactory)
+        return undefined;
+    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. Without any commit to wait for (a
+    // post-commit context) delivery stays immediate.
+    const { notifyCommitSink } = sinks;
+    if (notifyCommitSink === undefined)
+        return notifyInTransaction;
+    return createDeferringNotify({
+        registry,
+        tenantId: user.tenantId,
+        notifyAfterCommit,
+        notifyNow: notifyInTransaction,
+        scheduleAfterCommit: (hook) => {
+            notifyCommitSink.push(hook);
+        },
+    });
+}
+export function buildNotifyFacet(scope, sinks, outsideTxSource) {
+    const { ctx, tx, context } = scope;
+    const notifyFactory = context._notifyFactory;
+    const notifyJobDispatcher = isNotifyJobDispatcher(ctx.jobRunner) ? ctx.jobRunner : undefined;
+    // Inside the write tx the app pool's slots can all be held by waiting write txs, so the
+    // delivery's own DB work (broadcast lookup, attempt log, channel sends) runs on the outside-tx pool.
+    const notifyInTransactionFactory = notifyFactory && tx !== undefined
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, outsideTxSource, context._fileProviderResolver)
+        : undefined;
+    const notifyAfterCommitFactory = notifyFactory
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, undefined, context._fileProviderResolver)
+        : undefined;
+    const notify = buildNotify(scope, sinks, notifyAfterCommitFactory, notifyInTransactionFactory);
+    return {
+        notify,
+        factoryFragment: {
+            ...(notifyInTransactionFactory && {
+                _notifyInTransactionFactory: notifyInTransactionFactory,
+            }),
+            ...(notifyAfterCommitFactory && { _notifyAfterCommitFactory: notifyAfterCommitFactory }),
+        },
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildObservabilityFacet(scope: HandlerContextScope): {
+    log: import("@cosmicdrift/kumiko-types/logger").Logger | undefined;
+    tracer: import("@cosmicdrift/kumiko-types/observability/span").Tracer;
+    metrics: import("@cosmicdrift/kumiko-types/observability/metric").MetricsHandle;
+    metricsFor: (featureName: string) => import("@cosmicdrift/kumiko-types/observability/metric").MetricsHandle;
+};

package/dist/pipeline/handler-context-observability.js

@@ -0,0 +1,21 @@
+import { createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, getFallbackTracer, } from "../observability/index.js";
+export function buildObservabilityFacet(scope) {
+    const { type, user, context, reqCtx, featureName } = scope;
+    const log = context.log?.child({
+        handler: type,
+        tenantId: user.tenantId,
+        userId: user.id,
+        ...(reqCtx && { requestId: reqCtx.requestId }),
+    });
+    // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
+    // resolves to kumiko_<feature>_foo. Unknown feature falls back to noop
+    // so legacy internal handlers don't crash.
+    const tracer = context.tracer ?? getFallbackTracer();
+    const meter = context.meter;
+    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.
+    // Unregistered names no-op rather than throw.
+    const metricsFor = createMetricsForFactory(meter);
+    return { log, tracer, metrics, metricsFor };
+}

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

@@ -0,0 +1,48 @@
+import { type EscapeHatchDeclaration, type EscapeHatchReporter } from "@cosmicdrift/kumiko-types/handlers";
+import { type RequestContextData } from "../api/request-context.ts";
+import type { DbConnection, DbTx } from "../db/connection.ts";
+import type { AppContext, Registry, SessionUser } from "../engine/types/index.ts";
+import { type DispatchContext, type HandlerTransactionScope } from "./dispatch-shared.ts";
+import type { WriteOrigin } from "./write-origin.ts";
+export type HandlerContextScope = {
+    readonly ctx: DispatchContext;
+    readonly type: string;
+    readonly user: SessionUser;
+    readonly origin: WriteOrigin;
+    readonly tx: DbTx | undefined;
+    readonly transactionScope: HandlerTransactionScope;
+    readonly registry: Registry;
+    readonly context: AppContext;
+    readonly isSystem: boolean;
+    readonly dbSource: DbConnection | DbTx | undefined;
+    readonly reqCtx: RequestContextData | undefined;
+    readonly writeEscapeHatch: EscapeHatchDeclaration | undefined;
+    readonly handlerEscapeHatch: EscapeHatchDeclaration | undefined;
+    readonly isWriteHandler: boolean;
+    readonly isPerCommand: boolean;
+    readonly denyDbWrites: boolean;
+    readonly featureName: string | undefined;
+    readonly hasIdentitySwitchGrant: boolean;
+    readonly reportEscapeHatch: EscapeHatchReporter;
+    readonly identitySwitchAudit: {
+        readonly reason: string | undefined;
+        readonly report: EscapeHatchReporter;
+    };
+};
+export declare function resolveHandlerContextScope(input: {
+    readonly ctx: DispatchContext;
+    readonly type: string;
+    readonly user: SessionUser;
+    readonly origin: WriteOrigin;
+    readonly tx: DbTx | undefined;
+    readonly transactionScope: HandlerTransactionScope;
+}): HandlerContextScope;
+export declare function buildPreSaveFragment(scope: HandlerContextScope): {
+    runPreSave?: ((handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>) | undefined;
+};
+export declare function buildRuntimeFragment(scope: HandlerContextScope): {
+    signal?: AbortSignal | undefined;
+    effectiveFeatures?: import("@cosmicdrift/kumiko-framework/engine").EffectiveFeaturesResolver | undefined;
+    cacheSync?: import("@cosmicdrift/kumiko-types/cache-sync-types").CacheSyncBus | undefined;
+    jobRunner?: import("@cosmicdrift/kumiko-types/handlers").JobRunnerRef | undefined;
+};

package/dist/pipeline/handler-context-scope.js

@@ -0,0 +1,88 @@
+import { escapeHatchFor, } from "@cosmicdrift/kumiko-types/handlers";
+import { requestContext } from "../api/request-context.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { createEscapeHatchReporter } from "../observability/index.js";
+import { resolveDbSource, } from "./dispatch-shared.js";
+export function resolveHandlerContextScope(input) {
+    const { ctx, type, user, origin, tx, transactionScope } = input;
+    const { registry, appContext: context } = ctx;
+    const isSystem = registry.isHandlerSystemScoped(type);
+    // The outer dispatcher receives a DbConnection from the server/stack;
+    // AppContext's `db` union also allows TenantDb (for downstream hook calls),
+    // but at this point we're the root of the pipeline — cast is safe.
+    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 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;
+    const identitySwitchEscapeHatch = escapeHatchFor(handlerEscapeHatch, "systemIdentity");
+    const hasIdentitySwitchGrant = isSystem || identitySwitchEscapeHatch !== undefined;
+    const featureName = registry.getHandlerFeature(type);
+    const reportEscapeHatch = createEscapeHatchReporter({
+        handler: type,
+        tenantId: user.tenantId,
+        actor: user.id,
+        sink: context._escapeHatchAuditSink,
+        log: context.log ?? createFallbackLogger("dispatcher"),
+        window: ctx.escapeHatchReportWindow,
+        meter: context.meter,
+    });
+    const identitySwitchGrantReason = identitySwitchEscapeHatch?.reason ??
+        (isSystem ? `r.systemScope() feature "${featureName ?? "unknown"}"` : undefined);
+    return {
+        ctx,
+        type,
+        user,
+        origin,
+        tx,
+        transactionScope,
+        registry,
+        context,
+        isSystem,
+        dbSource,
+        reqCtx,
+        writeEscapeHatch,
+        handlerEscapeHatch,
+        isWriteHandler: writeHandler !== undefined,
+        isPerCommand,
+        denyDbWrites,
+        featureName,
+        hasIdentitySwitchGrant,
+        reportEscapeHatch,
+        identitySwitchAudit: { reason: identitySwitchGrantReason, report: reportEscapeHatch },
+    };
+}
+// preSave hooks need `changes`/`previous`/`isNew`, which only exist once
+// a handler actually starts building its write — bound here so entity
+// CRUD handlers (entity-handlers.ts) can forward it to the executor.
+export function buildPreSaveFragment(scope) {
+    const { lifecycle } = scope.ctx;
+    return {
+        ...(lifecycle && {
+            runPreSave: (handlerName, changes, previous, isNew) => lifecycle.runPreSave(handlerName, changes, previous, isNew, scope.context),
+        }),
+    };
+}
+export function buildRuntimeFragment(scope) {
+    const { ctx, reqCtx } = scope;
+    const { effectiveFeatures, jobRunner } = ctx;
+    return {
+        // Cancellation signal flows from the HTTP middleware via
+        // requestContext. Conditional spread so non-HTTP entry-points
+        // (jobs, dispatcher MSP-applies) don't get a phantom signal that
+        // would always read aborted=false but feel meaningful.
+        ...(reqCtx?.signal ? { signal: reqCtx.signal } : {}),
+        // Propagate the feature-toggle resolver so the lifecycle pipeline,
+        // MSP runner, and ctx.hasFeature all pull from the same source.
+        ...(effectiveFeatures && { effectiveFeatures }),
+        ...(ctx.cacheSync && { cacheSync: ctx.cacheSync }),
+        // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
+        // as a follow-up job would (test-stack.ts wires the matching runner).
+        ...(jobRunner && { jobRunner }),
+    };
+}

package/dist/pipeline/notify-scope.js

@@ -1,5 +1,6 @@
 import { assertNotificationVariables } from "../engine/template-variables.js";
 import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+import { parseJsonOrThrow } from "../utils/safe-json.js";
 function isTenantBroadcast(to) {
     return typeof to === "object" && to !== null && !Array.isArray(to) && "tenant" in to;
 }
@@ -12,6 +13,16 @@ export function assertNotifyTargetsOwnTenant(options, tenantId) {
         });
     }
 }
+// Temporal values, functions and class instances in `data` are not structured-cloneable; the
+// job pipeline serializes them to JSON on enqueue anyway, so the JSON form is the faithful snapshot.
+function snapshotNotifyOptions(options) {
+    try {
+        return structuredClone(options);
+    }
+    catch {
+        return parseJsonOrThrow(JSON.stringify(options), "notify options snapshot");
+    }
+}
 // Without `immediate`, a notify inside a write transaction waits for the commit so a
 // rolled-back write leaves no notification behind.
 export function createDeferringNotify(deps) {
@@ -24,7 +35,7 @@ export function createDeferringNotify(deps) {
         if (options.immediate === true)
             return notifyNow(notificationType, options);
         // The hook runs after the handler returned; a caller reusing `data` meanwhile must not change what is sent.
-        const optionsAtCallTime = structuredClone(options);
+        const optionsAtCallTime = snapshotNotifyOptions(options);
         scheduleAfterCommit(async () => {
             await notifyAfterCommit(notificationType, optionsAtCallTime);
         });

package/dist/pipeline/pre-handler-gates.js

@@ -2,16 +2,17 @@ import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { checkWriteFieldRoles } from "../engine/field-access.js";
 import { runValidation } from "../engine/validation.js";
-import { AccessDeniedError, FrameworkReasons, isKumikoError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
+import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, ValidationError, validationErrorFromZod, writeFailure, } from "../errors/index.js";
 import { checkFeatureEnabled, enforcePayloadRateLimits, enforceRateLimit, } from "./dispatch-shared.js";
 import { handlerAccessError } from "./handler-access-error.js";
 async function rejectDisabledFeature(ctx, type, user) {
     const disabledErr = await checkFeatureEnabled(ctx, type, user.tenantId);
     return disabledErr ? writeFailure(disabledErr) : undefined;
 }
-async function rejectRateLimited(ctx, handler, type, user) {
+async function rejectRateLimited(ctx, handler, type, user, resolveCostOverride) {
     try {
-        await enforceRateLimit(ctx, handler.rateLimit, type, user, ctx.registry.isHandlerSystemScoped(type));
+        const costOverride = resolveCostOverride?.();
+        await enforceRateLimit(ctx, handler.rateLimit, type, user, ctx.registry.isHandlerSystemScoped(type), costOverride);
     }
     catch (e) {
         if (isKumikoError(e))
@@ -20,6 +21,14 @@ async function rejectRateLimited(ctx, handler, type, user) {
     }
     return undefined;
 }
+function normalizeRateLimitCost(handlerName, cost) {
+    if (!Number.isFinite(cost)) {
+        throw new InternalError({
+            message: `Handler "${handlerName}" rateLimitCost returned ${cost}; expected a finite number.`,
+        });
+    }
+    return Math.max(1, Math.ceil(cost));
+}
 async function rejectPayloadRateLimited(ctx, handler, type, user, payload) {
     try {
         await enforcePayloadRateLimits(ctx, handler.additionalRateLimits, type, user, payload);
@@ -70,7 +79,7 @@ async function rejectBeforeParse(ctx, handler, type, user, mode) {
     const disabled = await rejectDisabledFeature(ctx, type, user);
     if (disabled)
         return disabled;
-    if (mode === "charge") {
+    if (mode === "charge" && !handler.rateLimitCost) {
         const rateLimited = await rejectRateLimited(ctx, handler, type, user);
         if (rateLimited)
             return rateLimited;
@@ -85,6 +94,13 @@ async function rejectAfterParse(ctx, handler, type, user, payload, mode) {
     const overrideDenied = tenantOverrideDenied(user, payload);
     if (overrideDenied)
         return writeFailure(overrideDenied);
+    if (mode === "charge" && handler.rateLimitCost) {
+        // Cost comes from the validated payload, so this bucket is billed after the parse instead of before it.
+        const { rateLimitCost } = handler;
+        const rateLimited = await rejectRateLimited(ctx, handler, type, user, () => normalizeRateLimitCost(type, rateLimitCost(payload)));
+        if (rateLimited)
+            return rateLimited;
+    }
     if (mode === "charge") {
         const rateLimited = await rejectPayloadRateLimited(ctx, handler, type, user, payload);
         if (rateLimited)

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

@@ -7,6 +7,7 @@ type ReservationConfirm = ReservationHandle["confirmInTransaction"];
 export type ConsumedReservation = {
     readonly confirmInTransaction: ReservationConfirm | undefined;
     readonly prepared: unknown;
+    readonly parsedPayload: unknown;
 };
 export declare function hasPreTransactionPhase(handler: WriteHandlerDef): boolean;
 export declare function runAsCommand<T>(reserved: {

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

@@ -62,10 +62,10 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
                 return { isSuccess: false, error: gates.error, failedIndex: index };
             }
             const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, command.type, user), inheritedOrigin);
-            const handlerContext = await buildHandlerContext(ctx, command.type, user, origin);
             const event = { type: command.type, payload: gates.payload, user };
             let confirmInTransaction;
             if (handler.reserveBeforeTransaction) {
+                const handlerContext = await buildHandlerContext(ctx, command.type, user, origin);
                 const handle = toReservationHandle(await handler.reserveBeforeTransaction(event, denyTransactionBoundSurfaces(handlerContext)));
                 if (handle)
                     releases.push(handle.release);
@@ -73,7 +73,9 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
             }
             let prepared;
             if (handler.beforeTransaction) {
-                const phaseContext = await buildHandlerContext(ctx, command.type, user, origin, undefined, undefined, undefined, undefined, undefined, true);
+                const phaseContext = await buildHandlerContext(ctx, command.type, user, origin, {
+                    readOnlyForTenant: true,
+                });
                 const phase = await handler.beforeTransaction(event, applyBeforeTransactionReadOnly(phaseContext));
                 if (!phase.isSuccess) {
                     await releaseAll(ctx, releases);
@@ -83,7 +85,11 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
                     releases.push(phase.release);
                 prepared = phase.data;
             }
-            reservedCommands.set(index, { confirmInTransaction, prepared });
+            reservedCommands.set(index, {
+                confirmInTransaction,
+                prepared,
+                parsedPayload: gates.payload,
+            });
         }
         catch (error) {
             await releaseAll(ctx, releases);

package/dist/pipeline/projection-rebuild.js

@@ -1,7 +1,8 @@
 import { countSubscribedEvents, finalizeProjectionRebuild, markProjectionRebuildFailed, markProjectionRebuilding, selectEventsForProjectionRebuildBatch, } from "../db/queries/projection-rebuild.js";
 import { assertLiveColumnsMatchMeta, assertLiveTableHasNoRowLevelSecurity, assertNoBlindIndexLoss, assertNoUnreachableLiveRows, buildShadowTable, countColumnDrift, ensureRebuildSchema, fenceLiveTable, rebuildMetaOrThrow, swapShadowIntoLive, } from "../db/queries/shadow-swap.js";
-import { coerceRow, extractTableInfo, runInSavepoint, selectMany } from "../db/query.js";
+import { coerceRow, runInSavepoint, selectMany } from "../db/query.js";
 import { withoutStatementTimeout } from "../db/statement-timeout.js";
+import { extractTableInfo } from "../db/table-info.js";
 import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { eventsTable, getEventsHighWaterMark, upcastStoredEvent, } from "../event-store/index.js";
 import { createRebuildDeadLetterTable, recordRebuildDeadLetters, } from "../event-store/rebuild-dead-letter.js";

package/dist/schema-cli/apply-command.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaCliContext } from "./shared.ts";
+export declare function runApplyCommand(ctx: SchemaCliContext): Promise<number>;