@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

package/src/engine/boot-validator/projection-list-screens.ts

@@ -1,12 +1,15 @@
-import { QnTypes, qualifyEntityName } from "../qualified-name";
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { parseQn, QnTypes, qualifyEntityName } from "../qualified-name";
 import { isEditLayoutScreen } from "../screen-helpers";
 import type {
   EditRelatedListSection,
+  EntityDefinition,
   FeatureDefinition,
   ProjectionListScreenDefinition,
   QueryHandlerDef,
 } from "../types";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
+import { findEntity } from "./parent-ref";
 import { getZodObjectShape } from "./zod-shape";
 
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -154,6 +157,65 @@ function validateRelatedListFacets(
   );
 }
 
+// parentFilter resolves an entity field map to
+// check `field` against ONLY when the query is one of the entity-convention
+// factories (defineEntityListHandler et al., branded by
+// ENTITY_CONVENTION_QUERY_BRAND) — a hand-written handler carries no entity,
+// same "capability absent, no throw" policy as schemaAccepts above. The
+// entity name comes from the handler's own `<entityName>:list` naming
+// convention (parseHandlerName in entity-handlers.ts), recovered here from
+// the query's fully qualified name.
+function resolveEntityBehindQuery(
+  queryQn: string,
+  handler: QueryHandlerDef | undefined,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): EntityDefinition | undefined {
+  if (handler === undefined || handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) return undefined;
+  let entityName: string;
+  try {
+    entityName = parseQn(queryQn).name.split(":")[0] ?? "";
+  } catch {
+    return undefined;
+  }
+  return entityName === "" ? undefined : findEntity(featureMap, entityName);
+}
+
+// parentFilter lets a relatedList reuse the
+// generic `<entity>:list` query instead of a bespoke child-rows handler —
+// same 422 footgun as facets/filter above, plus its own mutual-exclusivity
+// and field-existence checks.
+function validateRelatedListParentFilter(
+  prefix: string,
+  section: EditRelatedListSection,
+  schema: QueryHandlerDef["schema"] | undefined,
+  handler: QueryHandlerDef | undefined,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  // skip: no parentFilter declared — nothing to reject.
+  if (section.parentFilter === undefined) return;
+  if (section.parentParam !== undefined) {
+    throw new Error(
+      `${prefix}: declares both parentFilter and parentParam — parentFilter replaces the implicit ` +
+        `{ [parentParam]: parentId } payload key with a server-side "filter" clause, so the two can't ` +
+        `be combined. Remove parentParam or drop parentFilter.`,
+    );
+  }
+  if (!schemaAccepts(schema, "filter")) {
+    throw new Error(
+      `${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
+        `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+        `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
+    );
+  }
+  const entity = resolveEntityBehindQuery(section.query, handler, featureMap);
+  if (entity !== undefined && entity.fields[section.parentFilter.field] === undefined) {
+    throw new Error(
+      `${prefix}: parentFilter.field "${section.parentFilter.field}" is not a declared field on the ` +
+        `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`,
+    );
+  }
+}
+
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
@@ -163,15 +225,18 @@ function validateRelatedListFacets(
 // doesn't quietly skip these checks.
 export function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void {
   const queryHandlers = buildQueryHandlerMap(features);
+  const featureMap = new Map(features.map((f) => [f.name, f] as const));
   for (const feature of features) {
     for (const screen of Object.values(feature.screens)) {
       if (!isEditLayoutScreen(screen)) continue;
       for (const section of screen.layout.sections) {
         if (section.kind !== "relatedList") continue;
         const prefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
-        const schema = queryHandlers.get(section.query)?.schema;
+        const handler = queryHandlers.get(section.query);
+        const schema = handler?.schema;
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
+        validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
       }
     }
   }

package/src/engine/boot-validator/query-output-columns.ts

@@ -14,6 +14,7 @@ import type {
 } from "../types";
 import { metricField } from "../types";
 import { buildQueryHandlerMap } from "./projection-list-screens";
+import { validateActionFieldRefs } from "./screens";
 import { getZodObjectShape, getZodRowShape } from "./zod-shape";
 
 // fw#2493: query handlers can now declare `outputSchema` (the Zod shape of
@@ -139,6 +140,38 @@ function checkProjectionDetailOutputFields(
         `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`,
     );
   }
+  checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
+}
+
+// relatedList toolbarActions' visible/params evaluate against the ENCLOSING
+// projectionDetail's record, not the relatedList's own row — reuses the
+// same per-action field-ref check as rowActions/toolbarActions elsewhere
+// (validateActionFieldRefs), pinned to this screen's own outputSchema shape
+// instead of an entity's field map. Same additive policy as the rest of this
+// module: no introspectable outputSchema → no-op, not a throw.
+function checkRelatedListToolbarActionFields(
+  recordShape: ShapeLookup | undefined,
+  featureName: string,
+  screenId: string,
+  screen: ProjectionDetailScreenDefinition,
+): void {
+  // skip: no introspectable outputSchema — same additive policy as the rest of this module.
+  if (recordShape === undefined) return;
+  const fieldNames = new Set(Object.keys(recordShape));
+  for (const section of screen.layout.sections) {
+    if (section.kind !== "relatedList") continue;
+    for (const action of section.toolbarActions ?? []) {
+      validateActionFieldRefs(
+        featureName,
+        screenId,
+        "toolbarAction",
+        action.id,
+        action,
+        fieldNames,
+        new Set(),
+      );
+    }
+  }
 }
 
 // Stat panels' query contract is a flat record (not the paged `{ rows }`

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

@@ -7,6 +7,7 @@
 import { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 import { rowMetaFieldNames } from "../../db/table-builder";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
+import { parseRefTarget } from "../parse-ref-target";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import {
@@ -14,6 +15,7 @@ import {
   isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
+  resolveNavParentScreen,
 } from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
 import { metricField } from "../types";
@@ -31,6 +33,7 @@ import type {
   FieldCondition,
   ListColumnSpec,
   ListFacetSpec,
+  RelatedListToolbarAction,
   RowAction,
   RowActionNavigateBase,
   RowFieldExtractor,
@@ -270,13 +273,15 @@ function validateWizardLayout(
 // Felder pinnen — ein Tippfehler in pick/map-Quellfeldern oder
 // visible.field erzeugte sonst still `undefined` im Payload bzw. dauerhaft
 // falsche Sichtbarkeit (gleiche "Typo fällt erst beim Klick"-Klasse wie
-// navigate/handler).
-function validateActionFieldRefs(
+// navigate/handler). Exported for query-output-columns.ts, which reuses it
+// against a projectionDetail's outputSchema-derived record shape instead of
+// an entity's field map (relatedList toolbarActions' visible/params).
+export function validateActionFieldRefs(
   featureName: string,
   screenId: string,
   actionKind: "rowAction" | "toolbarAction",
   actionId: string,
-  action: RowAction | ToolbarAction,
+  action: RowAction | ToolbarAction | RelatedListToolbarAction,
   fieldNames: ReadonlySet<string>,
   rowMeta: ReadonlySet<string>,
 ): void {
@@ -581,6 +586,37 @@ function validateFormFieldsMap(
 // (an input-less secretMint declares BOTH `fields: {}` and
 // `layout.sections: []`; fields declared with no layout to show them stays
 // an error).
+// `fields`/`groups` are mutually exclusive on a fields-kind section; shared by
+// every EditLayout-walking screen type instead of four hand-rolled copies.
+function validateFieldsXorGroups(
+  errorPrefix: string,
+  section: { readonly title?: string; readonly fields: readonly EditFieldSpec[] } & {
+    readonly groups?: readonly { readonly fields: readonly EditFieldSpec[] }[];
+  },
+): void {
+  if (section.fields.length > 0 && section.groups !== undefined) {
+    throw new Error(
+      `${errorPrefix} section "${section.title}" declares both fields and groups — pass fields: [] ` +
+        `when using groups.`,
+    );
+  }
+  if (section.fields.length === 0 && section.groups === undefined) {
+    throw new Error(
+      `${errorPrefix} has a section "${section.title}" with zero fields — drop the section or add ` +
+        `fields (or groups) to it.`,
+    );
+  }
+}
+
+function flattenFieldsOrGroups(section: {
+  readonly fields: readonly EditFieldSpec[];
+  readonly groups?: readonly { readonly fields: readonly EditFieldSpec[] }[];
+}): readonly EditFieldSpec[] {
+  return section.groups !== undefined
+    ? section.groups.flatMap((group) => group.fields)
+    : section.fields;
+}
+
 function validateFormLayoutSections(
   featureName: string,
   screenId: string,
@@ -620,13 +656,8 @@ function validateFormLayoutSections(
           `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
       );
     }
-    if (section.fields.length === 0) {
-      throw new Error(
-        `[Feature ${featureName}] Screen "${screenId}" (${context}) has a section "${section.title}" ` +
-          `with zero fields — drop the section or add fields to it.`,
-      );
-    }
-    for (const fieldSpec of section.fields) {
+    validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (${context})`, section);
+    for (const fieldSpec of flattenFieldsOrGroups(section)) {
       const normalized = normalizeEditField(fieldSpec);
       if (!fieldNames.has(normalized.field)) {
         throw new Error(
@@ -792,6 +823,52 @@ function validateSecretMintConfirm(
   }
 }
 
+// nav.screen is a full QN (cross-feature), so a standalone r.nav() pointing
+// at `targetQn` must be found by scanning every feature's nav entries and actions.
+function hasStandaloneNavEntry(
+  targetQn: string,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): boolean {
+  for (const f of featureMap.values()) {
+    for (const nav of Object.values(f.navs)) {
+      if (nav.screen === targetQn) return true;
+      if (nav.createAction?.screen === targetQn) return true;
+      if (nav.actions?.some((a) => a.screen === targetQn)) return true;
+    }
+  }
+  return false;
+}
+
+// Every screen must resolve nav via `nav`, `r.nav()`, a parent list, or
+// `dormant: true`. Skipped when the composed set has no nav entries at all.
+function validateScreenHasNavArea(
+  feature: FeatureDefinition,
+  screenId: string,
+  screen: ScreenDefinition,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  // skip: the screen already declares its own nav entry.
+  if (screen.nav !== undefined) return;
+  // skip: explicitly opted out via `dormant: true`.
+  if (screen.dormant === true) return;
+  const anyNavRegistered = [...featureMap.values()].some((f) => Object.keys(f.navs).length > 0);
+  // skip: no nav entries exist anywhere in the composed set — a feature/
+  // recipe/test fixture booted without an app shell, not an omission.
+  if (!anyNavRegistered) return;
+  const targetQn = qualifyEntityName(feature.name, "screen", screenId);
+  // skip: a standalone r.nav() elsewhere already points at this screen.
+  if (hasStandaloneNavEntry(targetQn, featureMap)) return;
+  const allScreens = [...featureMap.values()].flatMap((f) => Object.values(f.screens));
+  // skip: resolves to a parent list via listScreenId/rowAction-target/same-entity.
+  if (resolveNavParentScreen(allScreens, screen, (s) => s.id) !== undefined) return;
+  throw new Error(
+    `[Feature ${feature.name}] Screen "${targetQn}" has no nav entry and no resolvable list — ` +
+      `declare listScreenId (or a rowAction/toolbarAction navigate target from a list screen), add ` +
+      `a standalone r.nav() pointing at it, or set dormant: true if it's intentionally reachable ` +
+      `only via a direct link/redirect or a consuming app's own r.nav().`,
+  );
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -816,6 +893,7 @@ export function validateScreens(
   // #1946) — kurze IDs bleiben same-feature wie zuvor.
   const navTargetShortIds = screenShortIdsFrom(allScreenQns);
   for (const [screenId, screen] of Object.entries(feature.screens)) {
+    validateScreenHasNavArea(feature, screenId, screen, featureMap);
     if (screen.type === "custom") {
       if (!screen.renderer.react && !screen.renderer.native) {
         throw new Error(
@@ -863,6 +941,8 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionList)`,
           screen.facets,
           screen.columns,
+          feature.name,
+          featureMap,
         );
       }
       if (screen.rowActions !== undefined) {
@@ -1158,8 +1238,26 @@ export function validateScreens(
               `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) relatedList section "${section.title}"`,
               section.facets,
               section.columns,
+              feature.name,
+              featureMap,
             );
           }
+          // Only drawer-kind is validated here — navigate/writeHandler
+          // toolbarActions have no boot check yet, same gap as above.
+          if (section.toolbarActions !== undefined) {
+            for (const action of section.toolbarActions) {
+              if (action.kind === "drawer") {
+                validateDrawerTargetAction(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "toolbarAction",
+                  action,
+                  feature.screens,
+                );
+              }
+            }
+          }
           continue;
         }
         if (isWriteFormEditSection(section)) {
@@ -1202,12 +1300,10 @@ export function validateScreens(
           }
           continue;
         }
-        if (section.fields.length === 0) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has a section "${section.title}" ` +
-              `with zero fields — drop the section or add fields to it.`,
-          );
-        }
+        validateFieldsXorGroups(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail)`,
+          section,
+        );
       }
       // Header actions reuse RowAction (the displayed record stands in for
       // the row), so the same navigate/writeHandler existence checks as
@@ -1320,13 +1416,11 @@ export function validateScreens(
               `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
           );
         }
-        if (section.fields.length === 0) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
-              `with zero fields — drop the section or add fields to it.`,
-          );
-        }
-        for (const fieldSpec of section.fields) {
+        validateFieldsXorGroups(
+          `[Feature ${feature.name}] Screen "${screenId}" (configEdit)`,
+          section,
+        );
+        for (const fieldSpec of flattenFieldsOrGroups(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(
@@ -1739,13 +1833,11 @@ export function validateScreens(
               `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
           );
         }
-        if (section.fields.length === 0) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +
-              `with zero fields — drop the section or add fields to it.`,
-          );
-        }
-        for (const fieldSpec of section.fields) {
+        validateFieldsXorGroups(
+          `[Feature ${feature.name}] Screen "${screenId}" (entityEdit)`,
+          section,
+        );
+        for (const fieldSpec of flattenFieldsOrGroups(section)) {
           const normalized = normalizeEditField(fieldSpec);
           if (!fieldNames.has(normalized.field)) {
             throw new Error(
@@ -2052,10 +2144,25 @@ export function validateColumnRendererForm(
 // typo (the user never sees the field anywhere), so this is hard-checked
 // rather than just documented. Shared by projectionList and relatedList
 // (fw#2740) — `prefix` carries the caller's own screen/section message lead-in.
+//
+// `type: "reference"` is exempt from the same-name-column rule (fw akte-
+// bedienkonzept-2): it filters by an id field (e.g. "propertyId") but
+// displays a different, human-readable column (e.g. "propertyLabel") — a
+// column named after the filter field would almost never exist, and
+// requiring one anyway would force apps to add a column no design calls
+// for just to satisfy this check. Its own `entity` is mandatory on the type
+// (TS, not just this validator) and is resolved below — that explicit,
+// checked declaration is this facet type's field inventory, filling the
+// same "not just a typo" role the column-name check plays for select/
+// boolean facets. select/boolean facets keep the column requirement
+// unchanged: both filter and display the same field, so a facet with no
+// matching column is still almost always a typo.
 function validateListFacets(
   prefix: string,
   facets: readonly ListFacetSpec[],
   columns: readonly ListColumnSpec[],
+  currentFeatureName: string,
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
   const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
   const seenFacetFields = new Set<string>();
@@ -2064,7 +2171,7 @@ function validateListFacets(
       throw new Error(`${prefix} declares facet "${facet.field}" more than once.`);
     }
     seenFacetFields.add(facet.field);
-    if (!columnFieldNames.has(facet.field)) {
+    if (facet.type !== "reference" && !columnFieldNames.has(facet.field)) {
       throw new Error(
         `${prefix} facet references field "${facet.field}" which is not a declared column. ` +
           `Known columns: ${[...columnFieldNames].sort().join(", ")}`,
@@ -2076,6 +2183,22 @@ function validateListFacets(
           `declare at least one option.`,
       );
     }
+    if (facet.type === "reference") {
+      const target = parseRefTarget(facet.entity, currentFeatureName);
+      const targetFeature = featureMap.get(target.featureName);
+      if (targetFeature?.entities?.[target.entityName] === undefined) {
+        throw new Error(
+          `${prefix} facet "${facet.field}" (type "reference") targets entity "${facet.entity}", ` +
+            `which does not resolve to a registered entity. Known entities in feature ` +
+            `"${target.featureName}": ` +
+            `${
+              Object.keys(targetFeature?.entities ?? {})
+                .sort()
+                .join(", ") || "(none)"
+            }.`,
+        );
+      }
+    }
   }
 }
 

package/src/engine/build-config-feature-schema.ts

@@ -498,9 +498,6 @@ function minMaskOrder(keys: readonly MaskedKey[]): number {
 // opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
 // AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
 // per Key gegated.
-const ALL_ROLE_OPEN_TO_ALL_REASON =
-  'config key declares the "all" role, so every signed-in user of the tenant may read/write it';
-
 // Union der Navs-Access-Regeln: ein openToAll-Nav öffnet das ganze Gate, sonst
 // die Vereinigung der Rollen. undefined-access-Navs tragen nichts bei.
 function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRule {
@@ -519,6 +516,12 @@ function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRul
 // `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt
 // server-seitig per Key gegated.
 function rolesToAccess(roles: readonly string[]): AccessRule {
-  if (roles.includes("all")) return { openToAll: { reason: ALL_ROLE_OPEN_TO_ALL_REASON } };
+  if (roles.includes("all"))
+    return {
+      openToAll: {
+        reason:
+          'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+      },
+    };
   return { roles: [...new Set(roles)] };
 }

package/src/engine/entity-handlers.ts

@@ -8,7 +8,8 @@ import {
 } from "../db/eagerload";
 import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
 import { buildEntityTable, type EntityTable } from "../db/table-builder";
-import { createTenantDb, type TenantDb } from "../db/tenant-db";
+import { acknowledgeConventionCrossTenant, type TenantDb } from "../db/tenant-db";
+import { isSystemIdentity } from "../pipeline/system-identity-switch";
 import { assertUnreachable } from "../utils";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
@@ -16,6 +17,7 @@ import type {
   AccessRule,
   DeriveContext,
   EntityDefinition,
+  EscapeHatchDeclaration,
   HandlerContext,
   QueryHandlerDef,
   SessionUser,
@@ -107,6 +109,33 @@ type ListPayload = {
 
 const idSchema = z.object({ id: z.uuid() });
 
+// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
+const deprecatedCrossTenantHandlers = new WeakSet<object>();
+
+export function isDeprecatedCrossTenantHandler(handler: object): boolean {
+  return deprecatedCrossTenantHandlers.has(handler);
+}
+
+export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
+
+function resolveCrossTenantReason(name: string, options: EntityHandlerOptions): string | undefined {
+  if (options.escapeHatch !== undefined && options.crossTenant === true) {
+    throw new Error(
+      `"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`,
+    );
+  }
+  if (options.escapeHatch !== undefined) {
+    if (options.escapeHatch.reason.trim().length === 0) {
+      throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
+    }
+    return options.escapeHatch.reason;
+  }
+  if (options.crossTenant === true) {
+    return `deprecated crossTenant: true on entity convention handler ${name}`;
+  }
+  return undefined;
+}
+
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
 // read.ts), letting a client demand a full-table materialisation or trip a
@@ -194,10 +223,10 @@ export function defineEntityWriteHandler(
   // behavior-preserving: ctx.db was already an unfiltered "system"-mode
   // TenantDb for these handlers before the ctx.db cutover.
   //
-  // options.crossTenant mirrors the query-handler branch below: this ONE
-  // write handler reads/writes across every tenant without making the
-  // whole feature r.systemScope().
-  const crossTenant = options?.crossTenant === true;
+  // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+  // query-handler branch below: this ONE write handler reads/writes across
+  // every tenant without making the whole feature r.systemScope().
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -205,7 +234,9 @@ export function defineEntityWriteHandler(
         `entity convention handler for r.systemScope() feature (${name})`,
       );
     }
-    return crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   // The event stream is keyed by the acting user's tenantId (streamTenantFor in
@@ -219,7 +250,7 @@ export function defineEntityWriteHandler(
     id: unknown,
     db: TenantDb,
   ): Promise<SessionUser> => {
-    if (!crossTenant || entity.systemStream) return user;
+    if (crossTenantReason === undefined || entity.systemStream) return user;
     const row = await db.fetchOne<Record<string, unknown>>(table, { id });
     const rowTenantId = row?.["tenantId"];
     if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId) return user;
@@ -234,7 +265,14 @@ export function defineEntityWriteHandler(
       schema = buildInsertSchema(entity);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
-        return executor.create(event.payload as DbRow, event.user, dbFor(ctx), {
+        // A caller-chosen id (deterministic-id idempotent creates) is only
+        // honored for a system-identity caller (jobs/hooks via
+        // createSystemUser) — an HTTP-authenticated end user can never
+        // present that identity, so their payload.id is dropped exactly as
+        // before this field became part of the schema.
+        const { id: _callerId, ...payloadWithoutId } = event.payload as DbRow;
+        const payload = isSystemIdentity(event.user) ? (event.payload as DbRow) : payloadWithoutId;
+        return executor.create(payload, event.user, dbFor(ctx), {
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -288,6 +326,9 @@ export function defineEntityWriteHandler(
       assertUnreachable(verb, "write verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
   return {
     name,
     schema,
@@ -340,21 +381,22 @@ export function defineEntityQueryHandler(
   // useReferenceLookup stays as a fallback (for apps that write custom
   // handlers by hand without this wrapper).
   const hasRefFields = collectReferenceFields(entity).length > 0;
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   // Preference order:
   //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
   //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
   //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
   //     TenantDb for these handlers before that cutover.
-  //  2. options.crossTenant — this ONE handler reads across every tenant
-  //     (e.g. a SystemAdmin-only operator inspector) without making the
-  //     whole feature r.systemScope() — that would drop tenant isolation
-  //     from every OTHER handler the feature registers too. The executor's
-  //     list()/detail() only add a tenant filter when db.mode === "tenant"
-  //     (see event-store-executor.ts), so handing them a "system"-mode
-  //     TenantDb built from the same raw connection is enough to skip it —
-  //     access-control (who may call this handler at all) is unaffected,
-  //     still gated by `options.access`.
+  //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+  //     ONE handler reads across every tenant (e.g. a SystemAdmin-only
+  //     operator inspector) without making the whole feature r.systemScope()
+  //     — that would drop tenant isolation from every OTHER handler the
+  //     feature registers too. The executor's list()/detail() only add a
+  //     tenant filter when db.mode === "tenant" (see event-store-executor.ts),
+  //     so handing them a "system"-mode TenantDb built from the same raw
+  //     connection is enough to skip it — access-control (who may call this
+  //     handler at all) is unaffected, still gated by `options.access`.
   //  3. plain ctx.db — the common case, tenant-filtered.
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -362,7 +404,9 @@ export function defineEntityQueryHandler(
         `entity convention handler for r.systemScope() feature (${entityName}:${verb})`,
       );
     }
-    return options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   switch (verb) {
@@ -418,6 +462,9 @@ export function defineEntityQueryHandler(
       assertUnreachable(verb, "query verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
   return {
     name,
     schema,
@@ -543,7 +590,11 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options: { access: AccessRule; unsafeAllTenants?: boolean },
+  options: {
+    access: AccessRule;
+    unsafeAllTenants?: boolean;
+    escapeHatch?: EscapeHatchDeclaration;
+  },
 ): QueryHandlerDef {
   return {
     name,
@@ -558,6 +609,7 @@ export function defineProjectionQueryHandler(
         options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ), // @wrapper-known semantic-alias
     access: options.access,
+    ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
   };
 }