@cosmicdrift/kumiko-framework 0.397.0 → 0.399.0

package/agents/api/framework-engine.md

@@ -0,0 +1,1804 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/engine/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/engine
+
+Import from `@cosmicdrift/kumiko-framework/engine`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function assertNotificationVariables(registry: Pick<Registry, "getAllNotifications">, notificationType: string, data: Readonly<Record<string, unknown>> | undefined): void;
+function assignableAppRolesFromUsages(usages: { entityName: string; options?: Record<string, unknown> | undefined; }[]): AssignableAppRoles;
+function assignableAppRolesOf(registry: Pick<Registry, "getExtensionUsages">): AssignableAppRoles;
+function attachOutsideTransaction<T extends object, O extends object | undefined>(db: T, outsideTransaction: O): T & { outsideTransaction: O; };
+function bridgeStub(opts?: { user?: SessionUser; log?: HandlerObservability["log"]; dispatch?: Partial<HandlerDispatch>; services?: Partial<ContextServices>; }): Pick<HandlerContext, "dispatch" | "events" | "auth" | "obs" | "hasFeature" | "tz" | "locale" | "user" | "services" | "lifecycle" | "tenants">;
+function buildAppSchema(registry: Registry, options?: BuildAppSchemaOptions): AppSchema;
+function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema;
+function buildInsertSchema(entity: EntityDefinition, currencies?: string[], excludedFields?: string[], options?: { allowCallerId?: boolean; }): z.ZodObject<Record<string, z.ZodTypeAny>>;
+function buildManifestFromRegistry(registry: Registry, options: BuildManifestOptions): FeatureManifest;
+function buildPipelineSteps<TPayload, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>>(pipelineDef: PipelineDef<TPayload, unknown, TAwaits>, event: WriteEvent<TPayload>): StepInstance[];
+function buildSessionRoles(globalRoles: string[], membershipRoles: string[]): string[];
+function buildUpdateSchema(entity: EntityDefinition, currencies?: string[], excludedFields?: string[]): z.ZodObject<Record<string, z.ZodTypeAny>>;
+function canActorAssignRole(actorRoles: string[], role: string, assignableAppRoles?: AssignableAppRoles): boolean;
+function collectCardMetaOverflow(features: FeatureDefinition[]): CardMetaOverflow[];
+function collectWriteHandlerQns(features: FeatureDefinition[]): Set<string>;
+function compareVersions(a: string, b: string): number;
+function computeDefinitionFingerprint<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>>(workflow: Pick<WorkflowDefinition<TPayload, TData, TAwaits>, "name" | "trigger" | "pipelineDef">): string; // Snapshot-at-Start fingerprint.
+function computeEffectiveFeatures(registry: Registry, readToggle: ToggleReader): ReadonlySet<string>;
+function createAnonymousUser(tenantId: TenantId): SessionUser;
+function createBigIntField<R extends true | false = false>(overrides?: Partial<Omit<BigIntFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): BigIntFieldDef & { required: R; };
+function createBooleanField<R extends true | false = false>(overrides?: Partial<Omit<BooleanFieldDef, "type" | "required">> & { required?: R; }): BooleanFieldDef & { required: R; default: boolean; };
+function createDateField<R extends true | false = false>(overrides?: Partial<Omit<DateFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): DateFieldDef & { required: R; };
+function createDecimalField<R extends true | false = false>(config: { precision: number; scale: number; } & Partial<Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): DecimalFieldDef & { required: R; };
+function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef; // Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
+function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & { multiple: true; };
+function createEntity<const F, const T extends EntityTenancy = "tenant">(def: { table?: string; fields: F; description?: string; softDelete?: boolean; systemStream?: boolean; eventVersion?: number; eventMigrations?: EntityDefinition["eventMigrations"]; searchWeight?: number; defaultCurrency?: string; transitions?: Readonly<Record<string, Readonly<Record<string, string[]>>>>; lockedWhen?: EntityDefinition["lockedWhen"]; indexes?: EntityIndexDef[]; idType?: "serial" | "uuid"; access?: EntityDefinition["access"]; parentRef?: EntityDefinition["parentRef"]; retention?: RetentionDef; derivedFields?: EntityDefinition["derivedFields"]; tenancy?: T; transferable?: boolean; attachedFileAccess?: EntityDefinition["attachedFileAccess"]; }): F extends FieldsMap ? EntityDefinition<F, T> : never;
+function createEntityExecutor<E extends EntityDefinition>(entityName: string, entity: E): { table: EntityTable; executor: EventStoreExecutor<EntityRow<E>>; };
+function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
+function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
+function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImageFieldDef;
+function createImagesField(overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImagesFieldDef;
+function createJsonbField(overrides?: Partial<Omit<JsonbFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): JsonbFieldDef;
+function createLocatedTimestampField<R extends true | false = false>(overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): LocatedTimestampFieldDef & { required: R; }; // Wall-clock time at a place as one atomic field.
+function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & { required?: R; }): EntityLongTextFieldDef & { required: R; };
+function createMoneyField<R extends true | false = false>(overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & { required?: R; }): MoneyFieldDef & { required: R; };
+function createMultiSelectField<const TOptions extends string[]>(opts: { options: TOptions; } & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): MultiSelectFieldDef<TOptions>; // Multi-select field — N values from a fixed option list.
+function createNumberField<R extends true | false = false>(overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): NumberFieldDef & { required: R; }; // Numeric field — `double precision` column by default (fractional values allowed end to end).
+function createRegistry(rawFeatures: FeatureDefinition[]): Registry;
+function createSeed(opts: CreateSeedOptions): ConfigSeedDef;
+function createSelectField<const TOptions extends string[], R extends true | false = false>(opts: { options: TOptions; } & Partial<Omit<SelectFieldDef<NoInfer<TOptions>>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): SelectFieldDef<TOptions> & { required: R; };
+function createSystemConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+function createSystemSeed(opts: CreateSeedOptions): ConfigSeedDef;
+function createSystemUser(tenantId: TenantId, extraRoles?: string[]): SessionUser;
+function createTenantConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+function createTenantSeed(opts: CreateSeedOptions, options?: CreateTenantSeedOptions): ConfigSeedDef;
+function createTextField<R extends true | false = false>(overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotations & { required?: R; }): EntityTextFieldDef & { required: R; };
+function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TimestampFieldDef & { required: R; }; // UTC instant for events occurring at a specific point in time (createdAt, loginAt, actualPickupAt).
+function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & { required?: R; }): TzFieldDef & { required: R; }; // IANA time-zone name (for example, "Europe/Berlin").
+function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+function declareEscapeHatch(declaration: EscapeHatchDeclaration): void;
+function dedupeFeatures(features: FeatureDefinition[]): FeatureDefinition[];
+function defineApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>): SingleStreamApplyFn;
+function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+function defineFeature<const TName extends string, TExports = undefined>(name: TName, setup: (r: FeatureRegistrar<TName>) => TExports, settings?: DefineFeatureSettings): FeatureDefinition & { exports: TExports; };
+function defineMspApply<TPayload = Record<string, unknown>>(fn: (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>): MultiStreamApplyFn;
+function definePagedQueryHandler<const TName extends string, TSchema extends ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap>, ..._noSecretInResponse: true extends ContainsSecret<CursorResult<TRow>> ? [ secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field." ] : [ ]): PagedQueryHandlerDefinition<TName, TSchema, TRow, TMap>;
+function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: { access: AccessRule; unsafeAllTenants?: boolean | { reason: string; }; escapeHatch?: EscapeHatchDeclaration; }): QueryHandlerDef;
+function defineQueryHandler<const TName extends string, TSchema extends ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TResult> ? [ secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field." ] : [ ]): QueryHandlerDefinition<TName, TSchema, TResult, TMap>;
+function defineRoles<const T extends string[]>(roles: T): RoleMap<T>;
+function defineStep<TArgs, TResult>(def: StepDef<TArgs, TResult>): StepDef<TArgs, TResult>;
+function defineTransitions<const TMap extends Record<string, string[]>>(map: TMap): TransitionGraph<keyof TMap & string>; // Defines allowed state transitions.
+function defineWorkflow<TPayload = unknown, TData = unknown, const TAwaits extends Record<string, string> = Record<string, string>>(input: WorkflowInput<TPayload, TData, TAwaits>): WorkflowDefinition<TPayload, TData, TAwaits>; // Define a suspendable workflow.
+function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared, TWhenNested>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [ secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field." ] : [ ]): WriteHandlerDefinition<TName, TSchema, TData, TMap, TPrepared, TWhenNested>;
+function describeWorkflowStepError(error: unknown): string;
+function emitEvent<TPayload>(ctx: EmitCtx, eventDef: EventDef<TPayload>, args: { aggregateId: string; aggregateType: string; payload: TPayload; headers?: AppendEventArgs["headers"]; }): Promise<void>;
+function entityHasAnonymizableSubjectField(fields: EntityDefinition["fields"]): boolean;
+function evaluateEventMatch(match: EventMatch, payload: unknown): boolean;
+function extensionSelectorTargets(registry: Pick<Registry, "getAllExtensionSelectors">): ReadonlyMap<string, string>;
+function extensionUsageEscapeHatchReason(usage: Pick<RegistrarExtensionRegistration, "options">): string | undefined;
+function fieldToZod(field: FieldDefinition, currencies: string[], opts?: { applyDefaults?: boolean; isUpdate?: boolean; }): z.ZodTypeAny;
+function filterEntriesAfter(entries: ChangelogEntry[], version: string): ChangelogEntry[];
+function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
+function findForbiddenMembershipRole(roles: string[]): string | undefined;
+function findForbiddenRoleAssignment(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles?: AssignableAppRoles): string | undefined;
+function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: string[]): string[] | undefined;
+function findTierResolverUsage(features: FeatureDefinition[]): RegistrarExtensionRegistration | undefined;
+function from(ref: OwnershipRef, column?: string): FromRule;
+function getStep(kind: StepKind): StepDef | undefined;
+function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void; // Asserts a state transition is allowed.
+function handlerFieldLabelKey(handlerQn: string, fieldName: string): string;
+function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;
+function handlerTitleKey(handlerQn: string): string;
+function hasAccess(user: Pick<SessionUser, "roles">, access: AccessRule | undefined): boolean;
+function i18nKey(value: string): string;
+function isAgentVisibleScreen(screen: { agent?: AgentScreenHints; }): boolean; // Screens are the inverse of handlers: the manifest lists every role-visible screen regardless of `description`, so only an explicit opt-out hides one.
+function isAssignableByRole(assignableFrom: AssignableFromRole, actorRole: AssignableFromRole): boolean; // True when `actorRole` ranks at least as high as the role an app role is assignable from.
+function isDeliveryErrorCode(value: unknown): value is DeliveryErrorCode;
+function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
+function isFieldsEditSection(section: EditSectionSpec): section is EditFieldsSection;
+function isOpenToAllGranted(rule: AccessRule): boolean;
+function isSystemTenant(tenantId: TenantId | null | undefined): boolean;
+function isTenantDataExtensionHooks(o: unknown): o is TenantDataExtensionHooks;
+function isTenantResourceExtensionHooks(o: unknown): o is TenantResourceExtensionHooks;
+function isTierResolverPlugin(v: unknown): v is TierResolverPlugin; // Narrows a registration's untyped `options` bag to the tier-resolver plugin shape — the only thing every implementation must provide is the `build` factory.
+function isToggleableFeature(feature: FeatureDefinition): feature is FeatureDefinition & { toggleableDefault: boolean; };
+function isUuid(value: unknown): value is string;
+function isValidQn(value: string): boolean;
+function maskWriteOnlyFields<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, row: T): T;
+function mayOverrideTenant(user: SessionUser): boolean;
+function mergeAssignedRoles(actorRoles: string[], assignedRoles: string[], targetCurrentRoles: string[], assignableAppRoles: AssignableAppRoles): string[];
+function normalizeAccessEntry(entry: OwnershipMap | string[] | undefined): OwnershipMap | undefined;
+function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string>;
+function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string>;
+function pageRows<TRow extends Readonly<Record<TSortField, PagedListRowValue>> & { id: string; }, TSortField extends string>(rows: TRow[], request: PagedListRequest<TSortField>, options: { searchFields: TSortField[]; defaultSort: TSortField; }): CursorResult<TRow>;
+function pagedListSchema<const TSortField extends string>(sortableFields: [ TSortField, ...TSortField[] ]): …;
+function parseChangesetChanges(markdown: string, source: string): PendingChange[]; // Parse structured upgrade metadata embedded in a Changeset body.
+function parseFeatureChangelog(raw: string, featureName: string): FeatureChangelog | null; // Parse a changes.json body.
+function parseQn(value: string): ParsedQn;
+function parseRefTarget(raw: string, currentFeature: string): ParsedRefTarget;
+function parseRefTargetEntityName(raw: string): string;
+function parseTenantId(value: unknown): TenantId | null;
+function projectAppSchemaForRoles(schema: AppSchema, roles: string[]): AppSchema;
+function qn(scope: string, type: QnType, name: string): string;
+function readClaim<T extends ClaimKeyType>(user: SessionUser, handle: ClaimKeyHandle<T>): ClaimKeyJsType<T> | undefined;
+function referenceGroupLabels(ctx: HandlerContext, user: SessionUser, sourceTableName: string, groupByField: string, keys: AggregateKey[], db: TenantDb): Promise<ReadonlyMap<string, string>>;
+function requireTierResolverPlugin(usage: RegistrarExtensionRegistration): TierResolverPlugin;
+function resolveAgentExposure(def: { description?: string; agent?: AgentHandlerHints; }, kind: "query" | "write"): AgentExposure; // Fail-closed: a handler without a `description` stays invisible to the agent unless it opts in explicitly.
+function resolveEntityTransferAdjacency(entities: ReadonlyMap<string, EntityDefinition>, rootEntityType?: string): TransferAdjacency;
+function runPipeline<TPayload, TData, TMap extends object = KumikoEventTypeMap>(pipelineDef: PipelineDef<TPayload, TData>, event: WriteEvent<TPayload>, handlerCtx: HandlerContext<TMap>, workflow?: PipelineCtx["workflow"], resumeFrom?: number): Promise<WriteResult<TData>>;
+function runStepList<TPayload, TMap extends object = KumikoEventTypeMap>(steps: StepInstance[], event: WriteEvent<TPayload>, handlerCtx: HandlerContext<TMap>, stepsAcc: Record<string, unknown>, scopeAcc: Record<string, unknown>, workflow?: PipelineCtx["workflow"], resumeFrom?: number): Promise<StepListOutcome>; // Walk a step-list.
+function sectionFieldSpecs(section: FieldsOrGroupsSection): EditFieldSpec[];
+function selectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
+function serializeManifest(manifest: FeatureManifest): string;
+function setFields(table: ProjectionTable, fields: Record<string, unknown> | ((event: Parameters<SingleStreamApplyFn>[0]) => Record<string, unknown>)): SingleStreamApplyFn;
+function stepsPipeline<TPayload = unknown, TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>>(closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => StepInstance[]): PipelineDef<TPayload, TData, TAwaits>;
+function templateVariablesToZod(variables: TemplateVariables): z.ZodObject;
+function tenantChannel(tenantId: TenantId): string;
+function toKebab(input: string): string;
+function typedPayload<TPayload>(event: { type: string; payload: Record<string, unknown>; }, eventDef: EventDef<TPayload>): TPayload;
+function unwrapWorkflowStepError(error: unknown): unknown;
+function validateAppCustomScreenWriteQns(appRoot: string, knownQns: ReadonlySet<string>): void; // Boot-time scan of app `src/**` for `dispatcher.write("…")` string literals.
+function validateBoot(rawFeatures: FeatureDefinition[], options?: ValidateBootOptions): void; // Validates all feature configurations at boot time.
+function validateBundledListsOptions(options: unknown): void;
+function walkStepInstances(steps: StepInstance[], where: string): Generator<StepInstance, void, void>;
+function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>; // Server counterpart of an actionForm's `derive`: recomputes the derived head fields before the schema validates them, so client-sent totals never count.
+function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T>; // Override the success-side `data` of a WriteResult while forwarding the failure half untouched.
+```
+
+## Constants
+
+```ts
+const ANONYMOUS_ROLE: "anonymous";
+const ANONYMOUS_USER_ID: "anonymous";
+const BUILT_IN_MEMBERSHIP_ROLES: string[]; // Every membership role the engine ranks, excluding the internal `system` actor.
+const CODEMOD_PLACEHOLDER_REASON_MARKER: "state the operator use case here";
+const ConfigScopes: { system: "system"; tenant: "tenant"; user: "user"; };
+const DEFAULT_CURRENCIES: ["EUR", "USD", "GBP", "CHF", "JPY", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "NZD", "CNY", "INR"];
+const DEFAULT_LOCALES: ["de", "en", "es"];
+const DELIVERY_FAILURE_CODES;
+const DELIVERY_SKIP_REASONS: ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
+const EXT_ASSIGNABLE_ROLE: "assignableRole"; // `assignableRole` — an app declares a membership role as assignable: `r.useExtension(EXT_ASSIGNABLE_ROLE, "<RoleName>", { assignableFrom?
+const EXT_DERIVATIVE_OVERLAY_RESOLVER: "derivativeOverlayResolver"; // `derivativeOverlayResolver` — per-entityType "resolve this overlay dataToken to its real value" contract for `file-derivatives`' overlay compositing (QR codes on a public variant).
+const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate"; // `derivativePublicPredicate` — per-entityType "is this FileRef's derivative publicly readable?" gate for the anonymous variant route (file-derivatives).
+const EXT_DERIVATIVE_RENDERER: "derivativeRenderer"; // `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection (file-derivatives).
+const EXT_EXTERNAL_RESOURCE: "externalResource"; // `externalResource` — external-service tenant-destroy hook (webhook subscriptions, Brevo recipient lists, provider customer accounts).
+const EXT_FILE_PROVIDER: "fileProvider"; // `fileProvider` — file-storage provider plugin selection (file-foundation).
+const EXT_INFRA_RESOURCE: "infraResource"; // `infraResource` — Pulumi-managed per-tenant resource tenant-destroy hook (custom domain, cert-manager issuer, dedicated pod/volume).
+const EXT_PRINCIPAL_STATUS: "principalStatus"; // `principalStatus` — "is this principal blocked from signing in" contract, consulted by the active-membership building block; fulfilled by the bundled `user` feature.
+const EXT_SEARCH_ADAPTER: "searchAdapter"; // `searchAdapter` — search-index tenant-destroy hook (Meilisearch index cleanup on tenant-destroy).
+const EXT_STORAGE_PROVIDER: "storageProvider"; // `storageProvider` — file-storage-plugin tenant-destroy hook.
+const EXT_TENANT_DATA: "tenantData"; // `tenantData` — per-entity tenant-destroy hooks (GDPR + end of data processing agreement).
+const EXT_TENANT_LIFECYCLE_STATUS: "tenantLifecycleStatus"; // `tenantLifecycleStatus` — tenant-teardown status contract, fulfilled by the bundled `tenant-lifecycle` feature; absent means no tenant is ever "in teardown".
+const EXT_USER_DATA: "userData"; // `userData` — user-data rights hooks (GDPR Articles 15, 17, and 20).
+const EXT_USER_DATA_ORDER: { REDACT_BEFORE_OWNER: -100; DEFAULT: 0; };
+const FILE_PROVIDER_CONFIG_KEY: "file-foundation:config:provider";
+const FILE_STORAGE_PROVIDER_BOOT_SENTINEL: "configured";
+const FILE_STORAGE_PROVIDER_ENV: "FILE_STORAGE_PROVIDER";
+const HTTP_ERROR_CODE_PATTERN: RegExp;
+const HookPhases: { inTransaction: "inTransaction"; afterCommit: "afterCommit"; };
+const LifecycleHookTypes: { preSave: "preSave"; postSave: "postSave"; preDelete: "preDelete"; postDelete: "postDelete"; postQuery: "postQuery"; };
+const MAX_LIST_LIMIT: 200;
+const MAX_TRANSFER_DEPTH: 5;
+const PII_DIRECT_NAME_HINTS: ReadonlySet<string>;
+const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string>;
+const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
+const QnTypes: { write; query; hook; job; notify; event; channel; config; secret; screen; nav; probe };
+const SECURITY_BASELINE_FEATURE_NAMES: ["sessions", "crypto-shredding", "rate-limiting", "audit"];
+const SELECTED_EXTENSIONS_QUERY: "config:query:config-value:selected-extensions";
+const SETTINGS_HUB_FEATURE: "config";
+const STEP_DISPATCHED_TYPE: "kumiko:system:step.dispatched";
+const STEP_DISPATCH_AGGREGATE_TYPE: "step-dispatch";
+const STEP_DISPATCH_FAILED_TYPE: "kumiko:system:step.dispatch-failed";
+const STEP_DISPATCH_REQUESTED_TYPE: "kumiko:system:step.dispatch-requested";
+const SYSTEM_ONLY_JSON_SCHEMA_KEY: "x-kumiko-system-only";
+const SYSTEM_ROLE: "system";
+const SYSTEM_TENANT_ID: TenantId;
+const SYSTEM_USER_ID: "00000000-0000-0000-0000-000000000000";
+const TENANT_CURRENCY_CONFIG_KEY: "tenant-settings:config:currency"; // Qualified config key a `{ kind: "tenant" }` MoneyCurrencySource resolves against — the tenant-settings bundle's per-tenant currency.
+const TENANT_MEMBERSHIPS_QUERY: "tenant:query:memberships";
+const TENANT_TIER_RESOLVER_EXT: "tenantTierResolver"; // Extension name under which a tier-resolver plugin must be registered in the registry.
+const WORKFLOW_AGGREGATE_TYPE: "workflow-run";
+const WORKFLOW_RESUMED_TYPE: "kumiko:system:workflow.step.resumed";
+const WORKFLOW_RETRY_SCHEDULED_TYPE: "kumiko:system:workflow.retry.scheduled";
+const WORKFLOW_RUN_COMPLETED_TYPE: "kumiko:system:workflow.run-completed";
+const WORKFLOW_RUN_FAILED_TYPE: "kumiko:system:workflow.run-failed";
+const WORKFLOW_RUN_STARTED_TYPE: "kumiko:system:workflow.run-started";
+const WORKFLOW_SYSTEM_EVENT_DEFS: ReadonlyMap<string, EventDef>;
+const WORKFLOW_WAITING_FOR_EVENT_TYPE: "kumiko:system:workflow.step.waiting-for-event";
+const WORKFLOW_WAITING_TYPE: "kumiko:system:workflow.step.waiting";
+const access: { all; admin; systemAdmin; system; privileged; authenticated; anonymous; roles; withSystem };
+const entityListSchema;
+const templateVariable: { text; link; richText; money; date; percent; images; list };
+```
+
+## Classes
+
+```ts
+class ProbeFailure extends Error {
+  constructor(text: ProbeText);
+}
+class WorkflowStepError extends Error {
+  constructor(stepIndex: number, cause: unknown);
+}
+```
+
+## Types
+
+```ts
+type AccessRule = RoleAccessRule | OpenToAllAccessRule;
+type ActionFormScreenDefinition = {
+  id: string;
+  type: "actionForm";
+  fillHeight?: boolean; // Default true: the screen fills the shell content height, its body scrolls inside and the pager / action bar stays pinned.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  urlPrefillFields?: string[]; // Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields.
+  writeExcludedFields?: string[]; // Derived by buildAppSchema from the `excludedFields` of the called `handler`; the form shows these fields read-only, not required and never in the payload.
+  submitPrefilled?: boolean; // Submit is enabled without edits: values seeded from navigate `params` count as the user's intent.
+  handler: string; // Write-handler QN called on submit.
+  fields: Readonly<Record<string, FormFieldDefinition>>; // Form shape: field map by name.
+  derive?: Readonly<Record<string, FormFieldDerivation>>; // Fields computed from other fields, shown read-only and recomputed on every change.
+  layout: EditLayout; // Layout analogous to EntityEditScreen: sections with fields from the fields map above.
+  fieldLabels?: Readonly<Record<string, string>>; // Per-field label i18n key override, same type/semantics as `EntityEditScreenDefinition.fieldLabels`.
+  submitLabel?: string; // i18n key for the submit button.
+  footerActions?: ActionFormFooterAction[]; // Extra buttons in the form footer next to the submit button.
+  summary?: {
+    title: string;
+    subtitle?: string;
+  }; // Context box above the fields (i18n keys).
+  submitStyle?: "primary" | "danger"; // Visual style of the submit button.
+  successMessage?: string; // i18n key of a confirmation shown above the form after a successful submit when the screen stays put (no `redirect`, not drawer-hosted).
+  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful submit: either a short ID (e.g. "item-list" — same feature, the nav-router resolves to the full path) or a fully-qualified cross-feature QN (`<feature>:screen:<id>`).
+  successLinks?: ActionFormSuccessLink[]; // Links shown in the success box after a successful submit while the screen stays put.
+  successFacts?: ActionFormSuccessFact[]; // Key figures from the handler's success payload, shown in the success box while the screen stays put (e.g. charged/skipped/failed of a batch run).
+  resetOnSuccess?: boolean; // Reset the form to its initial values after a successful submit (prefill kept, typed values cleared).
+  load?: ActionFormLoad; // Load the initial values from a query.
+  cancelTarget?: string | false; // Target of the Cancel button.
+  listScreenId?: string; // Parent list screen (short id) for breadcrumb + nav highlighting when this screen has no nav entry of its own.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type AgentHandlerHints = { // Per-handler hints for the AI-agent manifest.
+  expose?: boolean;
+  risk?: AgentRisk;
+};
+type AgentRisk = "low" | "mid" | "high";
+type AppContext = SharedContextFields & {
+  services?: never;
+  db?: DbConnection | TenantDb;
+  systemDb?: UncheckedSystemDb;
+  registry?: Registry;
+  systemUser?: SessionUser;
+  log?: Logger;
+  triggeredBy?: { id: string; tenantId: TenantId; } | null;
+  triggerName?: string; // For job-handler calls triggered by an event (`r.job` with `trigger: { on: ...
+  geoTzProvider?: GeoTzProvider; // Optional Geo→zone adapter.
+  clock?: Clock; // Overrides the system clock behind ctx.tz in handlers and jobs; tests inject a fixed time.
+  _tenantId?: TenantId; // Tenant of the current pipeline call.
+  defaultLocale?: string; // Boot-configured default locale (BCP-47).
+};
+type AssignableAppRoles = ReadonlyMap<string, AssignableFromRole>; // App role → lowest built-in role allowed to assign it.
+type AuthClaimsContext = {
+  db: TenantDb;
+  queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  config?: ConfigAccessor;
+};
+type AwaitedEventType = string & {
+  __awaitedEvent: unique symbol;
+};
+type BeforeTransactionContext<TMap extends object = KumikoEventTypeMap> = Omit<ReservationContext<TMap>, "db" | "systemDb"> & { // ctx of `beforeTransaction`: external I/O and reads only, so the outside-transaction handles are gone too.
+  db: TenantDb & { outsideTransaction: undefined; };
+  systemDb?: Omit<UncheckedSystemDb, "outsideTransaction"> & { outsideTransaction: undefined; };
+};
+type BeforeTransactionResult<TPrepared = unknown> = // Outcome of a write handler's pre-transaction phase.
+  | {
+    isSuccess: true;
+    data: TPrepared;
+    release?: ReservationRelease;
+  }
+  | WriteFailure
+;
+type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "rateLimit"; // runProdApp options a stack can depend on; runProdApp checks the set at boot.
+type BundledListsOptions = { // One `table` block for every entityList, projectionList and relatedList of the bundled features.
+  table: ListTableOptions;
+  pinFirstColumn?: boolean; // Pins the first column left on every bundled list where no column is pinned.
+};
+type ChangelogEntry = {
+  version: string;
+  type: ChangelogType;
+  title: string;
+  detail?: string;
+  migration?: string; // Required when type=breaking.
+  codemod?: string; // Path (relative to packages/feature-ast/src/, under scripts/codemod/) run by `kumiko upgrade --apply`.
+  manualAfterCodemod?: boolean; // The codemod only covers part of the migration: the entry is also recorded as pending manual work after it ran.
+};
+type ChatSendFailureCode = `http_${number}` | Exclude<DeliveryFailureCode, "render_failed" | "send_failed" | "channel_error">;
+type ClaimKeyType = "string" | "number" | "boolean" | "string[]" | "object";
+type ConfigAccessor = {
+  (qualifiedKey: string): Promise<string | number | boolean | undefined>;
+  <T extends ConfigKeyType>(handle: ConfigKeyHandle<T>): Promise<ConfigValue<T> | undefined>;
+};
+type ConfigAccessorFactory = (deps: { user: { id: string; tenantId: TenantId; }; db: DbConnection | TenantDb; secrets?: ConfigSecretsReader; }) => ConfigAccessor;
+type ConfigCascade = {
+  value: string | number | boolean | undefined;
+  source: ConfigValueSource;
+  levels: ConfigCascadeLevel[];
+};
+type ConfigCascadeLevel = {
+  label: string;
+  value: string | number | boolean | undefined;
+  source: ConfigValueSource;
+  isActive: boolean;
+  hasValue: boolean;
+};
+type ConfigEditScreenDefinition = {
+  id: string;
+  type: "configEdit";
+  fillHeight?: boolean; // Default true: the form fills the shell content height with a pinned footer.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  scope: "tenant" | "system" | "user"; // scope for config:write:set calls.
+  configKeys: Readonly<Record<string, string>>; // Map: form field name (short, as referenced in the layout) → fully qualified config key (`<feature>:config:<short>`).
+  secretKeys?: Readonly<Record<string, string>>; // Field name → qualified secret key (`<feature>:secret:<short>`), tenant scope only.
+  fields: Readonly<Record<string, FieldDefinition>>; // Form shape per field name.
+  layout: EditLayout; // Layout: sections with field refs.
+  fieldLabels?: Readonly<Record<string, string>>; // Optional per-field label i18n key (field name → key).
+  fieldDescriptions?: Readonly<Record<string, string>>; // Per-field help text i18n key (Field-Name → Key), from `mask.description`.
+  requiredFields?: string[]; // Field names whose config key declares `required: true` — drives the "Not set.
+  submitLabel?: string; // i18n key for the submit button.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
+  type: T;
+  default?: ConfigValue<T>;
+  scope: ConfigScope;
+  access: ConfigKeyAccess;
+  encrypted?: boolean;
+  piiEncrypted?: boolean; // User/admin may legitimately see the value — unlike `encrypted` (shared master-key cipher), this is the subject-KMS: the value is encrypted under the DEK of the scope actually written to (tenant-row → tenant subject, user-row → user subject).
+  options?: string[];
+  optionsQuery?: string; // Only on `type: "select"`: loads the options from this query (QN), contract `{ rows: { value, label, description?, group?
+  optionsQueryPayload?: OptionsQueryPayload; // Payload sent with every `optionsQuery` call.
+  bounds?: ConfigBounds;
+  pattern?: {
+    regex: string;
+    flags?: string;
+  };
+  computed?: ConfigComputedFn<T>;
+  validate?: ConfigValidateFn<T>;
+  allowPerRequest?: boolean;
+  required?: boolean;
+  env?: string;
+  inheritedToTenant?: boolean;
+  backing?: ConfigBacking;
+  mask?: ConfigMask;
+  group?: string;
+};
+type ConfigKeyHandle<T extends ConfigKeyType = ConfigKeyType> = {
+  name: string;
+  type: T;
+};
+type ConfigKeyType = "text" | "number" | "boolean" | "select";
+type ConfigResolver = {
+  get(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<string | number | boolean | undefined>;
+  getWithSource(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ConfigValueWithSource>;
+  getAll(tenantId: TenantId, userId: string, db: DbConnection | TenantDb): Promise<ReadonlyMap<string, ConfigStoredRow>>;
+  getCascade(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ConfigCascade>;
+  getCascadeBatch(keys: string[], keyDefs: ReadonlyMap<string, ConfigKeyDefinition>, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ReadonlyMap<string, ConfigCascade>>;
+};
+type ConfigScope = "system" | "tenant" | "user";
+type ConfigSecretsReader = {
+  get(tenantId: TenantId, key: string): Promise<{ reveal: () => string; } | undefined>;
+};
+type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
+type ConfigValue<T extends ConfigKeyType> = T extends "number" ? number : T extends "boolean" ? boolean : T extends "text" | "select" ? string : never;
+type ConfigValueSource = "user-row" | "tenant-row" | "system-row" | "app-override" | "computed" | "default" | "missing";
+type ConfigValueWithSource = {
+  value: string | number | boolean | undefined;
+  source: ConfigValueSource;
+};
+type ContentCollectionDefinition = {
+  id: string;
+  kind: string;
+  access?: AccessRule;
+  ownership?: "tenant" | "user";
+  contentFormat?: ContentEditorFormat;
+  variableSchema?: Readonly<Record<string, string>>;
+  nav: {
+    label: string;
+    icon?: NavIconKey;
+    parent?: string;
+    order?: number;
+    access?: AccessRule;
+    workspaces?: string[];
+    createAction?: TreeAction;
+    actions?: TreeAction[];
+  };
+};
+type DashboardCustomPanel = {
+  kind: "custom";
+  id: string;
+  component: PlatformComponent;
+  params?: Readonly<Record<string, unknown>>; // Static author values laid over the screen's filterParams, like `DashboardPanelQueryOptions.params`; the panel wins on a name clash.
+};
+type DashboardI18nText = { // Text a query handler can send untranslated: the renderer translates it.
+  i18nKey: string;
+  i18nParams?: Readonly<Record<string, DashboardTextParam>>;
+};
+type DeleteContext = {
+  kind: "delete";
+  id: EntityId;
+  data: Readonly<Record<string, unknown>>;
+  entityName?: string | undefined;
+  event: StoredEvent;
+  lockGuardBypassed?: boolean | undefined;
+};
+type DeliveryErrorCode = DeliveryFailureCode | DeliverySkipReason | `http_${number}`;
+type DeliveryFailureCode = (typeof DELIVERY_FAILURE_CODES)[number];
+type DeliverySkipReason = (typeof DELIVERY_SKIP_REASONS)[number];
+type DeriveContext = { // Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a derive body (no-date-api guard + testability).
+  asOf: Temporal.Instant;
+};
+type EditFieldSpec =
+  | string
+  | {
+    field: string;
+    span?: number;
+    visible?: FieldCondition;
+    readOnly?: FieldCondition;
+    required?: FieldCondition;
+    renderer?: FieldRenderer;
+    submit?: false; // `false` keeps the field out of the submitted payload — for values that are shown or prefilled for display only (a label, a counter) and that the write handler's schema does not accept.
+    icon?: FieldIconKey; // Prefix icon on the input — closed FieldIconKey vocabulary into the FIELD_ICONS registry (renderer/web), analogous to `ScreenNavSugar.icon` / NavIconKey.
+    placeholder?: string; // Input placeholder (i18n key, falls back to the literal).
+    prefix?: FieldAffix; // Static text shown before the input (i18n key, falls back to the literal), or `{ field }` for the current form value of another field (a hidden field carrying e.g. a base domain).
+    suffix?: FieldAffix; // Same as `prefix`, shown after the input.
+    fillAction?: FieldFillAction; // Button beside the input that runs a query and writes one scalar of its result into this field.
+    refEntity?: string; // Marks this field as a reference lookup instead of a plain value — for projectionDetail fields, which have no `EntityDefinition` to carry a real `reference` field type.
+    refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
+    embeddedList?: EmbeddedListEditSpec; // Embedded-list fields only (`createEmbeddedListField`).
+    prefill?: EditFieldPrefill; // Fills an empty value when the create form opens; the update form and values from URL params or a handoff are never touched.
+  }
+;
+type EditRelatedListSection = {
+  id?: string; // Kebab-case tab id, used as the `?tab=` value.
+  kind: "relatedList";
+  title: string;
+  query: string; // Fully qualified query QN.
+  parentParam?: string; // Query-payload key the parent record's id is passed under.
+  parentFilter?: {
+    field: string;
+  }; // Server-side WHERE clause pinning this section to the parent record — sent as `payload.filter: { field, op: "eq", value: parentId }`, kept out of the user-facet `filters` array so it can't be cleared by facet interaction.
+  columns: ListColumnSpec[];
+  entity?: string; // Entity the query's rows belong to: an entity name (same feature) or `feature:entity`.
+  description?: string; // i18n key for the one-line hint at the left of the tab toolbar.
+  itemNoun?: string; // i18n key holding plural forms for the footer count ("1 Position", "3 Positionen").
+  pageSize?: number;
+  table?: ListTableOptions; // Opt-in table behaviour: remembered state, reset, column picker, density.
+  defaultSort?: ListSortSpec; // Initial sort on mount, applied client-side over the already-loaded rows (this section has no pager; if the fetch is truncated, `nextCursor !== null`, the section shows a hint banner that the sort covers only the loaded rows).
+  searchable?: boolean; // Renders a search box whose debounced term rides along as `payload.search` on this section's own query.
+  facets?: ListFacetSpec[]; // User-toggleable facet dropdowns — same explicit-label `ListFacetSpec` as `projectionList.facets` (a relatedList has no entity to derive filterable fields from).
+  rowClick?: {
+    entity: string;
+    idColumn?: string;
+  }; // Row click opens the target entity's detail screen via ObjectTarget — the `detailFor` lookup owns the entity→screen mapping, so no screenId is named here.
+  rowActions?: RowAction[]; // Per-row actions — same type and dispatch semantics as `entityList`/ `projectionList`'s `rowActions` (writeHandler dispatch with a declarative `payload` extractor, or navigate).
+  rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
+  bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
+  rowTone?: RelatedListRowTone; // Tints rows whose field matches — a declarative rule, not a function, so the screen definition stays serializable.
+  toolbarActions?: RelatedListToolbarAction[]; // Toolbar actions above the table — same type and dispatch semantics as `entityList`/`projectionList`'s `toolbarActions` ("+ Anlegen" etc.), plus `visible`/`params` evaluated against the parent record (see RelatedListToolbarAction).
+  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the parent record.
+  emptyState?: RelatedListEmptyStateSpec; // Rendered inside the section's Card in place of the table when this section's query returns zero rows.
+};
+type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
+type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & { // Resolver callback shape: synchronous (on the dispatcher's hot path), per tenant.
+  trialGate?: TrialGate; // Optional live-trial gate, consulted by the dispatcher feature gate ONLY when the synchronous resolver reports a feature as disabled.
+};
+type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy = EntityTenancy> = {
+  table?: string;
+  fields: F;
+  softDelete?: boolean;
+  tenancy?: T; // "tenant" (default): auto-filtered by every db accessor.
+  systemStream?: boolean; // This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the creator's tenant.
+  eventVersion?: number; // Schema version stamped on every lifecycle event (default 1, integer 1..999).
+  eventMigrations?: EntityEventMigration[]; // One step per version, fromVersion → fromVersion+1.
+  searchWeight?: number;
+  defaultCurrency?: string;
+  lockedWhen?: FieldCondition; // Rows whose stored state meets this condition are read-only: every executor update and delete on them is rejected with a 409 (`errors.recordLocked`), whatever handler or job calls it.
+  transitions?: Readonly<Record<string, TransitionMap>>; // Allowed state transitions per field.
+  indexes?: EntityIndexDef[]; // Composite indexes over multiple fields.
+  idType?: "serial" | "uuid"; // Entity primary-key type.
+  access?: {
+    read?: OwnershipMap;
+    write?: OwnershipMap;
+  }; // Row-level ownership rules (H.2).
+  parentRef?: ParentRefDef; // Join-row carrier reference.
+  retention?: RetentionDef; // Default retention policy for this entity.
+  derivedFields?: DerivedFieldsMap; // Read-time computed fields, keyed by name.
+  description?: string; // Optional free-text semantics for the AI agent manifest — see TextFieldDef.description.
+  transferable?: boolean; // Opts the rows into `tenant-handover`, a grant-legitimated move from an anonymous tenant to the signed-up account's tenant.
+  attachedFileAccess?: "record-only"; // Attached files are readable only through the record's detail query: the files feature's privilegedRoles do not bypass it, the uploader check stays.
+};
+type EntityEditScreenDefinition = {
+  id: string;
+  type: "entityEdit";
+  fillHeight?: boolean; // Default true: the screen fills the shell content height, its body scrolls inside and the pager / action bar stays pinned.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  urlPrefillFields?: string[]; // Derived by buildAppSchema from the navigate `params` targeting this screen — the only URL query keys the create form prefills.
+  writeExcludedFields?: EntityWriteExcludedFields; // Derived by buildAppSchema from the entity's create/update write handlers (`excludeFields`): create hides these fields, update shows them read-only.
+  entity: string;
+  recordTitleField?: string; // Entity field whose value names the loaded record in the header breadcrumb (edit mode only).
+  titleTemplate?: string; // Screen title (i18n key) with `{field}` placeholders filled from the current form values, so the title follows what the user types (create wizard: "Add {make} {model}").
+  readOnly?: FieldCondition; // Shows a saved record read-only while the condition holds for the loaded record (not for unsaved form values): all fields disabled, no save, discard or delete button; record `actions` stay.
+  layout: EditLayout;
+  submitLabel?: string; // Optional i18n key (or raw string) for the submit button.
+  allowCreate?: boolean; // Default true.
+  allowDelete?: boolean; // Default true.
+  singleton?: boolean; // Default false.
+  redirect?: string | ActionFormRedirect; // Navigate to this screen ID after a successful save (create or update).
+  listScreenId?: string; // Parent list screen (short id) for breadcrumb + nav highlighting when this screen has no nav entry of its own.
+  fieldLabels?: Readonly<Record<string, string>>; // Optional per-field label i18n key (field name → key), overrides the default convention `<feature>:entity:<entity>:field:<name>`.
+  actions?: EntityEditAction[]; // Record actions.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type EntityId = number | string;
+type EntityListScreenDefinition = {
+  id: string;
+  type: "entityList";
+  fillHeight?: boolean; // Default true: the screen fills the shell content height, its body scrolls inside and the pager / action bar stays pinned.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  entity: string;
+  createScreen?: string; // Short screen id (same feature) the create button opens instead of the entity's default edit screen.
+  createUnavailable?: boolean; // Set by the role projection when `createScreen` is not reachable for the role: the renderer then shows no create button instead of falling back to the entity's edit screen.
+  allowCreate?: boolean; // `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action.
+  columns: ListColumnSpec[];
+  rowRenderer?: PlatformComponent;
+  cardRenderer?: PlatformComponent;
+  rowActions?: RowAction[]; // Per-row actions, rendered as an actions column on the right.
+  rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
+  bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
+  toolbarActions?: ToolbarAction[]; // Toolbar actions (list header).
+  expandableRow?: EntityListExpandableRow; // Expandable area under each row: a relatedList of the row's record (parentId = the row's `id`).
+  filter?: ScreenFilter; // Server-side filter, fixed on the screen — three buckets of the same entity without custom pages (e.g. "Upcoming" / "Active" / "Past" Maintenance).
+  pagination?: ListPaginationMode;
+  pageSize?: number;
+  table?: ListTableOptions; // Opt-in table behaviour: remembered state, reset, column picker, density.
+  defaultSort?: ListSortSpec;
+  defaultFilters?: Readonly<Record<string, string[] | boolean>>; // Initial facet selection, per filterable field: option values (string facets) or a boolean.
+  facets?: Readonly<Record<string, EntityListFacetConfig | false>>; // Per-facet display options for the entity's `filterable` fields, keyed by field name.
+  emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
+  createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
+  searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
+  searchable?: boolean;
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type EscapeHatchAuditSink = (event: EscapeHatchUseEvent) => Promise<void>;
+type EscapeHatchDeclaration = {
+  reason: string;
+  grants?: EscapeHatchGrant[];
+};
+type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants" | "cross-tenant-read";
+type EscapeHatchUseEvent = {
+  handler: string;
+  kind: EscapeHatchKind;
+  reason: string;
+  tenantId: TenantId;
+  actor: string;
+  caller?: string;
+  target?: EscapeHatchTarget;
+};
+type EventDef<TPayload = unknown, TName extends string = string> = {
+  name: TName;
+  schema: ZodType<TPayload>;
+  version: number;
+  piiFields: EventPiiStance;
+};
+type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap ? Record<never, never> extends KumikoExtensionOptionsMap[N] ? [ options?: ExtensionOptionsFor<N> ] : [ options: ExtensionOptionsFor<N> ] : [ options?: Record<string, unknown> ]; // Rest-tuple for useExtension's positional options arg: required for an augmented name with required keys, optional otherwise.
+type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap ? KumikoExtensionOptionsMap[N] & { escapeHatch?: EscapeHatchDeclaration; } : Record<string, unknown>; // Options shape for an extension name: the augmented hook shape plus `escapeHatch`, or an untyped bag if unaugmented.
+type FeatureDefinition = {
+  name: string;
+  description?: string;
+  systemScope: boolean;
+  exports?: unknown;
+  requires: string[];
+  optionalRequires: string[];
+  requiredProjections: ReadonlySet<string>;
+  requiredSteps: ReadonlySet<string>;
+  toggleableDefault?: boolean;
+  adoptsBundledLists?: true;
+  uiHints?: UiHints;
+  entities?: Readonly<Record<string, EntityDefinition>>;
+  entityTables?: Readonly<Record<string, unknown>>;
+  relations: Readonly<Record<string, EntityRelations>>;
+  writeHandlers: Readonly<Record<string, WriteHandlerDef>>;
+  queryHandlers: Readonly<Record<string, QueryHandlerDef>>;
+  streamHandlers: Readonly<Record<string, StreamHandlerDef>>;
+  translations: TranslationKeys;
+  hooks?: HookMap;
+  entityHooks?: EntityHookMap;
+  searchPayloadExtensions?: Readonly<Record<string, OwnedFn<SearchPayloadContributorFn>[]>>;
+  configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
+  configSeeds: ConfigSeedDef[];
+  jobs: Readonly<Record<string, JobDefinition>>;
+  registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
+  extensionUsages: RegistrarExtensionRegistration[];
+  extensionSelectors: ExtensionSelectorDef[];
+  exposedApis: ReadonlySet<string>; // Cross-feature API names this feature exposes via `r.exposesApi(name)`.
+  usedApis: ReadonlySet<string>; // Cross-feature API names this feature calls.
+  bootChecks: BootCheckFn[]; // Boot-time mount-invariant checks declared via `r.bootCheck(fn)`.
+  bootRequires?: StackBootRequirement;
+  referenceData: ReferenceDataDef[];
+  notifications: Readonly<Record<string, NotificationDefinition>>;
+  events: Readonly<Record<string, EventDef>>;
+  eventMigrations: Readonly<Record<string, EventMigrationDef[]>>;
+  configReads: string[];
+  handlerEntityMappings: Readonly<Record<string, string>>;
+  metrics: Readonly<Record<string, FeatureMetricDef>>;
+  secretKeys: Readonly<Record<string, SecretKeyDefinition>>;
+  secretNamespaces: Readonly<Record<string, SecretNamespaceDefinition>>;
+  probes?: Readonly<Record<string, ProbeDefinition>>;
+  projections: Readonly<Record<string, ProjectionDefinition>>;
+  entityProjectionExtensions?: Readonly<Record<string, EntityProjectionExtension[]>>;
+  multiStreamProjections: Readonly<Record<string, MultiStreamProjectionDefinition>>;
+  authClaimsHooks: AuthClaimsFn[];
+  claimKeys: Readonly<Record<string, ClaimKeyDefinition>>;
+  screens: Readonly<Record<string, ScreenDefinition>>;
+  navs: Readonly<Record<string, NavDefinition>>;
+  workspaces: Readonly<Record<string, WorkspaceDefinition>>;
+  treeActions?: Readonly<Record<string, TreeActionDef>>;
+  contentCollections?: Readonly<Record<string, ContentCollectionDefinition>>;
+  httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
+  webSocketRoutes: Readonly<Record<string, WebSocketRouteDefinition>>;
+  storeTables: Readonly<Record<string, StoreTableEntry>>;
+  envSchema?: z.ZodObject<z.ZodRawShape>;
+  dedupeOptions?: Readonly<Record<string, unknown>>;
+};
+type FeatureManifest = {
+  source: string;
+  featureCount: number;
+  features: ManifestFeature[];
+  systemEvents?: ManifestSystemEvent[];
+  tier?: string;
+};
+type FeatureRegistrar<TFeature extends string = string> = { // `TFeature` is the literal feature-name from `defineFeature("foo", ...)` — default-`string` keeps every existing usage zero-config.
+  systemScope(): void;
+  describe(text: string): void;
+  requires: RequiresApi;
+  optionalRequires(...featureNames: string[]): void;
+  optionalRequires(options: { features: string[]; }): void;
+  toggleable(options: { default: boolean; }): void;
+  adoptsBundledLists(): void;
+  uiHints(hints: UiHints): void;
+  entity(definition: EntityObjectDefinition): EntityRef;
+  crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+  writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared, TWhenNested>): HandlerRef;
+  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: { entity: NameOrRef; name: string; } & TDef): void;
+  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: { keys: TKeys; seeds?: Readonly<Record<string, ConfigSeedDef>>; }): { [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: { trigger?: { on: NameOrRef; }; recipient?: NotificationRecipientFn; data?: NotificationDataFn; templates?: Readonly<Record<string, NotificationTemplateFn>>; variables?: TemplateVariables; record?: NotificationRecordMapping; template?: Readonly<Record<string, NotificationTemplateBody>>; meta?: Readonly<Record<string, NotificationTemplateMeta>>; localizedTemplate?: () => NotificationLocalizedTemplate; renamedFrom?: string[]; systemOnly?: boolean; unsubscribe?: boolean; tenantTransport?: boolean; }): void;
+  notification(definition: { name: string; trigger?: { on: NameOrRef; }; recipient?: NotificationRecipientFn; data?: NotificationDataFn; templates?: Readonly<Record<string, NotificationTemplateFn>>; variables?: TemplateVariables; record?: NotificationRecordMapping; template?: Readonly<Record<string, NotificationTemplateBody>>; meta?: Readonly<Record<string, NotificationTemplateMeta>>; localizedTemplate?: () => NotificationLocalizedTemplate; renamedFrom?: string[]; systemOnly?: boolean; unsubscribe?: boolean; tenantTransport?: boolean; }): void;
+  translations(def: TranslationsDef): void;
+  defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: { version?: number; piiFields: EventPiiStance; migrations?: { fromVersion: number; toVersion: number; transform: EventUpcastFn | DeclarativeEventMigration; }[]; }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
+  readsConfig(...qualifiedKeys: string[]): void;
+  readsConfig(options: { keys: string[]; }): void;
+  referenceData(entity: NameOrRef, data: Record<string, unknown>[], options?: { upsertKey?: string; }): void;
+  referenceData(definition: { entity: NameOrRef; data: Record<string, unknown>[]; 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: { name: N; entity: NameOrRef; } & ExtensionOptionsFor<N>): void;
+  extensionSelector(extensionName: string, key: { name: string; } | string, options?: { panels?: ExtensionSelectorPanel[]; }): 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)`).
+  exposesApi(apiName: string): void; // Marker declaration: this feature provides a cross-feature API under the given name.
+  usesApi(apiName: string): void; // Declares that this feature calls a cross-feature API.
+  bootCheck(fn: BootCheckFn): void; // Declares a boot-time mount-invariant for this feature.
+  metric(shortName: string, options: MetricOptions): void;
+  metric(definition: { name: string; } & MetricOptions): void;
+  secret(shortName: string, options: SecretOptions): SecretKeyHandle;
+  secret(definition: { name: string; } & SecretOptions): SecretKeyHandle;
+  probe(options: ProbeOptions): void;
+  secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
+  secretNamespace(definition: { 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: { type: T; }): ClaimKeyHandle<T>;
+  claimKey<T extends ClaimKeyType>(definition: { name: string; 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;
+};
+type FieldCondition =
+  | boolean
+  | {
+    field: string;
+    eq: unknown;
+  }
+  | {
+    field: string;
+    ne: unknown;
+  }
+  | {
+    field: string;
+    in: unknown[];
+  }
+  | {
+    field: string;
+    notIn: unknown[];
+  }
+;
+type FieldDefinition = TextFieldDef | LongTextFieldDef | BooleanFieldDef | SelectFieldDef | MultiSelectFieldDef | NumberFieldDef | BigIntFieldDef | DecimalFieldDef | MoneyFieldDef | ReferenceFieldDef | EmbeddedFieldDef | JsonbFieldDef | DateFieldDef | TimestampFieldDef | TzFieldDef | LocatedTimestampFieldDef | FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;
+interface FieldFormatRegistry {
+  timestamp: {
+    locale?: string;
+    dateStyle?: "full" | "long" | "medium" | "short";
+    timeStyle?: "full" | "long" | "medium" | "short";
+    timeZone?: string; // IANA zone id (e.g. "Europe/Berlin").
+  };
+  date: {
+    locale?: string;
+    dateStyle?: "full" | "long" | "medium" | "short";
+  };
+  boolean: {
+    trueLabel?: string;
+    falseLabel?: string;
+  };
+  currency: {
+    symbol?: string;
+  };
+  priority: {
+    emptyLabel?: string;
+    prefix?: string;
+  };
+  number: NumberFormatOptions; // `grouping: false` renders without thousands-separators (e.g. a model year: "2021", not "2.021").
+  decimal: NumberFormatOptions; // Same options as `number`.
+  bigInt: {
+    locale?: string;
+    grouping?: boolean;
+  };
+  unit: {
+    unit: UnitKey;
+    locale?: string;
+    unitDisplay?: "long" | "short" | "narrow";
+  };
+  enumOption: {
+    keyPrefix: string;
+    tones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
+  };
+  i18nText: Record<never, never>; // Value is a `DashboardI18nText` (`{ i18nKey, i18nParams }`) a query built server-side, or a plain i18n key, translated in the user's language.
+  json: {
+    indent?: number;
+  }; // JSON-safe structured value rendered as indented text.
+  image: {
+    variant?: string;
+  }; // List cell: FileRef id (or id array) as a thumbnail.
+  file: {
+    previewOpenByDefault?: boolean;
+  }; // FileRef id (or id array) as a download link with the file name.
+}
+type HandlerAuth = {
+  resolveClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
+  resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
+};
+type HandlerContext<TMap extends object = KumikoEventTypeMap> = {
+  db: HandlerDb;
+  systemDb?: UncheckedSystemDb;
+  crossTenantReads?: CrossTenantReads;
+  registry: Registry;
+  user: SessionUser; // The active SessionUser for the handler call, exposed as a convenience alias for `event.user`.
+  rateLimitDigest?: (value: string) => string; // Keyed digest for handler-owned rate-limit keys, so Redis never holds a plaintext or plainly hashed identifier.
+  includeDeleted?: boolean;
+  dispatch: HandlerDispatch;
+  hasFeature: (featureName: string) => Promise<boolean>;
+  events: HandlerEvents<TMap>;
+  obs: HandlerObservability;
+  tz: TzContext;
+  locale: string;
+  auth: HandlerAuth;
+  config?: ConfigAccessor;
+  notify?: NotifyFn;
+  services: ContextServices;
+  lifecycle: HandlerLifecycle;
+  tenants: HandlerTenants;
+};
+type HandlerDb = TenantDb & { // `ctx.db` plus `outsideTransaction`: the same tenant scoping, but never bound to the handler's tx, so writes through it survive a rollback.
+  outsideTransaction: TenantDb | undefined;
+};
+type HandlerDispatch = { // Cross-feature bridge: `query`/`write` run the target handler AS THE CURRENT USER, sharing the active tx + afterCommit queue.
+  query: (qn: string, payload: unknown) => Promise<unknown>;
+  queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  write: (qn: string, payload: unknown) => Promise<WriteResult>;
+  writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+  queryAsMember: MemberReader;
+  queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: { unsafeAllTenants?: boolean; }) => Promise<T[]>;
+};
+type HandlerEvents<TMap extends object = KumikoEventTypeMap> = { // Event-store surface of a handler.
+  append: AppendEventFn<TMap>; // Default append: a typed domain event on one aggregate stream in the current tx.
+  unsafeAppend: UnsafeAppendEventFn; // Untyped append (`payload: unknown`) with the same runtime as `append`.
+  tryAppend: TryAppendEventFn; // 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.
+  fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
+  load: (aggregateId: string, options?: { asOf?: Temporal.Instant; atVersion?: never; } | { atVersion?: number; asOf?: never; }) => Promise<StoredEvent[]>;
+  archive: (aggregateId: string, args: { aggregateType: string; reason?: string; }) => Promise<void>;
+  restore: (aggregateId: string) => Promise<void>;
+  isArchived: (aggregateId: string) => Promise<boolean>;
+  snapshot: (args: { aggregateId: string; aggregateType: string; version: number; state: Record<string, unknown>; snapshotVersion?: number; }) => Promise<void>;
+  loadWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: SnapshotReducer<TState>, initial: TState, options?: Omit<LoadAggregateWithSnapshotOptions, "upcastEvent">) => Promise<LoadAggregateWithSnapshotResult<TState>>;
+};
+type HandlerObservability = {
+  log: Logger;
+  tracer: Tracer;
+  metrics: MetricsHandle;
+  metricsFor: (featureName: string) => MetricsHandle;
+  meter?: Meter;
+};
+type JobContext = {
+  db: TenantDb;
+  events: JobEvents;
+  registry: Registry;
+  systemUser: SessionUser;
+  obs: JobObservability;
+  tz: TzContext;
+  triggeredBy: { id: string; tenantId: TenantId; } | null;
+  attempt: number;
+  finalAttempt: boolean;
+  defer: (delayMs: number) => JobDeferral;
+  canDefer: boolean;
+  systemDb?: UncheckedSystemDb;
+  crossTenantReads?: CrossTenantReads;
+  dispatch: JobDispatch;
+  triggerName?: string;
+  triggerEvent?: JobTriggerEvent;
+  _tenantId?: TenantId;
+  config?: ConfigAccessor;
+  notify?: NotifyFn;
+  services: ContextServices;
+  lifecycle: JobLifecycle;
+};
+type JobDeferral = {
+  kind: "job-deferral";
+  delayMs: number;
+};
+type JobDefinition = {
+  name: string;
+  handler: JobHandlerFn;
+  trigger: JobTrigger;
+  concurrency?: ConcurrencyMode | undefined;
+  maxPerTenant?: number | MaxPerTenantOptions | undefined;
+  debounceMs?: number | undefined;
+  maxDefers?: number | undefined;
+  retries?: number | undefined;
+  backoff?: JobBackoff | undefined;
+  timeout?: number | undefined;
+  schema?: ZodType | undefined;
+  runOnBoot?: boolean | undefined;
+  bootGate?: boolean | undefined;
+  perTenant?: boolean | undefined;
+  runIn?: JobRunIn | undefined;
+  escapeHatch?: EscapeHatchDeclaration | undefined;
+  tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
+  tenantVisibleRun?: { subjectFields?: string[] | undefined; } | undefined;
+};
+type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
+type JobEvents = Pick<HandlerEvents, "append">;
+type JobHandlerFn = (payload: Record<string, unknown>, context: JobContext) => Promise<void | JobDeferral>;
+type JobObservability = Pick<HandlerObservability, "log" | "metricsFor" | "meter">;
+type JobTrigger =
+  | {
+    on: NameOrRef | NameOrRef[];
+    where?: Readonly<Record<string, string | number | boolean>>;
+    catchUp?: boolean;
+  }
+  | {
+    cron: string;
+    tz?: string;
+  }
+  | {
+    manual: true;
+  }
+;
+type JsonbFieldDef = ResolvedPiiFlags & {
+  type: "jsonb";
+  description?: string;
+  emptyValue?: JsonbEmptyValue; // `"array"`: the field holds a JSON array, so a row that never wrote it reads `[]` and writes take an array.
+  sensitive?: boolean;
+  readAsInstruction?: boolean; // A later run reads this field's value as an instruction — prompt, rule, template.
+  access?: FieldAccess;
+};
+interface KumikoEventTypeMap {}
+interface KumikoExtensionOptionsMap {}
+type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];
+type ListColumnSpec =
+  | string
+  | {
+    field: string;
+    renderer?: FieldRenderer;
+    label?: string; // Optional header, overriding the default `<feature>:entity:<entity>:field:<field>` i18n convention.
+    virtual?: boolean; // Marks a column on a query-backed list (projectionList, relatedList, dashboard list, expandableRow) as drawn by a renderer rather than read from a row field.
+    refEntity?: string; // Marks this column as a reference lookup instead of a plain value — for projectionList/relatedList columns, which have no `EntityDefinition` to carry a real `reference` field type.
+    refLabelField?: string; // Row field on the referenced entity shown as the label (default "id").
+    sortable?: boolean; // Marks this column as sortable via a clickable header — for relatedList columns, which have no `EntityDefinition` field to carry `sortable` on.
+    valueType?: "number" | "decimal" | "bigInt" | "money"; // Value type of a relatedList column, which has no `EntityDefinition` field to derive it from.
+    hideOnNarrow?: boolean; // Leaves the column out of the compact card layout used below the `md` breakpoint (tables keep it).
+    hidden?: boolean; // Start state for the column picker: the column begins hidden and the user can show it.
+    pinned?: ListColumnPin; // Start pin for the column: it sticks to this edge while the table scrolls horizontally.
+    width?: number; // Start width in px.
+    minWidth?: number; // Smallest width in px the user can resize to.
+    display?: ListColumnDisplay; // Dashboard list panels only.
+    badgeToneField?: string; // Row field naming the badge tone; only with `display: "badge"`.
+    linkScreenField?: string; // Row field holding a screen QN (`<feature>:screen:<id>`): the cell links to that screen when the row sets it and the user may open it.
+  }
+;
+type ListFacetSpec =
+  | {
+    field: string;
+    type: "select";
+    label: string;
+    options: { value: string; label: string; }[];
+  }
+  | {
+    field: string;
+    type: "boolean";
+    label: string;
+    trueLabel: string;
+    falseLabel: string;
+  }
+  | {
+    field: string;
+    type: "reference";
+    label: string;
+    entity: string; // Entity name (same feature) or `feature:entity` (cross-feature), same convention as `ListColumnSpec.refEntity`.
+    labelField?: string; // Row field on the referenced entity shown as the option label (default "id").
+  }
+  | {
+    field: string; // Declarative only — the date field the range narrows.
+    type: "dateRange";
+    label: string;
+    params: {
+      from: string;
+      to: string;
+    }; // Query-payload keys the chosen bounds are sent under as ISO instants.
+  }
+;
+type ListTableOptions = { // Opt-in table behaviour of a list.
+  rememberState?: boolean; // Keeps search, sort, page size, facets and date range for the browser session and restores them when the screen is opened without list parameters in the URL.
+  resetAll?: boolean; // Replaces the facet reset with one button that resets search, sort, page size, facets and date range, and drops the remembered list parameters (column and density choices stay).
+  columnPicker?: boolean; // Lets the user hide and reorder columns in the view menu.
+  pinning?: boolean; // Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`.
+  resizing?: boolean; // Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize.
+  keyboardNavigation?: boolean; // Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click.
+  density?: {
+    default?: ListTableDensity; // Row density on first visit.
+    userChoice?: boolean; // Shows the density choice in the view menu and remembers it per session.
+  };
+  export?: ListTableExportOptions; // Shows an export button; the server reads the whole filtered list (not just the visible page).
+  grouping?: ListTableGrouping; // Server-side grouping: group headers with count and the `totals` measures over all matching rows; each open group loads its own rows.
+  totals?: ListTableTotal[]; // Footer row under the rows, computed by the server over all rows matching the current filters and search.
+};
+type ManifestConfigKey = {
+  key: string;
+  qualifiedName: string;
+  type: "text" | "number" | "boolean" | "select";
+  scope: string;
+  default: string | number | boolean | null;
+  encrypted: boolean;
+  computed: boolean;
+  validated: boolean;
+  options: string[] | null;
+  bounds: { min?: number; max?: number; } | null;
+  pattern: { regex: string; flags?: string; } | null;
+  writeRoles: string[];
+  readRoles: string[];
+};
+type ManifestExtension = {
+  extensionName: string;
+  entityName: string;
+};
+type ManifestFeature = {
+  name: string;
+  description: string | null;
+  toggleableDefault: boolean | null;
+  adoptsBundledLists?: true;
+  requires: string[];
+  optionalRequires: string[];
+  configReads: string[];
+  exposesApis: string[];
+  usesApis: string[];
+  extensionsUsed: ManifestExtension[];
+  configKeys: ManifestConfigKey[];
+  secrets: ManifestSecret[];
+  writeHandlers: string[]; // All registered write-handler QNs for this feature (e.g. "user:write:user:create", "auth-email-password:write:login").
+  uiHints?: UiHints; // Picker/scaffolder UI metadata declared via r.uiHints().
+  tier?: string; // Optionaler Herkunfts-Tag (z.B.
+};
+type ManifestSecret = {
+  qualifiedName: string;
+  scope: string;
+  label: string | null;
+  hint: string | null;
+};
+type ManifestSystemEvent = { // Framework-owned registered event (`kumiko:system:*`), e.g. the workflow run-stream events a projection can apply.
+  name: string;
+  version: number;
+};
+type MetricNavigate = {
+  screen?: string;
+  entity?: string;
+  entityId?: string;
+  params?: RowFieldExtractor;
+  tab?: string; // Section id of the tab to activate at the destination.
+};
+type MspErrorMode = {
+  continuous?: MspErrorPolicy;
+  rebuild?: MspErrorPolicy;
+};
+type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>;
+type MultiStreamProjectionDefinition = {
+  name: string;
+  table?: ProjectionTable;
+  apply: Readonly<Record<string, MultiStreamApplyFn>>;
+  errorMode?: MspErrorMode;
+  runIn?: RunIn;
+  delivery?: "shared" | "per-instance";
+  startFrom?: "beginning" | "now";
+};
+type NavDefinition = {
+  id: string;
+  label: string;
+  icon?: NavIconKey;
+  parent?: string;
+  order?: number;
+  screen?: string;
+  target?: TargetRef;
+  actions?: TreeAction[];
+  createAction?: TreeAction;
+  provider?: boolean;
+  access?: AccessRule;
+  workspaces?: string[];
+};
+type NavIconKey = (typeof NAV_ICON_KEYS)[number];
+type NotificationDefinition = {
+  name: string;
+  trigger?: {
+    on: string;
+  };
+  recipient?: NotificationRecipientFn;
+  data?: NotificationDataFn;
+  templates: Readonly<Record<string, NotificationTemplateFn>> | undefined;
+  variables?: TemplateVariables;
+  record?: NotificationRecordMapping;
+  template?: Readonly<Record<string, NotificationTemplateBody>>;
+  meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+  renamedFrom?: string[];
+  localizedTemplate?: () => NotificationLocalizedTemplate;
+  systemOnly?: boolean;
+  unsubscribe?: boolean;
+  tenantTransport?: boolean;
+};
+type NotificationLocalizedTemplate = Readonly<Record<string, { body: string; meta: NotificationTemplateMeta; }>>;
+type NotificationRecordMapping = {
+  entity: string;
+  map: Readonly<Record<string, string>>;
+};
+type NotificationTemplateBody = {
+  body: string;
+};
+type NotificationTemplateMeta = {
+  subject: string;
+  previewText?: string;
+  layoutSlug?: string;
+  category?: "transactional" | "marketing";
+  sender?: string;
+  senderName?: string;
+  replyTo?: string;
+};
+type NotifyDelivery = {
+  channel: string;
+  recipientId: string | null;
+  status: NotifyDeliveryStatus;
+  error: DeliveryErrorCode | null;
+  confirmed?: false;
+  deliveryAttemptId?: string;
+};
+type NotifyDeliveryStatus = "queued" | "sent" | "failed" | "skipped";
+type NotifyDispatched = {
+  kind: "dispatched";
+  deliveries: NotifyDelivery[];
+};
+type NotifyFactory = (user: SessionUser, tenantId: TenantId, jobDispatcher?: NotifyJobDispatcher, deliveryDb?: DbConnection, fileProviderResolver?: FileProviderResolver) => NotifyFn;
+type NotifyFn = {
+  (notificationType: string, options: NotifyOptions & { immediate: true; }): Promise<NotifyDispatched>;
+  (notificationType: string, options: NotifyOptions): Promise<NotifyResult>;
+};
+type NotifyJobDispatcher = {
+  dispatch(jobName: string, payload: Record<string, unknown>, meta?: { priority?: number; }): Promise<unknown>;
+};
+type NotifyOptions = {
+  to?: string | string[] | { tenant: TenantId; };
+  route?: Readonly<Record<string, string>>;
+  data?: Readonly<Record<string, unknown>>;
+  priority?: NotifyPriority;
+  idempotencyKey?: string;
+  recipientId?: string;
+  immediate?: boolean;
+  locale?: string;
+};
+type NotifyPriority = "critical" | "normal" | "low";
+type NotifyResult = NotifyDispatched | NotifyDeferred;
+type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+type PagedQueryHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap> = QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap> & {
+  [PAGED_QUERY_HANDLER_BRAND]: true;
+};
+type PendingChange = {
+  feature: string;
+  type: ChangelogType;
+  title: string;
+  detail?: string;
+  migration?: string;
+  codemod?: string;
+  manualAfterCodemod?: boolean;
+  source: string;
+};
+type PipelineCtx<TPayload = unknown, TMap extends object = KumikoEventTypeMap> = HandlerContext<TMap> & { // Pipeline-side context handed to step argument resolvers.
+  event: WriteEvent<TPayload>;
+  steps: Readonly<Record<string, unknown>>;
+  scope: Readonly<Record<string, unknown>>;
+  workflow?: {
+    runId: string;
+    workflowName: string;
+    stepIndex: number; // Current step index in the pipeline — set by the executor before each step.
+    retryAttempt?: number; // Retry attempt counter for the current workflow.retry step.
+    definitionFingerprint?: string; // Snapshot-at-Start fingerprint of the workflow definition that started this run.
+  };
+};
+type PostDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+type PostSaveHookFn = (result: SaveContext, context: HandlerContext) => Promise<void>;
+type PreDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+type PreSaveHookFn = (changes: Record<string, unknown>, context: HandlerContext & { previous: Readonly<Record<string, unknown>>; isNew: boolean; }) => Promise<Record<string, unknown>>;
+type PrincipalProfile = {
+  globalRoles: string[];
+  timezone?: string;
+  locale?: string;
+};
+type PrincipalStatus = "active" | "blocked" | "unknown";
+type PrincipalStatusPlugin = {
+  resolveStatus: (userId: string, deps: { db: DbConnection; }) => Promise<PrincipalStatus>;
+  resolveProfile: (userId: string, deps: { db: DbConnection; }) => Promise<PrincipalProfile | null>;
+};
+type ProbeContext = Pick<JobContext, "db" | "registry" | "obs" | "tz" | "services"> & {
+  probeRunId: string;
+  tenantId: TenantId;
+  triggeredByUserId: string;
+  triggeredByEmail: string | undefined;
+};
+type ProbeCost = "free" | "paid";
+type ProbeDefinition = ProbeOptions & {
+  qualifiedName: string;
+};
+type ProbeOptions = {
+  name: string;
+  scope: ProbeScope;
+  cost: ProbeCost;
+  area: string; // i18n key, column "Bereich"
+  label: string; // i18n key, column "Check" (used when the probe has no targets)
+  timeoutMs?: number; // Default 10_000
+  fixScreen?: string; // Screen QN linked from a failed result
+  targets?: (ctx: ProbeContext) => Promise<ProbeTarget[]>;
+  run: (ctx: ProbeContext, target: ProbeTarget | undefined) => Promise<ProbeVerdict>; // Failure = throw
+};
+type ProbeScope = "tenant" | "system";
+type ProbeTarget = {
+  id: string;
+  label: ProbeText;
+  ownerUserId?: string;
+};
+type ProbeText = {
+  key: string;
+  params?: Readonly<Record<string, string | number>>;
+};
+type ProbeVerdict =
+  | {
+    status: "ok";
+    message: ProbeText;
+  }
+  | {
+    status: "skipped";
+    message: ProbeText;
+  }
+;
+type ProjectionDefinition = {
+  name: string;
+  source: string | string[];
+  extraSources?: string[];
+  extraSourceRowIds?: Readonly<Record<string, ProjectionRowIdOf>>;
+  table: ProjectionTable;
+  entity?: EntityDefinition;
+  apply: Readonly<Record<string, SingleStreamApplyFn>>;
+  isImplicit?: boolean;
+};
+type ProjectionDetailScreenDefinition = {
+  id: string;
+  type: "projectionDetail";
+  fillHeight?: boolean; // Default true: the screen fills the shell content height, its body scrolls inside and the pager / action bar stays pinned.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  query: string;
+  recordTitleField?: string; // Query output field whose value titles the page header (breadcrumb) when no `header` is set.
+  idParam?: string; // Query-payload key for the row-id.
+  singleton?: boolean; // The server determines the shown row from the caller's session/context instead of a row id in the path — a self-service screen ("my profile", "my data") that has no row to link to (unlike `EntityEditScreenDefinition.
+  live?: boolean; // Refetches the record and its relatedList sections when their entity changes (live SSE), for a screen that shows work a background job is still doing.
+  layout: EditLayout;
+  fieldLabels?: Readonly<Record<string, string>>; // Optional per-field label i18n key (field name → key), analogous to entityEdit.fieldLabels.
+  header?: RecordHeaderSpec; // Record header above the layout — title/subtitle/status name columns in the query row (not literals).
+  metrics?: MetricSpec[]; // Metric band above the layout — column names in the query row, each with its own i18n `label`.
+  metricsStyle?: "band" | "tiles"; // "tiles" draws the metrics as the dashboard KPI tiles (StatCard) instead of the plain band.
+  listScreenId?: string; // Parent list screen (short id) for a "back" navigation.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+  actions?: RowAction[]; // Header action buttons.
+  primaryAction?: string; // Id of the action that stays the visible header button when the actions collapse into a menu (and the one that keeps the phone icon slot when it has an icon and no confirm).
+  inlineActions?: string[]; // Action ids that stay visible buttons next to the primary action when the rest collapses into the menu.
+  valueDisplay?: "form" | "text"; // How head fields render.
+};
+type ProjectionListScreenDefinition = {
+  id: string;
+  type: "projectionList";
+  fillHeight?: boolean; // Default true: the screen fills the shell content height, its body scrolls inside and the pager / action bar stays pinned.
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  query: string;
+  columns: ListColumnSpec[];
+  rowRenderer?: PlatformComponent;
+  cardRenderer?: PlatformComponent;
+  rowActions?: RowAction[];
+  rowActionMode?: RowActionMode; // Layout of the row-action column — see `RowActionMode`.
+  bulkActions?: ListBulkAction[]; // Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action.
+  toolbarActions?: ToolbarAction[];
+  pagination?: ListPaginationMode;
+  pageSize?: number;
+  table?: ListTableOptions; // Opt-in table behaviour: remembered state, reset, column picker, density.
+  defaultSort?: ListSortSpec;
+  emptyState?: ListEmptyStateSpec; // Replaces the default empty-list title/hint; the create button stays when the list can create.
+  createLabel?: string; // i18n key for the primary create button label (default `kumiko.actions.create`).
+  searchPlaceholder?: string; // i18n key for the search field placeholder (default `kumiko.list.search-placeholder`).
+  searchable?: boolean;
+  sortable?: boolean; // Derived by buildAppSchema from the query handler's Zod schema (`sort` param present).
+  paginated?: boolean; // Derived by buildAppSchema from the query handler's Zod schema (`cursor` or `offset` param present).
+  filter?: ScreenFilter; // Server-side filter, fixed on the screen — see `ScreenFilter` doc above (entityList).
+  facets?: ListFacetSpec[]; // User-toggleable facet dropdowns — see `ListFacetSpec` doc.
+  slots?: ScreenSlots;
+  access?: AccessRule;
+};
+type QueryEvent<TPayload = unknown> = {
+  type: string;
+  payload: TPayload;
+  user: SessionUser;
+};
+type QueryHandlerDef = {
+  name: string;
+  schema: ZodType;
+  handler: QueryHandlerFn;
+  [ENTITY_CONVENTION_QUERY_BRAND]?: true; // Set only by defineEntityQueryHandler, which wires the parent-ref read-gate.
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  rateLimit?: RateLimitDeclaration;
+  outputSchema?: ZodType; // Zod schema of the handler's actual return value — the paged envelope `{ rows, nextCursor, total?
+  liveEntities?: string[]; // Entities whose changes this query reflects.
+  escapeHatch?: EscapeHatchDeclaration;
+};
+type QueryHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap> = {
+  name: TName;
+  schema: TSchema;
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  rateLimit?: RateLimitDeclaration;
+  escapeHatch?: EscapeHatchDeclaration;
+  handler: (query: QueryEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<TResult>;
+  outputSchema?: ZodType; // Zod schema of `handler`'s actual return value — see QueryHandlerDef's doc (handlers.ts) for the boot-validator checks this unlocks.
+  liveEntities?: string[]; // Entities whose changes this query reflects.
+};
+type RateLimitPer = (typeof RATE_LIMIT_PERS)[number];
+type ReferenceDataDef = {
+  entityName: string;
+  data: Record<string, unknown>[];
+  upsertKey?: string | undefined;
+};
+type Registry = {
+  features: ReadonlyMap<string, FeatureDefinition>;
+  getFeature(name: string): FeatureDefinition | undefined;
+  getEntity(name: string): EntityDefinition | undefined;
+  getReadModelEntity(name: string): EntityDefinition | undefined;
+  getReadModelEntityOwner(name: string): string | undefined;
+  getAllEntities(): ReadonlyMap<string, EntityDefinition>;
+  getWriteHandler(name: string): WriteHandlerDef | undefined;
+  getQueryHandler(name: string): QueryHandlerDef | undefined;
+  getAllQueryHandlers(): ReadonlyMap<string, QueryHandlerDef>;
+  getAllWriteHandlers(): ReadonlyMap<string, WriteHandlerDef>;
+  getStreamHandler(name: string): StreamHandlerDef | undefined;
+  getAllStreamHandlers(): ReadonlyMap<string, StreamHandlerDef>;
+  getSearchableFields(entityName: string): string[];
+  getSortableFields(entityName: string): string[];
+  getRelations(entityName: string): EntityRelations;
+  getSearchableReferences(entityName: string): ReadonlyArray<{ fieldName: string; targetEntityName: string; labelField: string; }>;
+  getSortableReferences(entityName: string): ReadonlyArray<{ fieldName: string; targetEntityName: string; labelField: string; }>;
+  getIncomingRelations(entityName: string): ReadonlyArray<{ sourceEntity: string; relationName: string; relation: RelationDefinition; }>;
+  getPreSaveHooks(name: string, effectiveFeatures?: ReadonlySet<string>): PreSaveHookFn[];
+  getPostSaveHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PostSaveHookFn[];
+  getPreDeleteHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PreDeleteHookFn[];
+  getPostDeleteHooks(name: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PostDeleteHookFn[];
+  getPostQueryHooks(name: string, effectiveFeatures?: ReadonlySet<string>): PostQueryHookFn[];
+  getEntityPostSaveHooks(entityName: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PostSaveHookFn[];
+  getEntityPreDeleteHooks(entityName: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PreDeleteHookFn[];
+  getEntityPostDeleteHooks(entityName: string, phase?: HookPhase, effectiveFeatures?: ReadonlySet<string>): PostDeleteHookFn[];
+  getEntityPostQueryHooks(entityName: string, effectiveFeatures?: ReadonlySet<string>): PostQueryHookFn[];
+  getSearchPayloadExtensions(entityName: string, effectiveFeatures?: ReadonlySet<string>): SearchPayloadContributorFn[];
+  getHandlerEntity(qualifiedHandler: string): string | undefined;
+  isHandlerSystemScoped(qualifiedHandler: string): boolean;
+  isJobSystemScoped(qualifiedJobName: string): boolean;
+  getHandlerFeature(qualifiedHandler: string): string | undefined;
+  getJobFeature(qualifiedJobName: string): string | undefined;
+  hasRateLimitedHandler(): boolean;
+  getAllMetrics(): ReadonlyMap<string, FeatureMetricDef & { featureName: string; }>;
+  getAllTranslations(): TranslationKeys;
+  getConfigKey(qualifiedKey: string): ConfigKeyDefinition | undefined;
+  getAllConfigKeys(): ReadonlyMap<string, ConfigKeyDefinition>;
+  getAllConfigSeeds(): ConfigSeedDef[];
+  getAllSecretKeys(): ReadonlyMap<string, SecretKeyDefinition>;
+  getSecretKey(qualifiedName: string): SecretKeyDefinition | undefined;
+  findSecretNamespace(key: string): SecretNamespaceDefinition | undefined;
+  getJob(qualifiedName: string): JobDefinition | undefined;
+  getAllJobs(): ReadonlyMap<string, JobDefinition>;
+  getEvent(qualifiedName: string): EventDef | undefined;
+  getEventUpcasters(): ReadonlyMap<string, { currentVersion: number; chain: ReadonlyMap<number, EventUpcastFn>; }>;
+  getExtension(name: string): RegistrarExtensionDef | undefined;
+  getExtensionUsages(extensionName: string): RegistrarExtensionRegistration[];
+  getAllExtensionSelectors(): ReadonlyMap<string, string>;
+  getExtensionSelectorPanels(extensionName: string): ExtensionSelectorPanel[];
+  getAllNotifications(): ReadonlyMap<string, NotificationDefinition>;
+  getAllReferenceData(): ReferenceDataDef[];
+  getProjectionsForSource(entityName: string): ProjectionDefinition[];
+  getAllProjections(): ReadonlyMap<string, ProjectionDefinition>;
+  getAllStoreTables(): ReadonlyMap<string, StoreTableDef>;
+  getAllMultiStreamProjections(): ReadonlyMap<string, MultiStreamProjectionDefinition>;
+  getMultiStreamProjectionFeature(qualifiedName: string): string | undefined;
+  getAuthClaimsHooks(): AuthClaimsHookDef[];
+  getAllClaimKeys(): ReadonlyMap<string, ClaimKeyDefinition>;
+  getClaimKey(qualifiedName: string): ClaimKeyDefinition | undefined;
+  getAllScreens(): ReadonlyMap<string, ScreenDefinition>;
+  getScreen(qualifiedName: string): ScreenDefinition | undefined;
+  getScreenFeature(qualifiedName: string): string | undefined;
+  getScreensByEntity(entityName: string): ScreenDefinition[];
+  getAllNavs(): ReadonlyMap<string, NavDefinition>;
+  getNav(qualifiedName: string): NavDefinition | undefined;
+  getNavFeature(qualifiedName: string): string | undefined;
+  getNavsByParent(parentQualifiedName: string): NavDefinition[];
+  getTopLevelNavs(): NavDefinition[];
+  getAllWorkspaces(): ReadonlyMap<string, WorkspaceDefinition>;
+  getWorkspace(qualifiedName: string): WorkspaceDefinition | undefined;
+  getWorkspaceFeature(qualifiedName: string): string | undefined;
+  getWorkspaceNavs(workspaceQualifiedName: string): string[];
+  getDefaultWorkspace(): WorkspaceDefinition | undefined;
+  getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
+};
+type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+type ReservationContext<TMap extends object = KumikoEventTypeMap> = Omit<HandlerContext<TMap>, PhaseWithoutTransaction> & { // ctx of `reserveBeforeTransaction`: nothing bound to the not-yet-open transaction.
+  dispatch: Omit<HandlerDispatch, "write" | "writeAs">;
+  lifecycle: Omit<HandlerLifecycle, "afterCommit" | "afterRollback">;
+};
+type ResolvedPiiFlags = {
+  pii?: boolean;
+  userOwned?: {
+    ownerField: string;
+    whenAbsent?: EntityPiiAbsentSubject;
+  };
+  tenantOwned?: boolean;
+  recordOwned?: true;
+  anonymize?: () => unknown | Promise<unknown>;
+  allowPlaintext?: string;
+  lookupable?: true; // Equality lookups (`fetchOne`/`filter eq`) remain possible despite encryption: the generated `<snake>_bidx` column carries an HMAC blind index, and the query compiler matches `(col = $1 OR col_bidx = $2)`.
+  subjectRef?: true; // Foreign key into the `user` entity (authorId, assigneeId, ...) with no annotated content of its own.
+};
+type RetentionDef = {
+  keepFor: string;
+  strategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete";
+  reference?: string;
+};
+type RoleAccessPersonalData = "public-intake";
+type RoleAccessRule = {
+  roles: string[];
+  personalData?: RoleAccessPersonalData;
+};
+type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
+type RowActionWriteHandler = {
+  kind?: "writeHandler"; // Default for RowActions without an explicitly set `kind` — backwards-compatible form.
+  id: string; // Stable id per screen — kebab-case, unique within the action set.
+  label: string; // Display text (i18n key).
+  handler: string; // Qualified name of the server handler, e.g. "publicstatus:write:maintenance:start".
+  payload?: RowFieldExtractor; // Declarative payload per row.
+  confirm?: string; // i18n key for the confirm dialog description.
+  confirmLabel?: string; // i18n key for the confirm button text in the dialog.
+  visible?: FieldCondition; // Conditional visibility per row.
+  style?: "primary" | "secondary" | "danger"; // Visual style.
+  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
+  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
+  redirect?: string | ActionFormRedirect; // Where to go after the write succeeded instead of staying on the shown record.
+};
+type SaveContext = {
+  kind: "save";
+  id: EntityId;
+  data: Readonly<Record<string, unknown>>;
+  changes: Readonly<Record<string, unknown>>;
+  previous: Readonly<Record<string, unknown>>;
+  isNew: boolean;
+  entityName?: string | undefined;
+  event: StoredEvent;
+};
+type ScreenDefinition = EntityListScreenDefinition | ProjectionListScreenDefinition | ProjectionDetailScreenDefinition | DashboardScreenDefinition | EntityEditScreenDefinition | ActionFormScreenDefinition | ConfigEditScreenDefinition | SecretsEditScreenDefinition | SecretMintScreenDefinition | CustomScreenDefinition;
+type SecretKeyDefinition = {
+  shortName: string;
+  qualifiedName: string;
+  label: {
+    [locale: string]: string;
+  };
+  redact?: (plaintext: string) => string;
+  hint?: {
+    [locale: string]: string;
+  };
+  scope: "tenant";
+  required?: boolean;
+  writeRoles?: string[];
+  valueSchema?: ZodType<string>;
+};
+type SecretKeyHandle = {
+  name: string;
+};
+type SecretMintScreenDefinition = { // Mint form → one-time reveal → explicit confirm.
+  id: string;
+  type: "secretMint";
+  nav?: ScreenNavSugar;
+  detailFor?: string;
+  description?: string;
+  agent?: AgentScreenHints;
+  dormant?: boolean; // Screen has no nav entry by design (opened via link or navved by the app); exempts it from the nav-area boot check.
+  visibleWhen?: ScreenVisibility; // UI-only gate, also on direct URL access; handlers still enforce access.
+  fallback?: ScreenFallback; // Same-feature short id or cross-feature QN `<feature>:screen:<id>` shown when `visibleWhen` is unmet (default: standard notice).
+  urlPrefillFields?: string[]; // Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields.
+  submitPrefilled?: boolean; // Submit is enabled without edits: values seeded from navigate `params` count as the user's intent.
+  handler: string; // Write-handler QN dispatched on submit.
+  fields: Readonly<Record<string, FormFieldDefinition>>;
+  layout: EditLayout;
+  redirect?: string; // Navigate here after the reveal is confirmed.
+  cancelTarget?: string | false;
+  listScreenId?: string;
+  access?: AccessRule;
+  reveal: SecretReveal;
+  submitLabel?: string; // i18n-key for the mint button.
+  confirm?: SecretMintConfirmStep; // Proof-of-receipt step rendered on the reveal card in place of the bare acknowledge button — see `SecretMintConfirmStep` doc.
+};
+type SecretNamespaceDefinition = {
+  shortName: string;
+  qualifiedPrefix: string;
+  label: {
+    [locale: string]: string;
+  };
+  hint?: {
+    [locale: string]: string;
+  };
+  scope: "tenant";
+  writeRoles?: string[];
+  nameSchema?: ZodType<string>;
+  valueSchema?: ZodType<string>;
+};
+type SecretNamespaceHandle = {
+  prefix: string;
+  keyFor(name: string): string;
+};
+type SecretNamespaceOptions = Omit<SecretNamespaceDefinition, "shortName" | "qualifiedPrefix">;
+type SessionUser = {
+  id: string;
+  tenantId: TenantId;
+  roles: string[];
+  timezone?: string;
+  locale?: string;
+  claims?: Readonly<Record<string, unknown>>;
+  sid?: string;
+  pat?: {
+    tokenId: string;
+    scopes: string[];
+    allowedQns: string[];
+  };
+  origin?: SessionUserOrigin;
+};
+type StepInstance = { // An instance of a step in a pipeline — what users build via the step-builder (`r.step.compute(...)`).
+  kind: StepKind;
+  args: unknown;
+  onFailure?: StepFailureStrategy;
+};
+type StepResolver<T, TPayload = unknown> = T | ((ctx: PipelineCtx<TPayload>) => T); // A resolver is either a static value or a function that derives the value from the pipeline-context.
+type StorageProviderDestroyTenantHook = TenantResourceDestroyHook;
+type StorageProviderHookCtx = TenantResourceHookCtx;
+type StreamHandlerDef = {
+  name: string;
+  schema: ZodType;
+  handler: StreamHandlerFn;
+  access: AccessRule;
+  rateLimit?: RateLimitDeclaration;
+  escapeHatch?: EscapeHatchDeclaration;
+};
+type TargetRef = {
+  featureId: string;
+  action: string;
+  args?: Readonly<Record<string, unknown>>;
+};
+type TemplateListVariableDef = TemplateVariableCommon & {
+  type: "list";
+  item: Readonly<Record<string, TemplateScalarVariableDef>>;
+  example?: Readonly<Record<string, unknown>>[];
+};
+type TemplateScalarVariableDef = (TemplateVariableCommon & { type: "text"; example?: string; }) | (TemplateVariableCommon & { type: "link"; example?: string; }) | (TemplateVariableCommon & { type: "richText"; example?: string; }) | (TemplateVariableCommon & { type: "money"; example?: number | { amount: number; currency: string; }; }) | (TemplateVariableCommon & { type: "date"; example?: string; }) | (TemplateVariableCommon & { type: "percent"; example?: number; });
+type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef | TemplateImagesVariableDef;
+type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
+type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<TenantDestroyHookResult | void>;
+interface TenantDataHookCtx {
+  db: ExecutorManagedTenantDb;
+  registry: Registry;
+  tenantId: TenantId;
+  deadlineAt?: number;
+  fileProviderResolver?: FileProviderResolver;
+  log?: (message: string) => void;
+}
+type TenantDestroyHookResult =
+  | {
+    done: true;
+    processed?: number;
+  }
+  | {
+    done: false;
+    processed: number;
+  }
+;
+type TenantId = string;
+type TenantLifecycleStatusPlugin = {
+  resolveStatus: (tenantId: TenantId, deps: { db: DbConnection; }) => Promise<{ status: string; } | null>;
+};
+type TenantResourceDestroyHook = (tenantId: TenantId, ctx: TenantResourceHookCtx) => Promise<TenantDestroyHookResult | void>;
+type TenantResourceExtensionName = typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE; // The four `destroyTenant(tenantId, ctx)`-only resource-cleanup extension points.
+interface TenantResourceHookCtx {
+  tenantId: TenantId;
+  deadlineAt?: number;
+  db: DbRunner;
+  fileProviderResolver?: FileProviderResolver;
+  log?: (message: string) => void;
+}
+type TenantUserModel = "single-user" | "multi-user"; // Effective tenant-occupancy model for THIS tenant during a forget run, set by the forget orchestrator.
+type TenantWriteTarget = {
+  db: TenantDb;
+  streamTenantId: TenantId | undefined;
+};
+type TierResolverPlugin = { // Plugin shape for the tier-resolver extension.
+  build: (deps: { db: DbConnection; registry: Registry; cacheSync?: CacheSyncBus; }) => Promise<EffectiveFeaturesResolver>;
+};
+type ToggleReader = (featureName: string) => boolean | undefined;
+type ToolbarAction = ({ kind: "navigate"; id: string; label: string; screen: string; tab?: string; style?: "primary" | "secondary" | "danger"; } | { kind: "writeHandler"; id: string; label: string; handler: string; payload?: Record<string, unknown>; confirm?: string; confirmLabel?: string; style?: "primary" | "secondary" | "danger"; } | { kind: "drawer"; id: string; label: string; screen: string; style?: "primary" | "secondary" | "danger"; title?: string; subtitle?: string; }) & {
+  visibleWhen?: DashboardPanelVisibility; // Shown only while the query's `field` equals `eq` (live, empty payload).
+};
+type TransferAdjacency = ReadonlyMap<string, TransferEdge[]>; // Outgoing edges per type: keyed by the type an edge hangs off, so the mover can ask "what hangs off the rows I just moved" for any type it reaches, at any depth, as often as it reaches it.
+type TransferEdge = {
+  entityName: string;
+  entity: EntityDefinition;
+  parentEntityName: string; // The already-resolved type this edge hangs off — its moved row ids are the parent ids the mover matches this edge's rows against.
+  link: TransferEdgeLink;
+};
+type TransferEdgeLink =
+  | {
+    kind: "parentRef";
+    typeField: string;
+    idField: string;
+  }
+  | {
+    kind: "reference";
+    field: string;
+  }
+;
+type TransitionGraph<TStates extends string = string> = { // Type-safe transition graph.
+  canTransition: (from: TStates, to: TStates) => boolean;
+  allowedFrom: (from: TStates) => TStates[];
+  assertTransition: (from: TStates, to: TStates) => void;
+};
+type TranslationEntry = Readonly<Record<string, TranslationValue>>;
+type TranslationKeys = Readonly<Record<string, TranslationEntry>>;
+type TreeAction = TreeActionBase & ({ screen: string; target?: never; } | { target: TargetRef; screen?: never; });
+type TreeActionDef<TArgs = Record<string, unknown>> = {
+  args?: TArgs;
+};
+type TreeChildrenSubscribe = () => Subscribe<TreeNode[]>;
+type TreeNode = {
+  label: string;
+  icon?: string;
+  state?: TreeNodeState;
+  target?: TargetRef;
+  actions?: TreeAction[];
+  children?: TreeNode[] | TreeChildrenSubscribe;
+  createAction?: TreeAction;
+};
+type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>; // Live-Trial-Gate-Shape.
+type UnitKey = "m2" | "km" | "m" | "kg" | "percent" | "mi";
+type UserDataDeleteHook = (ctx: UserDataHookCtx, strategy: UserDataDeleteStrategy) => Promise<UserDataDeleteHookResult>;
+type UserDataDeleteStrategy = "delete" | "anonymize"; // Strategy for the forget path per entity: - "delete": Physically remove the row (profile, personal notes, sessions).
+type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExportSnippet | null>; // Export hook: collects all data belonging to a user for an entity.
+interface UserDataExportSnippet { // Feature/entity snippet included in the export bundle.
+  entity: string;
+  rows: ReadonlyArray<Record<string, unknown>>;
+  fileRefs?: ReadonlyArray<{ fileRefId: string; storageKey: string; fileName: string; }>; // Optional signed URLs for file references.
+}
+interface UserDataHookCtx {
+  db: TenantDb;
+  registry: Registry; // The app registry.
+  tenantId: TenantId;
+  userId: UserId;
+  buildStorageProvider?: (tenantId: TenantId) => Promise<UserDataStorageProvider | undefined>; // Per-tenant storage-provider resolver, injected by the forget orchestrator from the mounted file-foundation — so a hook deletes binaries from the SAME store the upload/export path uses (delete-target == upload-target by construction).
+  tenantModel?: TenantUserModel; // Effective tenant-occupancy model for this tenant — see {@link TenantUserModel}.
+  userEmailBeforeDelete?: string | null; // Original user email captured before the forget transaction anonymizes it.
+}
+interface UserDataStorageProvider { // Minimal storage surface a file-aware forget hook needs to erase binaries.
+  delete(storageKey: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}
+type ValidateBootOptions = {
+  warnOnUniqueAccessRoles?: boolean; // Warn when an access role is used by exactly one handler/config-key/ field across the whole boot scan — often a typo, but also the normal shape of a legitimate fine-grained role (one role scoped to one admin endpoint on purpose).
+  navAllowlist?: ReadonlySet<string>; // QNs the app's sidebar allowlist admits.
+  navAllowlistExempt?: ReadonlySet<string>; // Nav QNs deliberately left out of the sidebar allowlist because their screen is reachable another way (e.g. as a sub-page of a generated settings hub).
+  env?: Readonly<Record<string, string | undefined>>; // Env the encrypted-field master-key probe reads.
+  entityFieldCipher?: EnvelopeCipher; // The cipher the runner injects after validation (built from the app's `masterKey` or the env keyring).
+  requiredLocales?: string[]; // Locales every translation key must carry across all mounted features (locale packages count).
+};
+type ValidationError = {
+  field: string;
+  error: string;
+};
+type ValidationHookFn = (data: Readonly<Record<string, unknown>>) => ValidationError[] | null;
+type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = { // Workflow definition — the result of defineWorkflow().
+  __kind: "workflow";
+  name: string;
+  trigger: WorkflowTrigger;
+  awaits?: TAwaits; // Declared expected events (workflow-resume-loop.md) — the sole route a waitForEvent step can reach an event type.
+  pipelineDef: PipelineDef<TPayload, TData, { [K in keyof TAwaits]: AwaitedEventType; }>; // The pipeline definition containing the step list closure.
+  idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string); // Idempotency key for deduplication — prevents duplicate runs.
+};
+type WorkspaceDefinition = {
+  id: string;
+  label: string;
+  icon?: string;
+  order?: number;
+  access?: AccessRule;
+  nav?: string[];
+  default?: boolean;
+};
+type WriteEvent<TPayload = unknown> = {
+  type: string;
+  payload: TPayload;
+  user: SessionUser;
+};
+type WriteHandlerDef = {
+  name: string;
+  schema: ZodType;
+  handler: WriteHandlerFn;
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  excludedFields?: string[]; // Fields a generic create/update handler never writes (`excludeFields`).
+  unsafeSkipTransitionGuard?: boolean;
+  rateLimit?: RateLimitDeclaration;
+  additionalRateLimits?: PayloadRateLimitOption[]; // Per-payload-field limits, e.g. per recipient address.
+  rateLimitCost?: (payload: unknown) => number; // Tokens each request books on every declared rateLimit bucket, computed from the validated payload (e.g. `(p) => p.files.length`).
+  escapeHatch?: EscapeHatchDeclaration;
+  reserveBeforeTransaction?: PreTransactionReservation; // Reserves before the handler transaction opens.
+  beforeTransaction?: BeforeTransactionPhase; // 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.
+  beforeTransactionWhenNested?: BeforeTransactionWhenNested; // `"skip"`: a nested ctx.dispatch.write of this handler runs without the beforeTransaction phase (`event.prepared` is undefined) and without a reservation, so the handler does that work inside its own transaction.
+  transaction?: WriteHandlerTransactionMode; // `"perCommand"`: the handler runs without a transaction of its own.
+  tenantlessAnonymous?: boolean; // Lets an anonymous `POST /api/write` for this handler proceed under SYSTEM_TENANT_ID when the host resolves no tenant.
+  perform?: PipelineDef;
+};
+type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined> = {
+  name: TName;
+  schema: TSchema;
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  excludedFields?: string[]; // Set by the entity convention create/update handlers; see WriteHandlerDef.excludedFields.
+  unsafeSkipTransitionGuard?: boolean;
+  rateLimit?: RateLimitDeclaration;
+  additionalRateLimits?: PayloadRateLimitOption[];
+  rateLimitCost?: (payload: z.infer<TSchema>) => number; // Tokens each request books on every declared rateLimit bucket, computed from the validated payload (e.g. `(p) => p.files.length`).
+  escapeHatch?: EscapeHatchDeclaration;
+  reserveBeforeTransaction?: PreTransactionReservation;
+  beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
+  beforeTransactionWhenNested?: TWhenNested;
+  tenantlessAnonymous?: boolean;
+  transaction?: WriteHandlerTransactionMode;
+  handler: (event: PreparedWriteEvent<z.infer<TSchema>, PreparedOrSkipped<TPrepared, TWhenNested>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+  perform?: PipelineDef<z.infer<TSchema>, TData>;
+};
+type WriteHandlerFn<TPayload = unknown, TData = unknown> = (event: WriteEvent<TPayload>, context: HandlerContext) => Promise<WriteResult<TData>>;
+type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined> = ({ handler: (event: PreparedWriteEvent<z.infer<TSchema>, PreparedOrSkipped<TPrepared, TWhenNested>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>; perform?: never; } | { perform: PipelineDef<z.infer<TSchema>, TData>; handler?: never; }) & {
+  name: TName;
+  schema: TSchema;
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  unsafeSkipTransitionGuard?: boolean;
+  rateLimit?: RateLimitDeclaration;
+  additionalRateLimits?: PayloadRateLimitOption[];
+  rateLimitCost?: (payload: z.infer<TSchema>) => number; // Tokens each request books on every declared rateLimit bucket, computed from the validated payload (e.g. `(p) => p.files.length`).
+  escapeHatch?: EscapeHatchDeclaration;
+  reserveBeforeTransaction?: PreTransactionReservation;
+  beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
+  beforeTransactionWhenNested?: TWhenNested;
+  tenantlessAnonymous?: boolean;
+  transaction?: WriteHandlerTransactionMode;
+};
+type WriteResult<TData = unknown> =
+  | {
+    isSuccess: true;
+    data: TData;
+  }
+  | WriteFailure
+;
+```