@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/pipeline/dispatch-scope.js

@@ -0,0 +1,27 @@
+import { runInRowLevelSecurityScope, SYSTEM_ROW_LEVEL_SECURITY_SCOPE, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
+// Handlers declared with r.systemScope() act across tenants, so a single-type dispatch of one runs system-scoped.
+// The caller picks the types of a batch, so a batch is system-scoped only when every command is; each command then
+// narrows or widens to its own type's scope (runInDispatchScope in runReservedCommand).
+export function dispatchRowLevelSecurityScope(registry, types, user) {
+    return types.length > 0 && types.every((type) => registry.isHandlerSystemScoped(type))
+        ? SYSTEM_ROW_LEVEL_SECURITY_SCOPE
+        : tenantRowLevelSecurityScope(user.tenantId);
+}
+export function runInDispatchScope(registry, types, user, fn) {
+    return runInRowLevelSecurityScope(dispatchRowLevelSecurityScope(registry, types, user), fn);
+}
+// Generator bodies resume in the consumer's async context, so each step re-enters the scope.
+export async function* streamInDispatchScope(scope, source) {
+    try {
+        while (true) {
+            const step = await runInRowLevelSecurityScope(scope, () => source.next());
+            // skip: source exhausted
+            if (step.done)
+                return;
+            yield step.value;
+        }
+    }
+    finally {
+        await runInRowLevelSecurityScope(scope, () => source.return(undefined));
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
+import type { JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { SseBroker } from "../api/sse-broker.ts";
 import type { DbConnection, DbTx } from "../db/connection.ts";
 import type { buildEntityTable } from "../db/table-builder.ts";
@@ -6,9 +7,10 @@ import { type TenantDb } from "../db/tenant-db.ts";
 import type { defineTransitions } from "../engine/state-machine.ts";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.ts";
 import type { TenantId } from "../engine/types/identifiers.ts";
-import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
-import { InternalError, type WriteErrorInfo } from "../errors/index.ts";
-import { type EscapeHatchReportWindow, type getFallbackMeter, type getFallbackTracer } from "../observability/index.ts";
+import type { AppContext, BeforeTransactionContext, HandlerContext, Registry, ReservationContext, SessionUser } from "../engine/types/index.ts";
+import { type WriteErrorInfo } from "../errors/index.ts";
+import type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.ts";
+import type { getFallbackMeter, getFallbackTracer } from "../observability/fallback.ts";
 import { type AfterCommitHook } from "./dispatcher-utils.ts";
 import type { IdempotencyGuard } from "./idempotency.ts";
 import type { LifecycleHooks } from "./lifecycle-pipeline.ts";
@@ -54,12 +56,8 @@ export type DispatchContext = {
 export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
-export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "dbOutsideTransaction", hint: string): TenantDb;
+export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "db.outsideTransaction", hint: string): TenantDb;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
-export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
-export declare function perCommandNestedDenied(targetType: string): InternalError;
-export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
-export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
 export type BuildHandlerContextOptions = {
     tx?: DbTx;
@@ -67,8 +65,14 @@ export type BuildHandlerContextOptions = {
     includeDeleted?: boolean;
     transactionScope?: HandlerTransactionScope;
     outerNotifySink?: AfterCommitHook[];
-    readOnlyForTenant?: boolean;
+    phase?: HandlerPhase;
 };
+export type HandlerPhase = "handler" | "reservation" | "beforeTransaction";
+type PhaseOptions<TPhase extends HandlerPhase> = BuildHandlerContextOptions & {
+    phase: TPhase;
+};
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options: PhaseOptions<"reservation">): Promise<ReservationContext>;
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options: PhaseOptions<"beforeTransaction">): Promise<BeforeTransactionContext>;
 export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options?: BuildHandlerContextOptions): Promise<HandlerContext>;
 export declare function createHandlerBoundDigest(digest: (value: string) => string, handlerName: string): (value: string) => string;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;

package/dist/pipeline/dispatch-shared.js

@@ -1,23 +1,32 @@
-import { requestContext, runWithOrigin } from "../api/request-context.js";
+import { resolveAgentExposure } from "@cosmicdrift/kumiko-types/agent-exposure";
+import { declaredRateLimitOptions, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
+import { requestContext } from "../api/request-context.js";
+import { runWithOrigin } from "../api/request-context-scopes.js";
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
 import { createTenantDb } from "../db/tenant-db.js";
-import { declaredRateLimitOptions, isRateLimitDisabled, resolveAgentExposure, } from "../engine/types/index.js";
-import { FeatureDisabledError, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, } from "../errors/index.js";
+import { RateLimitUnavailableError } from "../errors/classes.js";
+import { FeatureDisabledError, InternalError, RateLimitError, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { createEscapeHatchReporter, emitDispatcherError, emitDispatcherHandler, observabilityContext, } from "../observability/index.js";
+import { observabilityContext } from "../observability/context.js";
+import { createEscapeHatchReporter } from "../observability/escape-hatch-report.js";
+import { emitDispatcherError, emitDispatcherHandler } from "../observability/standard-metrics.js";
 import { buildBucketKey, buildPayloadBucketKey, normalizePayloadBucketValue, } from "../rate-limit/index.js";
 import { isPlainObject } from "../utils/is-plain-object.js";
 import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver.js";
 import { configAccessorFactoryOf } from "./config-accessor-factory.js";
+import { buildContextServices } from "./context-services.js";
 import { executeQuery } from "./dispatch-query.js";
 import { dispatcherSpanAttributes, isFailedWriteResult, } from "./dispatcher-utils.js";
 import { buildAuthFacet } from "./handler-context-auth.js";
 import { buildConfigFacet, resolveHandlerLocale, resolveHandlerTz, } from "./handler-context-config.js";
-import { buildFileFragment, buildForTenantFragment, buildHandlerDbFacet, } from "./handler-context-db.js";
+import { buildFileFragment, buildHandlerDbFacet, buildWriteTarget } from "./handler-context-db.js";
 import { buildDispatchFacet, createCommitSinks } from "./handler-context-dispatch.js";
 import { buildEventStoreFacet } from "./handler-context-events.js";
+import { applyMemberResolutionReadOnly } from "./handler-context-member-resolution.js";
 import { buildNotifyFacet } from "./handler-context-notify.js";
 import { buildObservabilityFacet } from "./handler-context-observability.js";
-import { buildPreSaveFragment, buildRuntimeFragment, resolveHandlerContextScope, } from "./handler-context-scope.js";
+import { applyBeforeTransactionReadOnly, denyEventStoreSurfaces, denyTransactionBoundSurfaces, withoutTransactionDenied, } from "./handler-context-phase-denials.js";
+import { buildLifecycleSignal, buildPreSave, buildRuntimeServices, resolveHandlerContextScope, } from "./handler-context-scope.js";
 import { createGatedIdentitySwitch, isSystemIdentity } from "./system-identity-switch.js";
 import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";
 import { rootWriteOrigin } from "./write-origin.js";
@@ -42,14 +51,17 @@ export function resolveAppPoolDb(ctx) {
 // r.systemScope() handlers must go through ctx.systemDb's guarded methods
 // (assertTenantMatch / acknowledgeCrossTenant) instead of plain ctx.db —
 // "system" mode has no tenant filter at all, so silent ctx.db or
-// ctx.dbOutsideTransaction use there is a cross-tenant leak. HandlerContext
+// ctx.db.outsideTransaction use there is a cross-tenant leak. HandlerContext
 // has no way to make either field optional per handler (isSystem is a
 // runtime-only registry lookup, not a type-level discriminant), so instead
 // of omitting the key we hand back a Proxy that throws on first touch,
 // naming the handler and pointing at the matching ctx.systemDb escape hatch.
+// Only the db guard answers `outsideTransaction` (the inner guard, set by attachOutsideTransaction).
 export function createSystemScopedDbGuard(handlerType, fieldName, hint) {
     return new Proxy({}, {
-        get(_target, prop) {
+        get(target, prop) {
+            if (fieldName === "db" && prop === "outsideTransaction")
+                return Reflect.get(target, prop);
             throw new InternalError({
                 message: `Handler "${handlerType}" is r.systemScope()'d — ctx.${fieldName} is unavailable ` +
                     `(it would be unfiltered across every tenant). Use ${hint} ` +
@@ -61,219 +73,85 @@ export function createSystemScopedDbGuard(handlerType, fieldName, hint) {
 export function isMemberResolutionPrincipal(user) {
     return user.origin === "member-resolution";
 }
-async function denyMemberResolutionWrite() {
-    throw memberResolutionReadOnlyDenied();
-}
-// JobRunnerRef's declared type only carries handleEvent, but callers
-// routinely bracket-access a fuller runner — a Proxy denies ANY property read.
-function denyingJobRunnerProxy(denied = memberResolutionReadOnlyDenied) {
-    return new Proxy({}, {
-        get() {
-            throw denied();
-        },
-    });
-}
-// 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",
-]);
-// Every write/side-effect surface throws, so "no writeAsMember" holds even
-// if a handler tries ctx.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) {
-    return {
-        ...handlerContext,
-        // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY
-        // transaction, and its `memberReadOnly` grant denies every raw-runner handout.
-        dbOutsideTransaction: undefined,
-        write: denyMemberResolutionWrite,
-        writeAs: denyMemberResolutionWrite,
-        // A resolved member cannot switch identity either — the target would get a normal, writable context.
-        queryAs: denyMemberResolutionWrite,
-        appendEvent: denyMemberResolutionWrite, // @cast-boundary engine-bridge
-        unsafeAppendEvent: denyMemberResolutionWrite,
-        tryAppendEvent: denyMemberResolutionWrite,
-        fetchForWriting: denyMemberResolutionWrite,
-        archiveStream: denyMemberResolutionWrite,
-        restoreStream: denyMemberResolutionWrite,
-        snapshotAggregate: denyMemberResolutionWrite,
-        queryAsMember: denyMemberResolutionWrite,
-        forTenant: undefined,
-        resolveActiveMembership: denyMemberResolutionWrite,
-        scheduleAfterCommit: () => {
-            throw memberResolutionReadOnlyDenied();
-        },
-        // A read as a member gets no system-scope DB, preSave pipeline or file storage.
-        runPreSave: undefined,
-        systemDb: undefined,
-        crossTenantReads: undefined,
-        files: undefined,
-        derivatives: undefined,
-        ...(handlerContext.jobRunner && { jobRunner: denyingJobRunnerProxy() }),
-        ...(handlerContext.notify && { notify: denyMemberResolutionWrite }),
-        ...(handlerContext.searchAdapter && {
-            searchAdapter: allowlistedReadOnlyProxy(handlerContext.searchAdapter, MEMBER_READ_SEARCH_METHODS),
-        }),
-        ...(handlerContext.redis && {
-            redis: allowlistedReadOnlyProxy(handlerContext.redis, MEMBER_READ_REDIS_METHODS),
-        }),
-        ...(handlerContext.entityCache && {
-            entityCache: allowlistedReadOnlyProxy(handlerContext.entityCache, MEMBER_READ_ENTITY_CACHE_METHODS),
-        }),
-    };
-}
-function beforeTransactionDenied(surface) {
-    return new InternalError({
-        message: `ctx.${surface} is not available before the transaction; move it into the handler`,
-    });
-}
-function withoutTransactionDenied(surface) {
-    return new InternalError({
-        message: `ctx.${surface} is not available without an open transaction; run the write through ctx.write so it gets its own transaction`,
-    });
-}
-export function perCommandNestedDenied(targetType) {
-    return new InternalError({
-        message: `handler "${targetType}" runs without a transaction (transaction: "perCommand") and cannot run as a nested write inside an open transaction`,
-    });
-}
-function denySurface(buildError, surface) {
-    return () => {
-        throw buildError(surface);
-    };
-}
-function denyEventStoreSurfaces(handlerContext, buildError) {
-    return {
-        ...handlerContext,
-        appendEvent: denySurface(buildError, "appendEvent"),
-        unsafeAppendEvent: denySurface(buildError, "unsafeAppendEvent"),
-        tryAppendEvent: denySurface(buildError, "tryAppendEvent"),
-        fetchForWriting: denySurface(buildError, "fetchForWriting"),
-        archiveStream: denySurface(buildError, "archiveStream"),
-        restoreStream: denySurface(buildError, "restoreStream"),
-        snapshotAggregate: denySurface(buildError, "snapshotAggregate"),
-    };
-}
-// Reservations write on purpose through the outside-transaction handles, so they keep those but
-// lose every surface bound to the not-yet-open transaction.
-export function denyTransactionBoundSurfaces(handlerContext) {
-    return {
-        ...denyEventStoreSurfaces(handlerContext, beforeTransactionDenied),
-        write: denySurface(beforeTransactionDenied, "write"),
-        writeAs: denySurface(beforeTransactionDenied, "writeAs"),
-        scheduleAfterCommit: denySurface(beforeTransactionDenied, "scheduleAfterCommit"),
-        ...(handlerContext.notify && { notify: denySurface(beforeTransactionDenied, "notify") }),
-        ...(handlerContext.jobRunner && {
-            jobRunner: denyingJobRunnerProxy(() => beforeTransactionDenied("jobRunner")),
-        }),
-    };
-}
-// The beforeTransaction phase has no write need at all, so it also loses the outside-transaction handles.
-export function applyBeforeTransactionReadOnly(handlerContext) {
-    return {
-        ...denyTransactionBoundSurfaces(handlerContext),
-        dbOutsideTransaction: undefined,
-    };
-}
 export async function buildHandlerContext(ctx, type, user, origin, options = {}) {
-    const { tx, afterCommitHooks, includeDeleted, outerNotifySink, readOnlyForTenant = false, transactionScope = tx ? "inTransaction" : "withoutTransaction", } = options;
+    const { tx, afterCommitHooks, includeDeleted, outerNotifySink, phase = "handler", transactionScope = tx ? "inTransaction" : "withoutTransaction", } = options;
+    const readOnlyForTenant = phase === "beforeTransaction";
     const scope = resolveHandlerContextScope({ ctx, type, user, origin, tx, transactionScope });
     const dbFacet = buildHandlerDbFacet(scope);
     const observability = buildObservabilityFacet(scope);
     const sinks = createCommitSinks(afterCommitHooks, transactionScope, outerNotifySink);
     const notifyFacet = buildNotifyFacet(scope, sinks, dbFacet.outsideTxSource);
     const configFacet = buildConfigFacet(scope, dbFacet.db);
-    const forTenantFragment = buildForTenantFragment(scope, dbFacet.exposedDb, readOnlyForTenant);
+    const writeTarget = buildWriteTarget(scope, dbFacet.exposedDb, readOnlyForTenant);
     const fileFragment = buildFileFragment(scope, dbFacet.db);
-    const dispatchFacet = buildDispatchFacet(scope, sinks);
     const authFacet = buildAuthFacet(scope);
     const eventStoreFacet = buildEventStoreFacet(scope);
+    const dispatchFacet = buildDispatchFacet(scope, sinks, {
+        queryAsMember: authFacet.queryAsMember,
+        queryProjection: eventStoreFacet.queryProjection,
+    });
     const tz = await resolveHandlerTz(scope, configFacet.config);
     const locale = resolveHandlerLocale(scope);
-    // The payload-bucket digest is dispatcher-internal; handlers must not be
-    // able to compute bucket keys.
-    const { _rateLimitPayloadDigest: payloadDigest, 
-    // Bound to this call's tx: an outer context's factory must not leak into a tx-less one.
-    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, _notifyAfterCommitFactory: _omitOuterNotifyAfterCommitFactory, ...contextForHandler } = scope.context;
+    const { _rateLimitPayloadDigest: payloadDigest } = scope.context;
+    // The final context (after the phase wrappers below) is what preSave hooks must see.
+    const finalContext = {};
+    const runPreSave = buildPreSave(scope, () => {
+        if (finalContext.current === undefined) {
+            throw new InternalError({
+                message: "lifecycle.runPreSave called before the context was built",
+            });
+        }
+        return finalContext.current;
+    });
     const handlerContext = {
-        ...contextForHandler,
-        ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
-        ...notifyFacet.factoryFragment,
         // Registry is always the dispatcher's registry — injecting it here lets
         // tests/callers pass `context` without `registry` and still get a valid
-        // HandlerContext. The spread-then-assign order matters: anything in
-        // `context` can be overridden, but we want the authoritative registry
-        // from the dispatcher's own closure to win.
+        // HandlerContext.
         registry: scope.registry,
         ...dbFacet.fragment,
-        log: observability.log,
-        notify: notifyFacet.notify,
-        ...configFacet.fragment,
-        ...forTenantFragment,
-        ...fileFragment,
-        ...buildPreSaveFragment(scope),
-        tracer: observability.tracer,
-        metrics: observability.metrics,
-        metricsFor: observability.metricsFor,
+        // The payload-bucket digest is dispatcher-internal; handlers get one bound to their own name.
+        ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
+        ...observability,
+        ...(notifyFacet.notify && { notify: notifyFacet.notify }),
+        ...(configFacet.config && { config: configFacet.config }),
+        services: buildContextServices(scope.context, {
+            ...fileFragment,
+            ...buildRuntimeServices(scope),
+            ...notifyFacet.factoryServices,
+        }),
+        lifecycle: {
+            ...(runPreSave && { runPreSave }),
+            ...dispatchFacet.commitHooks,
+            ...buildLifecycleSignal(scope),
+        },
+        tenants: {
+            ...(configFacet.configFor && { config: configFacet.configFor }),
+            ...(writeTarget && { writeTarget }),
+        },
         tz,
         locale,
-        ...buildRuntimeFragment(scope),
-        // ctx.user as a convenience alias for event.user. The intuitive path—"the
-        // context knows its user"—lets handlers avoid writing `event.user.tenantId`
-        // and reduces errors in ctx.user access patterns. It is identical to
-        // event.user; identity switches still use queryAs/writeAs.
+        // ctx.user as a convenience alias for event.user. Identity switches still use queryAs/writeAs.
         user,
-        _tenantId: user.tenantId,
-        ...dispatchFacet.scheduleFragment,
         ...(includeDeleted && { includeDeleted: true }),
-        ...dispatchFacet.bridge,
-        ...eventStoreFacet,
-        ...authFacet,
+        dispatch: dispatchFacet.dispatch,
+        events: eventStoreFacet.events,
+        auth: authFacet.auth,
+        hasFeature: authFacet.hasFeature,
     }; // @cast-boundary engine-bridge
     const scopedContext = transactionScope === "withoutTransaction"
         ? denyEventStoreSurfaces(handlerContext, withoutTransactionDenied)
         : handlerContext;
     // A resolved member principal is read-only by construction.
-    return isMemberResolutionPrincipal(user)
+    const memberSafeContext = isMemberResolutionPrincipal(user)
         ? applyMemberResolutionReadOnly(scopedContext)
         : scopedContext;
+    const phasedContext = phase === "reservation"
+        ? denyTransactionBoundSurfaces(memberSafeContext)
+        : phase === "beforeTransaction"
+            ? applyBeforeTransactionReadOnly(memberSafeContext)
+            : memberSafeContext;
+    finalContext.current = phasedContext;
+    return phasedContext;
 }
 // The handler-name prefix keeps a handler from reproducing the digests the
 // dispatcher uses for payload buckets (those hash the bare normalized value).
@@ -655,7 +533,10 @@ function buildAuthClaimsContext(ctx, user) {
         ...(configAccessor && { config: configAccessor }),
     };
 }
-export async function resolveAuthClaimsFn(ctx, user) {
+export function resolveAuthClaimsFn(ctx, user) {
+    return runInSystemRowLevelSecurityScope("auth claims resolution reads memberships before a tenant is known", () => resolveAuthClaimsInScope(ctx, user));
+}
+async function resolveAuthClaimsInScope(ctx, user) {
     const { registry, appContext: context } = ctx;
     const hooks = registry.getAuthClaimsHooks();
     if (hooks.length === 0)

package/dist/pipeline/dispatch-stream.js

@@ -2,8 +2,11 @@ import { accessInvalidationCredentialFor } from "../api/sse-broker.js";
 import { scheduleTokenExpiry } from "../api/token-expiry-timer.js";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
-import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, UnauthenticatedError, validationErrorFromZod, } from "../errors/index.js";
-import { assertNoSecretLeak } from "../secrets/index.js";
+import { UnauthenticatedError } from "../errors/classes.js";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors/index.js";
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
+import { assertNoSecretLeak } from "../secrets/leak-guard.js";
+import { dispatchRowLevelSecurityScope, streamInDispatchScope } from "./dispatch-scope.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runStreamInstrumented, } from "./dispatch-shared.js";
 import { handlerAccessError } from "./handler-access-error.js";
 // Standalone stream execution — used by the public dispatcher.stream().
@@ -13,14 +16,15 @@ import { handlerAccessError } from "./handler-access-error.js";
 // write/queryHandler — see feature-entity-handlers.ts), so there's no
 // field-access filter or postQuery-hook stage to run here.
 export async function* executeStream(ctx, type, payload, user, origin, options) {
-    yield* runStreamInstrumented(ctx, type, user, () => executeStreamInner(ctx, type, payload, user, origin, options));
+    const scope = dispatchRowLevelSecurityScope(ctx.registry, [type], user);
+    yield* streamInDispatchScope(scope, runStreamInstrumented(ctx, type, user, () => executeStreamInner(ctx, type, payload, user, origin, options)));
 }
 async function* executeStreamInner(ctx, type, payload, user, origin, options) {
     const { registry } = ctx;
     const handler = registry.getStreamHandler(type);
     if (!handler)
         throw new NotFoundError("handler", type);
-    // A resolved member principal (ctx.queryAsMember) is read-only — streams
+    // A resolved member principal (ctx.dispatch.queryAsMember) is read-only — streams
     // are excluded the same way executeWriteInner excludes writes.
     if (isMemberResolutionPrincipal(user)) {
         throw memberResolutionReadOnlyDenied();

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

@@ -1,5 +1,6 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { DbTx } from "../db/connection.ts";
-import type { SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { SessionUser } from "../engine/types/index.ts";
 import type { DispatchContext, WriteOrigin } from "./dispatch-shared.ts";
 import { type AfterCommitHook } from "./dispatcher-utils.ts";
 export declare function executeWrite(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx: DbTx | undefined, afterCommitHooks: AfterCommitHook[]): Promise<WriteResult>;

package/dist/pipeline/dispatch-write.js

@@ -5,17 +5,19 @@ import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { ConfigScopes } from "../engine/constants.js";
 import { checkWriteFieldOwnership, maskWriteOnlyFields } from "../engine/field-access.js";
+import { HookPhases } from "../engine/hook-helpers.js";
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
-import { HookPhases } from "../engine/types/index.js";
-import { AccessDeniedError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
+import { AccessDeniedError, FrameworkReasons, InternalError, NotFoundError, ValidationError, writeFailure, } from "../errors/index.js";
+import { memberResolutionReadOnlyDenied } from "../errors/member-resolution.js";
 import { assertFileRefsBelongToTenant } from "../files/assert-file-refs-belong-to-tenant.js";
 import { bindPendingFileRefs } from "../files/bind-pending-file-refs.js";
 import { disposeRemovedFileRefs } from "../files/dispose-removed-file-refs.js";
 import { loadSaveFileRefs } from "../files/load-save-file-refs.js";
 import { CACHE_SYNC_TOPICS } from "../redis/cache-sync-topics.js";
-import { assertNoSecretLeak } from "../secrets/index.js";
-import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, perCommandNestedDenied, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
+import { assertNoSecretLeak } from "../secrets/leak-guard.js";
+import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
+import { perCommandNestedDenied } from "./handler-context-phase-denials.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
 import { consumeReservation, hasPreTransactionPhase, } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
@@ -108,11 +110,11 @@ async function settleSaveFileRefs(handlerContext, result, user) {
 async function runLifecycle(ctx, type, data, handlerContext, user, origin, afterCommitHooks, runner) {
     const { lifecycle } = ctx;
     if (!lifecycle) {
-        handlerContext.log?.debug(`runLifecycle: skipping ${type} — no lifecycle pipeline`);
+        handlerContext.obs.log.debug(`runLifecycle: skipping ${type} — no lifecycle pipeline`);
         return;
     }
     if (!isLifecycleResult(data)) {
-        handlerContext.log?.debug(`runLifecycle: skipping ${type} — result is not a lifecycle kind`);
+        handlerContext.obs.log.debug(`runLifecycle: skipping ${type} — result is not a lifecycle kind`);
         return;
     }
     const result = data;
@@ -369,7 +371,7 @@ function resolveWriteEntry(ctx, type, user, tx) {
     if (!handler)
         return failedStep(writeFailure(new NotFoundError("handler", type)));
     // Defense in depth — covers runBatch and a spread-copied user that kept
-    // `origin`, beyond buildHandlerContext's own ctx.write replacement.
+    // `origin`, beyond buildHandlerContext's own ctx.dispatch.write replacement.
     if (isMemberResolutionPrincipal(user)) {
         return failedStep(writeFailure(memberResolutionReadOnlyDenied()));
     }
@@ -389,7 +391,7 @@ async function runWriteGates(ctx, handler, type, payload, user) {
         return failedStep(gates);
     const parsedPayload = reservation ? reservation.parsedPayload : gates.payload;
     // A handler with a pre-transaction phase cannot run that phase from inside an open transaction;
-    // running it without would skip the reservation or the prepared data, so a nested ctx.write of
+    // running it without would skip the reservation or the prepared data, so a nested ctx.dispatch.write of
     // such a handler is rejected instead.
     if (needsPreTransactionPhase && !reservation) {
         return failedStep(writeFailure(new InternalError({

package/dist/pipeline/dispatcher-utils.d.ts

@@ -1,4 +1,6 @@
-import type { HandlerRef, LifecycleResult, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { HandlerRef, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
+import type { LifecycleResult } from "@cosmicdrift/kumiko-types/hooks";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
 import { type KumikoError, type WriteErrorInfo } from "../errors/index.ts";
 export type FailedWriteResult = Extract<WriteResult, {
     isSuccess: false;

package/dist/pipeline/dispatcher-utils.js

@@ -1,5 +1,7 @@
+import { isInvalidDateTimeValue } from "../db/pg-error.js";
 import { parseQn, qn } from "../engine/qualified-name.js";
-import { toKumikoError, VersionConflictError, } from "../errors/index.js";
+import { ValidationError, VersionConflictError, } from "../errors/index.js";
+import { toKumikoError } from "../errors/to-kumiko-error.js";
 import { VersionConflictError as EventStoreVersionConflictError } from "../event-store/errors.js";
 export function isFailedWriteResult(result) {
     return (!!result && typeof result === "object" && "isSuccess" in result && result.isSuccess === false);
@@ -140,7 +142,7 @@ export class NestedWriteRollback extends Error {
 export function resolveType(type) {
     return typeof type === "string" ? type : type.name;
 }
-// A custom write losing an append race (ctx.appendEvent, stream.append) is a
+// A custom write losing an append race (ctx.events.append, stream.append) is a
 // retryable 409 like the CRUD executor's, not an internal error. Mapped here
 // because errors/ is client code and must not import the event store.
 // currentVersion -1 is the "not looked up" sentinel for a bare 23505 fallback.
@@ -152,5 +154,9 @@ export function wrapToKumiko(e) {
             currentVersion: e.currentVersion ?? -1,
         }, { cause: e });
     }
+    // Payload schemas without z.iso.date() let impossible dates reach the column; that is bad input, not a 500.
+    if (isInvalidDateTimeValue(e)) {
+        return new ValidationError({ fields: [] }, { cause: e instanceof Error ? e : undefined });
+    }
     return toKumikoError(e);
 }

package/dist/pipeline/dispatcher.d.ts

@@ -1,15 +1,16 @@
 import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
+import type { ActiveMembershipResult, DispatchWriteRef, JobRunnerRef, MemberReader, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { SseBroker } from "../api/sse-broker.ts";
 import type { DbConnection } from "../db/connection.ts";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.ts";
 import type { TenantId } from "../engine/types/identifiers.ts";
-import type { ActiveMembershipResult, AppContext, DispatchWriteRef, JobRunnerRef, MemberReader, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { AppContext, Registry, SessionUser } from "../engine/types/index.ts";
 import type { BatchCommand, BatchResult } from "./dispatch-shared.ts";
 import { type StreamOptions } from "./dispatch-stream.ts";
 import { type HandlerType } from "./dispatcher-utils.ts";
 import type { IdempotencyGuard } from "./idempotency.ts";
 import type { LifecycleHooks } from "./lifecycle-pipeline.ts";
-export type { WriteResult } from "../engine/types/index.ts";
+export type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 export type { BatchCommand, BatchResult } from "./dispatch-shared.ts";
 export type DispatcherOptions = {
     idempotency?: IdempotencyGuard;

package/dist/pipeline/dispatcher.js

@@ -1,8 +1,9 @@
-import { runWithWriteOrigin } from "../api/request-context.js";
+import { runWithWriteOrigin } from "../api/request-context-scopes.js";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
-import { withEscapeHatchAuditScopeStream } from "../observability/escape-hatch-report.js";
-import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
+import { createEscapeHatchReportWindow, withEscapeHatchAuditScope, withEscapeHatchAuditScopeStream, } from "../observability/escape-hatch-report.js";
+import { getFallbackMeter, getFallbackTracer } from "../observability/fallback.js";
+import { registerStandardMetrics } from "../observability/standard-metrics.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";

package/dist/pipeline/event-consumer-state.d.ts

@@ -12,5 +12,4 @@ export declare const ConsumerStatuses: {
     readonly dead: "dead";
     readonly disabled: "disabled";
 };
-export type ConsumerStatus = (typeof ConsumerStatuses)[keyof typeof ConsumerStatuses];
 export declare function createEventConsumerStateTable(db: DbConnection): Promise<void>;

package/dist/pipeline/event-dispatcher-delivery.d.ts

@@ -1,9 +1,9 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
+import type { Meter } from "@cosmicdrift/kumiko-types/observability";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection.ts";
 import { type PendingIdRange } from "../db/queries/event-store.ts";
 import type { AppContext } from "../engine/types/index.ts";
-import { type Meter } from "../observability/index.ts";
 import { type PendingGapEntry } from "./event-consumer-state.ts";
 import type { EventConsumer } from "./event-dispatcher.ts";
 export type ConsumerStateRowShape = {