@cosmicdrift/kumiko-types 0.199.2 → 0.200.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.199.2",
+  "version": "0.200.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/handlers.ts

@@ -311,6 +311,8 @@ type SharedContextFields = {
 // AppContext, so the union keeps that assignment straightforward.
 export type AppContext = SharedContextFields & {
   readonly db?: DbConnection | TenantDb;
+  // Hooks receive the same HandlerContext as their AppContext, so `db` is fail-closed here too.
+  readonly systemDb?: UncheckedSystemDb;
   readonly registry?: Registry;
   readonly systemUser?: SessionUser;
   readonly log?: Logger;
@@ -353,14 +355,19 @@ export type AppContext = SharedContextFields & {
 // `declare module "@cosmicdrift/kumiko-framework/engine"`). Code that bypasses the
 // type-map (runtime-pluggable events) uses `unsafeAppendEvent`.
 export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
+  // Tenant-filtered for ordinary handlers. For r.systemScope() handlers this
+  // is fail-closed instead (dispatch-shared.ts hands back a guard that
+  // throws on first touch) — there's no type-level way to make `db` optional
+  // only for system handlers (isSystem is a runtime-only registry lookup),
+  // so a system handler must reach for `systemDb` below.
   readonly db: TenantDb;
   // Same tenant scoping as `db`, but never bound to the handler's tx: writes
   // through it survive a rollback, for side effects that already happened
   // outside the DB. `undefined` when the pipeline has no outside-tx source
   // for this dispatch (see dispatch-shared.ts) — callers must check before use.
   readonly dbOutsideTransaction: TenantDb | undefined;
-  // Only present for r.systemScope() handlers, bound to the same `db` as above.
-  // Non-system handlers never receive this — reach for `db` instead.
+  // Only present for r.systemScope() handlers. Non-system handlers never
+  // receive this — reach for `db` instead, which is fail-closed for them.
   readonly systemDb?: UncheckedSystemDb;
   readonly registry: Registry;
   /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu