@cosmicdrift/kumiko-types 0.389.0 → 0.390.0

package/dist/config.d.ts

@@ -4,7 +4,7 @@ import type { ConfigScope } from "./config-scope.ts";
 import type { DbConnection } from "./db-connection.ts";
 import type { EntityFieldDefinition, OptionsQueryPayload } from "./fields.ts";
 import type { EscapeHatchDeclaration, JobContext, JobDeferral } from "./handlers.ts";
-import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.ts";
+import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn } from "./hooks.ts";
 import type { TenantId } from "./identifiers.ts";
 import type { NavIconKey } from "./nav-icon.ts";
 import type { DashboardCustomPanel, DashboardScreenPanel } from "./screen.ts";
@@ -283,7 +283,6 @@ export type RegistrarExtensionHooks = {
     readonly postSave?: PostSaveHookFn;
     readonly preDelete?: PreDeleteHookFn;
     readonly postDelete?: PostDeleteHookFn;
-    readonly preQuery?: PreQueryHookFn;
 };
 export type UiExtensionDef = {
     readonly editSection?: string;

package/dist/event-store-executor-types.d.ts

@@ -100,7 +100,7 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
     /** Per-call SearchAdapter override. When the
      *  executor didn't get a SearchAdapter via Options at build time
      *  (defaultEntityQueryHandler path), the caller (handler) can pass
-     *  one from ctx.searchAdapter here at runtime.
+     *  one from ctx.services.searchAdapter here at runtime.
      *  options.searchAdapter (build-time) wins — the runtime override
      *  is the fallback for the default wrapper. */
     runtimeOptions?: ListRuntimeOptions) => Promise<CursorResult<Row>>;

package/dist/event-type-map.js

@@ -1,6 +1,6 @@
 // Cross-Feature Compile-Time Type Map.
 //
-// Purpose: check ctx.appendEvent / ctx.queryProjection / dispatcher.write against a
+// Purpose: check ctx.events.append / ctx.dispatch.queryProjection / dispatcher.write against a
 // statically known schema image instead of failing only at boot or runtime
 // (zod-validate). The Designer/AI layer benefits immediately: autocomplete knows all
 // event types from all loaded features, and payload-shape mismatches appear in the

package/dist/feature-registrar.d.ts

@@ -9,7 +9,7 @@ import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-opti
 import type { BootCheckFn, MetricOptions, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableOptions, UiHints } from "./feature.ts";
 import type { EntityDefinition } from "./fields.ts";
 import type { AccessRule, AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, RateLimitDeclaration, StreamHandlerFn } from "./handlers.ts";
-import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
+import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
 import type { HttpRouteDefinition } from "./http-route.ts";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
@@ -57,11 +57,6 @@ export type HookDefinition = {
     readonly target: HookTarget;
     readonly handler: PostDeleteHookFn;
 } & HookEscapeHatch & HookPhaseOption) | ({
-    readonly type: "preQuery";
-    readonly target: RefOrRefs;
-    readonly handler: PreQueryHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
     readonly type: "postQuery";
     readonly target: HookTarget;
     readonly handler: PostQueryHookFn;
@@ -88,7 +83,7 @@ export type RequiresApi = ((options: {
  * features (apps that opt into the literal-name flavour) get propagated
  * through to `defineEvent` so the returned `EventDef.name` is a literal
  * `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`. That literal
- * threads through `ctx.appendEvent({ type: eventDef.name, ... })`,
+ * threads through `ctx.events.append({ type: eventDef.name, ... })`,
  * keeping strict-mode alive even when handlers route via `eventDef.name`
  * instead of hand-typed string literals.
  */

package/dist/feature.d.ts

@@ -4,7 +4,7 @@ import type { ConfigKeyDefinition, ConfigSeedDef, ExtensionSelectorDef, Extensio
 import type { EntityTableMeta } from "./entity-table-meta-types.ts";
 import type { EntityDefinition } from "./fields.ts";
 import type { AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, EventDef, EventMigrationDef, EventUpcastFn, QueryHandlerDef, StreamHandlerDef, WriteHandlerDef } from "./handlers.ts";
-import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn } from "./hooks.ts";
+import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn } from "./hooks.ts";
 import type { HttpRouteDefinition } from "./http-route.ts";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
@@ -228,7 +228,6 @@ export type Registry = {
     getPostSaveHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): readonly PostSaveHookFn[];
     getPreDeleteHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): readonly PreDeleteHookFn[];
     getPostDeleteHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): readonly PostDeleteHookFn[];
-    getPreQueryHooks(name: string, effectiveFeatures?: ReadonlySet<string>): readonly PreQueryHookFn[];
     getPostQueryHooks(name: string, effectiveFeatures?: ReadonlySet<string>): readonly PostQueryHookFn[];
     getEntityPostSaveHooks(entityName: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): readonly PostSaveHookFn[];
     getEntityPreDeleteHooks(entityName: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): readonly PreDeleteHookFn[];

package/dist/fields.d.ts

@@ -103,7 +103,7 @@ export type TextFieldDef = {
      *  (list/detail/write responses) show `true` = set, `null` = empty. Writes:
      *  `""` or omitted = unchanged, `null` = clear, string = new value.
      *  Server-side: executor reads (detail/list in server handlers) and
-     *  postSave/postQuery hooks see the plaintext; ctx.query, dispatcher.query,
+     *  postSave/postQuery hooks see the plaintext; ctx.dispatch.query, dispatcher.query,
      *  agent tools and `_refs` see true/null; ctx.db sees the ciphertext.
      *  Known limit: masking runs for entity-bound query handlers with array /
      *  {rows} / flat results; an unbound custom query handler that returns

package/dist/handler-context-facets.d.ts

@@ -0,0 +1,109 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import type { KumikoEventTypeMap } from "./event-type-map.ts";
+import type { HandlerLifecycle } from "./handler-context-services.ts";
+import type { ActiveMembershipResult, AggregateStreamHandle, AppendEventFn, FetchForWritingArgs, HandlerContext, MemberReader, SessionUser, TryAppendEventFn, UnsafeAppendEventFn, WriteResult } from "./handlers.ts";
+import type { TenantId } from "./identifiers.ts";
+import type { Logger } from "./logger.ts";
+import type { Meter, MetricsHandle, Tracer } from "./observability/index.ts";
+import type { TenantDb, UncheckedSystemDb } from "./tenant-db-types.ts";
+/**
+ * `ctx.db` plus `outsideTransaction`: the same tenant scoping, but never bound to the handler's
+ * tx, so writes through it survive a rollback. `undefined` only in the denial phases
+ * (member-resolution, before-transaction) and in platform-metering tenant mode; narrow with
+ * `if (ctx.db.outsideTransaction)`. For atomic multi-statement writes outside the tx use
+ * `runInOwnTransaction(ctx.db.outsideTransaction, fn)`; `fn` must not touch rows the handler's own
+ * tx has locked. For r.systemScope() handlers `ctx.db` is a fail-closed guard; use
+ * `systemDb.outsideTransaction`.
+ */
+export type HandlerDb = TenantDb & {
+    readonly outsideTransaction: TenantDb | undefined;
+};
+/** Event-store surface of a handler. TMap propagates the strict event-type-map through `append`. */
+export type HandlerEvents<TMap extends object = KumikoEventTypeMap> = {
+    /**
+     * Default append: a typed domain event on one aggregate stream in the current tx. The runtime
+     * bumps the stream version and fires matching projections in the same transaction. A version
+     * conflict throws and poisons the transaction.
+     */
+    readonly append: AppendEventFn<TMap>;
+    /**
+     * Untyped append (`payload: unknown`) with the same runtime as `append`. Only for
+     * migrations and upcasters, where the event type is not knowable at compile time.
+     */
+    readonly unsafeAppend: UnsafeAppendEventFn;
+    /**
+     * Optimistic append: runs in a savepoint and returns a version conflict as a result instead of
+     * throwing, so the handler can continue after losing a race on the same aggregate stream.
+     */
+    readonly tryAppend: TryAppendEventFn;
+    readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
+    readonly load: (aggregateId: string, options?: {
+        readonly asOf?: Temporal.Instant;
+        readonly atVersion?: never;
+    } | {
+        readonly atVersion?: number;
+        readonly asOf?: never;
+    }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
+    readonly archive: (aggregateId: string, args: {
+        readonly aggregateType: string;
+        readonly reason?: string;
+    }) => Promise<void>;
+    readonly restore: (aggregateId: string) => Promise<void>;
+    readonly isArchived: (aggregateId: string) => Promise<boolean>;
+    readonly snapshot: (args: {
+        readonly aggregateId: string;
+        readonly aggregateType: string;
+        readonly version: number;
+        readonly state: Record<string, unknown>;
+        readonly snapshotVersion?: number;
+    }) => Promise<void>;
+    readonly loadWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: import("./snapshot-types.ts").SnapshotReducer<TState>, initial: TState, options?: Omit<import("./snapshot-types.ts").LoadAggregateWithSnapshotOptions, "upcastEvent">) => Promise<import("./snapshot-types.ts").LoadAggregateWithSnapshotResult<TState>>;
+};
+/**
+ * Cross-feature bridge: `query`/`write` run the target handler AS THE CURRENT USER, sharing the
+ * active tx + afterCommit queue. `queryAs`/`writeAs` switch identity; any target other than the
+ * caller itself (or a subset of its roles) needs r.systemScope(), a job, or an escapeHatch.
+ */
+export type HandlerDispatch = {
+    readonly query: (qn: string, payload: unknown) => Promise<unknown>;
+    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly queryAsMember: MemberReader;
+    readonly queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
+        readonly unsafeAllTenants?: boolean;
+    }) => Promise<readonly T[]>;
+};
+export type HandlerAuth = {
+    readonly resolveClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
+    readonly resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
+};
+export type HandlerObservability = {
+    readonly log: Logger;
+    readonly tracer: Tracer;
+    readonly metrics: MetricsHandle;
+    readonly metricsFor: (featureName: string) => MetricsHandle;
+    readonly meter?: Meter;
+};
+export type JobEvents = Pick<HandlerEvents, "append">;
+export type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
+export type JobObservability = Pick<HandlerObservability, "log" | "metricsFor" | "meter">;
+type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
+/**
+ * ctx of `reserveBeforeTransaction`: nothing bound to the not-yet-open transaction. Reservations
+ * write on purpose through `db.outsideTransaction`, so it stays.
+ */
+export type ReservationContext<TMap extends object = KumikoEventTypeMap> = Omit<HandlerContext<TMap>, PhaseWithoutTransaction> & {
+    readonly dispatch: Omit<HandlerDispatch, "write" | "writeAs">;
+    readonly lifecycle: Omit<HandlerLifecycle, "afterCommit" | "afterRollback">;
+};
+/** ctx of `beforeTransaction`: external I/O and reads only, so the outside-transaction handles are gone too. */
+export type BeforeTransactionContext<TMap extends object = KumikoEventTypeMap> = Omit<ReservationContext<TMap>, "db" | "systemDb"> & {
+    readonly db: TenantDb & {
+        readonly outsideTransaction: undefined;
+    };
+    readonly systemDb?: Omit<UncheckedSystemDb, "outsideTransaction"> & {
+        readonly outsideTransaction: undefined;
+    };
+};
+export {};

package/dist/handler-context-facets.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,82 @@
+import type { Redis } from "ioredis";
+import type { CacheSyncBus } from "./cache-sync-types.ts";
+import type { ConfigAccessor, ConfigResolver } from "./config.ts";
+import type { DerivativesContext } from "./derivatives-types.ts";
+import type { EntityCache } from "./entity-cache.ts";
+import type { EnvelopeCipher } from "./envelope-cipher-types.ts";
+import type { FileContext } from "./file-handle-types.ts";
+import type { FileProviderResolver } from "./file-provider-resolver-types.ts";
+import type { EscapeHatchAuditSink, JobRunnerRef, NotifyFactory, NotifyFn, SessionUser, TenantWriteTarget } from "./handlers.ts";
+import type { TenantId } from "./identifiers.ts";
+import type { KmsAdapter } from "./kms-adapter-types.ts";
+import type { RateLimitResolver } from "./rate-limit-types.ts";
+import type { SearchAdapter } from "./search-adapter.ts";
+import type { MasterKeyProvider, SecretsContext } from "./secrets-types.ts";
+/**
+ * Infrastructure the app wired at boot, as the handler or job sees it. extraContext keys the
+ * framework does not know land in `extensions`.
+ */
+export type ContextServices = {
+    readonly redis?: Redis;
+    readonly cacheSync?: CacheSyncBus;
+    readonly jobRunner?: JobRunnerRef;
+    readonly searchAdapter?: SearchAdapter;
+    readonly entityCache?: EntityCache;
+    readonly secrets?: SecretsContext;
+    readonly kms?: KmsAdapter;
+    readonly files?: FileContext;
+    readonly derivatives?: DerivativesContext;
+    readonly configResolver?: ConfigResolver;
+    readonly configEncryption?: EnvelopeCipher;
+    readonly rateLimit?: RateLimitResolver;
+    readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+    readonly masterKeyProvider?: MasterKeyProvider;
+    readonly _fileProviderResolver?: FileProviderResolver;
+    readonly _notifyFactory?: NotifyFactory;
+    readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+    readonly _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+    readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
+    readonly extensions: Readonly<Record<string, unknown>>;
+};
+export type HandlerLifecycle = {
+    /**
+     * Runs the registered `preSave` hooks (and system preSave hooks) for `handlerName` and returns
+     * the hook-transformed `changes`. Entity CRUD handlers forward it to the executor; a custom
+     * `r.writeHandler` that bypasses the executor must call it itself. Undefined when no lifecycle
+     * pipeline is wired (bare stubs in unit tests).
+     */
+    readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
+    /**
+     * Queues a side-effect to run after the outermost write transaction commits (same sink as
+     * ctx.dispatch.write). Absent outside a write pipeline; callers fall back to firing immediately.
+     */
+    readonly afterCommit?: (hook: () => Promise<void>) => void;
+    /**
+     * Runs when the handler transaction (or enclosing savepoint) does not commit, also after a failed
+     * COMMIT of unknown outcome, so write it idempotent and outcome-safe. Present only inside a
+     * transaction scope.
+     */
+    readonly afterRollback?: (hook: () => Promise<void>) => void;
+    /**
+     * Cancellation. Aborts when the HTTP client disconnects. Undefined for non-HTTP entry points
+     * (jobs, MSP-applies). Long-running handlers throw `signal.throwIfAborted()` at chunk boundaries.
+     */
+    readonly signal?: AbortSignal;
+};
+export type JobLifecycle = Pick<HandlerLifecycle, "signal">;
+export type HandlerTenants = {
+    /**
+     * Config accessor resolved for ANOTHER tenant, identity = that tenant's system user. Cross-tenant
+     * calls throw AccessDeniedError unless the caller is a system identity or has the SystemAdmin
+     * role; the caller's own tenant needs no privilege. Present when the config feature wired its
+     * accessor factory.
+     */
+    readonly config?: (tenantId: TenantId) => ConfigAccessor;
+    /**
+     * Write target for ANOTHER tenant: a tenant-mode db bound to it plus the `streamTenantId` to hand
+     * the executor, so the event actor stays the operator. Cross-tenant calls throw AccessDeniedError
+     * unless the caller is SystemAdmin; the caller's own tenant yields `streamTenantId: undefined`.
+     * Write handlers only; absent for r.systemScope() handlers and without a db.
+     */
+    readonly writeTarget?: (tenantId: TenantId) => TenantWriteTarget;
+};

package/dist/handler-context-services.js

@@ -0,0 +1 @@
+export {};

package/dist/handlers.d.ts

@@ -11,11 +11,15 @@ import type { KumikoEventTypeMap } from "./event-type-map.ts";
 import type { FileContext } from "./file-handle-types.ts";
 import type { FileProviderResolver } from "./file-provider-resolver-types.ts";
 import type { GeoTzProvider } from "./geo-tz.ts";
+import type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext } from "./handler-context-facets.ts";
+import type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle } from "./handler-context-services.ts";
 import type { Logger } from "./logger.ts";
-import type { Meter, MetricsHandle, Tracer } from "./observability/index.ts";
+import type { Meter, Tracer } from "./observability/index.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { CrossTenantReads, TenantDb } from "./tenant-db-types.ts";
 import type { Clock, TzContext } from "./tz-context.ts";
+export type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext, } from "./handler-context-facets.ts";
+export type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle, } from "./handler-context-services.ts";
 export type OpenToAllPersonalData = "tenant-members";
 export type OpenToAllDeclaration = {
     readonly reason: string;
@@ -214,27 +218,12 @@ type SharedContextFields = {
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;
-    /**
-     * Config accessor resolved for ANOTHER tenant, identity = that tenant's system
-     * user (the caller's user-scope config never leaks in). Cross-tenant calls
-     * throw AccessDeniedError unless the caller is a system identity or has the
-     * SystemAdmin role; the caller's own tenant needs no privilege. Present when
-     * the config feature wired its accessor factory.
-     */
+    /** Becomes `ctx.tenants.config`. */
     readonly configFor?: (tenantId: TenantId) => ConfigAccessor;
-    /**
-     * Write target for ANOTHER tenant: a tenant-mode db bound to it plus the
-     * `streamTenantId` to hand the executor, so the event actor stays the
-     * operator. Cross-tenant calls throw AccessDeniedError unless the caller is
-     * SystemAdmin (the tenantIdOverride gate); the caller's own tenant needs no
-     * privilege and yields `streamTenantId: undefined`. Write handlers only;
-     * absent for r.systemScope() handlers and without a db.
-     */
+    /** Becomes `ctx.tenants.writeTarget`. */
     readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
     /** Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value. */
     readonly configAccessorFactory?: ConfigAccessorFactory;
-    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in 0.390.0. */
-    readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
     readonly _rateLimitPayloadDigest?: (value: string) => string;
@@ -255,11 +244,13 @@ type SharedContextFields = {
     readonly meter?: Meter;
     readonly signal?: AbortSignal;
     readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+    /** Becomes `ctx.lifecycle.afterCommit`. */
     readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+    /** Becomes `ctx.lifecycle.afterRollback`. */
     readonly scheduleAfterRollback?: (hook: () => Promise<void>) => void;
-    readonly queryAsMember?: MemberReader;
 };
 export type AppContext = SharedContextFields & {
+    readonly services?: never;
     readonly db?: DbConnection | TenantDb;
     readonly systemDb?: UncheckedSystemDb;
     readonly registry?: Registry;
@@ -285,7 +276,7 @@ export type AppContext = SharedContextFields & {
     /** Tenant of the current pipeline call. The dispatcher mirrors
      *  `user.tenantId` here when building HandlerContext so the lifecycle
      *  pipeline and system hooks can access it without the user object.
-     *  `effectiveFeatures(ctx._tenantId)` uses it at hook-filter points. */
+     *  `effectiveFeatures(ctx.user.tenantId)` uses it at hook-filter points. */
     readonly _tenantId?: TenantId;
     /** Boot-configured default locale (BCP-47). Last fallback in ctx.locale's
      *  Request-Locale → Boot-Default chain (dispatch-shared.ts) — used when
@@ -293,18 +284,8 @@ export type AppContext = SharedContextFields & {
      *  Absent falls back to "en". */
     readonly defaultLocale?: string;
 };
-export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
-    readonly db: TenantDb;
-    /**
-     * Same tenant scoping as `db`, but never bound to the handler's tx: writes through it survive
-     * a rollback. `undefined` only in the denial phases (member-resolution, before-transaction)
-     * and in platform-metering tenant mode; narrow with `hasOutsideTransactionDb(ctx)` or take it
-     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For atomic
-     * multi-statement writes outside the tx use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)`; `fn`
-     * must not touch rows the handler's own tx has locked. For
-     * r.systemScope() handlers it is a fail-closed Proxy; use `systemDb.outsideTransaction`.
-     */
-    readonly dbOutsideTransaction: TenantDb | undefined;
+export type HandlerContext<TMap extends object = KumikoEventTypeMap> = {
+    readonly db: HandlerDb;
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
     readonly registry: Registry;
@@ -314,84 +295,35 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
      *  The value is identical to `event.user`; identity switches still use
      *  `queryAs`/`writeAs`. */
     readonly user: SessionUser;
-    readonly systemUser?: SessionUser;
-    readonly log?: Logger;
-    readonly triggeredBy?: {
-        readonly id: string;
-        readonly tenantId: TenantId;
-    } | null;
     /** Keyed digest for handler-owned rate-limit keys, so Redis never holds a
      *  plaintext or plainly hashed identifier. Scoped to the running handler:
      *  the same input yields a different digest per handler and never matches a
      *  dispatcher payload-bucket digest. Absent when the app wires no digest key. */
     readonly rateLimitDigest?: (value: string) => string;
     readonly includeDeleted?: boolean;
-    readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
-    readonly query: (qn: string, payload: unknown) => Promise<unknown>;
-    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
-    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly dispatch: HandlerDispatch;
     readonly hasFeature: (featureName: string) => Promise<boolean>;
-    /**
-     * Default append: a typed domain event on one aggregate stream in the current tx. The runtime
-     * bumps the stream version and fires matching projections in the same transaction. A version
-     * conflict throws and poisons the transaction.
-     */
-    readonly appendEvent: AppendEventFn<TMap>;
-    /**
-     * Untyped append (`payload: unknown`) with the same runtime as `appendEvent`. Only for
-     * migrations and upcasters, where the event type is not knowable at compile time.
-     */
-    readonly unsafeAppendEvent: UnsafeAppendEventFn;
-    /**
-     * Optimistic append: runs in a savepoint and returns a version conflict as a result instead of
-     * throwing, so the handler can continue after losing a race on the same aggregate stream.
-     */
-    readonly tryAppendEvent: TryAppendEventFn;
-    readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
-    readonly loadAggregate: (aggregateId: string, options?: {
-        readonly asOf?: Temporal.Instant;
-        readonly atVersion?: never;
-    } | {
-        readonly atVersion?: number;
-        readonly asOf?: never;
-    }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
-    readonly archiveStream: (aggregateId: string, args: {
-        readonly aggregateType: string;
-        readonly reason?: string;
-    }) => Promise<void>;
-    readonly restoreStream: (aggregateId: string) => Promise<void>;
-    readonly isStreamArchived: (aggregateId: string) => Promise<boolean>;
-    readonly snapshotAggregate: (args: {
-        readonly aggregateId: string;
-        readonly aggregateType: string;
-        readonly version: number;
-        readonly state: Record<string, unknown>;
-        readonly snapshotVersion?: number;
-    }) => Promise<void>;
-    readonly loadAggregateWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: import("./snapshot-types.ts").SnapshotReducer<TState>, initial: TState, options?: Omit<import("./snapshot-types.ts").LoadAggregateWithSnapshotOptions, "upcastEvent">) => Promise<import("./snapshot-types.ts").LoadAggregateWithSnapshotResult<TState>>;
-    readonly queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
-        readonly unsafeAllTenants?: boolean;
-    }) => Promise<readonly T[]>;
-    readonly metrics: MetricsHandle;
-    readonly metricsFor: (featureName: string) => MetricsHandle;
-    readonly tracer: Tracer;
+    readonly events: HandlerEvents<TMap>;
+    readonly obs: HandlerObservability;
     readonly tz: TzContext;
     readonly locale: string;
-    readonly resolveAuthClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
-    readonly resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
-    readonly queryAsMember: MemberReader;
+    readonly auth: HandlerAuth;
+    readonly config?: ConfigAccessor;
+    readonly notify?: NotifyFn;
+    readonly services: ContextServices;
+    readonly lifecycle: HandlerLifecycle;
+    readonly tenants: HandlerTenants;
 };
 export type JobDeferral = {
     readonly kind: "job-deferral";
     readonly delayMs: number;
 };
-export type JobContext = SharedContextFields & {
+export type JobContext = {
     readonly db: TenantDb;
+    readonly events: JobEvents;
     readonly registry: Registry;
     readonly systemUser: SessionUser;
-    readonly log: Logger;
-    readonly metricsFor: (featureName: string) => MetricsHandle;
+    readonly obs: JobObservability;
     readonly tz: TzContext;
     readonly triggeredBy: {
         readonly id: string;
@@ -400,15 +332,17 @@ export type JobContext = SharedContextFields & {
     readonly attempt: number;
     readonly finalAttempt: boolean;
     readonly defer: (delayMs: number) => JobDeferral;
+    readonly canDefer: boolean;
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
-    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
-    readonly queryAsMember: MemberReader;
+    readonly dispatch: JobDispatch;
     readonly triggerName?: string;
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
+    readonly config?: ConfigAccessor;
+    readonly notify?: NotifyFn;
+    readonly services: ContextServices;
+    readonly lifecycle: JobLifecycle;
 };
 export type WriteHandlerFn<TPayload = unknown, TData = unknown> = (event: WriteEvent<TPayload>, context: HandlerContext) => Promise<WriteResult<TData>>;
 export type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
@@ -418,7 +352,7 @@ export type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: Quer
  * → kebab-case. Drives the literal-type of `EventDef.name`, so that
  * `r.defineEvent("foo", schema)` inside `defineFeature("driverOrders")`
  * carries `name: "driver-orders:event:foo"` as a literal — strict-mode
- * for `ctx.appendEvent({ type: eventDef.name, ... })` lights up.
+ * for `ctx.events.append({ type: eventDef.name, ... })` lights up.
  *
  * Algorithm mirrors the runtime regex pipeline:
  *   1. `.` → `-` (dot acts as word-boundary)
@@ -606,14 +540,14 @@ export type ReservationHandle = {
  *  its own short write instead of holding a second connection while the transaction is open.
  *  The returned release (or handle.release) runs when the transaction does not commit (failure
  *  result, throw, rollback, failed commit). Throwing a KumikoError rejects the write. */
-export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
+export type PreTransactionReservation = (event: WriteEvent, ctx: ReservationContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
 /** Outcome of a write handler's pre-transaction phase. `release` runs when the handler transaction does not commit (failure result, throw, rollback, failed commit with unknown outcome), so it must itself tolerate a commit that actually happened. */
 export type BeforeTransactionResult<TPrepared = unknown> = {
     readonly isSuccess: true;
     readonly data: TPrepared;
     readonly release?: ReservationRelease;
 } | WriteFailure;
-export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: HandlerContext) => Promise<BeforeTransactionResult<TPrepared>>;
+export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: BeforeTransactionContext) => Promise<BeforeTransactionResult<TPrepared>>;
 /** `perCommand`: the handler runs without a transaction of its own. */
 export type WriteHandlerTransactionMode = "perCommand";
 export type WriteHandlerDef = {
@@ -635,17 +569,17 @@ export type WriteHandlerDef = {
      *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
     readonly rateLimitCost?: (payload: unknown) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
-    /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
+    /** Reserves before the handler transaction opens. Reached through a nested ctx.dispatch.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     /** Runs after all pre-handler gates (and after reserveBeforeTransaction) and before the
      *  transaction opens: no transaction and no connection held, for external I/O and reads only.
      *  Its `data` reaches the handler as `event.prepared`; a failure result or throw rejects the
-     *  write before anything is written. A handler with this phase cannot run as a nested ctx.write.
-     *  `ctx.forTenant` is available but read-only here: its db denies writes for the own and a
+     *  write before anything is written. A handler with this phase cannot run as a nested ctx.dispatch.write.
+     *  `ctx.tenants.writeTarget` is available but read-only here: its db denies writes for the own and a
      *  foreign tenant alike (a foreign tenant stays gated by the SystemAdmin check). */
     readonly beforeTransaction?: BeforeTransactionPhase;
-    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.write/writeAs it
+    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.dispatch.write/writeAs it
      *  issues runs as its own top-level command with its own transaction and afterCommit hooks;
      *  ctx.db writes and event appends throw. It cannot run as a nested write or inside a
      *  multi-command batch, and cannot be combined with beforeTransaction/reserveBeforeTransaction. */
@@ -692,4 +626,3 @@ export type StreamHandlerDef = {
     readonly rateLimit?: RateLimitDeclaration;
     readonly escapeHatch?: EscapeHatchDeclaration;
 };
-export {};

package/dist/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { StoredEvent } from "./event-store-types.ts";
-import type { AppContext } from "./handlers.ts";
+import type { HandlerContext } from "./handlers.ts";
 import type { HookPhase } from "./hook-phase.ts";
 import type { EntityId } from "./identifiers.ts";
 export type ValidationError = {
@@ -26,23 +26,22 @@ export type DeleteContext = {
     readonly lockGuardBypassed?: boolean | undefined;
 };
 export type LifecycleResult = SaveContext | DeleteContext;
-export type PreSaveHookFn = (changes: Record<string, unknown>, context: AppContext & {
+export type PreSaveHookFn = (changes: Record<string, unknown>, context: HandlerContext & {
     readonly previous: Readonly<Record<string, unknown>>;
     readonly isNew: boolean;
 }) => Promise<Record<string, unknown>>;
-export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
-export type PostSaveBatchHookFn = (results: readonly SaveContext[], context: AppContext) => Promise<void>;
-export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-export type PostDeleteBatchHookFn = (payloads: readonly DeleteContext[], context: AppContext) => Promise<void>;
-export type PreQueryHookFn = (payload: Record<string, unknown>, context: AppContext) => Promise<Record<string, unknown>>;
+export type PostSaveHookFn = (result: SaveContext, context: HandlerContext) => Promise<void>;
+export type PostSaveBatchHookFn = (results: readonly SaveContext[], context: HandlerContext) => Promise<void>;
+export type PreDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+export type PostDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+export type PostDeleteBatchHookFn = (payloads: readonly DeleteContext[], context: HandlerContext) => Promise<void>;
 export type PostQueryHookFn = (result: {
     readonly entityName: string | undefined;
     readonly rows: ReadonlyArray<Record<string, unknown>>;
-}, context: AppContext) => Promise<{
+}, context: HandlerContext) => Promise<{
     rows: ReadonlyArray<Record<string, unknown>>;
 }>;
-export type LifecycleHookFn = PreSaveHookFn | PostSaveHookFn | PreDeleteHookFn | PostDeleteHookFn | PreQueryHookFn | PostQueryHookFn;
+export type LifecycleHookFn = PreSaveHookFn | PostSaveHookFn | PreDeleteHookFn | PostDeleteHookFn | PostQueryHookFn;
 export type { HookPhase } from "./hook-phase.ts";
 export type HookOwner = {
     readonly featureName?: string;
@@ -60,7 +59,6 @@ export type HookMap = {
     readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
     readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
     readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-    readonly preQuery?: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
     readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
 };
 export type EntityHookMap = {

package/dist/observability/metric.js

@@ -1,3 +1,3 @@
-// Metric + Meter contract. Feature code interacts through ctx.metrics
+// Metric + Meter contract. Feature code interacts through ctx.obs.metrics
 // (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
 export {};

package/dist/screen.d.ts

@@ -73,7 +73,7 @@ export interface FieldFormatRegistry {
     /** FileRef id (or id array) as a download link with the file name. On a
      *  read-only detail field it renders a file list with download links and an
      *  inline preview for PDFs; elsewhere the raw value is shown.
-     *  `previewOpenByDefault` opens the first file's PDF preview initially. */
+     *  `previewOpenByDefault` opens the newest (last) file's PDF preview initially. */
     file: {
         readonly previewOpenByDefault?: boolean;
     };

package/dist/secrets-types.js

@@ -6,7 +6,7 @@
 // but the nominal typing stops it from landing in an HTTP response by
 // accident — a response-serializer guard + the reveal() cost make the leak
 // intentional. Framework code that sees `Secret<string>` knows the caller
-// has already gone through the audited ctx.secrets.get path.
+// has already gone through the audited ctx.services.secrets.get path.
 //
 // Registered symbol, matching KUMIKO_*_SYMBOL in schema-table-types.ts. A
 // plain Symbol() is per-copy: two resolved copies of this package brand with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.389.0",
+  "version": "0.390.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/changes.json

@@ -43,7 +43,7 @@
     "type": "breaking",
     "title": "HandlerContext.outsideTransaction removed",
     "detail": "The deprecated outsideTransaction field no longer exists on HandlerContext. ctx.dbOutsideTransaction together with runInOwnTransaction replaces it.",
-    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(requireOutsideTransactionDb(ctx), fn); both are exported from @cosmicdrift/kumiko-framework/db and fn keeps its (db) => Promise signature."
+    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(requireOutsideTransactionDb(ctx), fn); both are exported from @cosmicdrift/kumiko-framework/db and fn keeps its (db) => Promise signature. Since #4031 the two helpers are internal and no longer exported from /db; narrow ctx.db.outsideTransaction directly (if (ctx.db.outsideTransaction))."
   },
   {
     "version": "0.377.0",