@cosmicdrift/kumiko-types 0.263.0 → 0.264.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.263.0",
+  "version": "0.264.1",
   "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

@@ -97,6 +97,7 @@ export type QueryHandlerDefinition<
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,
     context: HandlerContext<TMap>,

package/src/feature.ts

@@ -477,6 +477,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
       outputSchema?: ZodType;
       description?: string;
       agent?: AgentHandlerHints;
+      escapeHatch?: EscapeHatchDeclaration;
     },
   ): HandlerRef;
 
@@ -500,7 +501,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): void;
 
   hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
-  hook(type: "preSave", target: RefOrRefs, fn: PreSaveHookFn): void;
+  // escapeHatch grants this hook (not the handler) SYSTEM identity-switches — 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
@@ -511,19 +518,34 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     type: "postSave",
     target: HookTarget,
     fn: PostSaveHookFn,
-    options?: { phase?: HookPhase },
+    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): void;
+  hook(
+    type: "preDelete",
+    target: HookTarget,
+    fn: PreDeleteHookFn,
+    options?: { escapeHatch?: EscapeHatchDeclaration },
+  ): void;
   hook(
     type: "postDelete",
     target: HookTarget,
     fn: PostDeleteHookFn,
-    options?: { phase?: HookPhase },
+    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;
-  hook(type: "preQuery", target: RefOrRefs, fn: PreQueryHookFn): void;
-  hook(type: "postQuery", target: HookTarget, fn: PostQueryHookFn): void;
 
   // F3 — Search-Payload-Extension: contributor function adds flat fields to
   // an entity's search-index document. Fires synchronously during

package/src/handlers.ts

@@ -378,7 +378,9 @@ export type AppContext = SharedContextFields & {
 //   sharing the active tx + afterCommit queue. Field-access filters apply.
 //   ctx.queryAs / ctx.writeAs switch identity (e.g. SYSTEM for privileged
 //   lookups like "find user by email for auth" — system reads aren't filtered
-//   by field-access read rules).
+//   by field-access read rules). SYSTEM as the target is gated: reachable
+//   only from an r.systemScope() feature, a job, or a handler/hook that
+//   declared { escapeHatch: { reason } } (system-identity-switch.ts).
 //
 // The design: handlers are the contract between features. Feature A requires
 // Feature B and talks to it through B's registered handlers — never through
@@ -1063,6 +1065,10 @@ export type QueryHandlerDef = {
    *  `header`/`metrics`, dashboard `valueField`/`subField`/etc.) rather
    *  than requiring it retroactively. See fw#2493. */
   readonly outputSchema?: ZodType;
+  // Query 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.
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type StreamHandlerDef = {