@cosmicdrift/kumiko-types 0.268.0 → 0.269.0

package/package.json

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

@@ -126,6 +126,10 @@ export type StreamHandlerDefinition<
   readonly schema: TSchema;
   readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  // 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.
+  readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,
     context: HandlerContext<TMap>,

package/src/feature.ts

@@ -488,7 +488,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: StreamHandlerFn<z.infer<TSchema>>,
-    options: { access: AccessRule; rateLimit?: RateLimitOption },
+    options: {
+      access: AccessRule;
+      rateLimit?: RateLimitOption;
+      escapeHatch?: EscapeHatchDeclaration;
+    },
   ): HandlerRef;
 
   relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
@@ -501,7 +505,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): void;
 
   hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
-  // escapeHatch grants this hook (not the handler) SYSTEM identity-switches — see system-identity-switch.ts.
+  // escapeHatch grants this hook (not the handler) identity-switches beyond its caller — see system-identity-switch.ts.
   hook(
     type: "preSave",
     target: RefOrRefs,

package/src/handlers.ts

@@ -415,8 +415,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). SYSTEM as the target is gated: reachable
-//   only from an r.systemScope() feature, a job, or a handler/hook that
+//   by field-access read rules). Any target other than the caller itself (or
+//   a subset of its roles) 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
@@ -1128,4 +1129,8 @@ export type StreamHandlerDef = {
   readonly handler: StreamHandlerFn;
   readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  // 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.
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };