@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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

@@ -0,0 +1,89 @@
+import { runInSavepoint } from "../db/query.js";
+import { writeFailure } from "../errors/index.js";
+import { runBatch, unwrapSingle } from "./dispatch-batch.js";
+import { executeQuery } from "./dispatch-query.js";
+import { perCommandNestedDenied } from "./dispatch-shared.js";
+import { executeWrite } from "./dispatch-write.js";
+import { isFailedWriteResult, NestedWriteRollback, } from "./dispatcher-utils.js";
+import { createGatedIdentitySwitch } from "./system-identity-switch.js";
+export function createCommitSinks(afterCommitHooks, transactionScope, outerNotifySink) {
+    // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
+    // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
+    const bridgeSink = afterCommitHooks ?? [];
+    // Query bridges and post-commit contexts get a throwaway sink: hooks pushed there never run.
+    const hasLiveCommitSink = afterCommitHooks !== undefined && transactionScope !== "postCommit";
+    return {
+        bridgeSink,
+        hasLiveCommitSink,
+        notifyCommitSink: hasLiveCommitSink ? bridgeSink : outerNotifySink,
+    };
+}
+// A failed inner write has already appended its event and projections when a later
+// step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
+// failure result. The savepoint makes the failure undo exactly the inner write; the
+// inner afterCommit hooks only reach the outer sink if it succeeded.
+async function runNestedWriteInSavepoint(scope, sinks, asUser, targetType, payload) {
+    const { ctx, registry, origin, tx } = scope;
+    const { bridgeSink } = sinks;
+    if (registry.getWriteHandler(targetType)?.transaction === "perCommand") {
+        return writeFailure(perCommandNestedDenied(targetType));
+    }
+    if (!tx)
+        return executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink);
+    const innerAfterCommitHooks = [];
+    try {
+        const result = await runInSavepoint(tx, async (savepointTx) => {
+            const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary db-runner savepoint handle is a transaction handle
+            innerAfterCommitHooks);
+            if (isFailedWriteResult(innerResult))
+                throw new NestedWriteRollback(innerResult);
+            return innerResult;
+        });
+        bridgeSink.push(...innerAfterCommitHooks);
+        return result;
+    }
+    catch (e) {
+        if (e instanceof NestedWriteRollback)
+            return e.failure;
+        throw e;
+    }
+}
+// Savepoints on one connection are not serialized by the driver: two parallel nested writes would
+// interleave their statements and a ROLLBACK TO of the first would also discard the second's rows.
+// Writes nested one level deeper run on their own savepoint handle and therefore their own chain.
+function createSerializedNestedWriter(scope, sinks) {
+    let nestedWriteChain = Promise.resolve();
+    return (asUser, targetType, payload) => {
+        const run = nestedWriteChain.then(() => runNestedWriteInSavepoint(scope, sinks, asUser, targetType, payload));
+        nestedWriteChain = run.catch(() => undefined);
+        return run;
+    };
+}
+export function buildDispatchFacet(scope, sinks) {
+    const { ctx, type, user, origin, tx, transactionScope, hasIdentitySwitchGrant, identitySwitchAudit, } = scope;
+    const scheduleAfterCommit = (hook) => {
+        sinks.bridgeSink.push(hook);
+    };
+    const executeNestedWriteInSavepoint = createSerializedNestedWriter(scope, sinks);
+    // 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 identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
+        // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
+        queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx, sinks.notifyCommitSink), // @wrapper-known semantic-alias
+        writeAs: writeAsUser,
+    }, identitySwitchAudit);
+    return {
+        bridge: {
+            query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx, sinks.notifyCommitSink), // @wrapper-known semantic-alias
+            queryAs: identitySwitch.queryAs,
+            write: (targetType, payload) => writeAsUser(user, targetType, payload),
+            writeAs: identitySwitch.writeAs,
+        },
+        scheduleFragment: { ...(sinks.hasLiveCommitSink && { scheduleAfterCommit }) },
+    };
+}

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

@@ -0,0 +1,43 @@
+import type { AggregateStreamHandle, AppendEventArgs, AppendEventFn, FetchForWritingArgs } from "../engine/types/index.ts";
+import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError } from "../event-store/errors.ts";
+import { type StoredEvent } from "../event-store/event-store.ts";
+import { type LoadAggregateWithSnapshotOptions, type LoadAggregateWithSnapshotResult, type SnapshotReducer } from "../event-store/snapshot.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildEventStoreFacet(scope: HandlerContextScope): {
+    appendEvent: AppendEventFn;
+    unsafeAppendEvent: (args: AppendEventArgs) => Promise<void>;
+    tryAppendEvent: (args: AppendEventArgs) => Promise<{
+        ok: true;
+        event: StoredEvent;
+        conflict?: undefined;
+    } | {
+        event?: undefined;
+        ok: false;
+        conflict: EventStoreVersionConflictError;
+    } | {
+        event?: undefined;
+        ok: false;
+        conflict: EventStoreIdempotentAppendConflictError;
+    }>;
+    fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
+    loadAggregate: (aggregateId: string, loadOptions?: {
+        readonly asOf?: Temporal.Instant;
+    }) => Promise<readonly StoredEvent[]>;
+    archiveStream: (aggregateId: string, archiveArgs: {
+        readonly aggregateType: string;
+        readonly reason?: string;
+    }) => Promise<void>;
+    restoreStream: (aggregateId: string) => Promise<void>;
+    isStreamArchived: (aggregateId: string) => Promise<boolean>;
+    snapshotAggregate: (snapshotArgs: {
+        readonly aggregateId: string;
+        readonly aggregateType: string;
+        readonly version: number;
+        readonly state: Record<string, unknown>;
+        readonly snapshotVersion?: number;
+    }) => Promise<void>;
+    loadAggregateWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: SnapshotReducer<TState>, initial: TState, loadOptions?: Omit<LoadAggregateWithSnapshotOptions, "upcastEvent" | "entityEventVersionOf">) => Promise<LoadAggregateWithSnapshotResult<TState>>;
+    queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
+        readonly unsafeAllTenants?: boolean;
+    }) => Promise<readonly T[]>;
+};

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/irreversible-operation-gate.js

@@ -46,7 +46,7 @@ export function assertIrreversibleOperationAllowed(operation) {
 // Fields flagged readAsInstruction: true have their write payload presence checked here — the
 // same reasoning as assertIrreversibleOperationAllowed, but the irreversible property belongs to
 // the target field, not the verb. Presence in the payload (not a value comparison against the
-// loaded row) is the deliberate fail-closed choice — see kumiko-framework#3358.
+// loaded row) is the deliberate fail-closed choice.
 export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFieldNames, instructionFieldNames) {
     const fields = writtenFieldNames.filter((name) => instructionFieldNames.includes(name));
     // skip: the write touches no readAsInstruction field.

package/dist/pipeline/lifecycle-pipeline.js

@@ -5,17 +5,17 @@ function resolveTracer(context) {
     return context.tracer ?? getFallbackTracer();
 }
 /**
- * Resolve effective-feature set for the active context's tenant.
+ * Resolves the effective feature set for the active context's tenant.
  *
- * `_tenantId` wird vom dispatcher beim HandlerContext-Bau aus `user.tenantId`
- * gespiegelt. Bei legacy-callsites ohne user (system-jobs, boot-time
- * pipeline) ist es undefined — `effectiveFeatures(undefined)` wäre type-
- * unsafe; wir return undefined und behandeln das als "all features on"
- * (registry filterhooks akzeptieren undefined als "skip filter").
+ * `_tenantId` is copied from `user.tenantId` when the dispatcher builds the
+ * HandlerContext. Legacy call sites without a user (system jobs, boot-time
+ * pipeline) leave it undefined; `effectiveFeatures(undefined)` is type-unsafe,
+ * so this returns undefined and treats that as "all features on" (registry
+ * filter hooks accept undefined to skip filtering).
  *
- * Single source — die 4 lifecycle-hook-callsites (preSave, postSave,
- * preDelete, postDelete) rufen alle hier durch, damit der tenant-
- * scoping-Pfad nie inkonsistent ist.
+ * This is the single path used by all four lifecycle-hook call sites
+ * (preSave, postSave, preDelete, postDelete), keeping tenant scoping
+ * consistent.
  */
 function currentEffectiveFeatures(context) {
     if (context._tenantId === undefined)