@cosmicdrift/kumiko-framework 0.389.0 → 0.390.0

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,6 +1,7 @@
-import type { WriteResult } from "../engine/types/index.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 { HandlerTransactionScope } from "./dispatch-shared.ts";
 import { type AfterCommitHook } from "./dispatcher-utils.ts";
 import type { HandlerContextScope } from "./handler-context-scope.ts";
 export type CommitSinks = {
@@ -9,15 +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;
-        scheduleAfterRollback?: ((hook: AfterRollbackHook) => void) | undefined;
+    commitHooks: {
+        afterCommit?: ((hook: AfterCommitHook) => void) | undefined;
+        afterRollback?: ((hook: AfterRollbackHook) => void) | undefined;
     };
 };

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

@@ -1,15 +1,15 @@
-import { runWithWriteOrigin } from "../api/request-context.js";
+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.
@@ -63,7 +63,7 @@ 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);
@@ -85,17 +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" && { scheduleAfterRollback }),
+                transactionScope === "inTransaction" && { afterRollback: scheduleAfterRollback }),
         },
     };
 }

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

@@ -1,41 +1,27 @@
-import type { AggregateStreamHandle, AppendEventArgs, AppendEventFn, FetchForWritingArgs, HandlerContext } from "../engine/types/index.ts";
+import type { AppendEventArgs } from "@cosmicdrift/kumiko-types/handlers";
+import type { HandlerEvents } 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";
+import { type ProjectionReader } from "./system-identity-switch.ts";
+declare function buildTryAppendEvent(scope: HandlerContextScope): (args: AppendEventArgs) => Promise<{
+    ok: true;
+    event: StoredEvent;
+    conflict?: undefined;
+} | {
+    event?: undefined;
+    ok: false;
+    conflict: EventStoreVersionConflictError;
+} | {
+    event?: undefined;
+    ok: false;
+    conflict: EventStoreIdempotentAppendConflictError;
+}>;
+type EventsFacet = Omit<HandlerEvents, "tryAppend"> & {
+    readonly tryAppend: ReturnType<typeof buildTryAppendEvent>;
+};
 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[]>;
+    readonly events: EventsFacet;
+    readonly queryProjection: ProjectionReader;
 };
+export {};