@cosmicdrift/kumiko-types 0.260.0 → 0.262.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.260.0",
+  "version": "0.262.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>",
@@ -122,6 +122,10 @@
       "types": "./src/executor-brand.ts",
       "default": "./src/executor-brand.ts"
     },
+    "./tenancy-brand": {
+      "types": "./src/tenancy-brand.ts",
+      "default": "./src/tenancy-brand.ts"
+    },
     "./where-clause-types": {
       "types": "./src/where-clause-types.ts",
       "default": "./src/where-clause-types.ts"

package/src/define-handler.ts

@@ -3,6 +3,7 @@ import type { KumikoEventTypeMap } from "./event-type-map";
 import type {
   AccessRule,
   AgentHandlerHints,
+  EscapeHatchDeclaration,
   HandlerContext,
   QueryEvent,
   RateLimitOption,
@@ -34,11 +35,12 @@ export type WriteHandlerDefinition<
 > = {
   readonly name: TName;
   readonly schema: TSchema;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
   readonly handler: (
     event: WriteEvent<z.infer<TSchema>>,
     context: HandlerContext<TMap>,
@@ -61,11 +63,12 @@ export type WriteHandlerInput<
 > = {
   readonly name: TName;
   readonly schema: TSchema;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 } & (
   | {
       readonly handler: (
@@ -90,7 +93,7 @@ export type QueryHandlerDefinition<
 > = {
   readonly name: TName;
   readonly schema: TSchema;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
@@ -120,7 +123,7 @@ export type StreamHandlerDefinition<
 > = {
   readonly name: TName;
   readonly schema: TSchema;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
   readonly handler: (
     query: QueryEvent<z.infer<TSchema>>,

package/src/entity-handlers.ts

@@ -2,7 +2,7 @@ import type { EntityDefinition } from "./fields";
 import type { AccessRule, AgentHandlerHints, QueryHandlerDef, WriteHandlerDef } from "./handlers";
 
 export type EntityHandlerOptions = {
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   /** Reads and writes across every tenant instead of the caller's own — for a
@@ -26,9 +26,14 @@ export type EntityQueryHandlerOptions = EntityHandlerOptions;
 
 export type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
 
+// `access` stays optional here — registerEntityCrud resolves it per-verb from `verbAccess`, falling back to this default.
+export type EntityCrudHandlerDefaults = Omit<EntityHandlerOptions, "access"> & {
+  readonly access?: AccessRule;
+};
+
 export type RegisterEntityCrudOptions = {
-  readonly write?: EntityHandlerOptions;
-  readonly read?: EntityQueryHandlerOptions;
+  readonly write?: EntityCrudHandlerDefaults;
+  readonly read?: EntityCrudHandlerDefaults;
   readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
   /** Per-verb access override — falls back to `write.access`/`read.access` when unset for a verb. */
   readonly verbAccess?: Partial<Record<EntityCrudVerb, AccessRule>>;

package/src/entity-table-meta-types.ts

@@ -5,6 +5,7 @@
 // (crypto/DB deps).
 
 import type { EntityRelations } from "./relations";
+import type { EntityTenancy } from "./tenancy-brand";
 
 // PG type repertoire the read-model tables need. Deliberately narrow — no
 // vendor-specific types (TSVECTOR, HSTORE, etc.). An app-author who needs
@@ -80,6 +81,9 @@ export type EntityTableMeta = {
   // deriveEntityTableMeta so the registry can reject r.storeTable stores
   // whose direct writes would skip the executor's encryption (#820).
   readonly piiSubjectFields?: readonly string[];
+  // Only present for "global" tables — absent means "tenant" so existing
+  // schema snapshots don't drift. See EntityDefinition.tenancy.
+  readonly tenancy?: "global";
 };
 
 export type BuildEntityTableMetaOptions = {
@@ -93,4 +97,5 @@ export type UnmanagedTableInput = {
   readonly columns: readonly ColumnMeta[];
   readonly indexes?: readonly IndexMeta[];
   readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+  readonly tenancy?: EntityTenancy;
 };

package/src/feature.ts

@@ -35,6 +35,7 @@ import type {
   ClaimKeyType,
   DeclarativeEventMigration,
   EntityRef,
+  EscapeHatchDeclaration,
   EventDef,
   EventMigrationDef,
   EventPiiStance,
@@ -454,11 +455,12 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: WriteHandlerFn<z.infer<TSchema>>,
-    options?: {
-      access?: AccessRule;
+    options: {
+      access: AccessRule;
       rateLimit?: RateLimitOption;
       description?: string;
       agent?: AgentHandlerHints;
+      escapeHatch?: EscapeHatchDeclaration;
     },
   ): HandlerRef;
 
@@ -469,8 +471,8 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     name: string,
     schema: TSchema,
     handler: QueryHandlerFn<z.infer<TSchema>>,
-    options?: {
-      access?: AccessRule;
+    options: {
+      access: AccessRule;
       rateLimit?: RateLimitOption;
       outputSchema?: ZodType;
       description?: string;
@@ -485,7 +487,7 @@ 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 },
   ): HandlerRef;
 
   relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;

package/src/fields.ts

@@ -8,6 +8,7 @@ import type { VariantSpec } from "./derivatives-types";
 // array are auto-normalized to { [role]: "all" } at registry build.
 // Long-term: string[] disappears.
 import type { OwnershipMap } from "./ownership";
+import type { EntityTenancy } from "./tenancy-brand";
 
 export type FieldAccess = {
   readonly read?: OwnershipMap | readonly string[];
@@ -914,10 +915,16 @@ export type ParentRefDef = {
   readonly allowedTypes?: readonly string[];
 };
 
-export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
+export type EntityDefinition<
+  F extends FieldsMap = FieldsMap,
+  T extends EntityTenancy = EntityTenancy,
+> = {
   readonly table?: string;
   readonly fields: F;
   readonly softDelete?: boolean;
+  /** "tenant" (default): auto-filtered by every db accessor. "global": shared across
+   *  tenants, reachable only via `db.global(table)`. Not named `scope` — config keys use that. */
+  readonly tenancy?: T;
   /** This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the
    *  creator's tenant. Opt-in per entity (NOT inherited from r.systemScope()):
    *  only for genuinely tenant-independent aggregates like `user`. The first

package/src/handlers.ts

@@ -16,11 +16,35 @@ import type { TzContext } from "./tz-context";
 
 // --- Access ---
 
+export type OpenToAllDeclaration = { readonly reason: string };
+
+export type OpenToAllAccessRule = {
+  // `true` is the deprecated pre-#2855 form, kept until the call-site migration (fw#2854).
+  readonly openToAll: OpenToAllDeclaration | true;
+  // Write handler intentionally accepts personal data from any authenticated caller (boot-validator gate).
+  readonly publicIntake?: true;
+};
+
 // AccessRule is DEFAULT-DENY: a handler without an access rule is not reachable.
 // To grant access, set one of:
-//   - { roles: ["Admin", ...] }   — role-based allowlist (empty array denies everyone)
-//   - { openToAll: true }         — any authenticated user may call (still requires a valid JWT)
-export type AccessRule = { readonly roles: readonly string[] } | { readonly openToAll: true };
+//   - { roles: ["Admin", ...] }             — role-based allowlist (empty array denies everyone)
+//   - { openToAll: { reason: "..." } }      — any authenticated user may call (still requires a valid JWT)
+//   - { openToAll: true }                   — deprecated pre-#2855 form, still accepted
+export type AccessRule = { readonly roles: readonly string[] } | OpenToAllAccessRule;
+
+export type EscapeHatchDeclaration = { readonly reason: string };
+
+// AccessRule can arrive from untyped sources (pattern-library JSON, Designer)
+// where `openToAll` doesn't actually match the declared union — narrow via
+// `unknown` instead of trusting the static type, deny on anything malformed.
+export function isOpenToAllGranted(rule: AccessRule): boolean {
+  if (!("openToAll" in rule)) return false;
+  const openToAll: unknown = rule.openToAll;
+  if (openToAll === true) return true;
+  if (typeof openToAll !== "object" || openToAll === null) return false;
+  if (!("reason" in openToAll) || typeof openToAll.reason !== "string") return false;
+  return openToAll.reason.trim().length > 0;
+}
 
 // --- Pipeline User ---
 
@@ -996,11 +1020,12 @@ export type WriteHandlerDef = {
   readonly name: string;
   readonly schema: ZodType;
   readonly handler: WriteHandlerFn;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly unsafeSkipTransitionGuard?: boolean;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
   // Set when the author wrote a `perform: stepsPipeline(...)` block. Boot-
   // validators (projection-allowlist) and Designer/AI tooling read this
   // to inspect the step list. Absent on free-form handlers.
@@ -1025,7 +1050,7 @@ export type QueryHandlerDef = {
    *  read-gate. The boot-validator requires it on a `parentRef` entity's
    *  list/detail handler — see boot-validator/parent-ref.ts. */
   readonly [ENTITY_CONVENTION_QUERY_BRAND]?: true;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
@@ -1044,6 +1069,6 @@ export type StreamHandlerDef = {
   readonly name: string;
   readonly schema: ZodType;
   readonly handler: StreamHandlerFn;
-  readonly access?: AccessRule;
+  readonly access: AccessRule;
   readonly rateLimit?: RateLimitOption;
 };

package/src/screen.ts

@@ -1035,7 +1035,9 @@ export type EntityEditScreenDefinition = {
    *  The object form additionally names the success-payload field the
    *  navigation id comes from (`ActionFormRedirect.idFrom`) — needed when
    *  the edited record is a child and the target screen is the parent's
-   *  detail screen. */
+   *  detail screen. Update falls back to the loaded record when the
+   *  success payload doesn't carry that field flatly; create falls back
+   *  to the submitted form values. */
   readonly redirect?: string | ActionFormRedirect;
   /** Parent list screen (short id) for breadcrumb + nav highlighting when
    *  this screen has no nav entry of its own. Same field/semantics as on

package/src/tenancy-brand.ts

@@ -0,0 +1,9 @@
+// Makes `db.global()` on a "tenant" table a compile error, mirroring executor-brand.ts's
+// approach for the executor-only write path.
+export type EntityTenancy = "global" | "tenant";
+
+declare const TENANCY: unique symbol;
+
+export interface TenancyBrand<T extends EntityTenancy> {
+  readonly [TENANCY]: T;
+}

package/src/tenant-db-types.ts

@@ -1,8 +1,9 @@
 import type { DbRunner } from "./db-connection";
 import type { EntityTableMeta } from "./entity-table-meta-types";
-import type { NotExecutorOnly } from "./executor-brand";
+import type { ExecutorOnly, NotExecutorOnly } from "./executor-brand";
 import type { TenantId } from "./identifiers";
 import type { SchemaTable } from "./schema-table-types";
+import type { TenancyBrand } from "./tenancy-brand";
 import type { SelectOptions, WhereObject } from "./where-clause-types";
 
 // Method-form writes reject the executor-only brand exactly like the free-function
@@ -14,6 +15,28 @@ import type { SelectOptions, WhereObject } from "./where-clause-types";
 // the plain `SchemaTable` param.
 type WritableTable = (SchemaTable | EntityTableMeta) & NotExecutorOnly;
 
+// db.global(table)'s surface: reads are unrestricted; writes require the managed
+// EntityTable's executor-only brand to be absent (mirrors WritableTable above).
+type GlobalReads = {
+  selectMany<T = Record<string, unknown>>(
+    where?: WhereObject,
+    options?: SelectOptions,
+  ): Promise<readonly T[]>;
+  fetchOne<T = Record<string, unknown>>(where: WhereObject): Promise<T | undefined>;
+};
+type GlobalWrites = {
+  insertOne<T = Record<string, unknown>>(values: Record<string, unknown>): Promise<T | undefined>;
+  updateMany<T = Record<string, unknown>>(
+    set: Record<string, unknown>,
+    where: WhereObject,
+  ): Promise<readonly T[]>;
+  deleteMany(where: WhereObject): Promise<void>;
+};
+// Checks `extends ExecutorOnly`, not `NotExecutorOnly` — the latter's optional-never
+// property is a TS "weak type" that would silently collapse every TTable to GlobalReads.
+export type GlobalTableDb<TTable> = GlobalReads &
+  (TTable extends ExecutorOnly ? unknown : GlobalWrites);
+
 /**
  * TenantDb scope modes:
  *
@@ -34,8 +57,18 @@ export type TenantDb = {
    * 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.systemDb.unsafeRaw(reason)` or `db.global(table)`
+   * instead — both make the cross-tenant intent an explicit, named
+   * declaration instead of a silent unfiltered escape hatch. Removal fw#2860.
    */
   readonly raw: DbRunner;
+  /**
+   * Reach a "global" table with the tenant filter lifted — reads always work; writes
+   * reject unless the write handler declared `escapeHatch: { reason }`. "tenant"-tenancy is a compile error here.
+   */
+  global<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
+    table: TTable,
+  ): GlobalTableDb<TTable>;
   selectMany<T = Record<string, unknown>>(
     table: SchemaTable,
     where?: WhereObject,
@@ -68,6 +101,11 @@ export type UncheckedSystemDb = {
   assertTenantMatch(tenantId: TenantId): TenantDb;
   assertRowsTenant<T>(rows: readonly T[], tenantField: keyof T): readonly T[];
   acknowledgeCrossTenant(reason: string): TenantDb;
+  /**
+   * Raw unfiltered DbRunner, gated behind a mandatory non-empty `reason` for auditability.
+   * Throws on an empty (or whitespace-only) reason.
+   */
+  unsafeRaw(reason: string): DbRunner;
   // Same self-check pair as above, but hands back the caller's
   // ctx.dbOutsideTransaction TenantDb instead of the in-tx one — for
   // durability writes that must survive a rollback of the handler's own