@cosmicdrift/kumiko-framework 0.260.0 → 0.261.0

package/src/engine/boot-validator/access-declarations.ts

@@ -0,0 +1,141 @@
+import type { AccessRule, FeatureDefinition, WriteHandlerDef } from "../types";
+import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
+import { getZodObjectShape } from "./zod-shape";
+
+type HandlerKind = "write" | "query" | "stream";
+
+// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
+// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
+// sense openToAll+publicIntake is guarding against.
+function isPersonalDataField(field: unknown): boolean {
+  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
+  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
+}
+
+function personalFieldNames(entity: EntityDefinition): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    if (isPersonalDataField(field)) names.add(fieldName);
+  }
+  return names;
+}
+
+function candidatePersonalFieldNames(
+  feature: FeatureDefinition,
+  handlerName: string,
+): ReadonlySet<string> {
+  const mappedEntityName = feature.handlerEntityMappings?.[handlerName];
+  const entities = feature.entities ?? {};
+  if (mappedEntityName) {
+    const entity = entities[mappedEntityName];
+    return entity ? personalFieldNames(entity) : new Set();
+  }
+  const names = new Set<string>();
+  for (const entity of Object.values(entities)) {
+    for (const name of personalFieldNames(entity)) names.add(name);
+  }
+  return names;
+}
+
+// A value that is neither `true` nor an object with a non-empty string `reason`
+// counts as "empty" — catches malformed openToAll from untyped sources too.
+function openToAllReasonIsEmpty(access: AccessRule): boolean {
+  if (!("openToAll" in access)) return false;
+  const openToAll: unknown = access.openToAll;
+  if (openToAll === true) return false;
+  if (typeof openToAll !== "object" || openToAll === null) return true;
+  if (!("reason" in openToAll) || typeof openToAll.reason !== "string") return true;
+  return openToAll.reason.trim().length === 0;
+}
+
+function hasOpenToAll(access: AccessRule): boolean {
+  return "openToAll" in access;
+}
+
+function hasPublicIntake(access: AccessRule): boolean {
+  return "publicIntake" in access && access.publicIntake === true;
+}
+
+function validateOpenToAllReason(
+  feature: FeatureDefinition,
+  kind: HandlerKind,
+  handlerName: string,
+  access: AccessRule,
+): void {
+  // skip: reason is well-formed, nothing to validate
+  if (!openToAllReasonIsEmpty(access)) return;
+  throw new Error(
+    `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
+      '{ openToAll: ... } — must be `true` or { reason: "<non-empty explanation>" } ' +
+      "for why any authenticated user may call this handler.",
+  );
+}
+
+function validateEscapeHatchReason(
+  feature: FeatureDefinition,
+  handlerName: string,
+  escapeHatch: WriteHandlerDef["escapeHatch"],
+): void {
+  // skip: no escapeHatch declared, or its reason is already non-empty
+  if (!escapeHatch || escapeHatch.reason.trim().length > 0) return;
+  throw new Error(
+    `[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+      `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
+      "explaining why this handler needs db.global() write access.",
+  );
+}
+
+function validatePublicIntakeOnlyOnWrite(
+  feature: FeatureDefinition,
+  kind: HandlerKind,
+  handlerName: string,
+  access: AccessRule,
+): void {
+  // skip: write handlers may declare publicIntake, or it wasn't declared here
+  if (kind === "write" || !hasPublicIntake(access)) return;
+  throw new Error(
+    `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+      "{ publicIntake: true } — publicIntake is only meaningful on a write handler " +
+      "(it silences the personal-data + openToAll boot check for the fields a write " +
+      "handler's input accepts).",
+  );
+}
+
+function validateOpenToAllPersonalData(
+  feature: FeatureDefinition,
+  handlerName: string,
+  handler: WriteHandlerDef,
+): void {
+  const access = handler.access;
+  // skip: no openToAll declared, or publicIntake already covers personal data
+  if (!hasOpenToAll(access) || hasPublicIntake(access)) return;
+  const shape = getZodObjectShape(handler.schema);
+  // skip: handler schema isn't a zod object — nothing to inspect
+  if (!shape) return;
+  const personalNames = candidatePersonalFieldNames(feature, handlerName);
+  const offending = Object.keys(shape).filter((key) => personalNames.has(key));
+  // skip: no personal-data fields in the handler's input
+  if (offending.length === 0) return;
+  throw new Error(
+    `[Feature ${feature.name}] write handler "${handlerName}" declares openToAll and ` +
+      `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} without ` +
+      "{ publicIntake: true }. Restrict access to roles, or declare " +
+      "{ publicIntake: true } if any authenticated user may submit this personal data.",
+  );
+}
+
+export function validateAccessDeclarations(feature: FeatureDefinition): void {
+  for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
+    validateOpenToAllReason(feature, "write", handlerName, handler.access);
+    validateEscapeHatchReason(feature, handlerName, handler.escapeHatch);
+    validateOpenToAllPersonalData(feature, handlerName, handler);
+  }
+  for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
+    validateOpenToAllReason(feature, "query", handlerName, handler.access);
+    validatePublicIntakeOnlyOnWrite(feature, "query", handlerName, handler.access);
+  }
+  for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
+    validateOpenToAllReason(feature, "stream", handlerName, handler.access);
+    validatePublicIntakeOnlyOnWrite(feature, "stream", handlerName, handler.access);
+  }
+}

package/src/engine/boot-validator/entity-handler.ts

@@ -143,7 +143,7 @@ export function validateHandlerAccess(feature: FeatureDefinition): void {
       if (!handler.access) {
         throw new Error(
           `${label} handler "${feature.name}:${kind}:${name}" is missing an access rule. ` +
-            `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+            `Set { roles: [...] } for role-based access, or { openToAll: { reason: "..." } } for any authenticated user.`,
         );
       }
       validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);

package/src/engine/boot-validator/index.ts

@@ -1,6 +1,7 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
+import { validateAccessDeclarations } from "./access-declarations";
 import { warnOnUniqueAccessRoles } from "./access-roles";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
@@ -187,6 +188,7 @@ export function validateBoot(
     validateExtendSchemaCollisions(feature);
     validateDerivedFieldCollisions(feature);
     validateHandlerAccess(feature);
+    validateAccessDeclarations(feature);
     validateLocatedTimestamps(feature);
     validateEntityIndexes(feature);
     validateConfigKeyBounds(feature);

package/src/engine/define-handler.ts

@@ -85,6 +85,7 @@ export function defineWriteHandler<
       unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
     }),
     ...(def.rateLimit && { rateLimit: def.rateLimit }),
+    ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
   };
 
   if ("perform" in def && def.perform !== undefined) {

package/src/engine/entity-handlers.ts

@@ -30,6 +30,7 @@ import type {
 } from "./types/entity-handlers";
 
 export type {
+  EntityCrudHandlerDefaults,
   EntityCrudRegistrar,
   EntityCrudVerb,
   EntityHandlerOptions,
@@ -174,7 +175,7 @@ function parseHandlerName<TVerb extends string>(
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -291,9 +292,9 @@ export function defineEntityWriteHandler(
     name,
     schema,
     handler,
-    ...(options?.access && { access: options.access }),
-    ...(options?.description !== undefined && { description: options.description }),
-    ...(options?.agent !== undefined && { agent: options.agent }),
+    access: options.access,
+    ...(options.description !== undefined && { description: options.description }),
+    ...(options.agent !== undefined && { agent: options.agent }),
   };
 }
 
@@ -323,7 +324,7 @@ function augmentDerivedFields(
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
@@ -421,9 +422,9 @@ export function defineEntityQueryHandler(
     name,
     schema,
     handler,
-    ...(options?.access && { access: options.access }),
-    ...(options?.description !== undefined && { description: options.description }),
-    ...(options?.agent !== undefined && { agent: options.agent }),
+    access: options.access,
+    ...(options.description !== undefined && { description: options.description }),
+    ...(options.agent !== undefined && { agent: options.agent }),
     // The "list" verb's executor.list() always returns { rows, nextCursor,
     // total? } (see the handler body above) — brand it so the definition
     // site documents the PagedRows contract without needing
@@ -458,7 +459,7 @@ export function defineEntityQueryHandler(
 export function defineEntityCreateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:create`, entity, options);
 }
@@ -467,7 +468,7 @@ export function defineEntityCreateHandler(
 export function defineEntityUpdateHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:update`, entity, options);
 }
@@ -476,7 +477,7 @@ export function defineEntityUpdateHandler(
 export function defineEntityDeleteHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:delete`, entity, options);
 }
@@ -485,7 +486,7 @@ export function defineEntityDeleteHandler(
 export function defineEntityRestoreHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityHandlerOptions,
+  options: EntityHandlerOptions,
 ): WriteHandlerDef {
   return defineEntityWriteHandler(`${entityName}:restore`, entity, options);
 }
@@ -494,7 +495,7 @@ export function defineEntityRestoreHandler(
 export function defineEntityListHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:list`, entity, options);
 }
@@ -503,7 +504,7 @@ export function defineEntityListHandler(
 export function defineEntityDetailHandler(
   entityName: string,
   entity: EntityDefinition,
-  options?: EntityQueryHandlerOptions,
+  options: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   return defineEntityQueryHandler(`${entityName}:detail`, entity, options);
 }
@@ -542,7 +543,7 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options?: { access?: AccessRule; unsafeAllTenants?: boolean },
+  options: { access: AccessRule; unsafeAllTenants?: boolean },
 ): QueryHandlerDef {
   return {
     name,
@@ -554,9 +555,9 @@ export function defineProjectionQueryHandler(
     handler: async (_query, ctx) =>
       ctx.queryProjection(
         projectionQualifiedName,
-        options?.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
+        options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ), // @wrapper-known semantic-alias
-    ...(options?.access && { access: options.access }),
+    access: options.access,
   };
 }
 
@@ -588,14 +589,23 @@ export function registerEntityCrud(
   }
   const writeOpts = options?.write;
   const readOpts = options?.read;
+  const requireAccess = (verb: EntityCrudVerb, access: AccessRule | undefined): AccessRule => {
+    if (!access) {
+      throw new Error(
+        `registerEntityCrud("${entityName}", verb: "${verb}"): no access rule resolved. ` +
+          `Set write.access/read.access on registerEntityCrud's options, or verbAccess.${verb}.`,
+      );
+    }
+    return access;
+  };
   const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
     ...writeOpts,
-    access: options?.verbAccess?.[verb] ?? writeOpts?.access,
+    access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
     description: options?.descriptions?.[verb] ?? writeOpts?.description,
   });
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
-    access: options?.verbAccess?.[verb] ?? readOpts?.access,
+    access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
     description: options?.descriptions?.[verb] ?? readOpts?.description,
   });
 

package/src/engine/factories.ts

@@ -1,3 +1,4 @@
+import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type {
   BigIntFieldDef,
   BooleanFieldDef,
@@ -442,7 +443,7 @@ export function createImagesField(
 // Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
 // validieren wir die Conformance via conditional return type: wenn F
 // nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
-export function createEntity<F>(def: {
+export function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
   readonly table?: string;
   readonly fields: F;
   readonly description?: string;
@@ -460,7 +461,8 @@ export function createEntity<F>(def: {
   readonly parentRef?: EntityDefinition["parentRef"];
   readonly retention?: RetentionDef;
   readonly derivedFields?: EntityDefinition["derivedFields"];
-}): F extends FieldsMap ? EntityDefinition<F> : never {
+  readonly tenancy?: T;
+}): F extends FieldsMap ? EntityDefinition<F, T> : never {
   return {
     softDelete: false,
     searchWeight: 1,
@@ -468,5 +470,5 @@ export function createEntity<F>(def: {
     // aggregate-ids are UUID. Opt-out with `idType: "serial"` for pre-ES
     // legacy tables (should be rare).
     ...def,
-  } as F extends FieldsMap ? EntityDefinition<F> : never; // @cast-boundary engine-payload
+  } as F extends FieldsMap ? EntityDefinition<F, T> : never; // @cast-boundary engine-payload
 }

package/src/engine/feature-ast/extractors/hooks.ts

@@ -42,8 +42,12 @@ export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
   if (Array.isArray(value["roles"]) && value["roles"].every((r) => typeof r === "string")) {
     return { roles: value["roles"] as readonly string[] };
   }
+  const publicIntake = value["publicIntake"] === true ? { publicIntake: true as const } : {};
   if (value["openToAll"] === true) {
-    return { openToAll: true };
+    return { openToAll: true, ...publicIntake };
+  }
+  if (isPlainObject(value["openToAll"]) && typeof value["openToAll"]["reason"] === "string") {
+    return { openToAll: { reason: value["openToAll"]["reason"] }, ...publicIntake };
   }
   return undefined;
 }

package/src/engine/feature-entity-handlers.ts

@@ -19,6 +19,7 @@ import type {
   AgentHandlerHints,
   EntityDefinition,
   EntityRef,
+  EscapeHatchDeclaration,
   HandlerRef,
   NameOrRef,
   QueryHandlerFn,
@@ -67,6 +68,18 @@ function agentSlots(source: {
   };
 }
 
+function requireInlineHandlerArgs<TSchema, THandler, TOptions extends object>(
+  kind: string,
+  schema: TSchema | undefined,
+  handler: THandler | undefined,
+  options: TOptions | undefined,
+): { schema: TSchema; handler: THandler; options: TOptions } {
+  if (!schema || !handler || !options) {
+    throw new Error(`${kind} inline form requires schema + handler + options.access`);
+  }
+  return { schema, handler, options };
+}
+
 // Builds entity/relation/writeHandler/queryHandler — the registrar
 // methods that create or reference entities.
 export function buildEntityHandlerMethods<TName extends string>(
@@ -110,10 +123,11 @@ export function buildEntityHandlerMethods<TName extends string>(
       schema?: TSchema,
       handler?: WriteHandlerFn<z.infer<TSchema>>,
       options?: {
-        access?: AccessRule;
+        access: AccessRule;
         rateLimit?: RateLimitOption;
         description?: string;
         agent?: AgentHandlerHints;
+        escapeHatch?: EscapeHatchDeclaration;
       },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
@@ -130,10 +144,11 @@ export function buildEntityHandlerMethods<TName extends string>(
           // `satisfies` does not work here (it asserts assignability, which
           // is what fails). Explicit cast is the right tool.
           handler: def.handler as WriteHandlerFn,
-          ...(def.access && { access: def.access }),
+          access: def.access,
           ...agentSlots(def),
           ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
           // Forward the pipeline-build closure so boot-validators and
           // Designer/AI tooling can inspect the step list. Absent on
           // free-form handlers — defineWriteHandler only sets `perform`
@@ -147,15 +162,15 @@ export function buildEntityHandlerMethods<TName extends string>(
         tryMapEntity(state, name, def.name);
         return { name: def.name };
       }
-      if (!schema || !handler)
-        throw new Error("writeHandler inline form requires schema + handler");
+      const inline = requireInlineHandlerArgs("writeHandler", schema, handler, options);
       state.writeHandlers[nameOrDef] = {
         name: nameOrDef,
-        schema,
-        handler: handler as WriteHandlerFn, // @cast-boundary engine-bridge
-        ...(options?.access && { access: options.access }),
-        ...agentSlots(options ?? {}),
-        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+        schema: inline.schema,
+        handler: inline.handler as WriteHandlerFn, // @cast-boundary engine-bridge
+        access: inline.options.access,
+        ...agentSlots(inline.options),
+        ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+        ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
       };
       tryMapEntity(state, name, nameOrDef);
       return { name: nameOrDef };
@@ -165,7 +180,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       schema?: TSchema,
       handler?: QueryHandlerFn<z.infer<TSchema>>,
       options?: {
-        access?: AccessRule;
+        access: AccessRule;
         rateLimit?: RateLimitOption;
         outputSchema?: ZodType;
         description?: string;
@@ -179,7 +194,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           schema: def.schema,
           // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
           handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
-          ...(def.access && { access: def.access }),
+          access: def.access,
           ...agentSlots(def),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
           ...(def.outputSchema && { outputSchema: def.outputSchema }),
@@ -193,16 +208,15 @@ export function buildEntityHandlerMethods<TName extends string>(
         tryMapEntity(state, name, def.name);
         return { name: def.name };
       }
-      if (!schema || !handler)
-        throw new Error("queryHandler inline form requires schema + handler");
+      const inline = requireInlineHandlerArgs("queryHandler", schema, handler, options);
       state.queryHandlers[nameOrDef] = {
         name: nameOrDef,
-        schema,
-        handler: handler as QueryHandlerFn, // @cast-boundary engine-bridge
-        ...(options?.access && { access: options.access }),
-        ...agentSlots(options ?? {}),
-        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
-        ...(options?.outputSchema && { outputSchema: options.outputSchema }),
+        schema: inline.schema,
+        handler: inline.handler as QueryHandlerFn, // @cast-boundary engine-bridge
+        access: inline.options.access,
+        ...agentSlots(inline.options),
+        ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
+        ...(inline.options.outputSchema && { outputSchema: inline.options.outputSchema }),
       };
       tryMapEntity(state, name, nameOrDef);
       return { name: nameOrDef };
@@ -211,7 +225,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | StreamHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: StreamHandlerFn<z.infer<TSchema>>,
-      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+      options?: { access: AccessRule; rateLimit?: RateLimitOption },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -220,19 +234,18 @@ export function buildEntityHandlerMethods<TName extends string>(
           schema: def.schema,
           // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
           handler: def.handler as StreamHandlerFn, // @cast-boundary engine-bridge
-          ...(def.access && { access: def.access }),
+          access: def.access,
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
         };
         return { name: def.name };
       }
-      if (!schema || !handler)
-        throw new Error("streamHandler inline form requires schema + handler");
+      const inline = requireInlineHandlerArgs("streamHandler", schema, handler, options);
       state.streamHandlers[nameOrDef] = {
         name: nameOrDef,
-        schema,
-        handler: handler as StreamHandlerFn, // @cast-boundary engine-bridge
-        ...(options?.access && { access: options.access }),
-        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+        schema: inline.schema,
+        handler: inline.handler as StreamHandlerFn, // @cast-boundary engine-bridge
+        access: inline.options.access,
+        ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
       };
       return { name: nameOrDef };
     },

package/src/engine/index.ts

@@ -358,6 +358,7 @@ export type {
   EntityListScreenDefinition,
   EntityRef,
   EntityRelations,
+  EscapeHatchDeclaration,
   EventDef,
   FeatureDefinition,
   FeatureRegistrar,
@@ -414,6 +415,8 @@ export type {
   NotifyPriority,
   NumberFieldDef,
   OnDeleteStrategy,
+  OpenToAllAccessRule,
+  OpenToAllDeclaration,
   ParentRefDef,
   PersonalAnnotations,
   PersonalAnnotationsLongText,
@@ -489,6 +492,7 @@ export {
   DEFAULT_LOCALES,
   HookPhases,
   isAgentVisibleScreen,
+  isOpenToAllGranted,
   resolveAgentExposure,
 } from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";

package/src/engine/types/handlers.ts

@@ -1,2 +1,3 @@
 // Legacy path — re-exported for callers still importing this module directly.
 export type * from "@cosmicdrift/kumiko-types/handlers";
+export { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";

package/src/engine/types/index.ts

@@ -156,6 +156,7 @@ export type {
   DeclarativeEventMigration,
   DispatchWriteRef,
   EntityRef,
+  EscapeHatchDeclaration,
   EventDef,
   EventMigrationDef,
   EventPiiFields,
@@ -172,6 +173,8 @@ export type {
   NotifyFn,
   NotifyOptions,
   NotifyPriority,
+  OpenToAllAccessRule,
+  OpenToAllDeclaration,
   QualifiedEventName,
   QueryEvent,
   QueryHandlerDef,
@@ -189,6 +192,7 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "@cosmicdrift/kumiko-types/handlers";
+export { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
 export type {
   DeleteContext,
   EntityHookMap,

package/src/pipeline/__tests__/escape-hatch.integration.test.ts

@@ -0,0 +1,93 @@
+// fw#2855 — a write handler's `escapeHatch` gates writes through ctx.db.global(table):
+// WITH it the write succeeds, WITHOUT it the same handler rejects with access_denied.
+// Real HTTP calls + setupTestStack — never createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { defineFeature } from "../../engine";
+import { createTestUser, setupTestStack, type TestStack } from "../../stack";
+
+const globalStoreTable = defineUnmanagedTable({
+  tableName: "store_fw2855_escape_hatch_items",
+  tenancy: "global",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "note", pgType: "text", notNull: true },
+  ],
+});
+
+const escapeHatchFeature = defineFeature("escape-hatch-probe", (r) => {
+  r.storeTable(globalStoreTable, {
+    reason: "fw#2855 integration test — cross-tenant store table for db.global()",
+  });
+
+  r.writeHandler({
+    name: "write-with-hatch",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["User"] },
+    escapeHatch: { reason: "fw#2855 integration test — declared cross-tenant write" },
+    handler: async (event, ctx) => {
+      const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
+        tenantId: event.user.tenantId,
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: row };
+    },
+  });
+
+  r.writeHandler({
+    name: "write-without-hatch",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["User"] },
+    handler: async (event, ctx) => {
+      const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
+        tenantId: event.user.tenantId,
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: row };
+    },
+  });
+});
+
+let stack: TestStack;
+const user = createTestUser({
+  id: 91,
+  tenantId: "11111111-0000-4000-8000-000000000091",
+  roles: ["User"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [escapeHatchFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("write handler escapeHatch gates ctx.db.global() writes", () => {
+  test("WITH escapeHatch: the write succeeds", async () => {
+    const result = await stack.http.writeOk<{ id: string }>(
+      "escape-hatch-probe:write:write-with-hatch",
+      { note: "hi" },
+      user,
+    );
+    expect(result.id).toBeDefined();
+  });
+
+  test("WITHOUT escapeHatch: the same write shape fails with access_denied", async () => {
+    const err = await stack.http.writeErr(
+      "escape-hatch-probe:write:write-without-hatch",
+      { note: "hi" },
+      user,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+});