@cosmicdrift/kumiko-types 0.270.0 → 0.273.0

package/package.json

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

package/src/define-handler.ts

@@ -6,7 +6,7 @@ import type {
   EscapeHatchDeclaration,
   HandlerContext,
   QueryEvent,
-  RateLimitOption,
+  RateLimitDeclaration,
   WriteEvent,
   WriteResult,
 } from "./handlers";
@@ -39,7 +39,7 @@ export type WriteHandlerDefinition<
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     event: WriteEvent<z.infer<TSchema>>,
@@ -67,7 +67,7 @@ export type WriteHandlerInput<
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   readonly escapeHatch?: EscapeHatchDeclaration;
 } & (
   | {
@@ -96,7 +96,7 @@ export type QueryHandlerDefinition<
   readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,
@@ -125,7 +125,7 @@ export type StreamHandlerDefinition<
   readonly name: TName;
   readonly schema: TSchema;
   readonly access: AccessRule;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   // Stream handlers can't reach db.global() (that gate is write-only), but
   // they can still switch identity to SYSTEM via ctx.queryAs — this opts
   // in, same contract as WriteHandlerDefinition.escapeHatch.

package/src/entity-handlers.ts

@@ -1,24 +1,27 @@
 import type { EntityDefinition } from "./fields";
-import type { AccessRule, AgentHandlerHints, QueryHandlerDef, WriteHandlerDef } from "./handlers";
+import type {
+  AccessRule,
+  AgentHandlerHints,
+  EscapeHatchDeclaration,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "./handlers";
 
 export type EntityHandlerOptions = {
   readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
-  /** Reads and writes across every tenant instead of the caller's own — for a
-   *  SystemAdmin-only operator handler over an otherwise tenant-scoped entity.
-   *  Scope this to the ONE handler that needs it rather than making the whole
-   *  feature r.systemScope(), which would drop tenant isolation from every
-   *  other handler the feature registers too. This only lifts row filtering;
-   *  who may call the handler at all stays gated by `access`.
-   *
-   *  On write handlers it additionally addresses the event stream by the
-   *  target row's tenant instead of the acting user's, so update/delete/
-   *  restore hit the row's own stream. `create` has no target row and stays
-   *  on the acting user's tenant. On write handlers this also satisfies
-   *  entity write-ownership rules that compare against the acting user's
-   *  tenant, so `access` is the only remaining gate — grant it to operator
-   *  roles only. */
+  /** Lifts row filtering for this ONE handler across every tenant instead of
+   *  the caller's own — for a SystemAdmin-only operator handler over an
+   *  otherwise tenant-scoped entity. Every use reports an
+   *  `acknowledge-cross-tenant` escape-hatch audit event. On write handlers
+   *  update/delete/restore address the target row's own tenant stream.
+   *  `access` stays the only caller gate. Unlike `escapeHatch` on a
+   *  hand-written handler this does NOT grant `ctx.db.unsafeRaw`,
+   *  `db.global()` writes or identity switches. */
+  readonly escapeHatch?: EscapeHatchDeclaration;
+  /** @deprecated Use `escapeHatch: { reason }` — removed in a future release;
+   *  run `scripts/codemod/migrate-cross-tenant.ts`. */
   readonly crossTenant?: boolean;
 };
 

package/src/feature.ts

@@ -45,7 +45,7 @@ import type {
   QualifiedEventName,
   QueryHandlerDef,
   QueryHandlerFn,
-  RateLimitOption,
+  RateLimitDeclaration,
   StreamHandlerDef,
   StreamHandlerFn,
   WriteHandlerDef,
@@ -457,7 +457,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     handler: WriteHandlerFn<z.infer<TSchema>>,
     options: {
       access: AccessRule;
-      rateLimit?: RateLimitOption;
+      rateLimit?: RateLimitDeclaration;
       description?: string;
       agent?: AgentHandlerHints;
       escapeHatch?: EscapeHatchDeclaration;
@@ -473,7 +473,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     handler: QueryHandlerFn<z.infer<TSchema>>,
     options: {
       access: AccessRule;
-      rateLimit?: RateLimitOption;
+      rateLimit?: RateLimitDeclaration;
       outputSchema?: ZodType;
       description?: string;
       agent?: AgentHandlerHints;
@@ -490,7 +490,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     handler: StreamHandlerFn<z.infer<TSchema>>,
     options: {
       access: AccessRule;
-      rateLimit?: RateLimitOption;
+      rateLimit?: RateLimitDeclaration;
       escapeHatch?: EscapeHatchDeclaration;
     },
   ): HandlerRef;

package/src/handlers.ts

@@ -287,6 +287,29 @@ export type NotifyFn = (notificationType: string, options: NotifyOptions) => Pro
 // Concrete implementation in bundled-features/delivery (cross-package boundary)
 export type NotifyFactory = (user: SessionUser, tenantId: TenantId) => NotifyFn;
 
+export type EscapeHatchKind =
+  | "unsafe-raw"
+  | "acknowledge-cross-tenant"
+  | "global-write"
+  | "identity-switch"
+  | "unsafe-all-tenants";
+export type EscapeHatchTarget = { readonly id: string; readonly tenantId: TenantId };
+export type EscapeHatchUseEvent = {
+  readonly handler: string;
+  readonly kind: EscapeHatchKind;
+  readonly reason: string;
+  readonly tenantId: TenantId;
+  readonly actor: string;
+  readonly target?: EscapeHatchTarget;
+};
+export type EscapeHatchAuditSink = (event: EscapeHatchUseEvent) => Promise<void>;
+// Bound to handler/tenant/actor of one invocation; called once per actual escape-hatch use.
+export type EscapeHatchReporter = (
+  kind: EscapeHatchKind,
+  reason: string,
+  target?: EscapeHatchTarget,
+) => void;
+
 // Shared optional fields across all execution contexts
 type SharedContextFields = {
   readonly redis?: Redis;
@@ -323,6 +346,8 @@ type SharedContextFields = {
   readonly entityCache?: EntityCache;
   readonly notify?: NotifyFn;
   readonly _notifyFactory?: NotifyFactory;
+  // Wired at boot when the `audit` feature is mounted; absent → structured warn log.
+  readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
   // Tenant-scoped secrets accessor. Present when the app wired a
   // MasterKeyProvider at boot. Feature code reads ctx.secrets.get(...)
   // to pull a plaintext secret; Secret<string> carries the brand that
@@ -595,8 +620,9 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // name without the feature having to import the drizzle-table directly.
   //
   // Auto-applies tenant_id filter when the projection table has a tenant_id
-  // column (or opt out with { unsafeAllTenants: true } for system-scoped reads
-  // like cross-tenant analytics). Unknown projection name throws.
+  // column. { unsafeAllTenants: true } opts out but requires a grant —
+  // r.systemScope() or a declared escapeHatch on the handler (or hook).
+  // Unknown projection name throws.
   readonly queryProjection: <T = Record<string, unknown>>(
     qualifiedName: string,
     options?: { readonly unsafeAllTenants?: boolean },
@@ -690,14 +716,10 @@ export type JobContext = SharedContextFields & {
   readonly systemUser: SessionUser;
   readonly log: Logger;
   readonly triggeredBy: { readonly id: string; readonly tenantId: TenantId } | null;
-  // Only present for jobs whose owning feature declares r.systemScope(),
-  // mirroring HandlerContext.systemDb (dispatch-shared.ts buildHandlerContext).
-  // assertTenantMatch()/acknowledgeCrossTenant() return a TenantDb, not the
-  // raw DbConnection above — job code that needs a DbRunner for a helper
-  // like reindexEntity() reaches through `.raw` on that TenantDb. `.raw`
-  // bypasses tenant filtering entirely, so it's only safe to hand to a
-  // helper that filters by tenantId itself (as reindexEntity does) — never
-  // pass it to code that trusts the connection to already be scoped.
+  // Only present for jobs whose owning feature declares r.systemScope().
+  // assertTenantMatch()/acknowledgeCrossTenant() return a TenantDb; a raw,
+  // tenant-unfiltered DbRunner instead comes from ctx.systemDb.unsafeRaw(reason)
+  // — only safe for a helper that filters by tenantId itself (e.g. reindexEntity).
   readonly systemDb?: UncheckedSystemDb;
   readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
   readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
@@ -1053,6 +1075,13 @@ export type RateLimitOption = {
   readonly cost?: number;
 };
 
+export type RateLimitDisabled = { readonly disabled: true; readonly reason: string };
+export type RateLimitDeclaration = RateLimitOption | RateLimitDisabled;
+
+export function isRateLimitDisabled(v: RateLimitDeclaration | undefined): v is RateLimitDisabled {
+  return v !== undefined && "disabled" in v && v.disabled === true;
+}
+
 export type AgentRisk = "low" | "mid" | "high";
 
 /** Per-handler hints for the AI-agent manifest. `expose` overrides the
@@ -1075,7 +1104,7 @@ export type WriteHandlerDef = {
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   readonly escapeHatch?: EscapeHatchDeclaration;
   // Set when the author wrote a `perform: stepsPipeline(...)` block. Boot-
   // validators (projection-allowlist) and Designer/AI tooling read this
@@ -1104,7 +1133,7 @@ export type QueryHandlerDef = {
   readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   /** Zod schema of the handler's actual return value — the paged envelope
    *  `{ rows, nextCursor, total? }` for a `definePagedQueryHandler`, or the
    *  flat record (optionally `.nullable()`) for a plain query handler.
@@ -1125,7 +1154,7 @@ export type StreamHandlerDef = {
   readonly schema: ZodType;
   readonly handler: StreamHandlerFn;
   readonly access: AccessRule;
-  readonly rateLimit?: RateLimitOption;
+  readonly rateLimit?: RateLimitDeclaration;
   // Stream handlers can't reach db.global() (that gate is write-only), but
   // they can still switch identity to SYSTEM via ctx.queryAs — this opts
   // in, same contract as WriteHandlerDef.escapeHatch.

package/src/screen.ts

@@ -377,6 +377,32 @@ export type ToolbarAction =
       readonly style?: "primary" | "secondary" | "danger";
     };
 
+// relatedList-only extension of ToolbarAction:
+// a relatedList section's toolbar renders inside a projectionDetail, which
+// has a record to evaluate against — a plain entityList/projectionList
+// toolbar does not, so `visible`/`params` live here instead of on the base
+// union. `visible` uses the same FieldCondition as header actions/
+// RowAction; `params` reuses RowActionNavigate's RowFieldExtractor, applied
+// to the enclosing record instead of a clicked row. Every field is optional,
+// so a plain ToolbarAction is already a valid RelatedListToolbarAction —
+// callers pass either type without a cast.
+export type RelatedListToolbarAction =
+  | (Extract<ToolbarAction, { readonly kind: "navigate" }> & {
+      /** Conditional visibility, evaluated against the relatedList's parent
+       *  record (the "Akte"). */
+      readonly visible?: FieldCondition;
+      /** Declarative URL search params extracted from the parent record,
+       *  prefilling the target screen. Replaces the implicit
+       *  `{ [parentParam]: parentId }` default when set. */
+      readonly params?: RowFieldExtractor;
+    })
+  | (Extract<ToolbarAction, { readonly kind: "writeHandler" }> & {
+      readonly visible?: FieldCondition;
+    })
+  | (Extract<ToolbarAction, { readonly kind: "drawer" }> & {
+      readonly visible?: FieldCondition;
+    });
+
 export type EntityListScreenDefinition = {
   readonly id: string;
   readonly type: "entityList";
@@ -384,6 +410,9 @@ export type EntityListScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   readonly entity: string;
   readonly columns: readonly ListColumnSpec[];
   // Row renderer (Desktop) — when omitted, renderer draws the default table
@@ -455,6 +484,17 @@ export type ListFacetSpec =
       readonly label: string;
       readonly trueLabel: string;
       readonly falseLabel: string;
+    }
+  | {
+      readonly field: string;
+      readonly type: "reference";
+      readonly label: string;
+      /** Entity name (same feature) or `feature:entity` (cross-feature), same
+       *  convention as `ListColumnSpec.refEntity`. Options load at render time. */
+      readonly entity: string;
+      /** Row field on the referenced entity shown as the option label
+       *  (default "id"). */
+      readonly labelField?: string;
     };
 
 export type ProjectionListScreenDefinition = {
@@ -464,6 +504,9 @@ export type ProjectionListScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   readonly query: string;
   readonly columns: readonly ListColumnSpec[];
   readonly rowRenderer?: PlatformComponent;
@@ -558,6 +601,9 @@ export type ProjectionDetailScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   readonly query: string;
   /** Query-payload key for the row-id. Default "id". */
   readonly idParam?: string;
@@ -763,6 +809,9 @@ export type DashboardScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   readonly panels: readonly DashboardPanelDefinition[];
   readonly filter?: DashboardFilterDefinition;
   readonly slots?: ScreenSlots;
@@ -835,7 +884,17 @@ export type EditFieldsSection = {
    *  (subtitle-only section). */
   readonly description?: string;
   readonly columns?: number;
+  /** Mutually exclusive with `groups` — pass `[]` when using `groups`; the
+   *  boot-validator rejects both non-empty or both empty. */
   readonly fields: readonly EditFieldSpec[];
+  /** Splits the section into multiple titled cards instead of one flat grid.
+   *  Mutually exclusive with `fields`; fields named here still need to exist. */
+  readonly groups?: readonly {
+    readonly title: string;
+    readonly fields: readonly EditFieldSpec[];
+    /** Default 2. */
+    readonly columns?: number;
+  }[];
   /** Rendered left of the section title, `text-muted-foreground` — closed
    *  IconKey vocabulary into the ICONS registry (renderer-web), analogous
    *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
@@ -889,6 +948,15 @@ export type EditRelatedListSection = {
   readonly query: string;
   /** Query-payload key the parent record's id is passed under. Default "id". */
   readonly parentParam?: 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. Lets a tab reuse the generic `<entity>:list` query instead
+   *  of a bespoke child-rows handler. Mutually exclusive with `parentParam`
+   *  (the boot-validator rejects both). `field` must be a real field on the
+   *  entity behind `query`, and that query's Zod schema must accept
+   *  `filter` (same requirement `filter`/`facets` already have). */
+  readonly parentFilter?: { readonly field: string };
   readonly columns: readonly ListColumnSpec[];
   readonly pageSize?: number;
   /** Initial sort on mount, applied client-side over the already-loaded rows
@@ -921,6 +989,11 @@ export type EditRelatedListSection = {
    *  writeHandler action re-runs this section's own query, same as a
    *  projectionList row action re-running its list query. */
   readonly rowActions?: readonly RowAction[];
+  /** 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). */
+  readonly toolbarActions?: readonly RelatedListToolbarAction[];
   /** Record field rendered as a count badge in the tab label when the
    *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
    *  Ignored outside tabs mode or when the field's value is not a finite
@@ -995,6 +1068,9 @@ export type EntityEditScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   /** Derived by buildAppSchema from the navigate `params` targeting this
    *  screen — the only URL query keys the create form prefills. An authored
    *  value is overwritten. */
@@ -1092,6 +1168,9 @@ export type ActionFormScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
   readonly urlPrefillFields?: readonly string[];
   /** Write-Handler-QN der bei Submit gerufen wird. Form-Object landet
@@ -1104,6 +1183,9 @@ export type ActionFormScreenDefinition = {
   /** Layout analog zu EntityEditScreen: sections mit fields aus dem
    *  fields-Map oben. */
   readonly layout: EditLayout;
+  /** Per-field label i18n key override, same type/semantics as
+   *  `EntityEditScreenDefinition.fieldLabels`. Falls back to the convention when absent. */
+  readonly fieldLabels?: Readonly<Record<string, string>>;
   /** i18n-key für den Submit-Button. Default: i18n-Default des
    *  Renderers (typischerweise "actions.submit"). */
   readonly submitLabel?: string;
@@ -1223,6 +1305,9 @@ export type SecretMintScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   /** Derived by buildAppSchema — see EntityEditScreenDefinition.urlPrefillFields. */
   readonly urlPrefillFields?: readonly string[];
   /** Write-handler QN dispatched on submit. */
@@ -1276,7 +1361,8 @@ export type CustomScreenDefinition = {
    *  positive (kumiko-framework#2034). Only set this on screens the
    *  feature itself never navs — a screen the feature DOES nav still needs
    *  its client plugin mounted by every consumer, and should keep
-   *  triggering the diagnostic if it's missing. */
+   *  triggering the diagnostic if it's missing. Also gates the
+   *  boot-validator's nav-area check, same as `dormant` on other screens. */
   readonly dormant?: boolean;
 };
 
@@ -1320,6 +1406,9 @@ export type ConfigEditScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   /** scope für config:write:set Calls. Muss zur Scope-Deklaration der
    *  in `configKeys` referenzierten Keys passen — Boot-Validator
    *  prüft das gegen die Registry. */
@@ -1364,6 +1453,9 @@ export type SecretsEditScreenDefinition = {
   readonly detailFor?: string;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
+  /** Screen has no nav entry by design (opened via link or navved by the
+   *  app); exempts it from the nav-area boot check. */
+  readonly dormant?: boolean;
   /** field id -> qualified secret name (`<feature>:secret:<kebab>`). */
   readonly secretKeys: Readonly<Record<string, string>>;
   /** field id -> i18n key for the label. */

package/src/step.ts

@@ -262,13 +262,14 @@ export type StepNamespace = {
     readonly where: StepResolver<WhereObject>;
   }) => StepInstance;
   // Read sub-namespace — thin wrapper on selectMany/fetchOne (bun-db).
-  // Caller-owned tenant-filter (does NOT auto-inject like ctx.queryProjection does).
+  // Tenant-filtered like ctx.db; unsafeAllTenants needs escapeHatch on the handler (or systemScope).
   readonly read: {
     readonly findOne: (
       name: string,
       opts: {
         readonly table: unknown;
         readonly where: StepResolver<WhereObject | undefined>;
+        readonly unsafeAllTenants?: { readonly reason: string };
       },
     ) => StepInstance;
     readonly findMany: (
@@ -277,6 +278,7 @@ export type StepNamespace = {
         readonly table: unknown;
         readonly where?: StepResolver<WhereObject | undefined>;
         readonly limit?: number;
+        readonly unsafeAllTenants?: { readonly reason: string };
       },
     ) => StepInstance;
   };

package/src/tenant-db-types.ts

@@ -53,15 +53,6 @@ export type TenantDbMode = "tenant" | "system";
 export type TenantDb = {
   readonly tenantId: TenantId;
   readonly mode: TenantDbMode;
-  /**
-   * Underlying DbRunner. Framework-internal use (event-store, migrations) —
-   * bypasses tenant-filter. Feature code uses the typed helpers above so the
-   * automatic scoping stays intact.
-   * @deprecated Use `ctx.db.unsafeRaw(reason)` / `db.global(table)` (method-
-   * form) instead — both make the cross-tenant intent an explicit, named
-   * declaration instead of a silent unfiltered escape hatch. Removal fw#2860.
-   */
-  readonly raw: DbRunner;
   /**
    * Unfiltered DbRunner escape hatch for handlers/hooks that declare `escapeHatch: { reason }`.
    * Throws `AccessDeniedError` when ungranted, or `Error` when `reason` is empty.