@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/src/feature.ts

@@ -1,1132 +0,0 @@
-import type * as z from "zod";
-import type { ZodType } from "zod";
-import type {
-  ConfigKeyDefinition,
-  ConfigKeyHandle,
-  ConfigKeyType,
-  ConfigSeedDef,
-  ExtensionSelectorDef,
-  JobDefinition,
-  JobHandlerFn,
-  NotificationDataFn,
-  NotificationDefinition,
-  NotificationRecipientFn,
-  NotificationTemplateFn,
-  ReferenceDataDef,
-  RegistrarExtensionDef,
-  RegistrarExtensionRegistration,
-  TranslationKeys,
-  TranslationsDef,
-} from "./config";
-import type {
-  QueryHandlerDefinition,
-  StreamHandlerDefinition,
-  WriteHandlerDefinition,
-} from "./define-handler";
-import type { RegisterEntityCrudOptions } from "./entity-handlers";
-import type { EntityTableMeta } from "./entity-table-meta-types";
-import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map";
-import type { EntityDefinition } from "./fields";
-import type {
-  AccessRule,
-  AgentHandlerHints,
-  AuthClaimsFn,
-  AuthClaimsHookDef,
-  ClaimKeyDefinition,
-  ClaimKeyHandle,
-  ClaimKeyType,
-  DeclarativeEventMigration,
-  EntityRef,
-  EscapeHatchDeclaration,
-  EventDef,
-  EventMigrationDef,
-  EventPiiStance,
-  EventUpcastFn,
-  HandlerRef,
-  NameOrRef,
-  QualifiedEventName,
-  QueryHandlerDef,
-  QueryHandlerFn,
-  RateLimitDeclaration,
-  StreamHandlerDef,
-  StreamHandlerFn,
-  WriteHandlerDef,
-  WriteHandlerFn,
-} from "./handlers";
-import type {
-  EntityHookMap,
-  HookMap,
-  HookPhase,
-  OwnedFn,
-  PostDeleteHookFn,
-  PostQueryHookFn,
-  PostSaveHookFn,
-  PreDeleteHookFn,
-  PreQueryHookFn,
-  PreSaveHookFn,
-  SearchPayloadContributorFn,
-  ValidationHookFn,
-} from "./hooks";
-import type { HttpRouteDefinition } from "./http-route";
-import type { ContentCollectionDefinition, NavDefinition } from "./nav";
-import type {
-  EntityProjectionExtension,
-  MultiStreamProjectionDefinition,
-  ProjectionDefinition,
-} from "./projection";
-import type { EntityRelations, RelationDefinition } from "./relations";
-import type { ScreenDefinition } from "./screen";
-import type { TreeActionDef, TreeActionsHandle } from "./tree-node";
-import type { WorkspaceDefinition } from "./workspace";
-
-// --- Metrics (declared by features via r.metric()) ---
-
-export type FeatureMetricType = "counter" | "histogram" | "gauge";
-
-// The user-facing short form written in a feature. The Framework prefixes it
-// with `kumiko_<featureName>_` to produce the fully-qualified Prometheus name.
-export type FeatureMetricDef = {
-  readonly shortName: string;
-  readonly type: FeatureMetricType;
-  readonly description?: string;
-  readonly labels?: readonly string[];
-  readonly buckets?: readonly number[];
-  readonly unit?: string;
-  // When true, Framework auto-adds tenant_id to labels (ctx-driven). Default
-  // false — cardinality multiplies by tenant count, so opt-in.
-  readonly tenantLabel?: boolean;
-};
-
-export type MetricOptions = Omit<FeatureMetricDef, "shortName">;
-
-// --- Secret Keys (declared by features via r.secret()) ---
-
-// A feature-declared secret. The fully-qualified name is
-// `<featureName>:<shortName>` — the Framework prefixes. Ops see the
-// qualified name in list / audit; feature code reads it via
-// ctx.secrets.get(tenantId, SecretKeys.stripeKey) with the typed handle.
-export type SecretKeyDefinition = {
-  // Short name inside the feature (e.g. "stripe.apiKey"). Qualified to
-  // `<feature>:<shortName>` at registry-build time.
-  readonly shortName: string;
-  // Qualified name — `<feature>:<shortName>`. Set during registry build.
-  readonly qualifiedName: string;
-  // i18n label for TenantAdmin UI.
-  readonly label: { readonly [locale: string]: string };
-  // Optional redaction function. Takes the plaintext, returns the preview
-  // shown in list handlers. Default is first-3-chars + bullets.
-  readonly redact?: (plaintext: string) => string;
-  // Short human hint shown in UI ("Find this in your Stripe dashboard ...").
-  readonly hint?: { readonly [locale: string]: string };
-  // Per-secret scope. v1 only "tenant" — user / system scopes ship in v2.
-  readonly scope: "tenant";
-  // Tenant must set this secret before the owning feature works. Surfaced
-  // by readiness:query:status; keep in sync with the missing-secret throw
-  // in the feature's build-fn.
-  readonly required?: boolean;
-};
-
-export type SecretOptions = Omit<SecretKeyDefinition, "shortName" | "qualifiedName">;
-
-// Typed reference returned by r.secret(). Lets feature code pass a
-// strongly-named handle to ctx.secrets.get instead of retyping the
-// qualified string. Parallels ConfigKeyHandle from the config system.
-export type SecretKeyHandle = {
-  readonly name: string;
-};
-
-// --- Store tables (declared by features via r.storeTable()) ---
-// Post-drizzle-cut: unified with the former r.unmanagedTable() — both
-// carried the same reason/audit contract, differing only in whether the
-// table value was a legacy Drizzle PgTable (storeTable) or the framework-
-// native EntityTableMeta (unmanagedTable, consumed by migrate-runner).
-// EntityTableMeta was the forward-compatible shape, so storeTable adopted it.
-
-/** Options accepted by `r.storeTable()`. The `reason` is required so the
- *  bypass leaves an audit trail at the registration site — reviewers can
- *  judge legitimacy without spelunking into history, and a future cleanup
- *  pass can find candidates for migration to `r.entity()`. */
-export type StoreTableOptions = {
-  /** Why this table needs to bypass the event-sourcing system. Examples:
-   *  "imported from pre-ES system, read-only", "external Stripe webhook
-   *  payload cache, write-only by webhook handler", "denormalised
-   *  projection of a non-Kumiko data source". */
-  readonly reason: string;
-  /** Direct-write stores skip the executor, so the executor's PII
-   *  encryption never runs for them — a feature whose meta carries
-   *  piiSubjectFields must encrypt those fields itself before every
-   *  insert/update and declare that here, or boot fails (#820). */
-  readonly piiEncryptedOnWrite?: true;
-};
-
-/** Per-feature store-table registration. `meta` is the `EntityTableMeta`
- *  (framework-native shape used by `migrate-runner`). Carries the
- *  bypass-justification reason but knows nothing about the owning
- *  feature — that's added when the registry aggregates entries
- *  cross-feature into `StoreTableDef`. */
-export type StoreTableEntry = {
-  readonly name: string;
-  readonly meta: EntityTableMeta;
-  readonly reason: string;
-  readonly piiEncryptedOnWrite?: true;
-};
-
-/** Registry-aggregated store-table — the per-feature `StoreTableEntry` plus
- *  the owning feature name. This is what `Registry.getAllStoreTables()`
- *  exposes to readers (dev-server, ops UIs). */
-export type StoreTableDef = StoreTableEntry & {
-  readonly featureName: string;
-};
-
-// --- UI-Hints (manifest-only, picker/scaffolder metadata) ---
-
-// Optional, declarative UI metadata declared via `r.uiHints({...})`. Surfaces
-// in feature-manifest.json under `feature.uiHints`. Consumers (the picker in
-// `create-kumiko-app`, the docs feature-reference) treat absent hints as
-// "no special treatment" — bare feature.name + feature.description still work.
-//
-// Keep this list lean. Anything that already has a home on the feature
-// (configKeys.scope/default/encrypted, secretKeys, requires, etc.) lives there.
-// Only add fields here that are genuinely UI-only.
-// "select"/"text" variants dropped (569/1) — no bundled feature uses anything
-// but "boolean" yet and the picker doesn't render them either; re-add once a
-// real feature needs them.
-export type UiHintOption = {
-  readonly key: string;
-  readonly label: string;
-  readonly type: "boolean";
-  readonly default: boolean;
-};
-
-export type UiHints = {
-  // Picker-facing label ("Auth · Email + Password" instead of the bare
-  // feature-name "auth-email-password").
-  readonly displayLabel?: string;
-  // Grouping for the picker. Free-form string; the picker sorts/groups by it.
-  readonly category?: string;
-  // Pre-checked in the picker when the user runs `bun create kumiko-app`.
-  readonly recommended?: boolean;
-  // Sub-options the picker asks about per-feature (e.g. "Password-Reset-Flow
-  // on/off"). The scaffolder maps each key to a generator decision; the
-  // framework doesn't act on them at runtime.
-  readonly configurableOptions?: readonly UiHintOption[];
-};
-
-// --- Feature Definition (output of defineFeature) ---
-
-// Ctx passed to r.bootCheck(fn) — the full mounted-feature set, so a check
-// can inspect any other feature's shape (entities, PII fields, etc.).
-export type BootCheckContext = {
-  readonly features: readonly FeatureDefinition[];
-};
-export type BootCheckFn = (ctx: BootCheckContext) => void;
-
-export type FeatureDefinition = {
-  readonly name: string;
-  // Docs-lead paragraph declared via r.describe(). Flows through the
-  // manifest introspection into the generated feature-reference pages.
-  readonly description?: string;
-  readonly systemScope: boolean;
-  // Set from the setup-callback return — typed via `defineFeature<TExports>`.
-  // `undefined` for setups that return nothing.
-  readonly exports?: unknown;
-  readonly requires: readonly string[];
-  readonly optionalRequires: readonly string[];
-  // Read-side projection-tables this feature is allowed to write via
-  // r.step.unsafeProjectionUpsert / unsafeProjectionDelete. Declared via
-  // r.requires.projection("table_name"). Hard requirement — boot-error
-  // if a step targets a non-listed table or one that's already an
-  // r.entity-registered aggregate-table. See step-vocabulary.md Q10.
-  readonly requiredProjections: ReadonlySet<string>;
-  // Tier-2 step kinds opted-in via r.requires.step("webhook.send"). Q9.
-  readonly requiredSteps: ReadonlySet<string>;
-  // Declared via r.toggleable({ default }). Presence makes the feature
-  // operator-switchable via the feature-toggles bundled feature; absence
-  // means the feature is always-on (e.g. auth, tenant, user — core infra
-  // that would brick the system if switchable).
-  readonly toggleableDefault?: boolean;
-  // Declarative UI metadata for picker/scaffolder tooling. Set via r.uiHints().
-  // Pure manifest-side info — the framework runtime doesn't read it.
-  readonly uiHints?: UiHints;
-  // entities/hooks/entityHooks are optional: defineFeature always
-  // materializes them, but hand-built definitions at system boundaries
-  // (test fixtures, partial boots — see registry.test.ts "slot robustness")
-  // omit them and the registry guards against that. Type follows runtime.
-  readonly entities?: Readonly<Record<string, EntityDefinition>>;
-  // Optional backing Drizzle table per entity, declared via the third arg of
-  // `r.entity(name, def, { table })`. Source of truth for the physical DDL
-  // when the table carries columns/indexes the field-DSL can't express
-  // (e.g. secrets' envelope jsonb without default). `collectTableMetas` and
-  // the registry's implicit-projection use this object instead of the
-  // field-derived table, so generate + test-push + executor share ONE table.
-  readonly entityTables?: Readonly<Record<string, unknown>>;
-  readonly relations: Readonly<Record<string, EntityRelations>>;
-  readonly writeHandlers: Readonly<Record<string, WriteHandlerDef>>;
-  readonly queryHandlers: Readonly<Record<string, QueryHandlerDef>>;
-  readonly streamHandlers: Readonly<Record<string, StreamHandlerDef>>;
-  readonly translations: TranslationKeys;
-  readonly hooks?: HookMap;
-  readonly entityHooks?: EntityHookMap;
-  // F3 search-payload-extension — per-entity contributors that add flat fields
-  // to the search-index payload during indexing. Keyed by entityName. Wrapped
-  // in OwnedFn for feature-toggle filtering (consistent with postQuery-Hooks).
-  readonly searchPayloadExtensions?: Readonly<
-    Record<string, readonly OwnedFn<SearchPayloadContributorFn>[]>
-  >;
-  readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
-  readonly configSeeds: readonly ConfigSeedDef[];
-  readonly jobs: Readonly<Record<string, JobDefinition>>;
-  readonly registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
-  readonly extensionUsages: readonly RegistrarExtensionRegistration[];
-  readonly extensionSelectors: readonly ExtensionSelectorDef[];
-  /**
-   * Cross-feature API names this feature exposes via `r.exposesApi(name)`.
-   * Pure Marker-Deklaration — die echte Implementation wird als
-   * Query-/Write-Handler unter dem QN-Pattern registriert (z.B.
-   * `compliance-profiles:query:effective-profile`). Boot-Validator prüft
-   * dass jedes `r.usesApi(name)` einen passenden Exposer hier findet —
-   * Tippfehler oder Drop-Refactorings werden zu Boot-Fail statt Runtime-Crash.
-   */
-  readonly exposedApis: ReadonlySet<string>;
-  /**
-   * Cross-feature API names this feature calls. Pflicht-Boot-Check:
-   * jeder Eintrag muss in `exposedApis` irgendeines Features auftauchen
-   * UND das Provider-Feature muss in requires/optionalRequires sein.
-   */
-  readonly usedApis: ReadonlySet<string>;
-  /**
-   * Boot-time mount-invariant checks declared via `r.bootCheck(fn)`. Run
-   * once per feature after all other boot-validators, each with a ctx
-   * exposing the full mounted-feature set — throw to fail the boot with a
-   * feature-authored message (framework wraps it with `[Feature <name>]`).
-   */
-  readonly bootChecks: readonly BootCheckFn[];
-  readonly referenceData: readonly ReferenceDataDef[];
-  readonly notifications: Readonly<Record<string, NotificationDefinition>>;
-  readonly events: Readonly<Record<string, EventDef>>;
-  // Event schema migrations declared via defineEvent's `migrations` option. Keyed by event
-  // short-name; each entry carries the step transforms (fromVersion →
-  // toVersion). The registry stitches these with the defineEvent-declared
-  // current version and exposes a per-qualified-name upcaster chain.
-  readonly eventMigrations: Readonly<Record<string, readonly EventMigrationDef[]>>;
-  readonly configReads: readonly string[];
-  // Handler → entity mapping inferred from the colon convention
-  // ("entityName:verb") via tryMapEntity in defineFeature.
-  readonly handlerEntityMappings: Readonly<Record<string, string>>;
-  // Metrics declared via r.metric(). Short names — Framework prefixes on boot.
-  readonly metrics: Readonly<Record<string, FeatureMetricDef>>;
-  // Secret keys declared via r.secret(). Short names — Framework prefixes to
-  // "<feature>:<short>" during registry build.
-  readonly secretKeys: Readonly<Record<string, SecretKeyDefinition>>;
-  // Projections declared via r.projection(). Keyed by projection name; executor
-  // looks them up by source-entity at write-time.
-  readonly projections: Readonly<Record<string, ProjectionDefinition>>;
-  // Implicit-projection extensions declared via r.extendEntityProjection().
-  // Keyed by entity name; merged into that entity's implicit projection at
-  // registry build so rebuildProjection replays the extension's events.
-  readonly entityProjectionExtensions?: Readonly<
-    Record<string, readonly EntityProjectionExtension[]>
-  >;
-  // Multi-stream projections — cross-aggregate async read-models. Keyed by
-  // short name; the dispatcher wraps each into an EventConsumer with its
-  // own cursor.
-  readonly multiStreamProjections: Readonly<Record<string, MultiStreamProjectionDefinition>>;
-  // Auth-claims hooks declared via r.authClaims(). Executed at login (and
-  // switch-tenant) time; their returned records are merged into
-  // SessionUser.claims under the auto-prefix "<featureName>:<key>".
-  readonly authClaimsHooks: readonly AuthClaimsFn[];
-  // Declared claim keys via r.claimKey(). Shorts keyed by their JS-side
-  // short name, qualified name qualified at registration time.
-  readonly claimKeys: Readonly<Record<string, ClaimKeyDefinition>>;
-  // Screen definitions declared via r.screen(). Keyed by the feature-local
-  // short id; the registry qualifies to "<feature>:screen:<id>" on boot.
-  // Pure data — ui-core + renderer packages interpret; engine only stores
-  // and validates entity/field references against the feature's entities.
-  readonly screens: Readonly<Record<string, ScreenDefinition>>;
-  // Nav entries declared via r.nav(). Keyed by the feature-local short id;
-  // registry qualifies to "<feature>:nav:<id>". Flat list — the renderer's
-  // resolveNavigation assembles the tree from parent refs at mount time.
-  readonly navs: Readonly<Record<string, NavDefinition>>;
-  // Workspaces declared via r.workspace(). Keyed by feature-local short id;
-  // registry qualifies to "<feature>:workspace:<id>". Pure UI metadata —
-  // shellWorkspaces consumes the resolved per-workspace nav list at mount
-  // time; engine validates roles + nav refs at boot.
-  readonly workspaces: Readonly<Record<string, WorkspaceDefinition>>;
-  // Tree-Actions-Map declared via r.treeActions(). At-most-one per feature
-  // (only-once-guard at registration). Erased to `Record<string,
-  // TreeActionDef>` for runtime registry-lookup (Visual-Tree-Component
-  // dispatching, Pattern-AST consumers). The compile-time-typed surface
-  // is the registrar's return value (TreeActionsHandle) which the
-  // feature exports via setup-return — buildTarget consumes the handle,
-  // not this slot. See visual-tree.md A5 + A7.
-  readonly treeActions?: Readonly<Record<string, TreeActionDef>>;
-  // Content collections declared via r.contentCollection(). Keyed by the
-  // feature-local short id. Each one also produced a nav entry under the
-  // same id — this slot carries the `kind` the client needs to build the
-  // matching tree provider, which a NavDefinition has no place for.
-  readonly contentCollections?: Readonly<Record<string, ContentCollectionDefinition>>;
-  // HTTP-Routes declared via r.httpRoute(). Index is "METHOD path"
-  // (z.B. "GET /feed.xml") — eindeutig pro Feature. Die App-Server-
-  // Boot-Stage iteriert getAllHttpRoutes() und mountet jede Route auf
-  // den Hono-app (außerhalb /api/*). Pattern symmetrisch zu queryHandlers/
-  // writeHandlers — Routes leben mit dem Feature, nicht im Bootstrap.
-  readonly httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
-  // Store tables declared via r.storeTable() — bypass the event-sourcing
-  // system. Keyed by feature-local short name (derived from
-  // meta.tableName). The registry attaches featureName on aggregation,
-  // lifting StoreTableEntry → StoreTableDef. `kumiko schema generate`
-  // aggregates these alongside r.entity()-derived metas to build the
-  // full schema.
-  readonly storeTables: Readonly<Record<string, StoreTableEntry>>;
-  // Optional Zod-schema for env-vars this feature reads at runtime.
-  // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
-  // this to build one app-wide schema for boot-validation + dry-run
-  // rendering. Absence means the feature reads no env-vars (or hasn't
-  // been migrated yet — Sprint-9 migration is add-only per phase).
-  readonly envSchema?: z.ZodObject<z.ZodRawShape>;
-  // Factory guarantee: two instances with shallow-equal dedupeOptions are interchangeable.
-  readonly dedupeOptions?: Readonly<Record<string, unknown>>;
-};
-
-// --- Feature Registrar (the "r" object in defineFeature) ---
-
-type RefOrRefs = NameOrRef | readonly NameOrRef[];
-// Entity-wide hook target — "all query/write handlers of this entity",
-// same reach r.entityHook() used to have. Only valid for postSave/
-// preDelete/postDelete/postQuery (the same 4 types entityHook covered);
-// hook() throws at registration time if used with validation/preSave/
-// preQuery.
-type HookTarget = RefOrRefs | { readonly allOf: NameOrRef };
-
-/**
- * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
- * default-`string` keeps every existing usage zero-config. Strict-typed
- * features (apps that opt into the literal-name flavour) get propagated
- * through to `defineEvent` so the returned `EventDef.name` is a literal
- * `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`. That literal
- * threads through `ctx.appendEvent({ type: eventDef.name, ... })`,
- * keeping strict-mode alive even when handlers route via `eventDef.name`
- * instead of hand-typed string literals.
- */
-/**
- * `r.requires` is a callable+namespace: existing call form takes feature
- * names (`r.requires("auth", "tenant")`), the `.projection` extension
- * declares read-side projection tables that this feature's pipeline
- * steps are allowed to write via `r.step.unsafeProjectionUpsert`.
- * Hard-required for any unsafeProjection-* step usage (see Q10).
- */
-export type RequiresApi = ((...featureNames: string[]) => void) &
-  // Object-Form — the shape the feature-ast renderer (`render.ts`) emits
-  // for Designer/AI-generated code. A single object argument with named
-  // fields is easier to generate correctly than positional args whose
-  // count/order vary per registrar method.
-  ((options: { readonly features: readonly string[] }) => void) & {
-    readonly projection: (tableName: string) => void;
-    // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
-    readonly step: (stepKind: string) => void;
-  };
-
-export type FeatureRegistrar<TFeature extends string = string> = {
-  systemScope(): void;
-  // One-to-three-sentence docs-lead for the feature ("what it does + when
-  // you need it"). At most once per feature; must be non-empty.
-  describe(text: string): void;
-  requires: RequiresApi;
-  optionalRequires(...featureNames: string[]): void;
-  optionalRequires(options: { readonly features: readonly string[] }): void;
-  // Declare the feature as operator-togglable. `default` is the effective
-  // state when no global-toggle row exists. Must be called at most once per
-  // feature; calling on an always-on feature (e.g. auth/tenant/user) is a
-  // bug — and one nothing catches at boot, so don't.
-  toggleable(options: { default: boolean }): void;
-  // Picker/scaffolder metadata — see UiHints. At most once per feature.
-  uiHints(hints: UiHints): void;
-
-  entity(
-    name: string,
-    definition: EntityDefinition,
-    options?: { readonly table?: unknown },
-  ): EntityRef;
-  entity(definition: { readonly name: string } & EntityDefinition): EntityRef;
-
-  // Shorthand for registerEntityCrud(r, ...), scoped to this registrar.
-  crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
-
-  writeHandler<TName extends string, TSchema extends ZodType>(
-    def: WriteHandlerDefinition<TName, TSchema>,
-  ): HandlerRef;
-  writeHandler<TSchema extends ZodType>(
-    name: string,
-    schema: TSchema,
-    handler: WriteHandlerFn<z.infer<TSchema>>,
-    options: {
-      access: AccessRule;
-      rateLimit?: RateLimitDeclaration;
-      description?: string;
-      agent?: AgentHandlerHints;
-      escapeHatch?: EscapeHatchDeclaration;
-    },
-  ): HandlerRef;
-
-  queryHandler<TName extends string, TSchema extends ZodType>(
-    def: QueryHandlerDefinition<TName, TSchema>,
-  ): HandlerRef;
-  queryHandler<TSchema extends ZodType>(
-    name: string,
-    schema: TSchema,
-    handler: QueryHandlerFn<z.infer<TSchema>>,
-    options: {
-      access: AccessRule;
-      rateLimit?: RateLimitDeclaration;
-      outputSchema?: ZodType;
-      description?: string;
-      agent?: AgentHandlerHints;
-      escapeHatch?: EscapeHatchDeclaration;
-    },
-  ): 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;
-  // TDef inferred from the literal — keeps the excess-property check
-  // resolved against the matching RelationDefinition union member instead
-  // of distributing across all three (which spuriously rejects valid
-  // combinations when checked directly against the raw union).
-  relation<TDef extends RelationDefinition>(
-    definition: { readonly entity: NameOrRef; readonly name: string } & TDef,
-  ): void;
-
-  hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
-  // escapeHatch grants this hook (not the handler) identity-switches beyond its caller — see system-identity-switch.ts.
-  hook(
-    type: "preSave",
-    target: RefOrRefs,
-    fn: PreSaveHookFn,
-    options?: { escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-  // postSave/preDelete/postDelete/postQuery accept `{ allOf: entityRef }` —
-  // fires for every write/query handler of that entity, replacing the old
-  // r.entityHook(type, entity, fn). postQuery's entity-wide form fires for
-  // ALL query-handlers of the entity (e.g. customFields-bundle merging
-  // custom-fields-jsonb into every read); no phase semantics there
-  // (synchronous after handler-execute, before field-access-filter).
-  hook(
-    type: "postSave",
-    target: HookTarget,
-    fn: PostSaveHookFn,
-    options?: { phase?: HookPhase; escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-  // preDelete always runs in-transaction (it guards the delete — there is no
-  // meaningful "after" for a pre-hook). No phase option.
-  hook(
-    type: "preDelete",
-    target: HookTarget,
-    fn: PreDeleteHookFn,
-    options?: { escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-  hook(
-    type: "postDelete",
-    target: HookTarget,
-    fn: PostDeleteHookFn,
-    options?: { phase?: HookPhase; escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-  hook(
-    type: "preQuery",
-    target: RefOrRefs,
-    fn: PreQueryHookFn,
-    options?: { escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-  hook(
-    type: "postQuery",
-    target: HookTarget,
-    fn: PostQueryHookFn,
-    options?: { escapeHatch?: EscapeHatchDeclaration },
-  ): void;
-
-  // F3 — Search-Payload-Extension: contributor function adds flat fields to
-  // an entity's search-index document. Fires synchronously during
-  // buildSearchDocument indexing. Use-case: custom-fields-bundle merging
-  // customFields-jsonb-keys flat into search-doc; tags-bundle projecting
-  // tags-array as searchable. See `SearchPayloadContributorFn`.
-  searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
-
-  // Single-key form: bare handle, no wrapping record, no seeds (callers
-  // needing seeds use the multi-key form below).
-  config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
-
-  // Multi-key form: returns a handle map keyed exactly like the input. Pass
-  // any handle to `ctx.config(handle)` to get the value type narrowed by the
-  // key's `type`. Optional `seeds` declare boot-time system-rows that are
-  // written via the event-store executor — idempotent, skipped when the
-  // stream already exists.
-  config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
-    readonly keys: TKeys;
-    readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
-  }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
-
-  job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
-  job(definition: JobDefinition): void;
-
-  notification(
-    name: string,
-    definition: {
-      readonly trigger: { readonly on: NameOrRef };
-      readonly recipient: NotificationRecipientFn;
-      readonly data: NotificationDataFn;
-      readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-    },
-  ): void;
-  notification(definition: {
-    readonly name: string;
-    readonly trigger: { readonly on: NameOrRef };
-    readonly recipient: NotificationRecipientFn;
-    readonly data: NotificationDataFn;
-    readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-  }): void;
-
-  translations(def: TranslationsDef): void;
-
-  // Register an event payload shape. Returns the qualified def so callers
-  // can pass `.name` to ctx.appendEvent without hand-building the
-  // "<feature>:event:<short>" string.
-  //
-  // `options.version` declares the CURRENT schema generation. Defaults to 1
-  // on first registration. When you bump the payload shape, add a step to
-  // `options.migrations` covering N -> N+1 — the framework refuses to boot
-  // if the chain from 1 to `version` has gaps. Migrations were formerly a
-  // separate r.eventMigration() call; folded in here because an event and
-  // its schema evolution are one lifecycle, not two registrar concepts
-  // (#1082 step 8) — transforms are pure functions (old payload in, new
-  // payload out) and run once per read, not once per event persisted, so
-  // keep them cheap.
-  //
-  // `options.piiFields` is a mandatory, explicit PII stance (fw#2558) —
-  // registration fails without one. Pass a map of payload fields to their
-  // owning subject via `{ personal: { of: "<ownerField>" } }` (the older
-  // `{ subjectField: "<ownerField>" }` form still works) for fields carrying
-  // personal data (encrypted under that user's DEK, crypto-shredding #799),
-  // or `"none"` to declare the payload holds no personal data. append()
-  // enforces the resulting catalog on every write path.
-  //
-  // When the schema lets the owner field be null/undefined, the stance must
-  // also say what happens on those writes — `whenAbsent: "tenant"` encrypts
-  // under the envelope tenant key, `whenAbsent: "plaintext"` acknowledges an
-  // unshreddable value. Registration fails without one, and an owner that is
-  // empty at append time with no declared fallback aborts the write (fw#2776).
-  defineEvent<const TInner extends string, TPayload>(
-    name: TInner,
-    schema: ZodType<TPayload>,
-    options: {
-      readonly version?: number;
-      readonly piiFields: EventPiiStance;
-      readonly migrations?: readonly {
-        readonly fromVersion: number;
-        readonly toVersion: number;
-        readonly transform: EventUpcastFn | DeclarativeEventMigration;
-      }[];
-    },
-  ): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
-
-  readsConfig(...qualifiedKeys: string[]): void;
-  readsConfig(options: { readonly keys: readonly string[] }): void;
-
-  referenceData(
-    entity: NameOrRef,
-    data: readonly Record<string, unknown>[],
-    options?: { upsertKey?: string },
-  ): void;
-  referenceData(definition: {
-    readonly entity: NameOrRef;
-    readonly data: readonly Record<string, unknown>[];
-    readonly upsertKey?: string;
-  }): void;
-
-  extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
-
-  useExtension<N extends string>(
-    extensionName: N,
-    entity: NameOrRef,
-    ...options: ExtensionOptionsArgs<N>
-  ): void;
-  useExtension<N extends string>(
-    definition: { readonly name: N; readonly entity: NameOrRef } & ExtensionOptionsFor<N>,
-  ): void;
-
-  /**
-   * Declares which config key selects the active provider under an
-   * extension point — called by the point-owning foundation (e.g.
-   * `r.extensionSelector("mailTransport", configKeys.provider)`).
-   * Readiness gating counts a provider-feature's `required` keys and
-   * secrets only while that provider is the selected one. Registry-build
-   * fails on duplicate declarations per extension and on selector keys
-   * that no mounted feature declares. A masked tenant selector key makes the
-   * Settings-Hub render one tenant dashboard for the owner: the selector as a
-   * select of the mounted plugin ids, the selected plugin's config and secrets
-   * as panels, and plugin features lose their own tenant nav. `config:write:set`
-   * rejects unknown plugin ids (`""` clears).
-   */
-  extensionSelector(extensionName: string, key: { readonly name: string } | string): void;
-
-  /**
-   * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
-   * unter dem genannten Namen bereit. Die eigentliche Implementation
-   * wird separat als Query- oder Write-Handler unter dem QN-Pattern
-   * registriert; `r.exposesApi` ist reine Boot-Check-Surface.
-   *
-   * Boot-Validator prüft, dass jedes `r.usesApi(name)` einen passenden
-   * Exposer findet, dass das Exposer-Feature in requires/optionalRequires
-   * gelisted ist und dass kein API-Name doppelt exposed wird.
-   *
-   * ```ts
-   * defineFeature("compliance-profiles", (r) => {
-   *   r.exposesApi("compliance.forTenant");
-   *   r.queryHandler({
-   *     name: "compliance:query:for-tenant",
-   *     // ... echte Implementation
-   *   });
-   * });
-   * ```
-   */
-  exposesApi(apiName: string): void;
-
-  /**
-   * Declares that this feature calls a cross-feature API. Boot-Validator
-   * checkt dass irgendein anderes Feature `r.exposesApi(apiName)` macht
-   * und dass dieses Feature `r.requires/optionalRequires` darauf hat.
-   *
-   * ```ts
-   * defineFeature("user-data-rights", (r) => {
-   *   r.requires("compliance-profiles");
-   *   r.usesApi("compliance.forTenant");
-   * });
-   * ```
-   */
-  usesApi(apiName: string): void;
-
-  /**
-   * Declares a boot-time mount-invariant for this feature. `fn` runs once
-   * at boot with a ctx exposing every mounted feature — throw to fail the
-   * boot with a clear message. Multiple calls per feature are allowed.
-   *
-   * Use for cross-feature invariants that `r.requires` can't express
-   * because they're conditional (only fail when the feature has a
-   * specific shape), e.g. "if this feature has PII entities, some
-   * user-data-hook feature must be mounted" (the prompt-store trap,
-   * kumiko-enterprise#229 — a UserData feature was written but never
-   * mounted, and nothing caught it at boot):
-   *
-   * ```ts
-   * defineFeature("prompt-store", (r) => {
-   *   const promptFields = { text: createTextField({ personal: "self", find: "none" }) };
-   *   r.entity("prompt", { fields: promptFields });
-   *   r.bootCheck(({ features }) => {
-   *     // Conditional on this feature's own shape (has a pii field) —
-   *     // r.requires("user-data-hook") can't express that, it would fail
-   *     // even for a prompt-store variant with no PII fields at all.
-   *     const hasPiiField = Object.values(promptFields).some((f) => f.pii);
-   *     const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
-   *     if (hasPiiField && !hasUserDataHook) {
-   *       throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
-   *     }
-   *   });
-   * });
-   * ```
-   */
-  bootCheck(fn: BootCheckFn): void;
-
-  // Declare a metric. Short name (without kumiko_<feature>_ prefix) — Framework
-  // qualifies it on boot. Validation (snake_case + typ-suffix) runs at boot.
-  // Usage at runtime: ctx.metrics.inc("created_total", { status: "new" }).
-  metric(shortName: string, options: MetricOptions): void;
-  metric(definition: { readonly name: string } & MetricOptions): void;
-
-  // Declare a secret key. Qualified name follows "<feature>:secret:<kebab>"
-  // via the QN helper. Returns a typed handle so feature code can pass it
-  // to ctx.secrets.get without retyping the qualified string — same
-  // ergonomics as r.config's handle.
-  secret(shortName: string, options: SecretOptions): SecretKeyHandle;
-  secret(definition: { readonly name: string } & SecretOptions): SecretKeyHandle;
-
-  // Register a projection driven by events of one or more source entities.
-  // The runtime fires projection.apply[event.type] inside the event-store's
-  // transaction, so projections stay consistent with the events that feed them.
-  projection(definition: ProjectionDefinition): void;
-
-  // Register a cross-aggregate async projection. The event-dispatcher owns
-  // delivery via a dedicated cursor — at-least-once, strictly-ordered by
-  // events.id. Handlers must be idempotent. Marten's MultiStreamProjection
-  // equivalent: customer billing summaries, cross-feature audit views,
-  // saga state machines where a single view spans many aggregate types.
-  // Omit `table` for pure side-effect handlers (notifications, webhooks,
-  // external-system sync) — the dispatcher still delivers at-least-once with
-  // per-consumer ordering and dead-letter behaviour.
-  multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
-
-  // Merge extra apply handlers (+ extra event sources) into an entity's
-  // implicit projection so rebuildProjection replays event types a bundled
-  // extension materializes into the HOST entity's table (custom-fields
-  // pattern). Rebuild-only: the inline runner skips implicit projections —
-  // live delivery stays with the extension's own MSP. The entity must be
-  // declared via r.entity in the SAME feature; unknown entities and
-  // apply-key collisions fail at registry build.
-  extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
-
-  // Register a function that contributes claims into SessionUser.claims at
-  // login time. Multiple features (and multiple calls within one feature)
-  // are allowed; returns are merged. Keys are auto-prefixed with the feature
-  // name ("<feature>:<key>") — cross-feature collisions are impossible by
-  // construction. Same-feature duplicate keys follow last-wins.
-  //
-  // Hooks run in parallel. If one throws, the error is logged and that
-  // feature's claims are simply missing from the merged record — login
-  // still succeeds. This is a deliberate best-effort policy: identity-facts
-  // are convenience, not access-gates (that's what `roles` + field-access
-  // rules are for).
-  authClaims(fn: AuthClaimsFn): void;
-
-  // Declare a claim key. Qualified name follows "<feature>:<shortName>" —
-  // NO kebab conversion (it would break the claim round-trip, unlike
-  // r.secret / r.config). Returns a
-  // typed handle so feature code can pass it to `readClaim(user, handle)`
-  // without retyping the qualified string and with the right narrowed
-  // return type.
-  //
-  // Declaring claim keys also turns on a runtime check: when the feature's
-  // r.authClaims hooks return an inner-key not in the declared list, the
-  // resolver logs a warning (the claim still lands in the JWT — declared
-  // or not — so strict-mode isn't on; this is typo-drift protection).
-  claimKey<T extends ClaimKeyType>(
-    shortName: string,
-    options: { readonly type: T },
-  ): ClaimKeyHandle<T>;
-  claimKey<T extends ClaimKeyType>(definition: {
-    readonly name: string;
-    readonly type: T;
-  }): ClaimKeyHandle<T>;
-
-  // Register a screen. The id is the feature-local short name (kebab-case);
-  // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks
-  // that entity-bound screens reference a registered entity and that the
-  // columns / form-field refs name real fields — cross-feature component-QN
-  // validation (r.uiComponent) comes in M4/M5. Optional `nav` field is
-  // sugar for a single nav entry pointing at this screen — equivalent to
-  // a standalone r.nav({ id: <same id>, screen: "<feature>:screen:<id>", ... }).
-  screen(definition: ScreenDefinition): void;
-
-  // Register a nav entry. The id is the feature-local short name (kebab-case);
-  // the registry qualifies to "<feature>:nav:<id>". Boot-validation checks
-  // that `screen` and `parent` refs exist (cross-feature QNs allowed) and
-  // that parent chains don't contain cycles.
-  nav(definition: NavDefinition): void;
-
-  // Register a content collection — a set of template-resources of one kind,
-  // navigable where it fachlich belongs (mail templates under Mail, not under
-  // a central "Content" section). Sugar over r.nav(): registers the nav entry
-  // with `provider: true` under the same id and records the kind so the client
-  // can wire the tree provider without repeating navId + kind.
-  //
-  // Returns the qualified nav name ("<feature>:nav:<id>") — apps that pass the
-  // collection to a client feature explicitly take it from here instead of
-  // re-typing the QN.
-  contentCollection(definition: ContentCollectionDefinition): string;
-
-  // Register a workspace — a persona-/role-scoped UI surface. Pure UI
-  // composition; the registry qualifies the short id to
-  // "<feature>:workspace:<id>". Boot-validation checks that any nav refs
-  // exist, that workspace ids referenced from r.nav() are real, and that
-  // at most one workspace per app declares `default: true`.
-  workspace(definition: WorkspaceDefinition): void;
-
-  // Register an HTTP-route owned by this feature. The route is mounted
-  // outside the dispatcher pipeline (= outside /api/write|query|batch),
-  // directly on the app — use case: RSS/Atom feeds, OG images, OpenAPI specs.
-  // Duplicate "method path"-Combinations are rejected per feature at setup
-  // time; there is no cross-feature check.
-  // Symmetric to queryHandler/writeHandler — routes live with the feature,
-  // not in the bootstrap. Escape-hatch for non-feature-bound routes stays
-  // runProdApp.extraRoutes (declarative list with `entry` tier).
-  httpRoute(definition: HttpRouteDefinition): void;
-
-  // Declare an "unmanaged" framework-native table that bypasses the
-  // event-sourcing system. Reserved for legacy-import, read-only caches,
-  // write-only webhook payload buffers, or read-side projections of
-  // event-streams (delivery-attempts, job-run-logs) where r.entity()'s
-  // aggregate-lifecycle assumptions don't fit. The dev-server iterates
-  // these alongside r.entity() projections at boot so the table exists
-  // before the first query.
-  //
-  // EntityTableMeta carries the same column-shape that r.entity() builds,
-  // minus the audit-trail + base-columns scaffolding. The `meta` argument
-  // is the result of `defineUnmanagedTable(...)` / `deriveEntityTableMeta(...)`
-  // from `@cosmicdrift/kumiko-framework/db`.
-  //
-  // The required `reason` string is the marker that justifies the bypass —
-  // a non-empty string is the contract. If you can't write a reason,
-  // declare data via `r.entity()` instead.
-  storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
-
-  // Register the tree-actions schema for this feature — a map of
-  // action-name → action-definition (with optional typed args). At-most-
-  // one call per feature.
-  //
-  // Returns a TreeActionsHandle that the feature exports via setup-return
-  // (Memory `[EventDef-Exports-Pattern]`). The handle carries the
-  // literal-typed action-map that `buildTarget` consumes for compile-
-  // time validation:
-  //
-  //   const handle = r.treeActions({
-  //     edit: { args: { slug: "" as string } },
-  //     list: {},
-  //   });
-  //   return { handle };
-  //
-  // Without this typed return, the action-map collapses to
-  // `Record<string, TreeActionDef>` at the buildTarget call-site and
-  // every action becomes accept-anything-string. See visual-tree.md A5.
-  //
-  // The runtime FeatureDefinition.treeActions slot stores the same map
-  // as erased Record (registry lookup, Pattern-AST consumers).
-  treeActions<const TActions extends Record<string, TreeActionDef>>(
-    actions: TActions,
-  ): TreeActionsHandle<TFeature, TActions>;
-
-  // Declare the Zod-schema for env-vars this feature reads at runtime.
-  // At-most-one call per feature. composeEnvSchema reads it across all
-  // features to build one app-wide schema, which runProdApp parses
-  // process.env against at boot. App-Authors can also call
-  // `KUMIKO_DRY_RUN_ENV=human|json|pulumi|k8s` to introspect the
-  // required env-vars without booting.
-  //
-  // Convention: keys are SHOUTING_SNAKE_CASE env-var names. Per-var
-  // metadata (Pulumi-config-key override, openssl-generator suggestion,
-  // k8s-secret hints) goes into `.meta({ kumiko: { pulumi: {...} } })`
-  // — see framework/env/index.ts for the meta-shape.
-  envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
-};
-
-// --- Registry (created from features) ---
-
-export type Registry = {
-  readonly features: ReadonlyMap<string, FeatureDefinition>;
-
-  getFeature(name: string): FeatureDefinition | undefined;
-  getEntity(name: string): EntityDefinition | 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): readonly string[];
-  getSortableFields(entityName: string): readonly 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;
-  }>;
-  // Hook getters — pass `effectiveFeatures` to drop hooks registered by
-  // globally-disabled features. Omit the arg to get all hooks (legacy
-  // callers + places where the feature-toggles feature isn't wired).
-  getPreSaveHooks(name: string, effectiveFeatures?: ReadonlySet<string>): readonly PreSaveHookFn[];
-  getPostSaveHooks(
-    name: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostSaveHookFn[];
-  getPreDeleteHooks(
-    name: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PreDeleteHookFn[];
-  getPostDeleteHooks(
-    name: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostDeleteHookFn[];
-  getPreQueryHooks(
-    name: string,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PreQueryHookFn[];
-  getPostQueryHooks(
-    name: string,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostQueryHookFn[];
-  getEntityPostSaveHooks(
-    entityName: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostSaveHookFn[];
-  getEntityPreDeleteHooks(
-    entityName: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PreDeleteHookFn[];
-  getEntityPostDeleteHooks(
-    entityName: string,
-    phase?: HookPhase,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostDeleteHookFn[];
-  getEntityPostQueryHooks(
-    entityName: string,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly PostQueryHookFn[];
-  // F3 — contributors for an entity's search-doc-payload, fired during
-  // buildSearchDocument indexing. See `SearchPayloadContributorFn`.
-  // `effectiveFeatures` filters out contributors owned by feature-toggle-
-  // disabled features (parallel to other getters' filtering semantic).
-  getSearchPayloadExtensions(
-    entityName: string,
-    effectiveFeatures?: ReadonlySet<string>,
-  ): readonly SearchPayloadContributorFn[];
-  getHandlerEntity(qualifiedHandler: string): string | undefined;
-  isHandlerSystemScoped(qualifiedHandler: string): boolean;
-  // Job counterpart to isHandlerSystemScoped — a job's owning feature is
-  // tracked separately (jobFeatureMap) since jobs aren't write/query/stream
-  // handlers and don't populate handlerFeatureMap.
-  isJobSystemScoped(qualifiedJobName: string): boolean;
-  getHandlerFeature(qualifiedHandler: string): string | undefined;
-  // True iff at least one registered handler declares a `rateLimit`
-  // option. Pre-computed at registry-build so the boot path can skip
-  // wiring the RateLimitResolver (and its Lua-script registration on
-  // Redis) entirely when nobody opted in. Per-request cost stays zero
-  // for apps that don't use the feature.
-  hasRateLimitedHandler(): boolean;
-  // All metrics from all features, keyed by fully-qualified name
-  // (kumiko_<feature>_<shortName>). Consumed at boot to register them on the
-  // active Meter.
-  getAllMetrics(): ReadonlyMap<string, FeatureMetricDef & { readonly featureName: string }>;
-  getAllTranslations(): TranslationKeys;
-  getConfigKey(qualifiedKey: string): ConfigKeyDefinition | undefined;
-  getAllConfigKeys(): ReadonlyMap<string, ConfigKeyDefinition>;
-  getAllConfigSeeds(): readonly ConfigSeedDef[];
-  // Feature-declared secrets, aggregated across all registered features.
-  // Keyed by qualified name ("<feature>:<shortName>"). Used by the rotation
-  // job (to iterate "known" secrets) and admin-UIs to list available keys.
-  getAllSecretKeys(): ReadonlyMap<string, SecretKeyDefinition>;
-  getSecretKey(qualifiedName: string): SecretKeyDefinition | undefined;
-  getJob(qualifiedName: string): JobDefinition | undefined;
-  getAllJobs(): ReadonlyMap<string, JobDefinition>;
-  getEvent(qualifiedName: string): EventDef | undefined;
-
-  // Upcaster chain per qualified event name. Entries describe the current
-  // schema version and the step-wise transforms that upgrade older stored
-  // payloads. Empty chain when an event has never been migrated (version=1).
-  getEventUpcasters(): ReadonlyMap<
-    string,
-    { readonly currentVersion: number; readonly chain: ReadonlyMap<number, EventUpcastFn> }
-  >;
-  getExtension(name: string): RegistrarExtensionDef | undefined;
-  getExtensionUsages(extensionName: string): readonly RegistrarExtensionRegistration[];
-  // Extension point → selector config key, from r.extensionSelector calls.
-  getAllExtensionSelectors(): ReadonlyMap<string, string>;
-  getAllNotifications(): ReadonlyMap<string, NotificationDefinition>;
-  getAllReferenceData(): readonly ReferenceDataDef[];
-  // Look up projections by source-entity name. Empty list when no projection
-  // feeds off the entity — event-store-executor uses this as the hot-path.
-  getProjectionsForSource(entityName: string): readonly ProjectionDefinition[];
-  getAllProjections(): ReadonlyMap<string, ProjectionDefinition>;
-
-  // All r.storeTable() registrations across all features, keyed by
-  // feature-local short name. The dev-server iterates this alongside
-  // implicit projections at boot. Cross-feature uniqueness is enforced
-  // at registry-build — duplicate names from different features fail
-  // the boot, so callers can rely on a flat keyspace.
-  getAllStoreTables(): ReadonlyMap<string, StoreTableDef>;
-
-  // Multi-stream projections registered via r.multiStreamProjection().
-  // Keyed by qualified name. The server wires each into the event-dispatcher
-  // as its own EventConsumer with a dedicated cursor.
-  getAllMultiStreamProjections(): ReadonlyMap<string, MultiStreamProjectionDefinition>;
-  // The feature that registered the given MSP. Used by the event-dispatcher
-  // to pause MSP-consumers whose owning feature is globally disabled.
-  getMultiStreamProjectionFeature(qualifiedName: string): string | undefined;
-
-  // All r.authClaims() hooks across all features, tagged with the declaring
-  // feature name so the resolver can apply the auto-prefix. Pre-aggregated
-  // at registry-build so the login hot path is a single Map read.
-  getAuthClaimsHooks(): readonly AuthClaimsHookDef[];
-
-  // Feature-declared claim keys, aggregated across all features. Keyed by
-  // qualified name ("<feature>:<short>"). Ops-UI + Boot-Validator use this
-  // to introspect what claims the app can produce.
-  getAllClaimKeys(): ReadonlyMap<string, ClaimKeyDefinition>;
-  getClaimKey(qualifiedName: string): ClaimKeyDefinition | undefined;
-
-  // Screens declared via r.screen() across all features. Keyed by qualified
-  // name ("<feature>:screen:<id>"). ui-core / renderer consume this to build
-  // navigation + screen-tree at mount time.
-  getAllScreens(): ReadonlyMap<string, ScreenDefinition>;
-  getScreen(qualifiedName: string): ScreenDefinition | undefined;
-  // The feature that registered the given screen. Consumed by the nav
-  // resolver to gate a nav-entry whose screen belongs to a disabled feature.
-  getScreenFeature(qualifiedName: string): string | undefined;
-  // All entity-bound screens (entityList / entityEdit) that target the given
-  // entity. Pre-grouped so ui-core's view-model builders don't re-filter
-  // getAllScreens() on every render. Custom screens have no entity and are
-  // never returned here — walk getAllScreens() for those.
-  getScreensByEntity(entityName: string): readonly ScreenDefinition[];
-
-  // Nav entries declared via r.nav() across all features. Keyed by qualified
-  // name ("<feature>:nav:<id>"). Flat list — the renderer's resolveNavigation
-  // assembles the tree from parent refs and gates by effective-features.
-  getAllNavs(): ReadonlyMap<string, NavDefinition>;
-  getNav(qualifiedName: string): NavDefinition | undefined;
-  // The feature that registered the given nav entry. Used by the nav
-  // resolver to drop entries whose owning feature is globally disabled.
-  getNavFeature(qualifiedName: string): string | undefined;
-  // Direct children of the given parent nav entry. Empty array when the
-  // parent has no children. Pre-grouped for O(1) tree-walk — resolveNavigation
-  // recurses with getNavsByParent(child.qn) instead of filtering getAllNavs().
-  getNavsByParent(parentQualifiedName: string): readonly NavDefinition[];
-  // Nav entries that declare no parent — the roots of the navigation tree.
-  // resolveNavigation starts its walk here and descends via getNavsByParent.
-  getTopLevelNavs(): readonly NavDefinition[];
-
-  // Workspaces declared via r.workspace() across all features. Keyed by
-  // qualified name ("<feature>:workspace:<id>"). The active web shell
-  // (shellWorkspaces) consumes this to render the switcher.
-  getAllWorkspaces(): ReadonlyMap<string, WorkspaceDefinition>;
-  getWorkspace(qualifiedName: string): WorkspaceDefinition | undefined;
-  // The feature that registered the workspace. Mirrors getNavFeature —
-  // lets the resolver drop workspaces whose owning feature is disabled.
-  getWorkspaceFeature(qualifiedName: string): string | undefined;
-  // Resolved nav QNs that belong to the given workspace. Pre-computed at
-  // boot from BOTH r.workspace.nav AND r.nav.workspaces — the shell
-  // doesn't have to merge sources at render time.
-  getWorkspaceNavs(workspaceQualifiedName: string): readonly string[];
-  // The single workspace whose `default: true` is set, if any. Boot
-  // validator rejects more than one. Apps without a default fall back to
-  // the first workspace the user has access to.
-  getDefaultWorkspace(): WorkspaceDefinition | undefined;
-
-  // Tree-Actions-Map des Features. Returns the erased Record (compile-
-  // time-typed handle wandert über setup-export, nicht hier). Die
-  // Content-Tree-Nav nutzt das für Runtime-Action-Lookup beim Klick auf
-  // einen TreeNode.target — der Resolver findet das Feature via
-  // TargetRef.featureId und holt sich die zugehörige Action-Definition.
-  getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
-};