@cosmicdrift/kumiko-types 0.198.0 → 0.199.0

package/package.json

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

@@ -932,6 +932,10 @@ export type Registry = {
   ): 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

package/src/handlers.ts

@@ -177,6 +177,7 @@ export type WriteResult<TData = unknown> =
 // Forward import: Registry is in feature.ts (circular type import — fine in TS)
 import type { Registry } from "./feature";
 import type { TenantId } from "./identifiers";
+import type { UncheckedSystemDb } from "./tenant-db-types";
 
 // Minimal interface for job event triggers (framework-owned, concrete type in jobs/)
 export type JobRunnerRef = {
@@ -358,6 +359,9 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // 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.
+  readonly systemDb?: UncheckedSystemDb;
   readonly registry: Registry;
   /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
    *  `event.user`. Existiert weil Handler intuitiv `ctx.user.tenantId`
@@ -573,6 +577,15 @@ 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.
+  readonly systemDb?: UncheckedSystemDb;
   readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
   // Multi-trigger jobs (`on: [...]`) use this to tell which trigger fired —

package/src/tenant-db-types.ts

@@ -56,3 +56,16 @@ export type TenantDb = {
   ): Promise<readonly T[]>;
   deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
 };
+
+// Symbol.for (global registry) so the brand identity matches even if kumiko-types
+// resolves to two independent copies (workspace symlink vs. published npm) — a plain
+// `Symbol()` per copy would make each resolution's `UncheckedSystemDb` structurally
+// incompatible with the other, per the kumiko.secret precedent in secrets-types.ts.
+export const SYSTEM_SCOPE_CHECK_BRAND: unique symbol = Symbol.for("kumiko.system-scope-check");
+
+export type UncheckedSystemDb = {
+  readonly [SYSTEM_SCOPE_CHECK_BRAND]: true;
+  assertTenantMatch(tenantId: TenantId): TenantDb;
+  assertRowsTenant<T>(rows: readonly T[], tenantField: keyof T): readonly T[];
+  acknowledgeCrossTenant(reason: string): TenantDb;
+};