@cosmicdrift/kumiko-framework 0.389.0 → 0.390.0

package/dist/pipeline/context-services.d.ts

@@ -0,0 +1,56 @@
+import type { AppContext, ContextServices } from "../engine/types/index.ts";
+type ServiceKey = Exclude<keyof ContextServices, "extensions">;
+export declare const APP_CONTEXT_KEY_ROLES: {
+    readonly redis: "service";
+    readonly cacheSync: "service";
+    readonly jobRunner: "service";
+    readonly searchAdapter: "service";
+    readonly entityCache: "service";
+    readonly secrets: "service";
+    readonly kms: "service";
+    readonly files: "service";
+    readonly derivatives: "service";
+    readonly configResolver: "service";
+    readonly configEncryption: "service";
+    readonly rateLimit: "service";
+    readonly effectiveFeatures: "service";
+    readonly masterKeyProvider: "service";
+    readonly _fileProviderResolver: "service";
+    readonly _notifyFactory: "service";
+    readonly _notifyInTransactionFactory: "service";
+    readonly _notifyAfterCommitFactory: "service";
+    readonly _escapeHatchAuditSink: "service";
+    readonly db: "wiring";
+    readonly systemDb: "wiring";
+    readonly registry: "wiring";
+    readonly systemUser: "wiring";
+    readonly log: "wiring";
+    readonly triggeredBy: "wiring";
+    readonly triggerName: "wiring";
+    readonly geoTzProvider: "wiring";
+    readonly clock: "wiring";
+    readonly _tenantId: "wiring";
+    readonly defaultLocale: "wiring";
+    readonly configAccessorFactory: "wiring";
+    readonly _rateLimitPayloadDigest: "wiring";
+    readonly tracer: "wiring";
+    readonly meter: "wiring";
+    readonly config: "wiring";
+    readonly configFor: "wiring";
+    readonly forTenant: "wiring";
+    readonly notify: "wiring";
+    readonly signal: "wiring";
+    readonly scheduleAfterCommit: "wiring";
+    readonly scheduleAfterRollback: "wiring";
+};
+type ServiceRoleKey = {
+    [Key in keyof typeof APP_CONTEXT_KEY_ROLES]: (typeof APP_CONTEXT_KEY_ROLES)[Key] extends "service" ? Key : never;
+}[keyof typeof APP_CONTEXT_KEY_ROLES];
+type IsSame<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
+type MustBeTrue<Value extends true> = Value;
+export type ServiceRolesMatchContextServices = MustBeTrue<IsSame<ServiceRoleKey, ServiceKey>>;
+export type ContextServiceOverrides = {
+    -readonly [Key in ServiceKey]?: ContextServices[Key];
+};
+export declare function buildContextServices(context: AppContext, overrides?: ContextServiceOverrides): ContextServices;
+export {};

package/dist/pipeline/context-services.js

@@ -0,0 +1,73 @@
+// Every AppContext key is either a service a handler or job may use, or boot wiring the framework
+// consumes itself. The satisfies clause makes a new AppContext key a compile error until it is classified.
+export const APP_CONTEXT_KEY_ROLES = {
+    redis: "service",
+    cacheSync: "service",
+    jobRunner: "service",
+    searchAdapter: "service",
+    entityCache: "service",
+    secrets: "service",
+    kms: "service",
+    files: "service",
+    derivatives: "service",
+    configResolver: "service",
+    configEncryption: "service",
+    rateLimit: "service",
+    effectiveFeatures: "service",
+    masterKeyProvider: "service",
+    _fileProviderResolver: "service",
+    _notifyFactory: "service",
+    _notifyInTransactionFactory: "service",
+    _notifyAfterCommitFactory: "service",
+    _escapeHatchAuditSink: "service",
+    db: "wiring",
+    systemDb: "wiring",
+    registry: "wiring",
+    systemUser: "wiring",
+    log: "wiring",
+    triggeredBy: "wiring",
+    triggerName: "wiring",
+    geoTzProvider: "wiring",
+    clock: "wiring",
+    _tenantId: "wiring",
+    defaultLocale: "wiring",
+    configAccessorFactory: "wiring",
+    _rateLimitPayloadDigest: "wiring",
+    tracer: "wiring",
+    meter: "wiring",
+    config: "wiring",
+    configFor: "wiring",
+    forTenant: "wiring",
+    notify: "wiring",
+    signal: "wiring",
+    scheduleAfterCommit: "wiring",
+    scheduleAfterRollback: "wiring",
+};
+function isAppContextKey(key) {
+    return Object.hasOwn(APP_CONTEXT_KEY_ROLES, key);
+}
+function isServiceKey(key) {
+    return isAppContextKey(key) && APP_CONTEXT_KEY_ROLES[key] === "service";
+}
+// The dispatcher binds these two to one call's transaction; a factory inherited from an outer
+// context must not leak into a context that has none of its own.
+const PER_CALL_FACTORY_KEYS = new Set([
+    "_notifyInTransactionFactory",
+    "_notifyAfterCommitFactory",
+]);
+function copyService(target, source, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}
+const SERVICE_KEYS = Object.keys(APP_CONTEXT_KEY_ROLES).filter(isServiceKey);
+export function buildContextServices(context, overrides = {}) {
+    const services = {};
+    for (const key of SERVICE_KEYS) {
+        if (!PER_CALL_FACTORY_KEYS.has(key))
+            copyService(services, context, key);
+        copyService(services, overrides, key);
+    }
+    const extensions = Object.fromEntries(Object.entries(context).filter(([key]) => key !== "services" && !isAppContextKey(key)));
+    return { ...services, extensions };
+}

package/dist/pipeline/dispatch-batch.d.ts

@@ -1,5 +1,6 @@
 import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
-import type { SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
+import type { SessionUser } from "../engine/types/index.ts";
 import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.ts";
 export declare function runBatch(ctx: DispatchContext, commands: readonly BatchCommand[], user: SessionUser, requestId?: string, inheritedOrigin?: WriteOrigin): Promise<BatchResult>;
 export declare function unwrapSingle(batchResult: BatchResult): WriteResult;

package/dist/pipeline/dispatch-batch.js

@@ -1,10 +1,13 @@
-import { requestContext, runWithWriteOrigin } from "../api/request-context.js";
+import { requestContext } from "../api/request-context.js";
+import { runWithWriteOrigin } from "../api/request-context-scopes.js";
 import { transaction } from "../db/query.js";
-import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { InternalError, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { toWriteErrorInfo } from "../errors/write-error-info.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { flushAfterRollback } from "./after-rollback-sink.js";
-import { resolveAppPoolDb } from "./dispatch-shared.js";
+import { runInDispatchScope } from "./dispatch-scope.js";
+import { buildHandlerContext, resolveAppPoolDb } from "./dispatch-shared.js";
 import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
@@ -33,7 +36,7 @@ async function runReservedCommand(scope, cmd, index, tx) {
     const hookStart = afterCommitHooks.length;
     // Nested-write children would run inline with the in-transaction scope, so a perCommand command skips the expansion.
     const execute = isPerCommandHandler(ctx, cmd.type) ? executeWrite : executeNestedWrite;
-    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => execute(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
+    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => runInDispatchScope(ctx.registry, [cmd.type], user, () => execute(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks))));
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }
@@ -69,14 +72,16 @@ async function runCommandsWithoutTransaction(scope, commands, results) {
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
 export async function runBatch(ctx, commands, user, requestId, inheritedOrigin) {
-    const current = requestContext.get();
-    if (!current?.signal) {
-        return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
-    }
-    // Strip the signal: a client disconnect must not roll back a write whose
-    // afterCommit effects would then be lost.
-    const { signal: _signal, ...withoutSignal } = current;
-    return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
+    return runInDispatchScope(ctx.registry, commands.map((command) => command.type), user, () => {
+        const current = requestContext.get();
+        if (!current?.signal) {
+            return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
+        }
+        // Strip the signal: a client disconnect must not roll back a write whose
+        // afterCommit effects would then be lost.
+        const { signal: _signal, ...withoutSignal } = current;
+        return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
+    });
 }
 function perCommandBatchRejection(ctx, commands) {
     const index = commands.findIndex((cmd) => isPerCommandHandler(ctx, cmd.type));
@@ -102,6 +107,7 @@ async function checkBatchIdempotency(ctx, user, requestId) {
     // corrupted cache entry — treat as miss, let the request re-run
     return parsed ? { cached: parsed } : {};
 }
+const BATCH_HOOKS_CONTEXT_TYPE = "dispatcher:batch-hooks";
 async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     const { idempotency, lifecycle, appContext: context } = ctx;
     if (commands.length === 0) {
@@ -163,7 +169,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // Fires the batch-level system hooks with every successful save/delete
     // context from this run. Called after flushAfterCommit so per-save hooks
     // have all completed first; errors are isolated inside lifecycleHooks.
-    const flushBatchHooksInner = async () => {
+    const flushBatchHooksInner = async (origin) => {
         try {
             const saves = [];
             const deletes = [];
@@ -177,10 +183,17 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
                 else if (r.data.kind === "delete")
                     deletes.push(r.data);
             }
-            if (saves.length > 0 && lifecycle)
-                await lifecycle.runPostSaveBatch(saves, context);
-            if (deletes.length > 0 && lifecycle)
-                await lifecycle.runPostDeleteBatch(deletes, context);
+            // skip: nothing to flush when there are no lifecycle hooks or no successful save/delete
+            if (!lifecycle || (saves.length === 0 && deletes.length === 0))
+                return;
+            // Post-commit context: batch hooks may write, but nothing is left to roll back.
+            const hookContext = await buildHandlerContext(ctx, BATCH_HOOKS_CONTEXT_TYPE, user, origin, {
+                transactionScope: "postCommit",
+            });
+            if (saves.length > 0)
+                await lifecycle.runPostSaveBatch(saves, hookContext);
+            if (deletes.length > 0)
+                await lifecycle.runPostDeleteBatch(deletes, hookContext);
         }
         catch (e) {
             // Batch hooks must never fail the batch — the commit already happened.
@@ -196,7 +209,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
         // skip: no command ran, so batch hooks have no saves or deletes to see
         if (!strictest)
             return;
-        await runWithWriteOrigin(strictest, flushBatchHooksInner);
+        await runWithWriteOrigin(strictest, () => flushBatchHooksInner(strictest));
     };
     const perCommandRejection = perCommandBatchRejection(ctx, commands);
     if (perCommandRejection)

package/dist/pipeline/dispatch-query.js

@@ -4,15 +4,16 @@ import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
-import { assertNoSecretLeak } from "../secrets/index.js";
+import { assertNoSecretLeak } from "../secrets/leak-guard.js";
+import { runInDispatchScope } from "./dispatch-scope.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
 import { handlerAccessError } from "./handler-access-error.js";
 import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
 // Standalone query execution — used by the public dispatcher.query() and
-// by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
+// by ctx.dispatch.query/ctx.dispatch.queryAs inside handlers. Runs the handler, applies
 // field-level read filters for the given user, logs the event.
 export async function executeQuery(ctx, type, payload, user, origin, tx, outerNotifySink) {
-    return runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink));
+    return runInDispatchScope(ctx.registry, [type], user, () => runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink)));
 }
 async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink) {
     const { registry } = ctx;
@@ -52,7 +53,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNoti
     // so other handlers never see the flag. Visibility filters still apply
     // downstream (see HandlerContext.includeDeleted) — safe from raw input.
     const includeDeleted = propertyOf(parsed.data, "includeDeleted") === true;
-    // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
+    // A resolved member (ctx.dispatch.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
     return isMemberResolutionPrincipal(user)
         ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))
         : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx, outerNotifySink);

package/dist/pipeline/dispatch-scope.d.ts

@@ -0,0 +1,6 @@
+import type { SessionUser } from "@cosmicdrift/kumiko-types/handlers";
+import { type RowLevelSecurityScope } from "../db/row-level-security-scope.ts";
+import type { Registry } from "../engine/types/index.ts";
+export declare function dispatchRowLevelSecurityScope(registry: Registry, types: readonly string[], user: SessionUser): RowLevelSecurityScope;
+export declare function runInDispatchScope<T>(registry: Registry, types: readonly string[], user: SessionUser, fn: () => T): T;
+export declare function streamInDispatchScope<T>(scope: RowLevelSecurityScope, source: AsyncGenerator<T>): AsyncGenerator<T>;

package/dist/pipeline/dispatch-scope.js

@@ -0,0 +1,27 @@
+import { runInRowLevelSecurityScope, SYSTEM_ROW_LEVEL_SECURITY_SCOPE, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
+// Handlers declared with r.systemScope() act across tenants, so a single-type dispatch of one runs system-scoped.
+// The caller picks the types of a batch, so a batch is system-scoped only when every command is; each command then
+// narrows or widens to its own type's scope (runInDispatchScope in runReservedCommand).
+export function dispatchRowLevelSecurityScope(registry, types, user) {
+    return types.length > 0 && types.every((type) => registry.isHandlerSystemScoped(type))
+        ? SYSTEM_ROW_LEVEL_SECURITY_SCOPE
+        : tenantRowLevelSecurityScope(user.tenantId);
+}
+export function runInDispatchScope(registry, types, user, fn) {
+    return runInRowLevelSecurityScope(dispatchRowLevelSecurityScope(registry, types, user), fn);
+}
+// Generator bodies resume in the consumer's async context, so each step re-enters the scope.
+export async function* streamInDispatchScope(scope, source) {
+    try {
+        while (true) {
+            const step = await runInRowLevelSecurityScope(scope, () => source.next());
+            // skip: source exhausted
+            if (step.done)
+                return;
+            yield step.value;
+        }
+    }
+    finally {
+        await runInRowLevelSecurityScope(scope, () => source.return(undefined));
+    }
+}

package/dist/pipeline/dispatch-shared.d.ts

@@ -1,4 +1,5 @@
 import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
+import type { JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { SseBroker } from "../api/sse-broker.ts";
 import type { DbConnection, DbTx } from "../db/connection.ts";
 import type { buildEntityTable } from "../db/table-builder.ts";
@@ -6,9 +7,10 @@ import { type TenantDb } from "../db/tenant-db.ts";
 import type { defineTransitions } from "../engine/state-machine.ts";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.ts";
 import type { TenantId } from "../engine/types/identifiers.ts";
-import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
-import { InternalError, type WriteErrorInfo } from "../errors/index.ts";
-import { type EscapeHatchReportWindow, type getFallbackMeter, type getFallbackTracer } from "../observability/index.ts";
+import type { AppContext, BeforeTransactionContext, HandlerContext, Registry, ReservationContext, SessionUser } from "../engine/types/index.ts";
+import { type WriteErrorInfo } from "../errors/index.ts";
+import type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.ts";
+import type { getFallbackMeter, getFallbackTracer } from "../observability/fallback.ts";
 import { type AfterCommitHook } from "./dispatcher-utils.ts";
 import type { IdempotencyGuard } from "./idempotency.ts";
 import type { LifecycleHooks } from "./lifecycle-pipeline.ts";
@@ -54,12 +56,8 @@ export type DispatchContext = {
 export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
-export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "dbOutsideTransaction", hint: string): TenantDb;
+export declare function createSystemScopedDbGuard(handlerType: string, fieldName: "db" | "db.outsideTransaction", hint: string): TenantDb;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
-export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
-export declare function perCommandNestedDenied(targetType: string): InternalError;
-export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
-export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
 export type BuildHandlerContextOptions = {
     tx?: DbTx;
@@ -67,8 +65,14 @@ export type BuildHandlerContextOptions = {
     includeDeleted?: boolean;
     transactionScope?: HandlerTransactionScope;
     outerNotifySink?: AfterCommitHook[];
-    readOnlyForTenant?: boolean;
+    phase?: HandlerPhase;
 };
+export type HandlerPhase = "handler" | "reservation" | "beforeTransaction";
+type PhaseOptions<TPhase extends HandlerPhase> = BuildHandlerContextOptions & {
+    phase: TPhase;
+};
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options: PhaseOptions<"reservation">): Promise<ReservationContext>;
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options: PhaseOptions<"beforeTransaction">): Promise<BeforeTransactionContext>;
 export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, options?: BuildHandlerContextOptions): Promise<HandlerContext>;
 export declare function createHandlerBoundDigest(digest: (value: string) => string, handlerName: string): (value: string) => string;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;