@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

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

@@ -1,43 +1,27 @@
-import type { AggregateStreamHandle, AppendEventArgs, AppendEventFn, FetchForWritingArgs } from "../engine/types/index.ts";
+import type { AppendEventArgs } from "@cosmicdrift/kumiko-types/handlers";
+import type { HandlerEvents } 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";
+import { type ProjectionReader } from "./system-identity-switch.ts";
+declare function buildTryAppendEvent(scope: HandlerContextScope): (args: AppendEventArgs) => Promise<{
+    ok: true;
+    event: StoredEvent;
+    conflict?: undefined;
+} | {
+    event?: undefined;
+    ok: false;
+    conflict: EventStoreVersionConflictError;
+} | {
+    event?: undefined;
+    ok: false;
+    conflict: EventStoreIdempotentAppendConflictError;
+}>;
+type EventsFacet = Omit<HandlerEvents, "tryAppend"> & {
+    readonly tryAppend: ReturnType<typeof buildTryAppendEvent>;
+};
 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[]>;
+    readonly events: EventsFacet;
+    readonly queryProjection: ProjectionReader;
 };
+export {};

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

@@ -1,6 +1,8 @@
 import { runInSavepoint, selectMany } from "../db/query.js";
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
 import { hasTenantColumn } from "../db/tenant-db.js";
-import { InternalError, memberResolutionReadOnlyDenied, VersionConflictError, } from "../errors/index.js";
+import { InternalError, VersionConflictError } from "../errors/index.js";
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.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";
@@ -9,6 +11,7 @@ import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.j
 import { appendDomainEventCore } from "./append-event-core.js";
 import { isMemberResolutionPrincipal, resolveDbSource, } from "./dispatch-shared.js";
 import { createGatedProjectionReader } from "./system-identity-switch.js";
+import { asTypedAppendEventFn } from "./typed-append-event.js";
 function requireDbSource(ctx, tx, surfaceCall) {
     const dbSource = resolveDbSource(ctx, tx);
     if (!dbSource) {
@@ -18,7 +21,7 @@ function requireDbSource(ctx, tx, surfaceCall) {
     }
     return dbSource;
 }
-// ctx.appendEvent — append a domain event onto a specific aggregate stream
+// ctx.events.append — 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.
@@ -27,20 +30,20 @@ async function appendDomainEvent(ctx, args, user, tx, callerFeature) {
     if (isMemberResolutionPrincipal(user))
         throw memberResolutionReadOnlyDenied();
     const { registry } = ctx;
-    const dbSource = requireDbSource(ctx, tx, `ctx.appendEvent("${args.type}")`);
+    const dbSource = requireDbSource(ctx, tx, `ctx.events.append("${args.type}")`);
     await appendDomainEventCore({
         registry,
         db: dbSource,
         tenantId: user.tenantId,
         userId: String(user.id),
-        callSiteLabel: "ctx.appendEvent",
+        callSiteLabel: "ctx.events.append",
         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
+// without poisoning the rest of the handler's transaction. Postgres
+// aborts the WHOLE transaction on a statement error
+// (SQLSTATE 25P02 until rollback) 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
@@ -50,7 +53,7 @@ function buildTryAppendEvent(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.`,
+                message: `ctx.events.tryAppend("${args.type}") requires an active transaction — no tx is threaded through this call.`,
             });
         }
         try {
@@ -59,7 +62,7 @@ function buildTryAppendEvent(scope) {
                 db: sp,
                 tenantId: user.tenantId,
                 userId: String(user.id),
-                callSiteLabel: "ctx.tryAppendEvent",
+                callSiteLabel: "ctx.events.tryAppend",
                 callerFeature: registry.getHandlerFeature(type),
             }, args));
             return { ok: true, event };
@@ -78,7 +81,7 @@ function buildTryAppendEvent(scope) {
 function buildFetchForWriting(scope) {
     const { ctx, type, user, tx, registry } = scope;
     return async (args) => {
-        const dbSource = requireDbSource(ctx, tx, `ctx.fetchForWriting("${args.aggregateId}")`);
+        const dbSource = requireDbSource(ctx, tx, `ctx.events.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 });
@@ -124,10 +127,12 @@ function buildFetchForWriting(scope) {
 function buildLoadAggregate(scope) {
     const { ctx, user, tx, registry } = scope;
     return async (aggregateId, loadOptions) => {
-        const dbSource = requireDbSource(ctx, tx, `ctx.loadAggregate("${aggregateId}")`);
+        const dbSource = requireDbSource(ctx, tx, `ctx.events.load("${aggregateId}")`);
         const events = loadOptions?.asOf
             ? await loadAggregateAsOf(dbSource, aggregateId, user.tenantId, loadOptions.asOf)
-            : await loadAggregate(dbSource, aggregateId, user.tenantId);
+            : await loadAggregate(dbSource, aggregateId, user.tenantId, {
+                ...(loadOptions?.atVersion !== undefined && { atVersion: loadOptions.atVersion }),
+            });
         return upcastStoredEvents(events, registry.getEventUpcasters(), {
             db: dbSource,
             tenantId: user.tenantId,
@@ -137,7 +142,7 @@ function buildLoadAggregate(scope) {
 function buildSnapshotAggregate(scope) {
     const { ctx, user, tx, registry } = scope;
     return async (snapshotArgs) => {
-        const dbSource = requireDbSource(ctx, tx, `ctx.snapshotAggregate("${snapshotArgs.aggregateId}")`);
+        const dbSource = requireDbSource(ctx, tx, `ctx.events.snapshot("${snapshotArgs.aggregateId}")`);
         await saveSnapshot(dbSource, {
             aggregateId: snapshotArgs.aggregateId,
             tenantId: user.tenantId,
@@ -151,7 +156,7 @@ function buildSnapshotAggregate(scope) {
 function buildLoadAggregateWithSnapshot(scope) {
     const { ctx, user, tx, registry } = scope;
     return async (aggregateId, reducer, initial, loadOptions) => {
-        const dbSource = requireDbSource(ctx, tx, `ctx.loadAggregateWithSnapshot("${aggregateId}")`);
+        const dbSource = requireDbSource(ctx, tx, `ctx.events.loadWithSnapshot("${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
@@ -180,15 +185,17 @@ function buildHandlerProjectionReader(scope) {
             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 ` +
+                message: `ctx.dispatch.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);
+        const dbSource = requireDbSource(ctx, tx, `ctx.dispatch.queryProjection("${qualifiedName}")`);
+        const allTenants = queryOptions?.unsafeAllTenants === true;
+        const where = hasTenantColumn(projTable) && !allTenants ? { tenantId: user.tenantId } : undefined;
+        const read = () => selectMany(dbSource, projTable, where);
+        const rows = await (allTenants
+            ? runInSystemRowLevelSecurityScope("handler projection read with allTenants spans every tenant", read)
+            : read());
         return rows; // @cast-boundary engine-payload
     };
     return createGatedProjectionReader(`handler "${type}"`, hasIdentitySwitchGrant, ungatedQueryProjection, identitySwitchAudit, (qualifiedName) => {
@@ -199,21 +206,21 @@ function buildHandlerProjectionReader(scope) {
 }
 export function buildEventStoreFacet(scope) {
     const { ctx, type, user, tx, registry } = scope;
-    return {
+    const events = {
         // 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) => {
+        append: asTypedAppendEventFn(async (args) => {
             await appendDomainEvent(ctx, args, user, tx, registry.getHandlerFeature(type));
-        }), // @cast-boundary engine-bridge
-        unsafeAppendEvent: async (args) => {
+        }),
+        unsafeAppend: async (args) => {
             await appendDomainEvent(ctx, args, user, tx, registry.getHandlerFeature(type));
         },
-        tryAppendEvent: buildTryAppendEvent(scope),
+        tryAppend: buildTryAppendEvent(scope),
         fetchForWriting: buildFetchForWriting(scope),
-        loadAggregate: buildLoadAggregate(scope),
-        archiveStream: async (aggregateId, archiveArgs) => {
-            const dbSource = requireDbSource(ctx, tx, `ctx.archiveStream("${aggregateId}")`);
+        load: buildLoadAggregate(scope),
+        archive: async (aggregateId, archiveArgs) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.events.archive("${aggregateId}")`);
             await archiveStreamHelper(dbSource, {
                 tenantId: user.tenantId,
                 aggregateId,
@@ -222,16 +229,16 @@ export function buildEventStoreFacet(scope) {
                 reason: archiveArgs.reason,
             });
         },
-        restoreStream: async (aggregateId) => {
-            const dbSource = requireDbSource(ctx, tx, `ctx.restoreStream("${aggregateId}")`);
+        restore: async (aggregateId) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.events.restore("${aggregateId}")`);
             await restoreStreamHelper(dbSource, user.tenantId, aggregateId);
         },
-        isStreamArchived: async (aggregateId) => {
-            const dbSource = requireDbSource(ctx, tx, `ctx.isStreamArchived("${aggregateId}")`);
+        isArchived: async (aggregateId) => {
+            const dbSource = requireDbSource(ctx, tx, `ctx.events.isArchived("${aggregateId}")`);
             return isStreamArchived(dbSource, user.tenantId, aggregateId);
         },
-        snapshotAggregate: buildSnapshotAggregate(scope),
-        loadAggregateWithSnapshot: buildLoadAggregateWithSnapshot(scope),
-        queryProjection: buildHandlerProjectionReader(scope),
+        snapshot: buildSnapshotAggregate(scope),
+        loadWithSnapshot: buildLoadAggregateWithSnapshot(scope),
     };
+    return { events, queryProjection: buildHandlerProjectionReader(scope) };
 }

package/dist/pipeline/handler-context-member-resolution.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from "../engine/types/index.ts";
+export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;

package/dist/pipeline/handler-context-member-resolution.js

@@ -0,0 +1,110 @@
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
+import { denyingJobRunnerProxy, dropOutsideTransaction, withoutNotifyFactories, } from "./handler-context-phase-denials.js";
+import { asTypedAppendEventFn } from "./typed-append-event.js";
+async function denyMemberResolutionWrite() {
+    throw memberResolutionReadOnlyDenied();
+}
+function throwMemberResolutionDenied() {
+    throw memberResolutionReadOnlyDenied();
+}
+// Allowlist (not denylist): a method added to the target later stays denied
+// until someone decides it is read-only.
+function allowlistedReadOnlyProxy(target, allowedMethods) {
+    return new Proxy(target, {
+        get(inner, prop) {
+            if (typeof prop === "string" && allowedMethods.has(prop)) {
+                const method = Reflect.get(inner, prop, inner);
+                return typeof method === "function" ? method.bind(inner) : method;
+            }
+            // Symbol reads and "then" come from await/Promise.resolve/inspect, not from handler code.
+            if (typeof prop === "symbol" || prop === "then")
+                return undefined;
+            throw memberResolutionReadOnlyDenied();
+        },
+    });
+}
+const MEMBER_READ_SEARCH_METHODS = new Set(["search"]);
+const MEMBER_READ_ENTITY_CACHE_METHODS = new Set(["get", "mget"]);
+const MEMBER_READ_REDIS_METHODS = new Set([
+    "get",
+    "mget",
+    "exists",
+    "ttl",
+    "pttl",
+    "strlen",
+    "type",
+    "hget",
+    "hmget",
+    "hgetall",
+    "hexists",
+    "hlen",
+    "sismember",
+    "smembers",
+    "scard",
+    "llen",
+    "lrange",
+    "zscore",
+    "zcard",
+    "zrange",
+]);
+function readOnlyServices(services) {
+    const { searchAdapter, redis, entityCache, jobRunner } = services;
+    // A read as a member gets no file storage, no notify factory and no job runner; the read-only
+    // proxies keep the rest. The resolver and factories would reopen what files/notify close.
+    const { files: _files, derivatives: _derivatives, _fileProviderResolver: _resolver, ...kept } = withoutNotifyFactories(services);
+    const runner = jobRunner && denyingJobRunnerProxy();
+    return {
+        ...kept,
+        ...(runner && { jobRunner: runner }),
+        ...(searchAdapter && {
+            searchAdapter: allowlistedReadOnlyProxy(searchAdapter, MEMBER_READ_SEARCH_METHODS),
+        }),
+        ...(redis && { redis: allowlistedReadOnlyProxy(redis, MEMBER_READ_REDIS_METHODS) }),
+        ...(entityCache && {
+            entityCache: allowlistedReadOnlyProxy(entityCache, MEMBER_READ_ENTITY_CACHE_METHODS),
+        }),
+    };
+}
+// Every write/side-effect surface throws, so "no writeAsMember" holds even
+// if a handler tries ctx.dispatch.write directly on a resolved member principal.
+// Deliberately open: `db` (guarded by the READ ONLY transaction + memberReadOnly grant),
+// and read-only methods of searchAdapter / redis / entityCache (allowlisted).
+export function applyMemberResolutionReadOnly(handlerContext) {
+    // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY
+    // transaction, and its `memberReadOnly` grant denies every raw-runner handout.
+    dropOutsideTransaction(handlerContext);
+    const { systemDb: _systemDb, crossTenantReads: _crossTenantReads, ...kept } = handlerContext;
+    return {
+        ...kept,
+        dispatch: {
+            ...handlerContext.dispatch,
+            write: denyMemberResolutionWrite,
+            writeAs: denyMemberResolutionWrite,
+            // A resolved member cannot switch identity either — the target would get a normal, writable context.
+            queryAs: denyMemberResolutionWrite,
+            queryAsMember: denyMemberResolutionWrite,
+        },
+        events: {
+            ...handlerContext.events,
+            append: asTypedAppendEventFn(denyMemberResolutionWrite),
+            unsafeAppend: denyMemberResolutionWrite,
+            tryAppend: denyMemberResolutionWrite,
+            fetchForWriting: denyMemberResolutionWrite,
+            archive: denyMemberResolutionWrite,
+            restore: denyMemberResolutionWrite,
+            snapshot: denyMemberResolutionWrite,
+        },
+        auth: { ...handlerContext.auth, resolveActiveMembership: denyMemberResolutionWrite },
+        // A read as a member gets no system-scope DB, preSave pipeline or file storage.
+        lifecycle: {
+            afterCommit: throwMemberResolutionDenied,
+            afterRollback: throwMemberResolutionDenied,
+            ...(handlerContext.lifecycle.signal && { signal: handlerContext.lifecycle.signal }),
+        },
+        tenants: {
+            ...(handlerContext.tenants.config && { config: handlerContext.tenants.config }),
+        },
+        services: readOnlyServices(handlerContext.services),
+        ...(handlerContext.notify && { notify: denyMemberResolutionWrite }),
+    };
+}

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

@@ -1,11 +1,12 @@
+import type { NotifyFn } from "@cosmicdrift/kumiko-types/handlers";
 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 { 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: {
+    factoryServices: {
         _notifyInTransactionFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
         _notifyAfterCommitFactory?: ((notifyUser: SessionUser, notifyTenantId: TenantId) => NotifyFn) | undefined;
     };

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

@@ -45,7 +45,7 @@ export function buildNotifyFacet(scope, sinks, outsideTxSource) {
     const notify = buildNotify(scope, sinks, notifyAfterCommitFactory, notifyInTransactionFactory);
     return {
         notify,
-        factoryFragment: {
+        factoryServices: {
             ...(notifyInTransactionFactory && {
                 _notifyInTransactionFactory: notifyInTransactionFactory,
             }),

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

@@ -1,7 +1,5 @@
+import type { HandlerObservability } from "../engine/types/index.ts";
 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;
+    readonly obs: HandlerObservability;
 };

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

@@ -1,4 +1,6 @@
-import { createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, getFallbackTracer, } from "../observability/index.js";
+import { createFallbackFullLogger } from "../logging/utils.js";
+import { getFallbackTracer } from "../observability/fallback.js";
+import { createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, } from "../observability/index.js";
 export function buildObservabilityFacet(scope) {
     const { type, user, context, reqCtx, featureName } = scope;
     const log = context.log?.child({
@@ -6,16 +8,16 @@ export function buildObservabilityFacet(scope) {
         tenantId: user.tenantId,
         userId: user.id,
         ...(reqCtx && { requestId: reqCtx.requestId }),
-    });
-    // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
+    }) ?? createFallbackFullLogger("handler");
+    // Observability — feature-bound metrics handle, so ctx.obs.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
+    // obs.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 };
+    return { obs: { log, tracer, metrics, metricsFor, ...(meter && { meter }) } };
 }

package/dist/pipeline/handler-context-phase-denials.d.ts

@@ -0,0 +1,11 @@
+import type { JobRunnerRef } from "@cosmicdrift/kumiko-types/handlers";
+import type { HandlerContext } from "../engine/types/index.ts";
+import { InternalError } from "../errors/index.ts";
+export declare function denyingJobRunnerProxy(denied?: () => Error): JobRunnerRef;
+export declare function dropOutsideTransaction(handlerContext: HandlerContext): void;
+export declare function withoutTransactionDenied(surface: string): InternalError;
+export declare function perCommandNestedDenied(targetType: string): InternalError;
+export declare function denyEventStoreSurfaces(handlerContext: HandlerContext, buildError: (surface: string) => InternalError): HandlerContext;
+export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
+export declare function withoutNotifyFactories(services: HandlerContext["services"]): HandlerContext["services"];
+export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;

package/dist/pipeline/handler-context-phase-denials.js

@@ -0,0 +1,98 @@
+import { InternalError } from "../errors/index.js";
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
+import { attachOutsideTransaction } from "./attach-outside-transaction.js";
+// Phase denials of the write pipeline: member-resolution, without-transaction and the two
+// pre-transaction phases each strip a different set of ctx surfaces.
+// JobRunnerRef's declared type only carries handleEvent, but callers
+// routinely bracket-access a fuller runner — a Proxy denies ANY property read.
+export function denyingJobRunnerProxy(denied = memberResolutionReadOnlyDenied) {
+    const target = {
+        handleEvent: async () => {
+            throw denied();
+        },
+    };
+    return new Proxy(target, {
+        get() {
+            throw denied();
+        },
+    });
+}
+export function dropOutsideTransaction(handlerContext) {
+    if (handlerContext.db)
+        attachOutsideTransaction(handlerContext.db, undefined);
+}
+function beforeTransactionDenied(surface) {
+    return new InternalError({
+        message: `ctx.${surface} is not available before the transaction; move it into the handler`,
+    });
+}
+export function withoutTransactionDenied(surface) {
+    return new InternalError({
+        message: `ctx.${surface} is not available without an open transaction; run the write through ctx.dispatch.write so it gets its own transaction`,
+    });
+}
+export function perCommandNestedDenied(targetType) {
+    return new InternalError({
+        message: `handler "${targetType}" runs without a transaction (transaction: "perCommand") and cannot run as a nested write inside an open transaction`,
+    });
+}
+function denySurface(buildError, surface) {
+    return () => {
+        throw buildError(surface);
+    };
+}
+export function denyEventStoreSurfaces(handlerContext, buildError) {
+    const deny = (surface) => denySurface(buildError, `events.${surface}`);
+    return {
+        ...handlerContext,
+        events: {
+            ...handlerContext.events,
+            append: deny("append"),
+            unsafeAppend: deny("unsafeAppend"),
+            tryAppend: deny("tryAppend"),
+            fetchForWriting: deny("fetchForWriting"),
+            archive: deny("archive"),
+            restore: deny("restore"),
+            snapshot: deny("snapshot"),
+        },
+    };
+}
+// Reservations write on purpose through the outside-transaction handles, so they keep those but
+// lose every surface bound to the not-yet-open transaction.
+export function denyTransactionBoundSurfaces(handlerContext) {
+    const { lifecycle, services } = handlerContext;
+    return {
+        ...denyEventStoreSurfaces(handlerContext, beforeTransactionDenied),
+        dispatch: {
+            ...handlerContext.dispatch,
+            write: denySurface(beforeTransactionDenied, "dispatch.write"),
+            writeAs: denySurface(beforeTransactionDenied, "dispatch.writeAs"),
+        },
+        lifecycle: {
+            ...lifecycle,
+            afterCommit: denySurface(beforeTransactionDenied, "lifecycle.afterCommit"),
+            afterRollback: denySurface(beforeTransactionDenied, "lifecycle.afterRollback"),
+        },
+        ...(handlerContext.notify && { notify: denySurface(beforeTransactionDenied, "notify") }),
+        services: {
+            ...withoutNotifyFactories(services),
+            ...(services.jobRunner && {
+                jobRunner: denyingJobRunnerProxy(() => beforeTransactionDenied("services.jobRunner")),
+            }),
+        },
+    };
+}
+// A notify factory builds a working notify, so a phase that denies ctx.notify must drop them too.
+export function withoutNotifyFactories(services) {
+    const { _notifyFactory: _factory, _notifyInTransactionFactory: _inTransaction, _notifyAfterCommitFactory: _afterCommit, ...rest } = services;
+    return rest;
+}
+// The beforeTransaction phase has no write need at all, so it also loses the outside-transaction
+// handles. systemDb is mutated in place like db: its identity keys the unsafeRaw rebinders, so a
+// spread or proxy would lose them. It is built per call, so no other context shares it.
+export function applyBeforeTransactionReadOnly(handlerContext) {
+    dropOutsideTransaction(handlerContext);
+    if (handlerContext.systemDb)
+        attachOutsideTransaction(handlerContext.systemDb, undefined);
+    return denyTransactionBoundSurfaces(handlerContext);
+}

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

@@ -1,7 +1,8 @@
 import { type EscapeHatchDeclaration, type EscapeHatchReporter } from "@cosmicdrift/kumiko-types/handlers";
-import { type RequestContextData } from "../api/request-context.ts";
+import type { RequestContextData } from "../api/request-context-internals.ts";
 import type { DbConnection, DbTx } from "../db/connection.ts";
-import type { AppContext, Registry, SessionUser } from "../engine/types/index.ts";
+import type { AppContext, HandlerContext, HandlerLifecycle, Registry, SessionUser } from "../engine/types/index.ts";
+import type { ContextServiceOverrides } from "./context-services.ts";
 import { type DispatchContext, type HandlerTransactionScope } from "./dispatch-shared.ts";
 import type { WriteOrigin } from "./write-origin.ts";
 export type HandlerContextScope = {
@@ -37,12 +38,8 @@ export declare function resolveHandlerContextScope(input: {
     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;
+export declare function buildPreSave(scope: HandlerContextScope, finalContext: () => HandlerContext): HandlerLifecycle["runPreSave"];
+export declare function buildRuntimeServices(scope: HandlerContextScope): ContextServiceOverrides;
+export declare function buildLifecycleSignal(scope: HandlerContextScope): {
+    readonly signal?: AbortSignal;
 };

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

@@ -1,7 +1,7 @@
 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 { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
 import { resolveDbSource, } from "./dispatch-shared.js";
 export function resolveHandlerContextScope(input) {
     const { ctx, type, user, origin, tx, transactionScope } = input;
@@ -59,30 +59,28 @@ export function resolveHandlerContextScope(input) {
 }
 // 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) {
+// CRUD handlers (entity-handlers.ts) can forward it to the executor. The hooks receive the
+// final, phase-wrapped context, so the context is resolved lazily at call time.
+export function buildPreSave(scope, finalContext) {
     const { lifecycle } = scope.ctx;
-    return {
-        ...(lifecycle && {
-            runPreSave: (handlerName, changes, previous, isNew) => lifecycle.runPreSave(handlerName, changes, previous, isNew, scope.context),
-        }),
-    };
+    if (!lifecycle)
+        return undefined;
+    return (handlerName, changes, previous, isNew) => lifecycle.runPreSave(handlerName, changes, previous, isNew, finalContext());
 }
-export function buildRuntimeFragment(scope) {
-    const { ctx, reqCtx } = scope;
-    const { effectiveFeatures, jobRunner } = ctx;
+// Services the dispatcher resolves itself instead of copying from the boot context.
+export function buildRuntimeServices(scope) {
+    const { effectiveFeatures, jobRunner, cacheSync } = scope.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.
+        // One resolver for the lifecycle pipeline, MSP runner and ctx.hasFeature.
         ...(effectiveFeatures && { effectiveFeatures }),
-        ...(ctx.cacheSync && { cacheSync: ctx.cacheSync }),
-        // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
+        ...(cacheSync && { cacheSync }),
+        // Lets write handlers call ctx.services.jobRunner.dispatch(...) directly, same
         // as a follow-up job would (test-stack.ts wires the matching runner).
         ...(jobRunner && { jobRunner }),
     };
 }
+// Cancellation signal flows from the HTTP middleware via requestContext. Absent for non-HTTP
+// entry points (jobs, dispatcher MSP-applies) so it never reads as a phantom always-live signal.
+export function buildLifecycleSignal(scope) {
+    return scope.reqCtx?.signal ? { signal: scope.reqCtx.signal } : {};
+}