@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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

@@ -7,6 +7,7 @@ export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: Ap
 export type EventConsumerErrorPolicy = {
     readonly skipApplyErrors?: boolean;
     readonly maxAttempts?: number;
+    readonly isTransientError?: (error: unknown) => boolean;
 };
 export type EventConsumer = {
     readonly name: string;

package/dist/pipeline/event-dispatcher.js

@@ -16,12 +16,10 @@ const PENDING_GAPS_WARN_THRESHOLD = 1000;
 // Only these say the database socket itself is gone; timeouts, schema or pool errors do not
 // imply the dedicated LISTEN connection dropped.
 const CONNECTION_LOSS_CODES = new Set([
-    "CONNECTION_CLOSED",
-    "CONNECTION_DESTROYED",
-    "CONNECTION_ENDED",
-    "CONNECT_TIMEOUT",
-    "ECONNREFUSED",
-    "ECONNRESET",
+    "ERR_POSTGRES_CONNECTION_CLOSED",
+    "ERR_POSTGRES_CONNECTION_REFUSED",
+    "ERR_POSTGRES_CONNECTION_TIMEOUT",
+    "ERR_POSTGRES_CONNECTION_FAILED",
     "57P01",
 ]);
 function isConnectionLossError(e) {
@@ -111,7 +109,7 @@ export function createEventDispatcher(options) {
     let pgSubscription = null;
     // Bounds how many consumer turns hold a DB transaction at once. Each turn's
     // db.begin() checks out one pool connection, plus any writes the handler
-    // itself makes via context.db — the app db pool defaults to postgres-js's
+    // itself makes via context.db — the app db pool defaults to Bun.SQL's
     // max=10 (db/connection.ts, no DATABASE_POOL_MAX override) and is shared
     // with HTTP request handlers, so turns can't be allowed to claim it all.
     // A pool no larger than this limit can deadlock: every connection held by
@@ -493,8 +491,7 @@ export function createEventDispatcher(options) {
                     const sub = await options.pgClient.listen(EVENTS_PUBSUB_CHANNEL, runBackgroundPass, () => {
                         // Fires on initial connect and again when the driver's own
                         // re-LISTEN lands after a drop; during an outage that re-LISTEN
-                        // waits in its connection backoff (postgres-js: measured 10-30s
-                        // after the DB returns), polling covers
+                        // waits in the driver's reconnect backoff, polling covers
                         // delivery meanwhile. Never unlisten()
                         // + listen() by hand: that leaves duplicate listeners.
                         // ponytail: no own LISTEN reconnect, the backoff gap is polled;

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,23 @@
+import type { WriteResult } from "../engine/types/index.ts";
+import { type AfterRollbackHook } from "./after-rollback-sink.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;
+        scheduleAfterRollback?: ((hook: AfterRollbackHook) => void) | undefined;
+    };
+};

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

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

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

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