@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/pipeline/event-consumer-state.js

@@ -4,7 +4,7 @@ import { tableExists } from "../db/schema-inspection.js";
 import { unsafePushTables } from "../db/table-push.js";
 // Reserved sentinel used in the instance_id column for consumers whose
 // delivery is "shared" — i.e. one cursor across all dispatcher instances
-// (the default, pre-Welle-2.7 behaviour). Per-instance consumers store
+// (the default behaviour). Per-instance consumers store
 // the concrete instanceId. Postgres PK columns can't be NULL and
 // `NULL = NULL` is UNKNOWN in SQL — a nullable instance_id would break
 // both uniqueness and PK constraints. The boot-validator refuses to
@@ -62,7 +62,7 @@ export async function createEventConsumerStateTable(db) {
         // no need to pre-check columnNamesOf first. Two instances booting
         // concurrently against the same DB (this table is explicitly
         // multi-instance) both ALTER, neither crashes on "column already
-        // exists" (#1362).
+        // exists".
         await alterTableAddColumn(db, "kumiko_event_consumers", "rearm_count", "integer", " DEFAULT 0", " NOT NULL", 
         /* ifNotExists */ true);
         await alterTableAddColumn(db, "kumiko_event_consumers", "pending_gaps", "jsonb", " DEFAULT '[]'::jsonb", " NOT NULL", 

package/dist/pipeline/event-dispatcher-admin.js

@@ -1,6 +1,7 @@
 import { advanceConsumerPastEventReturning, removePendingGapReturning, selectConsumerForUpdate, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
 import { selectNextEventIdAfter, selectSmallestVisibleIdInRanges, } from "../db/queries/event-store.js";
-import { coerceRow, extractTableInfo, runInNewTransaction, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, } from "../db/query.js";
+import { coerceRow, runInNewTransaction, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, } from "../db/query.js";
+import { extractTableInfo } from "../db/table-info.js";
 import { getEventsHighWaterMark } from "../event-store/index.js";
 import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 import { mergeContiguousGapRanges, rangeContainsId, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";

package/dist/pipeline/event-dispatcher-delivery.js

@@ -3,7 +3,8 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
 import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries/event-store.js";
-import { coerceRow, extractTableInfo } from "../db/query.js";
+import { coerceRow } from "../db/query.js";
+import { extractTableInfo } from "../db/table-info.js";
 import { qnScope } from "../engine/qualified-name.js";
 import { eventsTable, toStoredEvent as rowToStoredEvent, } from "../event-store/index.js";
 import { emitDispatcherError, emitEventConsumerLag, emitEventConsumerPendingGaps, getFallbackMeter, } from "../observability/index.js";
@@ -30,10 +31,6 @@ const UNPARSEABLE_STORED_WRITE_ORIGIN = {
 export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs, maxRearmCount) {
     const rawState = await selectConsumerForUpdateSkipLocked(tx, name, instanceId);
     if (!rawState) {
-        return { state: null, skip: "not_registered" };
-    }
-    const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable));
-    if (!state) {
         // Either the row never existed (no pre-reg, no ensureRegistered) or
         // another instance currently holds the lock with SKIP LOCKED filtering
         // us out. We can't distinguish here in a single query, so return
@@ -42,6 +39,7 @@ export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs
         // this path is never taken.
         return { state: null, skip: "not_registered" };
     }
+    const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable));
     if (state.status === ConsumerStatuses.disabled)
         return { state: null, skip: "disabled" };
     if (state.status === ConsumerStatuses.dead) {
@@ -239,7 +237,7 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
 // turn (see applyBatch for why). requestId falls back to a fresh id
 // because the dispatcher runs outside any HTTP request (background poll),
 // and a stable log-correlation handle is still useful for debugging.
-// #3043 — an event this apply writes is attributed to the consumer, not
+// An event this apply writes is attributed to the consumer, not
 // to whatever wrote the triggering event; causationId already links back.
 function buildConsumerRequestScope(consumer, causationSource) {
     const correlationId = causationSource.metadata.correlationId ?? requestContext.generateId();

package/dist/pipeline/event-dispatcher.js

@@ -2,6 +2,7 @@ import { extractPgError } from "../db/pg-error.js";
 import { recordConsumerPassFailure, selectSnapshotXmax, selectSnapshotXmin, } from "../db/queries/event-consumer.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
 import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
@@ -52,15 +53,9 @@ export function createEventDispatcher(options) {
     }
     const tracer = options.tracer ?? getFallbackTracer();
     const meter = options.meter ?? getFallbackMeter();
-    // A standalone dispatcher has no logger on its context; console.error keeps the failure in pod logs.
-    const logDispatcherError = (message) => {
-        if (context.log) {
-            context.log.error(message);
-        }
-        else {
-            console.error(message);
-        }
-    };
+    // A standalone dispatcher has no logger on its context; the fallback keeps the failure in pod logs.
+    const dispatcherLog = createFallbackLogger("event-dispatcher", context.log);
+    const logDispatcherError = (message) => dispatcherLog.error(message);
     // Tracks which (consumer, instanceId) pairs already fired
     // kumiko_event_consumer_rearm_exhausted_total, so a consumer stuck dead
     // across many poll passes emits the ops-signal once, not every pass
@@ -79,7 +74,7 @@ export function createEventDispatcher(options) {
         if (count <= PENDING_GAPS_WARN_THRESHOLD || reportedLargeGapSets.has(key))
             return;
         reportedLargeGapSets.add(key);
-        logDispatcherError(`[event-dispatcher] ${consumerName} tracks ${count} pending gap ranges (> ${PENDING_GAPS_WARN_THRESHOLD}); ` +
+        logDispatcherError(`${consumerName} tracks ${count} pending gap ranges (> ${PENDING_GAPS_WARN_THRESHOLD}); ` +
             `a long-running write transaction is probably holding back the snapshot xmin`);
     };
     // Per-(consumer, instanceId) backoff after a thrown pass (see the catch in
@@ -245,13 +240,13 @@ export function createEventDispatcher(options) {
         // consumers see the same disabled-set even if an operator flips a
         // toggle mid-pass, so "this event batch" decisions stay consistent.
         //
-        // Sprint-8a tier-composition: per-tenant resolver per-pass-konsultiert
-        // mit SYSTEM_TENANT_ID. Async-events sind tier-agnostic — wenn ein
-        // Tenant downgrade'd, sollen seine queued events trotzdem verarbeitet
-        // werden (events sind immutable, projection ist eventually-consistent).
-        // Tier-cuts wirken request-time im sync-dispatcher + lifecycle-pipeline,
-        // nicht im async-replay. App-level resolver entscheidet was er bei
-        // SYSTEM_TENANT_ID returnt (typisch: union-of-all-tier-features).
+        // Tier composition: the per-tenant resolver is consulted once per pass
+        // with SYSTEM_TENANT_ID. Async events are tier-agnostic — if a tenant is
+        // downgraded, its queued events are still processed (events are immutable,
+        // and the projection is eventually consistent).
+        // Tier cuts apply at request time in the sync dispatcher and lifecycle
+        // pipeline, not during async replay. The app-level resolver decides what
+        // it returns for SYSTEM_TENANT_ID (typically: the union of all tier features).
         const effective = context.effectiveFeatures?.(SYSTEM_TENANT_ID);
         // Lock-free pre-check, once per pass: which consumers are provably idle
         // (no locking, no xid, no WAL — see selectIdleConsumerKeys). Read
@@ -275,13 +270,7 @@ export function createEventDispatcher(options) {
             if (idlePreCheckErrorLogged) {
                 idlePreCheckErrorLogged = false;
                 emitEventDispatcherListenConnected(meter, listenSubscribed);
-                const recoveredMsg = "[event-dispatcher] idle pre-check recovered, database reachable again";
-                if (context.log) {
-                    context.log.info(recoveredMsg);
-                }
-                else {
-                    console.log(recoveredMsg);
-                }
+                dispatcherLog.info("idle pre-check recovered, database reachable again");
             }
         }
         catch (e) {
@@ -297,7 +286,7 @@ export function createEventDispatcher(options) {
                 if (isConnectionLossError(e))
                     emitEventDispatcherListenConnected(meter, false);
                 const msg = e instanceof Error ? e.message : String(e);
-                const logMsg = `[event-dispatcher] idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
+                const logMsg = `idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
                 logDispatcherError(logMsg);
             }
         }
@@ -438,7 +427,7 @@ export function createEventDispatcher(options) {
             // callers and at-least-once-with-duplicate-delivery on the next pass;
             // neither is what we want, so ops needs to see it.
             const msg = e instanceof Error ? e.message : String(e);
-            logDispatcherError(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
+            logDispatcherError(`${consumer.name} pass failed: ${msg}`);
             span.setStatus("error", msg);
             // The whole pass rolled back, so markProcessing/persistConsumerOutcome
             // never committed — attempts/last_error are stuck at their pre-pass
@@ -452,7 +441,7 @@ export function createEventDispatcher(options) {
             }
             catch (persistErr) {
                 const persistMsg = persistErr instanceof Error ? persistErr.message : String(persistErr);
-                const failureMsg = `[event-dispatcher] ${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
+                const failureMsg = `${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
                 logDispatcherError(failureMsg);
             }
             // Escalate the backoff so this consumer isn't retried on the very
@@ -519,7 +508,7 @@ export function createEventDispatcher(options) {
                 catch (e) {
                     emitEventDispatcherListenConnected(meter, false);
                     const msg = e instanceof Error ? e.message : String(e);
-                    context.log?.error(`[event-dispatcher] pg LISTEN failed: ${msg}`);
+                    dispatcherLog.error("pg LISTEN failed", { err: msg });
                 }
             }
         },

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

@@ -0,0 +1,9 @@
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { MemberReader, SessionUser } from "../engine/types/index.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildAuthFacet(scope: HandlerContextScope): {
+    resolveAuthClaims: (claimsUser: SessionUser) => Promise<Record<string, unknown>>;
+    resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<import("@cosmicdrift/kumiko-types/handlers").ActiveMembershipResult>;
+    queryAsMember: MemberReader;
+    hasFeature: (featureName: string) => Promise<boolean>;
+};

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

@@ -0,0 +1,54 @@
+import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
+import { resolveAuthClaimsFn } from "./dispatch-shared.js";
+import { createMemberReaderFn } from "./member-reader.js";
+import { createGatedMemberReader, systemIdentitySwitchDenied } from "./system-identity-switch.js";
+export function buildAuthFacet(scope) {
+    const { ctx, type, user, tx, hasIdentitySwitchGrant, identitySwitchAudit } = scope;
+    const { effectiveFeatures } = ctx;
+    // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
+    // on first actual use, not on every HandlerContext build.
+    let ungatedMemberReader;
+    const queryAsMember = createGatedMemberReader(`handler "${type}"`, hasIdentitySwitchGrant, (userId, qn, payload) => {
+        ungatedMemberReader ??= createMemberReaderFn(ctx, user.tenantId, tx);
+        return ungatedMemberReader(userId, qn, payload);
+    }, { ...identitySwitchAudit, tenantId: user.tenantId });
+    return {
+        // 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) => resolveAuthClaimsFn(ctx, claimsUser), // @wrapper-known semantic-alias
+        // Thin pass-through, same reasoning as resolveAuthClaims above — one
+        // resolve impl lives on the dispatcher so callers can't drift apart.
+        // Internally queries memberships as SYSTEM, so it needs the same grant
+        // as a SYSTEM queryAs/writeAs (r.systemScope() or escapeHatch).
+        resolveActiveMembership: (userId, tenantId) => {
+            if (!hasIdentitySwitchGrant)
+                throw systemIdentitySwitchDenied(`handler "${type}"`);
+            return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY); // @wrapper-known semantic-alias
+        },
+        // Needs the same grant as a SYSTEM queryAs.
+        queryAsMember,
+        // 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.
+        //
+        // Falls back to the live trialGate when the sync set says the feature
+        // is off — the sync set never contains trial-tier features (time-
+        // derived, can't boot-cache), so without this a trial tenant checking
+        // a companion feature's toggle would silently read `false` even though
+        // the dispatch gate already lets trial-tier handlers run.
+        hasFeature: async (featureName) => {
+            if (!effectiveFeatures)
+                return true;
+            if (effectiveFeatures(user.tenantId).has(featureName))
+                return true;
+            if (!effectiveFeatures.trialGate)
+                return false;
+            return effectiveFeatures.trialGate(user.tenantId, featureName);
+        },
+    };
+}

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

@@ -0,0 +1,14 @@
+import { type TenantDb } from "../db/tenant-db.ts";
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { ConfigAccessor } from "../engine/types/index.ts";
+import { createTzContext } from "../time/index.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildConfigFacet(scope: HandlerContextScope, db: TenantDb | undefined): {
+    config: ConfigAccessor | undefined;
+    fragment: {
+        config?: ConfigAccessor | undefined;
+        configFor?: ((targetTenantId: TenantId) => ConfigAccessor) | undefined;
+    };
+};
+export declare function resolveHandlerTz(scope: HandlerContextScope, config: ConfigAccessor | undefined): Promise<ReturnType<typeof createTzContext>>;
+export declare function resolveHandlerLocale(scope: HandlerContextScope): string;

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

@@ -0,0 +1,113 @@
+import { createTenantDb } from "../db/tenant-db.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { AccessDeniedError } from "../errors/index.js";
+import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
+import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
+import { configAccessorFactoryOf } from "./config-accessor-factory.js";
+import { isSystemIdentity } from "./system-identity-switch.js";
+import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";
+// Cross-tenant accessor for SystemAdmin/system callers. The
+// identity is the target tenant's system user so the caller's own user-scope
+// values never resolve into another tenant's config; the db is tenant-mode
+// scoped to the target.
+function buildConfigFor(scope, configFactory, config) {
+    const { user, context, registry, dbSource } = scope;
+    return configFactory && dbSource
+        ? (targetTenantId) => {
+            if (targetTenantId === user.tenantId && config)
+                return config;
+            if (!isSystemIdentity(user) && !user.roles.includes("SystemAdmin")) {
+                throw new AccessDeniedError({
+                    message: "ctx.configFor(otherTenant) requires the system role or SystemAdmin",
+                    details: { reason: "config_for_requires_system_admin" },
+                });
+            }
+            const targetSystemUser = createSystemUser(targetTenantId);
+            return configFactory({
+                user: { id: targetSystemUser.id, tenantId: targetTenantId },
+                db: createTenantDb({
+                    db: dbSource,
+                    tenantId: targetTenantId,
+                    mode: "tenant",
+                    tracer: context.tracer,
+                    meter: context.meter,
+                    grants: { projectionRegistry: registry },
+                }),
+                secrets: context.secrets,
+            });
+        }
+        : undefined;
+}
+export function buildConfigFacet(scope, db) {
+    const { user, context } = scope;
+    // Mirror notify: only built when the config feature wired its factory.
+    const configFactory = configAccessorFactoryOf(context);
+    const config = configFactory && db
+        ? configFactory({
+            user: { id: user.id, tenantId: user.tenantId },
+            db,
+            secrets: context.secrets,
+        })
+        : undefined;
+    const configFor = buildConfigFor(scope, configFactory, config);
+    return { config, fragment: { ...(config && { config }), ...(configFor && { configFor }) } };
+}
+async function readTenantTimezone(scope, config) {
+    const { ctx, user, tx } = scope;
+    if (config === undefined)
+        return undefined;
+    const cachedTz = ctx.tenantTimezoneCache.get(user.tenantId);
+    if (cachedTz)
+        return cachedTz.value;
+    const generationAtRead = ctx.tenantTimezoneCache.generation();
+    const tenantTz = await config(TENANT_TIMEZONE_CONFIG_KEY);
+    if (tx === undefined) {
+        ctx.tenantTimezoneCache.setIfFresh(user.tenantId, typeof tenantTz === "string" ? tenantTz : undefined, generationAtRead);
+    }
+    return tenantTz;
+}
+// ctx.tz is always present. tenant reads tenant:config:timezone through
+// the already-built `config` accessor (raw qualified-key — no import of
+// the tenant feature, framework/pipeline stays bundled-features-free);
+// falls back to "UTC" when config is missing or the key is unset. user
+// comes from SessionUser.timezone (set at login), else falls back to
+// tenant (createTzContext's own default). An app-injected GeoTzProvider
+// (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
+//
+// Resolving this via `config()` is a config-table SELECT on every single
+// dispatch — ctx.tenantTimezoneCache memoizes it per tenant.
+// dispatch-write.ts invalidates on config:write:set/reset for this key.
+// Only populate from a tx-free read (tx === undefined): a write-path
+// lookup runs inside the caller's own open transaction, and caching a
+// value read there could memoize state from a write earlier in that same
+// transaction before it's known to commit. Reads always consult the
+// cache regardless of tx, since serving a slightly stale cached value on
+// the write path is harmless (bounded by ttlMs) and avoids reintroducing
+// the SELECT on the hot path this fix targets.
+export async function resolveHandlerTz(scope, config) {
+    const { user, context } = scope;
+    const tenantTz = await readTenantTimezone(scope, config);
+    // Guarded against garbage: an unvalidated string here (free-form config
+    // key, legacy JWT claim predating validation) blows up every ctx.tz call
+    // for the whole tenant with a RangeError. Fall back to UTC/tenant instead
+    // of trusting the raw value.
+    const safeTenantTz = typeof tenantTz === "string" && isValidIanaTimeZone(tenantTz) ? tenantTz : "UTC";
+    const safeUserTz = user.timezone !== undefined && isValidIanaTimeZone(user.timezone) ? user.timezone : undefined;
+    return createTzContext({
+        ...(context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {}),
+        ...(context.clock !== undefined ? { clock: context.clock } : {}),
+        tenant: safeTenantTz,
+        ...(safeUserTz !== undefined && { user: safeUserTz }),
+    });
+}
+// ctx.locale — request-layer signal (X-Locale header → Accept-Language,
+// resolved once at the HTTP boundary by request-id-middleware.ts) wins;
+// then SessionUser.locale (set at login — stale until re-login, same
+// tradeoff as ctx.tz.user); falls back to the app's
+// boot-configured defaultLocale, then DEFAULT_LOCALE. Mirrors ctx.tz's
+// Request → Session → Boot-Default chain.
+export function resolveHandlerLocale(scope) {
+    const { user, reqCtx, context } = scope;
+    const safeUserLocale = user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
+    return reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
+}

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

@@ -0,0 +1,24 @@
+import type { DbConnection, DbTx } from "../db/connection.ts";
+import { type TenantDb } from "../db/tenant-db.ts";
+import type { TenantId } from "../engine/types/identifiers.ts";
+import type { TenantWriteTarget } from "../engine/types/index.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export declare function buildTenantScopedDb(scope: HandlerContextScope, source: DbConnection | DbTx, signal: AbortSignal | undefined, foreignTenantId?: TenantId, denyWrites?: boolean): TenantDb;
+export declare function buildHandlerDbFacet(scope: HandlerContextScope): {
+    db: TenantDb | undefined;
+    exposedDb: TenantDb | undefined;
+    outsideTxSource: DbConnection | undefined;
+    fragment: {
+        db: TenantDb | undefined;
+        dbOutsideTransaction: TenantDb | undefined;
+        systemDb?: import("@cosmicdrift/kumiko-types/tenant-db-types").UncheckedSystemDb | undefined;
+        crossTenantReads?: import("@cosmicdrift/kumiko-types/tenant-db-types").CrossTenantReads | undefined;
+    };
+};
+export declare function buildForTenantFragment(scope: HandlerContextScope, exposedDb: TenantDb | undefined, readOnlyForTenant: boolean): {
+    forTenant?: ((targetTenantId: TenantId) => TenantWriteTarget) | undefined;
+};
+export declare function buildFileFragment(scope: HandlerContextScope, db: TenantDb | undefined): {
+    files?: import("@cosmicdrift/kumiko-types/file-handle-types").FileContext | undefined;
+    derivatives?: import("@cosmicdrift/kumiko-types/derivatives-types").DerivativesContext | undefined;
+};

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

@@ -0,0 +1,149 @@
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { isAgentToolCallScope } from "../api/request-context.js";
+import { createHandlerCrossTenantReads } from "../db/cross-tenant-reads.js";
+import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
+import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { mayOverrideTenant } from "../engine/cross-tenant.js";
+import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+import { createTenantFileContext } from "../files/file-handle.js";
+import { createSystemScopedDbGuard, isMemberResolutionPrincipal, resolveAppPoolDb, } from "./dispatch-shared.js";
+import { buildPersonalDataGate } from "./write-origin.js";
+export function buildTenantScopedDb(scope, source, signal, foreignTenantId, denyWrites = false) {
+    const { user, context, registry, origin, isSystem, writeEscapeHatch, handlerEscapeHatch } = scope;
+    return createTenantDb({
+        db: source,
+        tenantId: foreignTenantId ?? user.tenantId,
+        mode: isSystem && foreignTenantId === undefined ? "system" : "tenant",
+        tracer: context.tracer,
+        meter: context.meter,
+        signal,
+        grants: {
+            ...(foreignTenantId === undefined && {
+                globalWrites: escapeHatchFor(writeEscapeHatch, "globalWrites"),
+                unsafeRaw: escapeHatchFor(handlerEscapeHatch, "unsafeRaw"),
+            }),
+            report: scope.reportEscapeHatch,
+            memberReadOnly: isMemberResolutionPrincipal(user),
+            personalDataGate: buildPersonalDataGate(registry, origin),
+            projectionRegistry: registry,
+            ...(denyWrites && { writesDeniedReason: "without an open transaction" }),
+        },
+    });
+}
+function buildHandlerCrossTenantReads(scope) {
+    const { user, context, registry, origin, dbSource, reqCtx, handlerEscapeHatch } = scope;
+    // An agent tool call runs with the user's session but feeds the LLM context, so
+    // cross-tenant rows must never reach it, even when unsafeRaw implies the grant.
+    const crossTenantReadsReason = isAgentToolCallScope()
+        ? undefined
+        : crossTenantReadsGrantFor(handlerEscapeHatch)?.reason;
+    return dbSource && crossTenantReadsReason !== undefined
+        ? createHandlerCrossTenantReads({
+            db: dbSource,
+            tenantId: user.tenantId,
+            tracer: context.tracer,
+            meter: context.meter,
+            signal: reqCtx?.signal,
+            reason: crossTenantReadsReason,
+            report: scope.reportEscapeHatch,
+            grants: {
+                report: scope.reportEscapeHatch,
+                memberReadOnly: isMemberResolutionPrincipal(user),
+                personalDataGate: buildPersonalDataGate(registry, origin),
+                projectionRegistry: registry,
+            },
+        })
+        : undefined;
+}
+export function buildHandlerDbFacet(scope) {
+    const { ctx, type, isSystem, dbSource, reqCtx, denyDbWrites } = scope;
+    // 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.
+    const db = dbSource
+        ? buildTenantScopedDb(scope, dbSource, reqCtx?.signal, undefined, denyDbWrites)
+        : undefined;
+    // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
+    // through it survive a rollback of the handler's own transaction. No
+    // AbortSignal here: a client disconnect must not abort a durability write
+    // that is meant to outlive the request. Computed before `systemDb` below
+    // so its guarded escape hatch (ctx.systemDb.outsideTransaction) can wrap
+    // this same TenantDb instead of a second, independently-built one.
+    const outsideTxSource = ctx.outsideTransactionDb ?? resolveAppPoolDb(ctx);
+    const rawDbOutsideTransaction = outsideTxSource
+        ? buildTenantScopedDb(scope, outsideTxSource, undefined)
+        : undefined;
+    const systemDb = isSystem && db
+        ? createUncheckedSystemDb(db, rawDbOutsideTransaction, scope.reportEscapeHatch)
+        : undefined;
+    const crossTenantReads = buildHandlerCrossTenantReads(scope);
+    // Exposed as ctx.db below — the internal `db` above stays the real,
+    // working TenantDb for config/derivatives accessors and systemDb
+    // construction.
+    const exposedDb = isSystem && db
+        ? createSystemScopedDbGuard(type, "db", "ctx.systemDb.assertTenantMatch(...) or ctx.systemDb.acknowledgeCrossTenant(...)")
+        : db;
+    // Same fail-closed treatment as `exposedDb` — a system handler reaching
+    // ctx.dbOutsideTransaction directly would be a second, unguarded door to
+    // the same cross-tenant access ctx.db closes off above.
+    const dbOutsideTransaction = isSystem && rawDbOutsideTransaction
+        ? createSystemScopedDbGuard(type, "dbOutsideTransaction", "ctx.systemDb.outsideTransaction.assertTenantMatch(...) or " +
+            "ctx.systemDb.outsideTransaction.acknowledgeCrossTenant(...)")
+        : rawDbOutsideTransaction;
+    return {
+        db,
+        exposedDb,
+        outsideTxSource,
+        fragment: {
+            db: exposedDb,
+            dbOutsideTransaction,
+            ...(systemDb && { systemDb }),
+            ...(crossTenantReads && { crossTenantReads }),
+        },
+    };
+}
+// Write handlers only, and not r.systemScope() ones (they have ctx.systemDb). The gate is the
+// dispatcher's tenantIdOverride predicate, so no caller reaches more than it could via
+// tenantIdOverride. The foreign db carries no unsafeRaw/globalWrites grant and is tenant mode
+// bound to the target; the executor accepts streamTenantId only on a db bound to that tenant.
+export function buildForTenantFragment(scope, exposedDb, readOnlyForTenant) {
+    const { user, isSystem, dbSource, isWriteHandler, reqCtx, denyDbWrites, isPerCommand } = scope;
+    const forTenant = !isSystem && dbSource && isWriteHandler
+        ? (targetTenantId) => {
+            if (targetTenantId === user.tenantId && exposedDb) {
+                // Only perCommand handlers lose forTenant writes; reservations keep their pre-transaction contract.
+                const ownTenantDb = denyDbWrites && !isPerCommand
+                    ? buildTenantScopedDb(scope, dbSource, reqCtx?.signal, undefined, readOnlyForTenant)
+                    : exposedDb;
+                return { db: ownTenantDb, streamTenantId: undefined };
+            }
+            if (!mayOverrideTenant(user)) {
+                throw new AccessDeniedError({
+                    details: { reason: FrameworkReasons.tenantOverrideRequiresSystemAdmin },
+                });
+            }
+            return {
+                db: buildTenantScopedDb(scope, dbSource, reqCtx?.signal, targetTenantId, denyDbWrites && (isPerCommand || readOnlyForTenant)),
+                streamTenantId: targetTenantId,
+            };
+        }
+        : undefined;
+    return { ...(forTenant && { forTenant }) };
+}
+// 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).
+export function buildFileFragment(scope, db) {
+    const { context, registry, user } = scope;
+    const fileResolver = context._fileProviderResolver;
+    const files = fileResolver ? createTenantFileContext(fileResolver, user.tenantId) : context.files;
+    // ctx.derivatives builds on ctx.files (needs a FileContext to read the
+    // original + write the variant) plus db (to look up the FileRef row) — so
+    // it can only be constructed exactly when files+db both resolved; falls
+    // back to a statically-injected context.derivatives otherwise (tests).
+    const derivatives = files && db
+        ? createDerivativesContext({ files, registry, db, tenantId: user.tenantId })
+        : context.derivatives;
+    return { ...(files && { files }), ...(derivatives && { derivatives }) };
+}

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

@@ -0,0 +1,21 @@
+import type { WriteResult } from "../engine/types/index.ts";
+import { type HandlerTransactionScope } from "./dispatch-shared.ts";
+import { type AfterCommitHook } from "./dispatcher-utils.ts";
+import type { HandlerContextScope } from "./handler-context-scope.ts";
+export type CommitSinks = {
+    readonly bridgeSink: AfterCommitHook[];
+    readonly hasLiveCommitSink: boolean;
+    readonly notifyCommitSink: AfterCommitHook[] | undefined;
+};
+export declare function createCommitSinks(afterCommitHooks: AfterCommitHook[] | undefined, transactionScope: HandlerTransactionScope, outerNotifySink: AfterCommitHook[] | undefined): CommitSinks;
+export declare function buildDispatchFacet(scope: HandlerContextScope, sinks: CommitSinks): {
+    bridge: {
+        query: (targetType: string, payload: unknown) => Promise<unknown>;
+        queryAs: import("./system-identity-switch.ts").QueryAsFn;
+        write: (targetType: string, payload: unknown) => Promise<WriteResult>;
+        writeAs: import("./system-identity-switch.ts").WriteAsFn;
+    };
+    scheduleFragment: {
+        scheduleAfterCommit?: ((hook: AfterCommitHook) => void) | undefined;
+    };
+};