@cosmicdrift/kumiko-types 0.388.0 → 0.390.0

package/dist/feature.d.ts

@@ -1,20 +1,16 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TemplateVariables, TranslationKeys, TranslationsDef } from "./config.ts";
-import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.ts";
-import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
+import type { ConfigKeyDefinition, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, NotificationDefinition, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys } from "./config.ts";
 import type { EntityTableMeta } from "./entity-table-meta-types.ts";
-import type { KumikoEventTypeMap } from "./event-type-map.ts";
-import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.ts";
 import type { EntityDefinition } from "./fields.ts";
-import type { AccessRule, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, QueryHandlerDef, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef } from "./handlers.ts";
-import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.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, 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";
 import type { EntityRelations, RelationDefinition } from "./relations.ts";
 import type { ScreenDefinition } from "./screen.ts";
-import type { TreeActionDef, TreeActionsHandle } from "./tree-node.ts";
+import type { TreeActionDef } from "./tree-node.ts";
 import type { WebSocketRouteDefinition } from "./websocket-route.ts";
 import type { WorkspaceDefinition } from "./workspace.ts";
 export type FeatureMetricType = "counter" | "histogram" | "gauge";
@@ -116,7 +112,7 @@ export type BootCheckContext = {
 };
 export type BootCheckFn = (ctx: BootCheckContext) => void;
 /** runProdApp options a stack can depend on; runProdApp checks the set at boot. */
-export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "demoMode" | "seeds" | "signals" | "rateLimit";
+export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "rateLimit";
 export type StackBootRequirement = {
     readonly stack: string;
     readonly options: readonly BootOptionName[];
@@ -133,6 +129,7 @@ export type FeatureDefinition = {
     readonly requiredProjections: ReadonlySet<string>;
     readonly requiredSteps: ReadonlySet<string>;
     readonly toggleableDefault?: boolean;
+    readonly adoptsBundledLists?: true;
     readonly uiHints?: UiHints;
     readonly entities?: Readonly<Record<string, EntityDefinition>>;
     readonly entityTables?: Readonly<Record<string, unknown>>;
@@ -198,310 +195,6 @@ export type FeatureDefinition = {
     readonly envSchema?: z.ZodObject<z.ZodRawShape>;
     readonly dedupeOptions?: Readonly<Record<string, unknown>>;
 };
-type RefOrRefs = NameOrRef | readonly NameOrRef[];
-type HookTarget = RefOrRefs | {
-    readonly allOf: NameOrRef;
-};
-export type EntityObjectDefinition = {
-    readonly name: string;
-    readonly backingTable?: unknown;
-} & EntityDefinition;
-type HookEscapeHatch = {
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-type HookPhaseOption = {
-    readonly phase?: HookPhase;
-};
-export type HookDefinition = {
-    readonly type: "validation";
-    readonly target: RefOrRefs;
-    readonly handler: ValidationHookFn;
-    readonly escapeHatch?: never;
-    readonly phase?: never;
-} | ({
-    readonly type: "preSave";
-    readonly target: RefOrRefs;
-    readonly handler: PreSaveHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    readonly type: "postSave";
-    readonly target: HookTarget;
-    readonly handler: PostSaveHookFn;
-} & HookEscapeHatch & HookPhaseOption) | ({
-    readonly type: "preDelete";
-    readonly target: HookTarget;
-    readonly handler: PreDeleteHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    readonly type: "postDelete";
-    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;
-    readonly phase?: never;
-} & HookEscapeHatch);
-/**
- * `r.requires({ features })` declares the features this one depends on; the
- * `.projection` extension declares read-side projection tables that this
- * feature's pipeline steps are allowed to write via
- * `r.step.unsafeProjectionUpsert` (hard-required for any unsafeProjection-*
- * step usage, see Q10).
- *
- * @example r.requires({ features: ["auth", "tenant"] });
- */
-export type RequiresApi = ((options: {
-    readonly features: readonly string[];
-}) => void) & {
-    readonly projection: (tableName: string) => void;
-    readonly step: (stepKind: string) => void;
-};
-/**
- * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
- * default-`string` keeps every existing usage zero-config. Strict-typed
- * 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, ... })`,
- * keeping strict-mode alive even when handlers route via `eventDef.name`
- * instead of hand-typed string literals.
- */
-export type FeatureRegistrar<TFeature extends string = string> = {
-    systemScope(): void;
-    describe(text: string): void;
-    requires: RequiresApi;
-    optionalRequires(...featureNames: string[]): void;
-    optionalRequires(options: {
-        readonly features: readonly string[];
-    }): void;
-    toggleable(options: {
-        default: boolean;
-    }): void;
-    uiHints(hints: UiHints): void;
-    /**
-     * @example r.entity({ name: "note", fields: { title: createTextField({ required: true }) } });
-     */
-    entity(definition: EntityObjectDefinition): EntityRef;
-    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
-    /**
-     * @example r.writeHandler({ name: "note:archive", schema, handler, access: { roles: ["User"] } });
-     */
-    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
-    /**
-     * @example r.queryHandler({ name: "note:list", schema, handler, access: { roles: ["User"] } });
-     */
-    queryHandler<TName extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName, TSchema>): HandlerRef;
-    streamHandler<TName extends string, TSchema extends ZodType>(def: StreamHandlerDefinition<TName, TSchema>): HandlerRef;
-    streamHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: StreamHandlerFn<z.infer<TSchema>>, options: {
-        access: AccessRule;
-        rateLimit?: RateLimitDeclaration;
-        escapeHatch?: EscapeHatchDeclaration;
-    }): HandlerRef;
-    relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
-    relation<TDef extends RelationDefinition>(definition: {
-        readonly entity: NameOrRef;
-        readonly name: string;
-    } & TDef): void;
-    /**
-     * @example r.hook({ type: "postSave", target: { allOf: noteRef }, handler: notifyOwner });
-     */
-    hook(definition: HookDefinition): void;
-    searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
-    config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
-    config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
-        readonly keys: TKeys;
-        readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
-    }): {
-        readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
-    };
-    job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
-    job(definition: JobDefinition): void;
-    notification(name: string, definition: {
-        readonly trigger?: {
-            readonly on: NameOrRef;
-        };
-        readonly recipient?: NotificationRecipientFn;
-        readonly data?: NotificationDataFn;
-        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-        readonly variables?: TemplateVariables;
-        readonly record?: NotificationRecordMapping;
-        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
-        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
-        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
-        readonly renamedFrom?: readonly string[];
-        readonly systemOnly?: boolean;
-        readonly unsubscribe?: boolean;
-        readonly tenantTransport?: boolean;
-    }): void;
-    notification(definition: {
-        readonly name: string;
-        readonly trigger?: {
-            readonly on: NameOrRef;
-        };
-        readonly recipient?: NotificationRecipientFn;
-        readonly data?: NotificationDataFn;
-        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-        readonly variables?: TemplateVariables;
-        readonly record?: NotificationRecordMapping;
-        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
-        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
-        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
-        readonly renamedFrom?: readonly string[];
-        readonly systemOnly?: boolean;
-        readonly unsubscribe?: boolean;
-        readonly tenantTransport?: boolean;
-    }): void;
-    translations(def: TranslationsDef): void;
-    defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {
-        readonly version?: number;
-        readonly piiFields: EventPiiStance;
-        readonly migrations?: readonly {
-            readonly fromVersion: number;
-            readonly toVersion: number;
-            readonly transform: EventUpcastFn | DeclarativeEventMigration;
-        }[];
-    }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
-    readsConfig(...qualifiedKeys: string[]): void;
-    readsConfig(options: {
-        readonly keys: readonly string[];
-    }): void;
-    referenceData(entity: NameOrRef, data: readonly Record<string, unknown>[], options?: {
-        upsertKey?: string;
-    }): void;
-    referenceData(definition: {
-        readonly entity: NameOrRef;
-        readonly data: readonly Record<string, unknown>[];
-        readonly upsertKey?: string;
-    }): void;
-    extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
-    useExtension<N extends string>(extensionName: N, entity: NameOrRef, ...options: ExtensionOptionsArgs<N>): void;
-    useExtension<N extends string>(definition: {
-        readonly name: N;
-        readonly entity: NameOrRef;
-    } & ExtensionOptionsFor<N>): void;
-    /**
-     * Declares which config key selects the active provider under an
-     * extension point — called by the point-owning foundation (e.g.
-     * `r.extensionSelector("mailTransport", configKeys.provider)`).
-     * Readiness gating counts a provider-feature's `required` keys and
-     * secrets only while that provider is the selected one. Registry-build
-     * fails on duplicate declarations per extension and on selector keys
-     * that no mounted feature declares. A masked tenant selector key makes the
-     * Settings-Hub render one tenant dashboard for the owner: the selector as a
-     * select of the mounted plugin ids, the selected plugin's config and secrets
-     * as panels, and plugin features lose their own tenant nav. `config:write:set`
-     * rejects unknown plugin ids (`""` clears). `options.panels` adds the owner's own
-     * `custom`/`screen` panels to that dashboard, after the selection and before the
-     * plugin panels (a short `screen` id means a screen of the declaring feature).
-     */
-    extensionSelector(extensionName: string, key: {
-        readonly name: string;
-    } | string, options?: {
-        readonly panels?: readonly ExtensionSelectorPanel[];
-    }): void;
-    /**
-     * Marker declaration: this feature provides a cross-feature API under the
-     * given name. The implementation is registered separately as a query or
-     * write handler under the QN pattern; `r.exposesApi` is only a boot-check
-     * surface.
-     *
-     * The boot validator checks that every `r.usesApi(name)` finds a matching
-     * exposer, that the exposer feature is listed in requires/optionalRequires,
-     * and that no API name is exposed more than once.
-     *
-     * ```ts
-     * defineFeature("compliance-profiles", (r) => {
-     *   r.exposesApi("compliance.forTenant");
-     *   r.queryHandler({
-     *     name: "compliance:query:for-tenant",
-     *     // ... actual implementation
-     *   });
-     * });
-     * ```
-     */
-    exposesApi(apiName: string): void;
-    /**
-     * Declares that this feature calls a cross-feature API. The boot validator
-     * checks that another feature provides `r.exposesApi(apiName)` and that
-     * this feature lists it in `r.requires/optionalRequires`.
-     *
-     * ```ts
-     * defineFeature("user-data-rights", (r) => {
-     *   r.requires({ features: ["compliance-profiles"] });
-     *   r.usesApi("compliance.forTenant");
-     * });
-     * ```
-     */
-    usesApi(apiName: string): void;
-    /**
-     * Declares a boot-time mount-invariant for this feature. `fn` runs once
-     * at boot with a ctx exposing every mounted feature — throw to fail the
-     * boot with a clear message. Multiple calls per feature are allowed.
-     *
-     * Use for cross-feature invariants that `r.requires` can't express
-     * because they're conditional (only fail when the feature has a
-     * specific shape), e.g. "if this feature has PII entities, some
-     * user-data-hook feature must be mounted" (the prompt-store trap —
-     * a UserData feature was written but never mounted, and nothing caught
-     * it at boot):
-     *
-     * ```ts
-     * defineFeature("prompt-store", (r) => {
-     *   const promptFields = { text: createTextField({ personal: "self", find: "none" }) };
-     *   r.entity({ name: "prompt", fields: promptFields });
-     *   r.bootCheck(({ features }) => {
-     *     // Conditional on this feature's own shape (has a pii field) —
-     *     // r.requires({ features: ["user-data-hook"] }) can't express that, it would fail
-     *     // even for a prompt-store variant with no PII fields at all.
-     *     const hasPiiField = Object.values(promptFields).some((f) => f.pii);
-     *     const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
-     *     if (hasPiiField && !hasUserDataHook) {
-     *       throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
-     *     }
-     *   });
-     * });
-     * ```
-     */
-    bootCheck(fn: BootCheckFn): void;
-    metric(shortName: string, options: MetricOptions): void;
-    metric(definition: {
-        readonly name: string;
-    } & MetricOptions): void;
-    secret(shortName: string, options: SecretOptions): SecretKeyHandle;
-    secret(definition: {
-        readonly name: string;
-    } & SecretOptions): SecretKeyHandle;
-    secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
-    secretNamespace(definition: {
-        readonly name: string;
-    } & SecretNamespaceOptions): SecretNamespaceHandle;
-    projection(definition: ProjectionDefinition): void;
-    multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
-    extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
-    authClaims(fn: AuthClaimsFn): void;
-    claimKey<T extends ClaimKeyType>(shortName: string, options: {
-        readonly type: T;
-    }): ClaimKeyHandle<T>;
-    claimKey<T extends ClaimKeyType>(definition: {
-        readonly name: string;
-        readonly type: T;
-    }): ClaimKeyHandle<T>;
-    screen(definition: ScreenDefinition): void;
-    nav(definition: NavDefinition): void;
-    contentCollection(definition: ContentCollectionDefinition): string;
-    workspace(definition: WorkspaceDefinition): void;
-    httpRoute(definition: HttpRouteDefinition): void;
-    webSocketRoute(definition: WebSocketRouteDefinition): void;
-    storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
-    treeActions<const TActions extends Record<string, TreeActionDef>>(actions: TActions): TreeActionsHandle<TFeature, TActions>;
-    envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
-};
 export type Registry = {
     readonly features: ReadonlyMap<string, FeatureDefinition>;
     getFeature(name: string): FeatureDefinition | undefined;
@@ -535,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[];
@@ -595,4 +287,3 @@ export type Registry = {
     getDefaultWorkspace(): WorkspaceDefinition | undefined;
     getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
 };
-export {};

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 {};