@cosmicdrift/kumiko-framework 0.259.0 → 0.261.0

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");
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -206,6 +206,8 @@ export async function buildHandlerContext(
   // but at this point we're the root of the pipeline — cast is safe.
   const dbSource = resolveDbSource(ctx, tx);
   const reqCtx = requestContext.get();
+  // db.global()'s write-gate — undefined for query/stream handlers, which can't declare escapeHatch.
+  const escapeHatch = registry.getWriteHandler(type)?.escapeHatch;
   const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
@@ -214,6 +216,7 @@ export async function buildHandlerContext(
       context.tracer,
       context.meter,
       signal,
+      escapeHatch,
     );
   // Propagate the request's AbortSignal so every TenantDb query throws when
   // the client has disconnected — handlers with many sequential queries skip

package/src/secrets/__tests__/contains-secret.test.ts

@@ -54,6 +54,7 @@ declare const aSecret: Secret<string>;
 defineQueryHandler({
   name: "t:query:leak",
   schema,
+  access: { openToAll: true },
   handler: async () => ({ apiKey: aSecret }),
 });
 
@@ -64,6 +65,7 @@ function genericResponseHandler<K extends string>(kind: K) {
   return defineQueryHandler({
     name: "t:query:generic",
     schema,
+    access: { openToAll: true },
     handler: async () => ({ kind, ok: true }) as { kind: K; ok: boolean },
   });
 }
@@ -81,6 +83,7 @@ declare const leakingUnion: { ok: true } | { apiKey: Secret<string> };
 defineQueryHandler({
   name: "t:query:union-leak",
   schema,
+  access: { openToAll: true },
   handler: async () => leakingUnion,
 });
 
@@ -88,6 +91,7 @@ declare const cleanUnion: { ok: true } | { id: string };
 defineQueryHandler({
   name: "t:query:union-clean",
   schema,
+  access: { openToAll: true },
   handler: async () => cleanUnion,
 });
 
@@ -96,6 +100,7 @@ describe("R6 ContainsSecret", () => {
     const def = defineQueryHandler({
       name: "t:query:clean",
       schema,
+      access: { openToAll: true },
       handler: async () => ({ ok: true, value: createSecret("x").reveal() }),
     });
     expect(def.name).toBe("t:query:clean");

package/src/testing/__tests__/e2e-generator.test.ts

@@ -34,7 +34,7 @@ function createTasksFeature() {
   return defineFeature("tasks", (r) => {
     r.systemScope();
     r.entity("task", taskEntity);
-    r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+    r.writeHandler(defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }));
     r.screen({
       id: "task-list",
       type: "entityList",
@@ -105,7 +105,7 @@ describe("generateE2ESpec", () => {
     const feature = defineFeature("events", (r) => {
       r.systemScope();
       r.entity("event", entity);
-      r.writeHandler(defineEntityCreateHandler("event", entity));
+      r.writeHandler(defineEntityCreateHandler("event", entity, { access: { openToAll: true } }));
       r.screen({
         id: "event-edit",
         type: "entityEdit",
@@ -164,7 +164,9 @@ describe("generateE2ESpec", () => {
     const editOnly = defineFeature("edit-only", (r) => {
       r.systemScope();
       r.entity("task", taskEntity);
-      r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+      r.writeHandler(
+        defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }),
+      );
       r.screen({
         id: "edit",
         type: "entityEdit",
@@ -198,7 +200,9 @@ describe("generateE2ESpec", () => {
     const feature = defineFeature("contacts", (r) => {
       r.systemScope();
       r.entity("contact", contactEntity);
-      r.writeHandler(defineEntityCreateHandler("contact", contactEntity));
+      r.writeHandler(
+        defineEntityCreateHandler("contact", contactEntity, { access: { openToAll: true } }),
+      );
       r.screen({
         id: "list",
         type: "entityList",
@@ -220,7 +224,9 @@ describe("generateE2ESpec", () => {
     const mixed = defineFeature("mixed", (r) => {
       r.systemScope();
       r.entity("task", taskEntity);
-      r.writeHandler(defineEntityCreateHandler("task", taskEntity));
+      r.writeHandler(
+        defineEntityCreateHandler("task", taskEntity, { access: { openToAll: true } }),
+      );
       r.screen({ id: "list", type: "entityList", entity: "task", columns: ["title"] });
       r.screen({
         id: "edit",

package/src/ui-types/index.ts

@@ -52,7 +52,12 @@ export type {
   SelectFieldDef,
   TextFieldDef,
 } from "../engine/types/fields";
-export type { AccessRule } from "../engine/types/handlers";
+export type {
+  AccessRule,
+  OpenToAllAccessRule,
+  OpenToAllDeclaration,
+} from "../engine/types/handlers";
+export { isOpenToAllGranted } from "../engine/types/handlers";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";
 export type {
   ActionFormRedirect,