@cosmicdrift/kumiko-framework 0.259.0 → 0.261.0

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

@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { createEntity, createTextField } from "../../factories";
+import type { AccessRule } from "../../types";
+import { validateAccessDeclarations } from "../access-declarations";
+
+const noteEntity = createEntity({
+  table: "fw2855_guard_notes",
+  fields: {
+    email: createTextField({ personal: "self", find: "none" }),
+    title: createTextField({ personal: false, reason: "test_fixture" }),
+  },
+});
+
+describe("validateAccessDeclarations", () => {
+  // 1. openToAll reason must be non-empty.
+  test("openToAll with an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { openToAll: { reason: "" } },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+  });
+
+  test("openToAll with a non-empty reason boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { openToAll: { reason: "internal signup form" } },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  // 1b. malformed openToAll (from untyped sources) counts as invalid, not a crash.
+  test.each([{ openToAll: false }, { openToAll: {} }])(
+    "malformed openToAll %p throws, naming the handler",
+    (access) => {
+      const feature = defineFeature("notes", (r) => {
+        r.entity("note", noteEntity);
+        r.writeHandler(
+          "note:create",
+          z.object({ title: z.string() }),
+          async () => ({
+            isSuccess: true as const,
+            data: {},
+          }),
+          {
+            // @cast-boundary test — simulates JSON/Designer input that doesn't match the static union
+            access: access as unknown as AccessRule,
+          },
+        );
+      });
+      expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+      expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+    },
+  );
+
+  // 2. escapeHatch reason must be non-empty.
+  test("escapeHatch with an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["Admin"] },
+          escapeHatch: { reason: "" },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+  });
+
+  test("escapeHatch with a non-empty reason boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["Admin"] },
+          escapeHatch: { reason: "cross-tenant note import job" },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  // 3. openToAll write handler accepting a personal-data field needs publicIntake.
+  test("openToAll write handler accepting a personal-data field without publicIntake throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ email: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { openToAll: { reason: "public signup" } },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"email"/);
+  });
+
+  test("openToAll write handler accepting a personal-data field WITH publicIntake boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ email: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { openToAll: { reason: "public signup" }, publicIntake: true },
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  // 4. publicIntake is only meaningful on a write handler.
+  test("publicIntake on a query handler throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { openToAll: { reason: "public listing" }, publicIntake: true },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:list"/);
+  });
+
+  test("query handler without publicIntake boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { openToAll: { reason: "public listing" } },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  test("publicIntake on a stream handler throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler("note:watch", z.object({}), async function* () {}, {
+        access: { openToAll: { reason: "public stream" }, publicIntake: true },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:watch"/);
+  });
+
+  test("stream handler without publicIntake boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.streamHandler("note:watch", z.object({}), async function* () {}, {
+        access: { openToAll: { reason: "public stream" } },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+});

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/boot-validator/screens.ts

@@ -18,6 +18,7 @@ import {
 import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import { metricField } from "../types";
 import type {
+  ActionFormRedirect,
   ActionFormScreenDefinition,
   DashboardCustomPanel,
   DashboardFilterDefinition,
@@ -631,6 +632,42 @@ function validateFormLayoutSections(
   }
 }
 
+// redirect is either a short screen id (same-feature, e.g. "item-list") or
+// a fully-qualified cross-feature QN (`<feature>:screen:<id>`) — the
+// renderer strips the latter to the short id (lastSegment) when
+// navigating, which the nav-router resolves app-wide (#1946). The object
+// form (fw#2670) carries the same target under `screen` plus the payload
+// field `idFrom`. Shared by actionForm/secretMint (validateInlineFormNavTargets)
+// and entityEdit — same rule, same error message, one place to keep them in sync.
+function validateRedirectTarget(
+  feature: FeatureDefinition,
+  screenId: string,
+  screenKind: "actionForm" | "secretMint" | "entityEdit",
+  redirect: string | ActionFormRedirect,
+  allScreenQns: ReadonlySet<string>,
+): void {
+  const redirectTarget = typeof redirect === "string" ? redirect : redirect.screen;
+  if (
+    typeof redirect !== "string" &&
+    (typeof redirect.idFrom !== "string" || redirect.idFrom.trim() === "")
+  ) {
+    throw new Error(
+      `[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is empty or not a string — ` +
+        `name the success-payload field carrying the navigation id, or use the plain string ` +
+        `redirect form to navigate with the handler's own "id".`,
+    );
+  }
+  validateScreenNavTarget(
+    feature.name,
+    screenId,
+    screenKind,
+    "redirect",
+    redirectTarget,
+    allScreenQns,
+    feature.screens,
+  );
+}
+
 function validateInlineFormNavTargets(
   feature: FeatureDefinition,
   screenId: string,
@@ -639,33 +676,7 @@ function validateInlineFormNavTargets(
   allScreenQns: ReadonlySet<string>,
 ): void {
   if (screen.redirect !== undefined) {
-    // redirect is either a short screen id (same-feature, e.g. "item-list")
-    // or a fully-qualified cross-feature QN (`<feature>:screen:<id>`) — the
-    // renderer strips the latter to the short id (lastSegment) when
-    // navigating, which the nav-router resolves app-wide (#1946). The object
-    // form (fw#2670, actionForm only) carries the same target under `screen`
-    // plus the payload field `idFrom`.
-    const redirectTarget =
-      typeof screen.redirect === "string" ? screen.redirect : screen.redirect.screen;
-    if (
-      typeof screen.redirect !== "string" &&
-      (typeof screen.redirect.idFrom !== "string" || screen.redirect.idFrom.trim() === "")
-    ) {
-      throw new Error(
-        `[Feature ${feature.name}] Screen "${screenId}" (${kind}) redirect.idFrom is empty or not a string — ` +
-          `name the success-payload field carrying the navigation id, or use the plain string ` +
-          `redirect form to navigate with the handler's own "id".`,
-      );
-    }
-    validateScreenNavTarget(
-      feature.name,
-      screenId,
-      kind,
-      "redirect",
-      redirectTarget,
-      allScreenQns,
-      feature.screens,
-    );
+    validateRedirectTarget(feature, screenId, kind, screen.redirect, allScreenQns);
   }
   if (typeof screen.cancelTarget === "string") {
     // Same rule as redirect — `false` (no Cancel button) needs no validation.
@@ -986,6 +997,20 @@ export function validateScreens(
                 `there is no fallback to the raw column name.`,
             );
           }
+          const navigate = typeof metric === "string" ? undefined : metric.navigate;
+          // Cross-screen navigate+tab isn't checked here — the target screen
+          // validates its own section ids when the loop reaches it.
+          if (
+            navigate?.tab !== undefined &&
+            navigate.screen === undefined &&
+            navigate.entity === undefined &&
+            !screen.layout.sections.some((section) => section.id === navigate.tab)
+          ) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
+                `navigates to tab "${navigate.tab}", which is not a section id on this screen.`,
+            );
+          }
         }
       }
       for (const section of screen.layout.sections) {
@@ -1785,17 +1810,7 @@ export function validateScreens(
         }
       }
       if (screen.redirect !== undefined) {
-        // Same rule as actionForm's redirect: short screen-ID (same-feature)
-        // or a fully-qualified cross-feature QN (#1946).
-        validateScreenNavTarget(
-          feature.name,
-          screenId,
-          "entityEdit",
-          "redirect",
-          screen.redirect,
-          allScreenQns,
-          feature.screens,
-        );
+        validateRedirectTarget(feature, screenId, "entityEdit", screen.redirect, allScreenQns);
       }
     }
   }

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
 }