@cosmicdrift/kumiko-framework 0.146.2 → 0.146.3

package/src/pipeline/dispatcher.ts

@@ -1,119 +1,22 @@
-import { requestContext } from "../api/request-context";
-import type { DbConnection, DbRow, DbTx } from "../db/connection";
-import { selectRowForUpdateById } from "../db/queries/entity-read";
-import { asEntityTableMeta, selectMany, transaction } from "../db/query";
-import { buildEntityTable, toSnakeCase } from "../db/table-builder";
-import { createTenantDb } from "../db/tenant-db";
-import { hasAccess } from "../engine/access";
-import { checkWriteFieldRoles, filterReadFields } from "../engine/field-access";
-import { defineTransitions, guardTransition } from "../engine/state-machine";
+import type { buildEntityTable } from "../db/table-builder";
+import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
-import type {
-  AggregateStreamHandle,
-  AppContext,
-  AppendEventArgs,
-  AppendEventFn,
-  AuthClaimsContext,
-  DeleteContext,
-  FetchForWritingArgs,
-  HandlerContext,
-  JobRunnerRef,
-  Registry,
-  SaveContext,
-  SessionUser,
-  WriteResult,
-} from "../engine/types";
-import { HookPhases } from "../engine/types";
-import type { TenantId } from "../engine/types/identifiers";
-import { createFileContext } from "../files/file-handle";
-import { createFallbackLogger } from "../logging/utils";
+import type { AppContext, JobRunnerRef, Registry, SessionUser, WriteResult } from "../engine/types";
+import { reraiseAsKumikoError } from "../errors";
+import { getFallbackMeter, getFallbackTracer, registerStandardMetrics } from "../observability";
+import { runBatch, unwrapSingle } from "./dispatch-batch";
+import { executeQuery } from "./dispatch-query";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
+import { resolveAuthClaimsFn } from "./dispatch-shared";
+import { type HandlerType, resolveType } from "./dispatcher-utils";
+import type { IdempotencyGuard } from "./idempotency";
+import type { LifecycleHooks } from "./lifecycle-pipeline";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
 // here keeps imports single-source.
 export type { WriteResult } from "../engine/types";
-
-import { runValidation } from "../engine/validation";
-import {
-  AccessDeniedError,
-  FeatureDisabledError,
-  FrameworkReasons,
-  InternalError,
-  isKumikoError,
-  NotFoundError,
-  reraiseAsKumikoError,
-  toWriteErrorInfo,
-  ValidationError,
-  VersionConflictError,
-  validationErrorFromZod,
-  type WriteErrorInfo,
-  writeFailure,
-} from "../errors";
-import {
-  archiveStream as archiveStreamHelper,
-  isStreamArchived,
-  restoreStream as restoreStreamHelper,
-} from "../event-store/archive";
-import {
-  getStreamVersion,
-  loadAggregate,
-  loadAggregateAsOf,
-  type StoredEvent,
-} from "../event-store/event-store";
-import {
-  type LoadAggregateWithSnapshotOptions,
-  type LoadAggregateWithSnapshotResult,
-  loadAggregateWithSnapshot,
-  type SnapshotReducer,
-  saveSnapshot,
-} from "../event-store/snapshot";
-import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster";
-import {
-  createMetricsHandle,
-  createNoopMetricsHandle,
-  emitDispatcherError,
-  emitDispatcherHandler,
-  getFallbackMeter,
-  getFallbackTracer,
-  registerStandardMetrics,
-} from "../observability";
-import { buildBucketKey } from "../rate-limit";
-import { assertNoSecretLeak } from "../secrets";
-import { createTzContext } from "../time";
-import { parseJsonSafe } from "../utils/safe-json";
-import { appendDomainEventCore } from "./append-event-core";
-import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver";
-import {
-  type AfterCommitHook,
-  BatchRollback,
-  describeShape,
-  dispatcherSpanAttributes,
-  extractNestedSpecs,
-  type HandlerType,
-  isFailedWriteResult,
-  isLifecycleResult,
-  isWriteResultShape,
-  prefixValidationPath,
-  resolveType,
-  wrapToKumiko,
-} from "./dispatcher-utils";
-import type { IdempotencyGuard } from "./idempotency";
-import type { LifecycleHooks } from "./lifecycle-pipeline";
-import { runProjections } from "./projections-runner";
-
-export type BatchCommand = {
-  readonly type: string;
-  readonly payload: unknown;
-};
-
-export type BatchResult =
-  | { readonly isSuccess: true; readonly results: readonly WriteResult[] }
-  | {
-      readonly isSuccess: false;
-      readonly error: WriteErrorInfo;
-      readonly failedIndex: number;
-      readonly results: readonly WriteResult[];
-    };
+export type { BatchCommand, BatchResult } from "./dispatch-shared";
 
 export type DispatcherOptions = {
   idempotency?: IdempotencyGuard;
@@ -176,1291 +79,44 @@ export function createDispatcher(
 ): Dispatcher {
   const { idempotency, lifecycle, jobRunner, effectiveFeatures } = options;
 
-  // Narrowing-helper: AppContext.db ist DbConnection|TenantDb|undefined. Die
-  // dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
-  // appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
-  function resolveDbSource(tx: DbTx | undefined): DbConnection | DbTx | undefined {
-    return tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
-  }
-
   // Pre-build tables and transition maps for auto-guard (avoid per-request allocation)
   const tableCache = new Map<string, ReturnType<typeof buildEntityTable>>();
   const transitionCache = new Map<string, ReturnType<typeof defineTransitions>>();
 
-  function getTable(entityName: string): ReturnType<typeof buildEntityTable> | undefined {
-    if (tableCache.has(entityName)) return tableCache.get(entityName);
-    const entity = registry.getEntity(entityName);
-    if (!entity) return undefined;
-    const table = buildEntityTable(entityName, entity, {
-      relations: registry.getRelations(entityName),
-    });
-    tableCache.set(entityName, table);
-    return table;
-  }
-
-  function getTransitions(args: {
-    entityName: string;
-    fieldName: string;
-    map: Record<string, readonly string[]>;
-  }): ReturnType<typeof defineTransitions> {
-    // Scope by entity — `fieldName` alone collides across entities (e.g. both
-    // `invoice.status` and `driverOrder.status` exist with different maps),
-    // which would apply the wrong transition rules to whichever entity arrives
-    // second.
-    const key = `${args.entityName}:${args.fieldName}`;
-    const cached = transitionCache.get(key);
-    if (cached) return cached;
-    const transitions = defineTransitions(args.map);
-    transitionCache.set(key, transitions);
-    return transitions;
-  }
-
-  // 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(
-    args: AppendEventArgs,
-    user: SessionUser,
-    tx: DbTx | undefined,
-    callerFeature: string | undefined,
-  ): Promise<void> {
-    const dbSource = resolveDbSource(tx);
-    if (!dbSource) {
-      throw new InternalError({
-        message: `ctx.appendEvent("${args.type}") requires a database connection — none is configured.`,
-      });
-    }
-    await appendDomainEventCore(
-      {
-        registry,
-        db: dbSource,
-        tenantId: user.tenantId,
-        userId: String(user.id),
-        callSiteLabel: "ctx.appendEvent",
-        callerFeature,
-      },
-      args,
-    );
-  }
-
-  function buildHandlerContext(
-    type: string,
-    user: SessionUser,
-    tx?: DbTx,
-    afterCommitHooks?: AfterCommitHook[],
-    includeDeleted?: boolean,
-  ): HandlerContext {
-    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(tx);
-    const reqCtx = requestContext.get();
-    const db = dbSource
-      ? createTenantDb(
-          dbSource,
-          user.tenantId,
-          isSystem ? "system" : "tenant",
-          context.tracer,
-          context.meter,
-          // Propagate the request's AbortSignal so every TenantDb query
-          // throws when the client has disconnected — handlers with many
-          // sequential queries skip the rest of the chain instead of
-          // burning DB-CPU for results no one reads.
-          reqCtx?.signal,
-        )
-      : undefined;
-    const log = context.log?.child({
-      handler: type,
-      tenantId: user.tenantId,
-      userId: user.id,
-      ...(reqCtx && { requestId: reqCtx.requestId }),
-    });
-    const notify = context._notifyFactory ? context._notifyFactory(user, user.tenantId) : undefined;
-    // Mirror notify: only built when the config feature wired its factory.
-    const config =
-      context._configAccessorFactory && db
-        ? context._configAccessorFactory({
-            user: { id: user.id, tenantId: user.tenantId },
-            db,
-            secrets: context.secrets,
-          })
-        : undefined;
-    // ctx.files resolved per-tenant through file-foundation (lazy — the
-    // provider is only resolved when a handle actually does I/O). Boot wires
-    // _fileProviderResolver when a file-provider plugin is mounted; falls back
-    // to a statically-injected context.files (tests).
-    const fileResolver = context._fileProviderResolver;
-    const files = fileResolver
-      ? createFileContext(() => fileResolver(user.tenantId))
-      : context.files;
-
-    // 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 featureName = registry.getHandlerFeature(type);
-    const metrics =
-      meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
-
-    // Cross-feature bridge. Queries and writes invoked through ctx.* share:
-    //   - the current transaction (tx) — nested writes roll back with the parent
-    //   - the current afterCommitHooks sink — deferred side-effects fire once
-    //     when the outermost transaction commits
-    // `queryAs` / `writeAs` let a handler explicitly switch identity
-    // (e.g. system-privileged lookups that bypass field-access read filters).
-    const bridgeSink = afterCommitHooks ?? [];
-    const bridge = {
-      query: (targetType: string, payload: unknown) => executeQuery(targetType, payload, user, tx), // @wrapper-known semantic-alias
-      queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-        executeQuery(targetType, payload, asUser, tx), // @wrapper-known semantic-alias
-      write: async (targetType: string, payload: unknown) => {
-        const res = await executeWrite(targetType, payload, user, tx, bridgeSink);
-        return res;
-      },
-      writeAs: async (asUser: SessionUser, targetType: string, payload: unknown) => {
-        const res = await executeWrite(targetType, payload, asUser, tx, bridgeSink);
-        return res;
-      },
-      // 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: AppendEventArgs) => {
-        await appendDomainEvent(args, user, tx, registry.getHandlerFeature(type));
-      }) as AppendEventFn, // @cast-boundary engine-bridge
-      unsafeAppendEvent: async (args: AppendEventArgs) => {
-        await appendDomainEvent(args, user, tx, registry.getHandlerFeature(type));
-      },
-      fetchForWriting: async (args: FetchForWritingArgs): Promise<AggregateStreamHandle> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.fetchForWriting("${args.aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        // Stream-version authoritative (same policy as CRUD executor + Block 0).
-        // A single SELECT MAX(version) is cheaper than loading the full stream
-        // when the caller just wants to append — but most callers also want
-        // the events (business-rule checks), so fetch both in parallel.
-        const [storedEvents, fetchedVersion] = await Promise.all([
-          loadAggregate(dbSource, args.aggregateId, user.tenantId),
-          getStreamVersion(dbSource, args.aggregateId, user.tenantId),
-        ]);
-        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,
-          });
-        }
-
-        // Handle's internal version bumps on every appendOne so multiple
-        // appends in a row stay in order without re-reading the DB.
-        let handleVersion = fetchedVersion;
-        const appendOne = async (appendArgs: {
-          readonly type: string;
-          readonly payload: unknown;
-        }): Promise<void> => {
-          await appendDomainEvent(
-            {
-              aggregateId: args.aggregateId,
-              aggregateType: args.aggregateType,
-              type: appendArgs.type,
-              payload: appendArgs.payload,
-            },
-            user,
-            tx,
-            registry.getHandlerFeature(type),
-          );
-          handleVersion += 1;
-        };
-
-        return {
-          events,
-          get version() {
-            return handleVersion;
-          },
-          appendOne,
-        };
-      },
-      loadAggregate: async (
-        aggregateId: string,
-        loadOptions?: { readonly asOf?: Temporal.Instant },
-      ): Promise<readonly StoredEvent[]> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.loadAggregate("${aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        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,
-        });
-      },
-      archiveStream: async (
-        aggregateId: string,
-        archiveArgs: { readonly aggregateType: string; readonly reason?: string },
-      ): Promise<void> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.archiveStream("${aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        await archiveStreamHelper(dbSource, {
-          tenantId: user.tenantId,
-          aggregateId,
-          aggregateType: archiveArgs.aggregateType,
-          archivedBy: user.id,
-          reason: archiveArgs.reason,
-        });
-      },
-      restoreStream: async (aggregateId: string): Promise<void> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.restoreStream("${aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        await restoreStreamHelper(dbSource, user.tenantId, aggregateId);
-      },
-      isStreamArchived: async (aggregateId: string): Promise<boolean> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.isStreamArchived("${aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        return isStreamArchived(dbSource, user.tenantId, aggregateId);
-      },
-      snapshotAggregate: async (snapshotArgs: {
-        readonly aggregateId: string;
-        readonly aggregateType: string;
-        readonly version: number;
-        readonly state: Record<string, unknown>;
-        readonly snapshotVersion?: number;
-      }): Promise<void> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.snapshotAggregate("${snapshotArgs.aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        await saveSnapshot(dbSource, {
-          aggregateId: snapshotArgs.aggregateId,
-          tenantId: user.tenantId,
-          aggregateType: snapshotArgs.aggregateType,
-          version: snapshotArgs.version,
-          state: snapshotArgs.state,
-          snapshotVersion: snapshotArgs.snapshotVersion,
-        });
-      },
-      loadAggregateWithSnapshot: async <TState extends Record<string, unknown>>(
-        aggregateId: string,
-        reducer: SnapshotReducer<TState>,
-        initial: TState,
-        loadOptions?: Omit<LoadAggregateWithSnapshotOptions, "upcastEvent">,
-      ): Promise<LoadAggregateWithSnapshotResult<TState>> => {
-        const dbSource = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.loadAggregateWithSnapshot("${aggregateId}") requires a database connection — none is configured.`,
-          });
-        }
-        // 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<TState>(
-          dbSource,
-          aggregateId,
-          user.tenantId,
-          reducer,
-          initial,
-          {
-            ...loadOptions,
-            upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx), // @wrapper-known semantic-alias
-          },
-        );
-      },
-      queryProjection: async <T = Record<string, unknown>>(
-        qualifiedName: string,
-        queryOptions?: { readonly unsafeAllTenants?: boolean },
-      ): Promise<readonly T[]> => {
-        // 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).
-        const singleProj = registry.getAllProjections().get(qualifiedName);
-        const mspProj = registry.getAllMultiStreamProjections().get(qualifiedName);
-        const projTable = singleProj?.table ?? mspProj?.table;
-        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 = resolveDbSource(tx);
-        if (!dbSource) {
-          throw new InternalError({
-            message: `ctx.queryProjection("${qualifiedName}") requires a database connection — none is configured.`,
-          });
-        }
-        // Introspect for a tenant_id column on the projection table. Auto-
-        // filter keeps cross-tenant leaks out unless the handler explicitly
-        // opts in. Works with any drizzle-table whose tenant column is named
-        // tenantId on the JS side.
-        const tenantCol = (projTable as Record<string, unknown>)["tenantId"];
-        const where =
-          tenantCol && !queryOptions?.unsafeAllTenants ? { tenantId: user.tenantId } : undefined;
-        const rows = await selectMany<Record<string, unknown>>(dbSource, projTable, where);
-        return rows as readonly T[]; // @cast-boundary engine-payload
-      },
-      // Thin pass-through: one resolve impl lives on the dispatcher, the
-      // handler surface just forwards the call so both entry points (login
-      // handler via ctx.resolveAuthClaims, switch-tenant route via
-      // dispatcher.resolveAuthClaims) cannot drift.
-      resolveAuthClaims: (claimsUser: SessionUser) => resolveAuthClaimsFn(claimsUser), // @wrapper-known semantic-alias
-
-      // Feature-effective check for in-handler opt-in logic. Scope:
-      // **current user's tenant** — for cross-tenant lookups (rare,
-      // SysAdmin operations) read effectiveFeatures(otherTenantId) directly.
-      // When the feature-toggles or tier-engine feature isn't wired (no
-      // effectiveFeatures callback), always returns true — apps without
-      // tier-cuts treat all features on.
-      hasFeature: (featureName: string): boolean =>
-        effectiveFeatures ? effectiveFeatures(user.tenantId).has(featureName) : true,
-    };
-
-    // 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.
-    // ctx.tz ist immer da. Tenant + User-Defaults kommen aus dem
-    // SessionUser sobald die Felder existieren — bis dahin "UTC". Ein
-    // app-injizierter GeoTzProvider (context.geoTzProvider) speist
-    // ctx.tz.fromCoordinates / fromAddress.
-    const tz = createTzContext(
-      context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {},
-    );
-
-    return {
-      ...context,
-      registry,
-      db,
-      log,
-      notify,
-      ...(config && { config }),
-      ...(files && { files }),
-      tracer,
-      metrics,
-      tz,
-      // 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.user als Convenience-Alias auf event.user. Der typisch-
-      // intuitive Pfad „der Context kennt seinen User" — ohne den
-      // schreiben Handler `event.user.tenantId` und brechen sich die
-      // Finger an typo-resistenten ctx.user-Patterns. Identisch zum
-      // event.user-Wert; Identity-Switches nutzen weiterhin queryAs/writeAs.
-      user,
-      _userId: user.id,
-      _tenantId: user.tenantId,
-      _handlerType: type,
-      ...(includeDeleted && { includeDeleted: true }),
-      ...bridge,
-    } as HandlerContext; // @cast-boundary engine-bridge
-  }
-
   const dispatcherTracer = context.tracer ?? getFallbackTracer();
   const dispatcherMeter = context.meter ?? getFallbackMeter();
   // Ensure standard metrics exist on whatever meter we ended up with.
   // Idempotent: buildServer may have registered them already.
   registerStandardMetrics(dispatcherMeter);
 
-  // Wrap handler execution in a dispatcher.handler span AND emit the standard
-  // dispatcher metrics (duration + error counter). Errors are re-thrown so
-  // control flow stays identical to the uninstrumented path.
-  //
-  // Writes are special-cased: executeWriteInner converts thrown handler errors
-  // into a WriteResult with isSuccess=false (rather than letting them bubble).
-  // We inspect the result to paint the dispatcher span + error counter on
-  // those structural failures too — otherwise "handler threw" would only show
-  // up when the caller forgot to use writeFailure().
-  async function runHandlerInstrumented<T>(
-    type: string,
-    operation: "query" | "write",
-    user: SessionUser,
-    inner: () => Promise<T>,
-  ): Promise<T> {
-    const start = performance.now();
-    // Outcome recorded inside the withSpan callback, emitted in finally so
-    // success/failure/throw all hit a single metric-emit path.
-    let success = true;
-    let errorClass: string | undefined;
-
-    try {
-      return await dispatcherTracer.withSpan(
-        "kumiko.dispatcher.handler",
-        {
-          attributes: dispatcherSpanAttributes(
-            type,
-            operation,
-            user,
-            registry.getHandlerFeature(type),
-          ),
-        },
-        async (span) => {
-          try {
-            const result = await inner();
-            if (operation === "write" && isFailedWriteResult(result)) {
-              success = false;
-              errorClass = result.error?.code ?? "UnknownError";
-              span.setStatus("error", errorClass);
-            }
-            return result;
-          } catch (error) {
-            success = false;
-            errorClass = error instanceof Error && error.name ? error.name : "UnknownError";
-            throw error;
-          }
-        },
-      );
-    } finally {
-      if (!success && errorClass) {
-        emitDispatcherError(dispatcherMeter, { handler: type, errorClass });
-      }
-      emitDispatcherHandler(
-        dispatcherMeter,
-        { handler: type, success },
-        (performance.now() - start) / 1000,
-      );
-    }
-  }
-
-  // L3 rate limit gate. Called by both query and write paths before
-  // access-check. Reasoning:
-  //   - handler without rateLimit → no-op
-  //   - app booted without rateLimit resolver → InternalError so the
-  //     misconfig surfaces immediately, not on first 429
-  //   - bucket builder returns "skip" (e.g. ip-based but no client IP):
-  //     pass through. ip-modes are commonly used at L1/L2 middleware
-  //     where the IP comes from Hono directly; falling back to "skip"
-  //     here keeps non-HTTP entry-points (jobs, MSPs) functional.
-  // Feature-toggle gate. Returns the error to fold into a WriteFailure in the
-  // write path, or throws for the query path (where throws flow through the
-  // same outer instrumentation wrapper as other dispatcher errors).
-  //
-  // When `effectiveFeatures` is not wired (tests, apps without feature-toggles
-  // loaded), every handler is treated as enabled — the gate is a pure
-  // pass-through in that common case.
-  async function checkFeatureEnabled(
-    qualifiedHandler: string,
-    tenantId: TenantId,
-  ): Promise<import("../errors").FeatureDisabledError | undefined> {
-    if (!effectiveFeatures) return undefined;
-    const owner = registry.getHandlerFeature(qualifiedHandler);
-    // skip: handler without an owning feature cannot be toggled — shouldn't
-    // happen for registry-built handlers, but guards against edge-case
-    // runtime injections.
-    if (!owner) return undefined;
-    const set = effectiveFeatures(tenantId);
-    if (set.has(owner)) return undefined;
-    // Feature is off for the stored tier — give the live trial-gate a last
-    // chance. Time-derived (tenant.inserted_at + window), so it can't live in
-    // the boot-cached sync resolver; consulted only on this already-disabled
-    // cold path, never on the hot enabled path.
-    if (effectiveFeatures.trialGate && (await effectiveFeatures.trialGate(tenantId, owner))) {
-      return undefined;
-    }
-    return new FeatureDisabledError(owner, qualifiedHandler);
-  }
-
-  async function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): Promise<void> {
-    const err = await checkFeatureEnabled(qualifiedHandler, tenantId);
-    if (err) throw err;
-  }
-
-  async function enforceRateLimit(
-    rateLimit: import("../engine/types").RateLimitOption | undefined,
-    handlerName: string,
-    user: SessionUser,
-  ): Promise<void> {
-    // skip: defence-in-depth — both call-sites already gate on
-    //       handler.rateLimit !== undefined, so this branch only fires
-    //       if a future caller forgets the inline check.
-    if (!rateLimit) return;
-    const reqCtx = requestContext.get();
-    const bucket = buildBucketKey(rateLimit, {
-      handlerName,
-      user,
-      ip: reqCtx?.ip,
-    });
-    // skip: ip-bucket + no IP (non-HTTP entry point) — pass through before
-    // requiring a resolver; HTTP path always has an IP + L1/L2 middleware.
-    if (bucket.kind === "skip") return;
-    if (!context.rateLimit) {
-      throw new InternalError({
-        message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
-      });
-    }
-    await context.rateLimit.enforce(bucket.key, {
-      limit: rateLimit.limit,
-      windowSeconds: rateLimit.windowSeconds,
-      cost: rateLimit.cost,
-    });
-  }
-
-  // Standalone query execution — used by the public dispatcher.query() and
-  // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
-  // field-level read filters for the given user, logs the event.
-  async function executeQuery(
-    type: string,
-    payload: unknown,
-    user: SessionUser,
-    tx?: DbTx,
-  ): Promise<unknown> {
-    return runHandlerInstrumented(type, "query", user, () =>
-      executeQueryInner(type, payload, user, tx),
-    );
-  }
-
-  async function executeQueryInner(
-    type: string,
-    payload: unknown,
-    user: SessionUser,
-    tx?: DbTx,
-  ): Promise<unknown> {
-    const handler = registry.getQueryHandler(type);
-    if (!handler) throw new NotFoundError("handler", type);
-
-    // Feature-toggle gate runs BEFORE rate-limit on purpose: calls to a
-    // disabled feature must not consume the rate-limit quota — the call
-    // never happened from the feature's perspective. Order is: lookup →
-    // feature-gate → rate-limit → access → validation → handler.
-    await ensureFeatureEnabled(type, user.tenantId);
-
-    // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
-    // unauthorized callers must hit the cap too (otherwise the limit
-    // would be a free probe-detector for valid credentials). The
-    // resolver throws RateLimitError which the dispatcher's outer
-    // wrapper turns into a 429 response. Inline-skip when the handler
-    // didn't opt in — keeps the hot path zero-cost (no await on a
-    // no-op promise).
-    if (handler.rateLimit !== undefined) {
-      await enforceRateLimit(handler.rateLimit, type, user);
-    }
-
-    // Default-deny: missing access rule is treated as "no one has access".
-    // The registry boot-validator refuses to register handlers without one,
-    // so in normal boots this branch shouldn't fire — the guard is belt-and-
-    // suspenders in case a handler sneaks through (e.g. runtime injection).
-    if (!hasAccess(user, handler.access)) {
-      throw new AccessDeniedError({
-        message: `access denied for ${type}`,
-        details: { handler: type },
-      });
-    }
-
-    const parsed = handler.schema.safeParse(payload);
-    if (!parsed.success) {
-      throw validationErrorFromZod(parsed.error);
-    }
-
-    // Trash opt-in rides the validated query payload: only the entity-list
-    // schema (and custom query schemas that opt in) carries `includeDeleted`,
-    // so other handlers never see the flag. Visibility filters still apply
-    // downstream (see HandlerContext.includeDeleted) — safe from raw input.
-    const includeDeleted =
-      typeof parsed.data === "object" &&
-      parsed.data !== null &&
-      (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
-    const handlerContext = buildHandlerContext(type, user, tx, undefined, includeDeleted);
-    let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
-
-    // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
-    // and can merge custom-fields/computed-counts/tags/etc. Each hook is
-    // responsible for its own field-access on values it adds (the filter
-    // below only knows the entity's stammfields).
-    //
-    // Two firing-pfade kombiniert in dieser Reihenfolge:
-    //   1. Handler-keyed hooks via r.hook("postQuery", "ns:query:list", fn)
-    //      — feuern nur für genau diesen handler
-    //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
-    //      — feuern für ALLE query-handlers des entity
-    const entityName = registry.getHandlerEntity(type);
-
-    // Handler-keyed postQuery hooks fire for any query (incl. entity-less
-    // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
-    // when the handler maps to an entity — so this block must NOT be gated on
-    // entityName, or hooks on standalone queries register silently and never fire.
-    const handlerHooks = registry.getPostQueryHooks(type);
-    const entityHooks = entityName ? registry.getEntityPostQueryHooks(entityName) : [];
-    const postQueryHooks = [...handlerHooks, ...entityHooks];
-    if (postQueryHooks.length > 0 && result && typeof result === "object") {
-      if (Array.isArray(result)) {
-        let rows = result as Record<string, unknown>[]; // @cast-boundary engine-payload
-        for (const hook of postQueryHooks) {
-          const out = await hook({ entityName, rows }, handlerContext);
-          rows = [...out.rows];
-        }
-        result = rows;
-      } else if (Array.isArray((result as { rows?: unknown }).rows)) {
-        // @cast-boundary engine-payload
-        const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null };
-        let rows = r.rows;
-        for (const hook of postQueryHooks) {
-          const out = await hook({ entityName, rows }, handlerContext);
-          rows = [...out.rows];
-        }
-        result = { ...r, rows };
-      } else {
-        let rows: Record<string, unknown>[] = [result as Record<string, unknown>]; // @cast-boundary engine-payload
-        for (const hook of postQueryHooks) {
-          const out = await hook({ entityName, rows }, handlerContext);
-          rows = [...out.rows];
-        }
-        // A single-object result carries exactly one row through the hook
-        // pipeline. Returning 0 rows (effect lost) or ≥2 rows (extras
-        // dropped) cannot be represented in the single-object response —
-        // surface it instead of silently falling back / truncating.
-        if (rows.length !== 1) {
-          throw new Error(
-            `postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`,
-          );
-        }
-        result = rows[0];
-      }
-    }
-
-    // Field-level read filter — only applies to entity-bound results.
-    const entity = entityName ? registry.getEntity(entityName) : undefined;
-    if (entity && result && typeof result === "object") {
-      if (Array.isArray(result)) {
-        result = result.map((row: Record<string, unknown>) => filterReadFields(entity, row, user));
-      } else {
-        const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
-        if (Array.isArray((resultAsDbRow as { rows?: unknown }).rows)) {
-          // generic handler-result shape narrow
-          const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null }; // @cast-boundary engine-payload
-          result = {
-            ...r,
-            rows: r.rows.map((row) => filterReadFields(entity, row, user)),
-          };
-        } else {
-          result = filterReadFields(entity, result as DbRow, user); // @cast-boundary engine-payload
-        }
-      }
-    }
-
-    // Response-guard: fail the request if a handler accidentally included
-    // a Secret<> branded value in its return. Must run AFTER field-access
-    // filtering so a legitimately stripped secret doesn't false-positive.
-    assertNoSecretLeak(result);
-    return result;
-  }
-
-  // Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
-  // (they see the tx via ctx.db when batch/write opens a transaction).
-  // afterCommit hooks are queued into `afterCommitHooks` for the caller to
-  // flush after commit.
-  async function runLifecycle(
-    type: string,
-    data: unknown,
-    handlerContext: HandlerContext,
-    afterCommitHooks: AfterCommitHook[],
-  ): Promise<void> {
-    if (!lifecycle) {
-      handlerContext.log?.debug(`runLifecycle: skipping ${type} — no lifecycle pipeline`);
-      return;
-    }
-    if (!isLifecycleResult(data)) {
-      handlerContext.log?.debug(`runLifecycle: skipping ${type} — result is not a lifecycle kind`);
-      return;
-    }
-    const result = data;
-
-    // Projections run FIRST, inside the tx, before any user postSave/postDelete
-    // hooks. If a projection apply() throws, the whole tx rolls back — the
-    // event and the auto-projection row go with it. Running before the hooks
-    // keeps projection state consistent with what the hooks observe.
-    await runProjections(result, handlerContext);
-
-    if (result.kind === "save") {
-      await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
-      afterCommitHooks.push(() =>
-        lifecycle.runPostSave(type, result, handlerContext, HookPhases.afterCommit),
-      );
-    } else if (result.kind === "delete") {
-      await lifecycle.runPreDelete(type, result, handlerContext);
-      await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
-      afterCommitHooks.push(() =>
-        lifecycle.runPostDelete(type, result, handlerContext, HookPhases.afterCommit),
-      );
-    }
-  }
-
-  // Shared write pipeline: validates, executes handler, runs lifecycle + side effects.
-  // Used by runBatch (which opens a transaction and flushes afterCommitHooks on commit).
-  //
-  // Contract:
-  //   - `tx` is the active Drizzle transaction handle (or undefined for the no-DB
-  //     fallback path used by tests without a Postgres connection).
-  //   - `afterCommitHooks` collects deferred side-effects that must only fire
-  //     after the transaction commits. The caller flushes them on commit, drops
-  //     them on rollback. executeWrite never fires them directly.
-  async function executeWrite(
-    type: string,
-    payload: unknown,
-    user: SessionUser,
-    tx: DbTx | undefined,
-    afterCommitHooks: AfterCommitHook[],
-  ): Promise<WriteResult> {
-    return runHandlerInstrumented(type, "write", user, () =>
-      executeWriteInner(type, payload, user, tx, afterCommitHooks),
-    );
-  }
-
-  // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
-  //
-  // When a parent `:create` handler's payload carries values under keys
-  // declared as `hasMany` relations with `nestedWrite: true`, those values
-  // are expanded into child writes: parent first (so its new id exists),
-  // then each nested entry as a separate `<target>:create` write with the
-  // foreign key set by the framework — never taken from the client. All of
-  // this runs inside the caller's transaction, so a child failure rolls the
-  // parent (and any earlier children) back together.
-  //
-  // This wrapper is what runBatch calls, not executeWrite. Single writes
-  // (`dispatcher.write`) flow through runBatch as batch-of-one, so they get
-  // nested-expansion too for free. A batch with N heterogeneous commands
-  // can each independently carry nested-children — all still one TX.
-  async function executeNestedWrite(
-    type: string,
-    payload: unknown,
-    user: SessionUser,
-    tx: DbTx | undefined,
-    afterCommitHooks: AfterCommitHook[],
-  ): Promise<WriteResult> {
-    const nested = extractNestedSpecs(type, payload, registry);
-    if (!nested) return executeWrite(type, payload, user, tx, afterCommitHooks);
-
-    // Pre-flight client-shape checks. Merge non-array issues (collected up
-    // front by extractNestedSpecs) with fk-injection issues into one error
-    // so the client sees every problem in a single round-trip.
-    //
-    // Security rail: the client MUST NOT supply the foreign key on nested
-    // items. The framework binds it from the parent's new id. Silent-overwrite
-    // would mask an attempt to attach children to a different parent — fail
-    // loud with a ValidationError carrying a client-mappable path.
-    const issues: Array<{ path: string; code: string; i18nKey: string }> = [...nested.typeIssues];
-    for (const spec of nested.specs) {
-      for (let i = 0; i < spec.items.length; i++) {
-        const item = spec.items[i];
-        if (item && typeof item === "object" && spec.foreignKey in item) {
-          issues.push({
-            path: `${spec.key}.${i}.${spec.foreignKey}`,
-            code: "unexpected_field",
-            i18nKey: "errors.validation.unexpected_field",
-          });
-        }
-      }
-    }
-    if (issues.length > 0) {
-      return writeFailure(new ValidationError({ fields: issues }));
-    }
-
-    const parentResult = await executeWrite(type, nested.cleanPayload, user, tx, afterCommitHooks);
-    if (!parentResult.isSuccess) return parentResult;
-
-    // Handlers built on the CRUD executor return a SaveContext wrapper —
-    // `{ kind: "save", id, data: <row>, changes, previous, event, ... }`.
-    // The wrapper is load-bearing for batch-level hooks downstream (see
-    // flushBatchHooks), so we mutate in place: nested children land on the
-    // inner `data` (which mirrors the entity shape the client expects) while
-    // the wrapper keeps its SaveContext semantics intact for the lifecycle
-    // pipeline. For handlers that return a bare row (no wrapper), children
-    // land directly on that object.
-    //
-    // Hook-ordering note: per-entity postSave hooks already ran inside the
-    // parent's executeWrite call above — they never saw `tasks`, which is
-    // the right semantic (postSave gets the entity's own columns, not
-    // synthetic relation keys). A future postSaveBatch subscriber that
-    // enumerates columns generically WOULD see `tasks`; no such subscriber
-    // exists today. If you add one that iterates `Object.keys(save.data)`,
-    // filter by `entity.fields` membership to stay correct.
-    // handler-Result.data ist generic über alle Entity-Handler; nested-
-    // write inspiziert die shape strukturell.
-    const parentWrapper = parentResult.data as Record<string, unknown>; // @cast-boundary engine-payload
-    const parentRow = (parentWrapper["data"] ?? parentWrapper) as Record<string, unknown>; // @cast-boundary engine-payload
-    const parentId = parentRow["id"];
-    if (typeof parentId !== "string") {
-      return writeFailure(
-        new InternalError({
-          message: `nested-write: parent handler "${type}" returned no string "id" — cannot attach children`,
-        }),
-      );
-    }
-
-    for (const spec of nested.specs) {
-      const subRows: Record<string, unknown>[] = [];
-      for (let i = 0; i < spec.items.length; i++) {
-        const rawItem = spec.items[i];
-        const itemObj = (rawItem ?? {}) as Record<string, unknown>; // @cast-boundary engine-payload
-        const subPayload = { ...itemObj, [spec.foreignKey]: parentId };
-        const subResult = await executeWrite(spec.subType, subPayload, user, tx, afterCommitHooks);
-        if (!subResult.isSuccess) {
-          return {
-            isSuccess: false,
-            error: prefixValidationPath(subResult.error, `${spec.key}.${i}`),
-          };
-        }
-        const subWrapper = subResult.data as Record<string, unknown>; // @cast-boundary engine-payload
-        const subRow = (subWrapper["data"] ?? subWrapper) as Record<string, unknown>; // @cast-boundary engine-payload
-        subRows.push(subRow);
-      }
-      parentRow[spec.key] = subRows;
-    }
-
-    return parentResult;
-  }
-
-  async function executeWriteInner(
-    type: string,
-    payload: unknown,
-    user: SessionUser,
-    tx: DbTx | undefined,
-    afterCommitHooks: AfterCommitHook[],
-  ): Promise<WriteResult> {
-    const handler = registry.getWriteHandler(type);
-    if (!handler) return writeFailure(new NotFoundError("handler", type));
-
-    // Feature-toggle gate: disabled handlers must short-circuit before any
-    // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = await checkFeatureEnabled(type, user.tenantId);
-    if (disabledErr) return writeFailure(disabledErr);
-
-    // Rate-limit gate before access (same reasoning as in executeQueryInner).
-    // Throws RateLimitError; the outer wrapper turns it into a 429
-    // WriteFailure via toWriteErrorInfo. Inline-skip when no opt-in —
-    // hot path stays zero-cost.
-    if (handler.rateLimit !== undefined) {
-      try {
-        await enforceRateLimit(handler.rateLimit, type, user);
-      } catch (e) {
-        if (isKumikoError(e)) return writeFailure(e);
-        throw e;
-      }
-    }
-
-    // Default-deny: missing access rule is treated as "no one has access".
-    // The registry boot-validator refuses to register handlers without one,
-    // so in normal boots this branch shouldn't fire — the guard is belt-and-
-    // suspenders in case a handler sneaks through (e.g. runtime injection).
-    if (!hasAccess(user, handler.access)) {
-      return writeFailure(
-        new AccessDeniedError({
-          message: `access denied for ${type}`,
-          details: { handler: type },
-        }),
-      );
-    }
-
-    const parsed = handler.schema.safeParse(payload);
-    if (!parsed.success) {
-      return writeFailure(validationErrorFromZod(parsed.error));
-    }
-
-    const hookErrors = runValidation(registry, type, parsed.data as DbRow); // @cast-boundary engine-payload
-    if (hookErrors) {
-      return writeFailure(
-        new ValidationError({
-          fields: hookErrors.map((e) => ({
-            path: e.field,
-            code: e.error,
-            i18nKey: `errors.validation.${e.error}`,
-          })),
-        }),
-      );
-    }
-
-    // Field-level write access check
-    const entityName = registry.getHandlerEntity(type);
-    if (entityName) {
-      const entity = registry.getEntity(entityName);
-      if (entity) {
-        const fieldsToCheck = (parsed.data as DbRow)["changes"] as
-          | Record<string, unknown>
-          | undefined; // @cast-boundary engine-payload
-        const writePayload = fieldsToCheck ?? (parsed.data as DbRow); // @cast-boundary engine-payload
-        // Pre-handler check: role-only gate. Ownership-level row-match runs
-        // later in the executor where oldRow is loaded — that split lets
-        // updates with partial changes still pass the pre-handler check and
-        // get their full evaluation at save time.
-        const deniedField = checkWriteFieldRoles(entity, writePayload, user);
-        if (deniedField) {
-          return writeFailure(
-            new AccessDeniedError({
-              message: `field access denied: ${deniedField}`,
-              i18nKey: "errors.access.fieldDenied",
-              details: {
-                reason: FrameworkReasons.fieldAccessDenied,
-                field: deniedField,
-                handler: type,
-              },
-            }),
-          );
-        }
-      }
-    }
-
-    const handlerContext = buildHandlerContext(type, user, tx, afterCommitHooks);
-
-    // Auto transition guard: if entity has transitions and handler doesn't skip it
-    if (entityName && !handler.unsafeSkipTransitionGuard) {
-      const entity = registry.getEntity(entityName);
-      if (entity?.transitions && handlerContext.db) {
-        const parsedData = parsed.data as DbRow; // @cast-boundary engine-payload
-        const changes = (parsedData["changes"] as DbRow) ?? parsedData; // @cast-boundary engine-payload
-        const id = (parsedData["id"] as number) ?? undefined; // @cast-boundary engine-payload
-
-        for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
-          const newValue = changes[fieldName] as string | undefined; // @cast-boundary engine-bridge
-          if (!newValue || !id) continue;
-
-          const table = getTable(entityName);
-          if (!table) continue;
-
-          // SELECT FOR UPDATE inside the surrounding transaction — locks the
-          // row so a concurrent handler can't mutate `status` between our
-          // guard check and the handler's UPDATE. Without this lock the guard
-          // can false-pass; optimistic locking would catch it later, but with
-          // a less specific error. Falls back to a plain SELECT if no tx is
-          // active (tests without a DB connection).
-          const tableName = asEntityTableMeta(table)?.tableName ?? "";
-          const rows = tx
-            ? await selectRowForUpdateById(handlerContext.db, tableName, id)
-            : await selectMany(handlerContext.db, table, { id });
-          const row = rows[0];
-
-          if (!row) continue;
-          // Skip guard for soft-deleted rows — they shouldn't be transitioning
-          // at all; a handler that wants to move a deleted row should use
-          // unsafeSkipTransitionGuard or restore first.
-          const rowAsRow = row as DbRow; // @cast-boundary engine-payload
-          const isDeleted = rowAsRow["isDeleted"] ?? rowAsRow["is_deleted"];
-          if (entity.softDelete && isDeleted === true) {
-            continue;
-          }
-          const currentValue =
-            ((row as DbRow)[fieldName] as string | undefined) ??
-            ((row as DbRow)[toSnakeCase(fieldName)] as string); // @cast-boundary engine-bridge
-          guardTransition(
-            getTransitions({ entityName, fieldName, map: transitionMap }),
-            currentValue,
-            newValue,
-          );
-        }
-      }
-    }
-
-    // The handler itself plus the lifecycle pipeline run under the same
-    // try-wrapper: any KumikoError bubbles up as a typed WriteErrorInfo, any
-    // other throw gets wrapped in InternalError so the Prod contract holds
-    // ("unexpected throw → 500 with sanitized body"). We intentionally do NOT
-    // catch further out (runBatch still sees these as exceptions via
-    // writeFailure, not via a rethrow) so batches roll back naturally.
-    let result: WriteResult;
-    try {
-      result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
-    } catch (e) {
-      return writeFailure(wrapToKumiko(e));
-    }
-
-    // Runtime shape-guard. The compile-time type WriteHandlerFn already
-    // requires `Promise<WriteResult>`, but custom handlers wired through
-    // r.writeHandler(name, schema, fn, opts) sometimes slip through with
-    // `Promise<{id: string}>` — TypeScript misses it under structural-
-    // widening, the dispatcher then reads .isSuccess on undefined and
-    // crashes obscure. Surface a clear actionable message instead.
-    if (!isWriteResultShape(result)) {
-      return writeFailure(
-        new InternalError({
-          message:
-            `Write handler "${type}" returned an invalid shape. Expected WriteResult ` +
-            `({ isSuccess: true, data: ... } or writeFailure(err)), got ${describeShape(result)}. ` +
-            `Use defineWriteHandler() or wrap the return as { isSuccess: true as const, data: ... }.`,
-        }),
-      );
-    }
-
-    if (result.isSuccess) {
-      try {
-        await runLifecycle(type, result.data, handlerContext, afterCommitHooks);
-      } catch (e) {
-        return writeFailure(wrapToKumiko(e));
-      }
-
-      // jobRunner has external side-effects (BullMQ enqueue) — must NOT
-      // fire for rolled-back writes. Defer to afterCommit.
-      if (jobRunner) {
-        const eventData = (parsed.data ?? {}) as DbRow; // @cast-boundary engine-payload
-        afterCommitHooks.push(() => jobRunner.handleEvent(type, eventData, user));
-      }
-    }
-
-    // Response-guard: block Secret<> leaks in write responses (SaveContext
-    // data / previous / changes). Feature code that fed a plaintext through
-    // to the return payload fails here instead of hitting the client.
-    if (result.isSuccess) assertNoSecretLeak(result.data);
-    return result;
-  }
-
-  // Core batch logic extracted so write() and command() can reuse it
-  // (a single write = batch of one, running in its own transaction).
-  async function runBatch(
-    commands: readonly BatchCommand[],
-    user: SessionUser,
-    requestId?: string,
-  ): Promise<BatchResult> {
-    if (commands.length === 0) {
-      return { isSuccess: true, results: [] };
-    }
-
-    // Idempotency: if the same requestId has already been processed, return the
-    // cached result without re-executing. The cache holds the full BatchResult.
-    if (requestId && idempotency) {
-      const cached = await idempotency.check(requestId);
-      if (cached) {
-        const parsed = parseJsonSafe<BatchResult | null>(cached, null);
-        if (parsed) return parsed;
-        // corrupted cache entry — treat as miss, let the request re-run
-      }
-    }
-
-    // Wrap return paths: cache the final result under requestId so retries get
-    // the same answer (both success and failure results are cached).
-    const finalize = async (result: BatchResult): Promise<BatchResult> => {
-      if (requestId && idempotency) {
-        await idempotency.store(requestId, result);
-      }
-      return result;
-    };
-
-    const afterCommitHooks: AfterCommitHook[] = [];
-    const results: WriteResult[] = [];
-
-    // Flush afterCommit hooks in parallel. Errors are logged, not rethrown:
-    // the writes are already committed, we can't undo them.
-    //
-    // Parallelisation is safe because afterCommit hooks are deferred side-
-    // effects (e.g. feature-level postSave hooks in afterCommit phase)
-    // that don't depend on each other — the in-transaction work already ran
-    // sequentially inside the lifecycle pipeline where ordering matters. If a
-    // future hook ever needs ordering, it should do its sequencing internally
-    // (one hook pushing multiple sub-calls) rather than relying on the
-    // flush-loop order.
-    const flushAfterCommit = async () => {
-      const logError = createFallbackLogger("dispatcher", context.log);
-      const outcomes = await Promise.allSettled(afterCommitHooks.map((hook) => hook()));
-      for (const outcome of outcomes) {
-        if (outcome.status === "rejected") {
-          const detail =
-            outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-          logError.error("afterCommit hook failed", { error: detail });
-        }
-      }
-    };
-
-    // Fires the batch-level system hooks with every successful save/delete
-    // context from this run. Called after flushAfterCommit so per-save hooks
-    // have all completed first; errors are isolated inside lifecycleHooks.
-    const flushBatchHooks = async () => {
-      try {
-        const saves: SaveContext[] = [];
-        const deletes: DeleteContext[] = [];
-        for (const r of results) {
-          if (!r.isSuccess) continue;
-          if (!isLifecycleResult(r.data)) continue;
-          if (r.data.kind === "save") saves.push(r.data);
-          else if (r.data.kind === "delete") deletes.push(r.data);
-        }
-        if (saves.length > 0 && lifecycle) await lifecycle.runPostSaveBatch(saves, context);
-        if (deletes.length > 0 && lifecycle) await lifecycle.runPostDeleteBatch(deletes, context);
-      } catch (e) {
-        // Batch hooks must never fail the batch — the commit already happened.
-        // Pass the raw error so the logger preserves stack + cause chain;
-        // collapsing to .message hides exactly what ops needs to debug.
-        const logError = createFallbackLogger("dispatcher", context.log);
-        logError.error("batch hook flush failed", { error: e });
-      }
-    };
-
-    // batch() opens its own outer transaction — needs the top-level
-    // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
-    const db = resolveDbSource(undefined) as DbConnection | undefined;
-    if (!db) {
-      // Without a DB connection there is no transaction to open. Fall back to
-      // sequential execution — useful for unit tests that don't touch the DB.
-      // Each command runs independently; a failure stops the batch.
-      for (let i = 0; i < commands.length; i++) {
-        const cmd = commands[i];
-        if (!cmd) continue;
-        const res = await executeNestedWrite(
-          cmd.type,
-          cmd.payload,
-          user,
-          undefined,
-          afterCommitHooks,
-        );
-        results.push(res);
-        if (!res.isSuccess) {
-          // No tx means no rollback — but we still drop afterCommit hooks,
-          // matching the semantic "failure = side-effects don't fire".
-          return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
-        }
-      }
-      await flushAfterCommit();
-      await flushBatchHooks();
-      return finalize({ isSuccess: true, results });
-    }
-
-    try {
-      await transaction(db, async (tx) => {
-        for (let i = 0; i < commands.length; i++) {
-          const cmd = commands[i];
-          if (!cmd) continue;
-          const res = await executeNestedWrite(cmd.type, cmd.payload, user, tx, afterCommitHooks);
-          results.push(res);
-          if (!res.isSuccess) {
-            throw new BatchRollback(i, res.error);
-          }
-        }
-      });
-    } catch (e) {
-      if (e instanceof BatchRollback) {
-        return finalize({
-          isSuccess: false,
-          error: e.failureError,
-          failedIndex: e.failedIndex,
-          results,
-        });
-      }
-      return finalize({
-        isSuccess: false,
-        error: toWriteErrorInfo(wrapToKumiko(e)),
-        failedIndex: results.length,
-        results,
-      });
-    }
-
-    // Commit succeeded — fire deferred side-effects.
-    await flushAfterCommit();
-    await flushBatchHooks();
-    return finalize({ isSuccess: true, results });
-  }
-
-  // Unwrap a BatchResult into a single WriteResult for write()/command().
-  // Picks the last result if present (the failing one for failures, the only
-  // one for successful single writes). Falls back to a synthetic error if the
-  // batch didn't produce any results (unexpected).
-  function unwrapSingle(batchResult: BatchResult): WriteResult {
-    if (batchResult.isSuccess) {
-      return (
-        batchResult.results[0] ?? writeFailure(new InternalError({ message: "empty_batch_result" }))
-      );
-    }
-    return (
-      batchResult.results[batchResult.failedIndex] ?? {
-        isSuccess: false,
-        error: batchResult.error,
-      }
-    );
-  }
-
-  // Build the per-hook context every auth-claims invocation gets. Claims
-  // hooks run OUTSIDE any request transaction (login is itself the root
-  // operation, not a nested call) and read-only — so the TenantDb is
-  // scoped as "tenant" and no tx is threaded through. Hooks that need
-  // cross-tenant lookups opt in explicitly via queryAs(systemUser, ...).
-  function buildAuthClaimsContext(user: SessionUser): AuthClaimsContext {
-    const dbSource = resolveDbSource(undefined);
-    if (!dbSource) {
-      throw new InternalError({
-        message:
-          "dispatcher.resolveAuthClaims requires a database connection — none is configured.",
-      });
-    }
-    const db = createTenantDb(dbSource, user.tenantId, "tenant", context.tracer, context.meter);
-    const configAccessor = context._configAccessorFactory
-      ? context._configAccessorFactory({
-          user: { id: user.id, tenantId: user.tenantId },
-          db,
-          secrets: context.secrets,
-        })
-      : undefined;
-    return {
-      db,
-      queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
-        executeQuery(qn, payload, asUser), // @wrapper-known semantic-alias
-      ...(configAccessor && { config: configAccessor }),
-    };
-  }
-
-  async function resolveAuthClaimsFn(user: SessionUser): Promise<Record<string, unknown>> {
-    const hooks = registry.getAuthClaimsHooks();
-    if (hooks.length === 0) return {};
-    return runAuthClaimsResolver({
-      user,
-      hooks,
-      contextFactory: buildAuthClaimsContext,
-      ...(context.log && { log: context.log }),
-    });
-  }
+  const ctx: DispatchContext = {
+    registry,
+    appContext: context,
+    idempotency,
+    lifecycle,
+    jobRunner,
+    effectiveFeatures,
+    tableCache,
+    transitionCache,
+    tracer: dispatcherTracer,
+    meter: dispatcherMeter,
+  };
 
   return {
     async write(typeOrRef, payload, user, requestId?) {
       const type = resolveType(typeOrRef);
       // Idempotency handled inside runBatch (caches BatchResult under requestId).
-      const batchResult = await runBatch([{ type, payload }], user, requestId);
+      const batchResult = await runBatch(ctx, [{ type, payload }], user, requestId);
       return unwrapSingle(batchResult);
     },
 
-    batch: runBatch,
+    batch: (commands, user, requestId?) => runBatch(ctx, commands, user, requestId),
 
-    query: (typeOrRef, payload, user) => executeQuery(resolveType(typeOrRef), payload, user),
+    query: (typeOrRef, payload, user) => executeQuery(ctx, resolveType(typeOrRef), payload, user),
 
     async command(typeOrRef, payload, user) {
       const type = resolveType(typeOrRef);
-      const batchResult = await runBatch([{ type, payload }], user);
+      const batchResult = await runBatch(ctx, [{ type, payload }], user);
       const result = unwrapSingle(batchResult);
 
       if (!result.isSuccess) {
@@ -1468,6 +124,6 @@ export function createDispatcher(
       }
     },
 
-    resolveAuthClaims: resolveAuthClaimsFn,
+    resolveAuthClaims: (user) => resolveAuthClaimsFn(ctx, user),
   };
 }