@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

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

@@ -6,8 +6,10 @@ import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries
 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";
+import { eventsTable } from "../event-store/index.js";
+import { toStoredEvent as rowToStoredEvent } from "../event-store/row-to-stored-event.js";
+import { getFallbackMeter } from "../observability/fallback.js";
+import { emitDispatcherError, emitEventConsumerLag, emitEventConsumerPendingGaps, } from "../observability/standard-metrics.js";
 import { ConsumerStatuses, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
 import { parseWriteOrigin } from "./write-origin.js";
 // Fails closed without throwing: a throw would poison the event for every consumer.
@@ -212,9 +214,11 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
                 resolve(row.id);
                 continue;
             }
-            attempts += 1;
             lastError = errMessage;
             failedEventId = row.id;
+            if (consumer.errorPolicy?.isTransientError?.(e))
+                break;
+            attempts += 1;
             if (attempts >= effectiveMaxAttempts)
                 deadLettered = true;
             break;

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

@@ -1,12 +1,13 @@
+import type { Meter, Tracer } from "@cosmicdrift/kumiko-types/observability";
 import type { PgListenClient } from "../db/connection.ts";
 import type { AppContext } from "../engine/types/index.ts";
-import { type StoredEvent } from "../event-store/index.ts";
-import { type Meter, type Tracer } from "../observability/index.ts";
+import type { StoredEvent } from "../event-store/index.ts";
 export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
 export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: AppContext) => Promise<void>;
 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

@@ -1,9 +1,11 @@
 import { extractPgError } from "../db/pg-error.js";
 import { recordConsumerPassFailure, selectSnapshotXmax, selectSnapshotXmin, } from "../db/queries/event-consumer.js";
+import { assertNoActiveRowLevelSecurityScope, runInSystemRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
+import { EVENTS_PUBSUB_CHANNEL } from "../event-store/event-store.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
+import { getFallbackMeter, getFallbackTracer } from "../observability/fallback.js";
+import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, } from "../observability/standard-metrics.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";
 import { mergeContiguousGapRanges, partitionBurntGaps, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";
@@ -16,12 +18,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 +111,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
@@ -223,7 +223,8 @@ export function createEventDispatcher(options) {
         if (!preRegistered) {
             throw new Error("EventDispatcher.runOnce() called before start() — consumer state rows are not registered. Call start() first (production) or ensureRegistered() (tests after truncating kumiko_event_consumers).");
         }
-        const pass = doPass();
+        // Per pass, never around start(): the poll loop itself must stay outside any scope.
+        const pass = runInSystemRowLevelSecurityScope("event dispatcher pass runs consumers for every tenant", doPass);
         inFlightPasses.add(pass);
         try {
             return await pass;
@@ -459,6 +460,7 @@ export function createEventDispatcher(options) {
     return {
         consumers,
         async start() {
+            assertNoActiveRowLevelSecurityScope("EventDispatcher");
             // skip: already running, idempotent
             if (running)
                 return;
@@ -493,8 +495,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/event-retention.js

@@ -1,6 +1,7 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import { lockEventConsumersShareMode } from "../db/queries/event-consumer.js";
 import { deleteMany, selectMany, transaction } from "../db/query.js";
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
 import { eventsTable } from "../event-store/index.js";
 import { eventConsumerStateTable } from "./event-consumer-state.js";
 export class ConsumerLagError extends Error {
@@ -27,64 +28,66 @@ function resolveCutoff(opts) {
     return Temporal.Now.instant().subtract({ hours: days * 24 });
 }
 export async function pruneEvents(db, options) {
-    const cutoff = resolveCutoff(options);
-    if (!options.aggregateTypes || options.aggregateTypes.length === 0) {
-        throw new Error("pruneEvents: aggregateTypes is required and must be non-empty. Pruning the event log is destructive — name the aggregate types to delete explicitly.");
-    }
-    if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
-        throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
-    }
-    if (options.batchSize !== undefined &&
-        (!Number.isInteger(options.batchSize) || options.batchSize < 1)) {
-        throw new Error("pruneEvents: batchSize must be a positive integer.");
-    }
-    const aggregateTypes = options.aggregateTypes;
-    const aggregateIds = options.aggregateIds;
-    const dryRun = options.dryRun === true;
-    return transaction(db, async (tx) => {
-        // Serialise against consumer-bootstrap INSERTs. Without this, the race
-        // is: prune reads consumers (snapshot misses a consumer bootstrapping
-        // in a parallel tx) → consumer commits its row with
-        // lastProcessedEventId=0 → prune deletes events below its new cursor
-        // → first pass of the new consumer silently skips the deleted events.
-        //
-        // SHARE is the lightest table-mode that conflicts with ROW EXCLUSIVE
-        // (the mode INSERT/UPDATE/DELETE take). Concurrent INSERTs on the
-        // consumer table queue until this TX commits; concurrent UPDATEs
-        // (cursor advances) do too, but prune is measured in milliseconds and
-        // pausing cursor advances for that window is cheap insurance against
-        // a silent data-loss bug.
-        await lockEventConsumersShareMode(tx);
-        // Step 1 — collect candidate event ids.
-        const candidates = await selectMany(tx, eventsTable, {
-            aggregateType: [...aggregateTypes],
-            ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
-            createdAt: { lt: cutoff },
-        }, options.batchSize === undefined
-            ? undefined
-            : { orderBy: { col: "id", direction: "asc" }, limit: options.batchSize });
-        if (candidates.length === 0) {
-            return { deletedCount: 0, cutoff, aggregateTypes, dryRun };
+    return runInSystemRowLevelSecurityScope("event retention pruning deletes expired events of all tenants", async () => {
+        const cutoff = resolveCutoff(options);
+        if (!options.aggregateTypes || options.aggregateTypes.length === 0) {
+            throw new Error("pruneEvents: aggregateTypes is required and must be non-empty. Pruning the event log is destructive — name the aggregate types to delete explicitly.");
         }
-        const maxCandidateId = candidates.reduce((acc, row) => (row.id > acc ? row.id : acc), candidates[0]?.id ?? 0n);
-        // Step 2 — safety guard: check every ACTIVE consumer has moved past
-        // the candidate set. Disabled consumers are intentionally excluded —
-        // ops disables them precisely to park them while pruning happens.
-        // The SHARE lock above guarantees this SELECT sees a complete view:
-        // no new consumer can INSERT a fresh-cursor row between here and the
-        // DELETE below.
-        const activeConsumers = await selectMany(tx, eventConsumerStateTable, { status: { ne: "disabled" } });
-        for (const consumer of activeConsumers) {
-            if (consumer.lastProcessedEventId < maxCandidateId) {
-                throw new ConsumerLagError(consumer.name, consumer.lastProcessedEventId, maxCandidateId);
-            }
+        if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
+            throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
         }
-        if (dryRun) {
-            return { deletedCount: candidates.length, cutoff, aggregateTypes, dryRun: true };
+        if (options.batchSize !== undefined &&
+            (!Number.isInteger(options.batchSize) || options.batchSize < 1)) {
+            throw new Error("pruneEvents: batchSize must be a positive integer.");
         }
-        // Step 3 — actual delete, bounded to the candidate set.
-        const candidateIds = candidates.map((c) => c.id);
-        await deleteMany(tx, eventsTable, { id: candidateIds });
-        return { deletedCount: candidateIds.length, cutoff, aggregateTypes, dryRun: false };
+        const aggregateTypes = options.aggregateTypes;
+        const aggregateIds = options.aggregateIds;
+        const dryRun = options.dryRun === true;
+        return transaction(db, async (tx) => {
+            // Serialise against consumer-bootstrap INSERTs. Without this, the race
+            // is: prune reads consumers (snapshot misses a consumer bootstrapping
+            // in a parallel tx) → consumer commits its row with
+            // lastProcessedEventId=0 → prune deletes events below its new cursor
+            // → first pass of the new consumer silently skips the deleted events.
+            //
+            // SHARE is the lightest table-mode that conflicts with ROW EXCLUSIVE
+            // (the mode INSERT/UPDATE/DELETE take). Concurrent INSERTs on the
+            // consumer table queue until this TX commits; concurrent UPDATEs
+            // (cursor advances) do too, but prune is measured in milliseconds and
+            // pausing cursor advances for that window is cheap insurance against
+            // a silent data-loss bug.
+            await lockEventConsumersShareMode(tx);
+            // Step 1 — collect candidate event ids.
+            const candidates = await selectMany(tx, eventsTable, {
+                aggregateType: [...aggregateTypes],
+                ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
+                createdAt: { lt: cutoff },
+            }, options.batchSize === undefined
+                ? undefined
+                : { orderBy: { col: "id", direction: "asc" }, limit: options.batchSize });
+            if (candidates.length === 0) {
+                return { deletedCount: 0, cutoff, aggregateTypes, dryRun };
+            }
+            const maxCandidateId = candidates.reduce((acc, row) => (row.id > acc ? row.id : acc), candidates[0]?.id ?? 0n);
+            // Step 2 — safety guard: check every ACTIVE consumer has moved past
+            // the candidate set. Disabled consumers are intentionally excluded —
+            // ops disables them precisely to park them while pruning happens.
+            // The SHARE lock above guarantees this SELECT sees a complete view:
+            // no new consumer can INSERT a fresh-cursor row between here and the
+            // DELETE below.
+            const activeConsumers = await selectMany(tx, eventConsumerStateTable, { status: { ne: "disabled" } });
+            for (const consumer of activeConsumers) {
+                if (consumer.lastProcessedEventId < maxCandidateId) {
+                    throw new ConsumerLagError(consumer.name, consumer.lastProcessedEventId, maxCandidateId);
+                }
+            }
+            if (dryRun) {
+                return { deletedCount: candidates.length, cutoff, aggregateTypes, dryRun: true };
+            }
+            // Step 3 — actual delete, bounded to the candidate set.
+            const candidateIds = candidates.map((c) => c.id);
+            await deleteMany(tx, eventsTable, { id: candidateIds });
+            return { deletedCount: candidateIds.length, cutoff, aggregateTypes, dryRun: false };
+        });
     });
 }

package/dist/pipeline/handler-access-error.js

@@ -1,5 +1,6 @@
 import { isAnonymousSessionUser } from "../engine/system-user.js";
-import { AccessDeniedError, UnauthenticatedError } from "../errors/index.js";
+import { UnauthenticatedError } from "../errors/classes.js";
+import { AccessDeniedError } from "../errors/index.js";
 // Anonymous callers get 401 so a client whose session lapsed (browser dropped
 // the expired auth cookie) can tell "sign in again" apart from "signed in but
 // not allowed", which stays 403.

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

@@ -1,9 +1,8 @@
-import type { TenantId } from "../engine/types/identifiers.ts";
-import type { MemberReader, SessionUser } from "../engine/types/index.ts";
+import type { MemberReader } from "@cosmicdrift/kumiko-types/handlers";
+import type { HandlerAuth } 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>;
+    readonly auth: HandlerAuth;
+    readonly queryAsMember: MemberReader;
+    readonly hasFeature: (featureName: string) => Promise<boolean>;
 };

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

@@ -12,13 +12,13 @@ export function buildAuthFacet(scope) {
         ungatedMemberReader ??= createMemberReaderFn(ctx, user.tenantId, tx);
         return ungatedMemberReader(userId, qn, payload);
     }, { ...identitySwitchAudit, tenantId: user.tenantId });
-    return {
+    const auth = {
         // 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
+        // handler via ctx.auth.resolveClaims, 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
+        resolveClaims: (claimsUser) => resolveAuthClaimsFn(ctx, claimsUser), // @wrapper-known semantic-alias
+        // Thin pass-through, same reasoning as resolveClaims 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).
@@ -27,6 +27,9 @@ export function buildAuthFacet(scope) {
                 throw systemIdentitySwitchDenied(`handler "${type}"`);
             return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY); // @wrapper-known semantic-alias
         },
+    };
+    return {
+        auth,
         // Needs the same grant as a SYSTEM queryAs.
         queryAsMember,
         // Feature-effective check for in-handler opt-in logic. Scope:

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

@@ -1,14 +1,11 @@
+import type { ConfigAccessor } from "@cosmicdrift/kumiko-types/config";
 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;
-    };
+    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

@@ -18,7 +18,7 @@ function buildConfigFor(scope, configFactory, config) {
                 return config;
             if (!isSystemIdentity(user) && !user.roles.includes("SystemAdmin")) {
                 throw new AccessDeniedError({
-                    message: "ctx.configFor(otherTenant) requires the system role or SystemAdmin",
+                    message: "ctx.tenants.config(otherTenant) requires the system role or SystemAdmin",
                     details: { reason: "config_for_requires_system_admin" },
                 });
             }
@@ -50,7 +50,7 @@ export function buildConfigFacet(scope, db) {
         })
         : undefined;
     const configFor = buildConfigFor(scope, configFactory, config);
-    return { config, fragment: { ...(config && { config }), ...(configFor && { configFor }) } };
+    return { config, configFor };
 }
 async function readTenantTimezone(scope, config) {
     const { ctx, user, tx } = scope;

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

@@ -1,23 +1,48 @@
+import type { TenantWriteTarget } from "@cosmicdrift/kumiko-types/handlers";
 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;
+    exposedDb: ({
+        readonly tenantId: TenantId;
+        readonly mode: import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbMode;
+        unsafeRaw(): import("@cosmicdrift/kumiko-types/db-connection").DbRunner;
+        global<TTable extends (import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta) & import("@cosmicdrift/kumiko-types/tenancy-brand").TenancyBrand<"global">>(table: TTable): import("@cosmicdrift/kumiko-types/tenant-db-types").GlobalTableDb<TTable>;
+        selectMany<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject, options?: import("@cosmicdrift/kumiko-types/where-clause-types").SelectOptions): Promise<readonly T[]>;
+        fetchOne<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<T | undefined>;
+        count(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<number>;
+        advisoryXactLock(namespace: number, key: string): Promise<void>;
+        databaseNow(): Promise<Date>;
+        aggregate(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, spec: import("@cosmicdrift/kumiko-types/aggregate-types").AggregateSpec, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<readonly import("@cosmicdrift/kumiko-types/aggregate-types").AggregateRow[]>;
+        upsert<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/executor-brand").WritableTable, values: Record<string, unknown>, options: import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbUpsertOptions): Promise<T | undefined>;
+    } & import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbWrites<import("@cosmicdrift/kumiko-types/executor-brand").WritableTable> & {
+        readonly outsideTransaction: TenantDb | undefined;
+    }) | undefined;
     outsideTxSource: DbConnection | undefined;
     fragment: {
-        db: TenantDb | undefined;
-        dbOutsideTransaction: TenantDb | undefined;
+        db: ({
+            readonly tenantId: TenantId;
+            readonly mode: import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbMode;
+            unsafeRaw(): import("@cosmicdrift/kumiko-types/db-connection").DbRunner;
+            global<TTable extends (import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta) & import("@cosmicdrift/kumiko-types/tenancy-brand").TenancyBrand<"global">>(table: TTable): import("@cosmicdrift/kumiko-types/tenant-db-types").GlobalTableDb<TTable>;
+            selectMany<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject, options?: import("@cosmicdrift/kumiko-types/where-clause-types").SelectOptions): Promise<readonly T[]>;
+            fetchOne<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<T | undefined>;
+            count(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<number>;
+            advisoryXactLock(namespace: number, key: string): Promise<void>;
+            databaseNow(): Promise<Date>;
+            aggregate(table: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta, spec: import("@cosmicdrift/kumiko-types/aggregate-types").AggregateSpec, where?: import("@cosmicdrift/kumiko-types/where-clause-types").WhereObject): Promise<readonly import("@cosmicdrift/kumiko-types/aggregate-types").AggregateRow[]>;
+            upsert<T = Record<string, unknown>>(table: import("@cosmicdrift/kumiko-types/executor-brand").WritableTable, values: Record<string, unknown>, options: import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbUpsertOptions): Promise<T | undefined>;
+        } & import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDbWrites<import("@cosmicdrift/kumiko-types/executor-brand").WritableTable> & {
+            readonly outsideTransaction: TenantDb | undefined;
+        }) | 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 buildWriteTarget(scope: HandlerContextScope, exposedDb: TenantDb | undefined, readOnlyForTenant: boolean): ((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

@@ -1,19 +1,19 @@
 import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
-import { isAgentToolCallScope } from "../api/request-context.js";
+import { isAgentToolCallScope } from "../api/request-context-scopes.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 { attachOutsideTransaction } from "./attach-outside-transaction.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({
+    const options = {
         db: source,
         tenantId: foreignTenantId ?? user.tenantId,
-        mode: isSystem && foreignTenantId === undefined ? "system" : "tenant",
         tracer: context.tracer,
         meter: context.meter,
         signal,
@@ -28,7 +28,14 @@ export function buildTenantScopedDb(scope, source, signal, foreignTenantId, deny
             projectionRegistry: registry,
             ...(denyWrites && { writesDeniedReason: "without an open transaction" }),
         },
-    });
+    };
+    return isSystem && foreignTenantId === undefined
+        ? createTenantDb({
+            ...options,
+            mode: "system",
+            reason: "system-scope handler dispatch reads and writes across tenants by design",
+        })
+        : createTenantDb(options);
 }
 function buildHandlerCrossTenantReads(scope) {
     const { user, context, registry, origin, dbSource, reqCtx, handlerEscapeHatch } = scope;
@@ -77,26 +84,28 @@ export function buildHandlerDbFacet(scope) {
         ? createUncheckedSystemDb(db, rawDbOutsideTransaction, scope.reportEscapeHatch)
         : undefined;
     const crossTenantReads = buildHandlerCrossTenantReads(scope);
+    // Same fail-closed treatment as `exposedDb` — a system handler reaching
+    // ctx.db.outsideTransaction directly would be a second, unguarded door to
+    // the same cross-tenant access ctx.db closes off.
+    const dbOutsideTransaction = isSystem && rawDbOutsideTransaction
+        ? createSystemScopedDbGuard(type, "db.outsideTransaction", "ctx.systemDb.outsideTransaction.assertTenantMatch(...) or " +
+            "ctx.systemDb.outsideTransaction.acknowledgeCrossTenant(...)")
+        : rawDbOutsideTransaction;
     // 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
+    const unattachedExposedDb = 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;
+    const exposedDb = unattachedExposedDb
+        ? attachOutsideTransaction(unattachedExposedDb, dbOutsideTransaction)
+        : undefined;
     return {
         db,
         exposedDb,
         outsideTxSource,
         fragment: {
             db: exposedDb,
-            dbOutsideTransaction,
             ...(systemDb && { systemDb }),
             ...(crossTenantReads && { crossTenantReads }),
         },
@@ -106,7 +115,7 @@ export function buildHandlerDbFacet(scope) {
 // 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) {
+export function buildWriteTarget(scope, exposedDb, readOnlyForTenant) {
     const { user, isSystem, dbSource, isWriteHandler, reqCtx, denyDbWrites, isPerCommand } = scope;
     const forTenant = !isSystem && dbSource && isWriteHandler
         ? (targetTenantId) => {
@@ -128,9 +137,9 @@ export function buildForTenantFragment(scope, exposedDb, readOnlyForTenant) {
             };
         }
         : undefined;
-    return { ...(forTenant && { forTenant }) };
+    return forTenant;
 }
-// ctx.files resolved per-tenant through file-foundation (lazy — the
+// ctx.services.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).
@@ -138,7 +147,7 @@ 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
+    // ctx.services.derivatives builds on ctx.services.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).

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

@@ -1,5 +1,7 @@
-import type { WriteResult } from "../engine/types/index.ts";
-import { type HandlerTransactionScope } from "./dispatch-shared.ts";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
+import type { HandlerDispatch } 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 = {
@@ -8,14 +10,20 @@ export type CommitSinks = {
     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: {
+export type DispatchFacetInput = Pick<HandlerDispatch, "queryAsMember" | "queryProjection">;
+export declare function buildDispatchFacet(scope: HandlerContextScope, sinks: CommitSinks, readers: DispatchFacetInput): {
+    dispatch: {
+        queryAsMember: import("@cosmicdrift/kumiko-types/handlers").MemberReader;
+        queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
+            readonly unsafeAllTenants?: boolean;
+        }) => Promise<readonly T[]>;
         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;
+    commitHooks: {
+        afterCommit?: ((hook: AfterCommitHook) => void) | undefined;
+        afterRollback?: ((hook: AfterRollbackHook) => void) | undefined;
     };
 };

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

@@ -1,13 +1,15 @@
+import { runWithWriteOrigin } from "../api/request-context-scopes.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 { perCommandNestedDenied } from "./handler-context-phase-denials.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.
+    // Cross-feature bridge: ctx.dispatch.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.
@@ -40,9 +42,11 @@ async function runNestedWriteInSavepoint(scope, sinks, asUser, targetType, paylo
             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;
@@ -59,11 +63,14 @@ function createSerializedNestedWriter(scope, sinks) {
         return run;
     };
 }
-export function buildDispatchFacet(scope, sinks) {
+export function buildDispatchFacet(scope, sinks, readers) {
     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
@@ -78,12 +85,18 @@ export function buildDispatchFacet(scope, sinks) {
         writeAs: writeAsUser,
     }, identitySwitchAudit);
     return {
-        bridge: {
+        dispatch: {
+            ...readers,
             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 }) },
+        commitHooks: {
+            ...(sinks.hasLiveCommitSink && { afterCommit: scheduleAfterCommit }),
+            // perCommand and no-tx paths have earlier commands already committed: nothing to compensate on rollback.
+            ...(sinks.hasLiveCommitSink &&
+                transactionScope === "inTransaction" && { afterRollback: scheduleAfterRollback }),
+        },
     };
 }