@cosmicdrift/kumiko-framework 0.265.0 → 0.268.0

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

@@ -1,38 +1,88 @@
-import type { AccessRule, FeatureDefinition, QueryHandlerDef, WriteHandlerDef } from "../types";
+import type {
+  AccessRule,
+  FeatureDefinition,
+  OwnershipMap,
+  OwnershipRule,
+  QueryHandlerDef,
+  WriteHandlerDef,
+} from "../types";
 import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
-import { getZodObjectShape } from "./zod-shape";
+import { collectZodObjectKeys } 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.
+// sense the openToAll personal-data check 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> {
+function isCallerIdRuleOn(rule: OwnershipRule, column: string): boolean {
+  if (rule === "all" || rule.kind !== "from") return false;
+  return rule.refKind === "user" && rule.refPath === "id" && rule.column === column;
+}
+
+// The executor checks access.write against every created/updated row; one "all" role
+// or an empty map (= public) lets a caller write rows owned by someone else.
+function writeMapBindsRowsToCaller(
+  writeMap: OwnershipMap | undefined,
+  ownerColumn: string,
+): boolean {
+  const rules = Object.values(writeMap ?? {});
+  return rules.length > 0 && rules.every((rule) => isCallerIdRuleOn(rule, ownerColumn));
+}
+
+const ROW_ID_COLUMN = "id";
+
+// A self/record-owned field's subject is the row itself, so only from("user:id", "id")
+// makes that row the caller — on any other entity "self" names a third party.
+function callerBindingColumn(annot: ResolvedPiiFlags): string | undefined {
+  if (annot.userOwned) return annot.userOwned.ownerField;
+  if (annot.pii || annot.recordOwned) return ROW_ID_COLUMN;
+  return undefined;
+}
+
+function isOwnerBoundField(field: unknown, entity: EntityDefinition): boolean {
+  const column = callerBindingColumn(field as ResolvedPiiFlags); // @cast-boundary schema-walk — see pii-retention.ts
+  return column !== undefined && writeMapBindsRowsToCaller(entity.access?.write, column);
+}
+
+function personalFieldNames(
+  entity: EntityDefinition,
+  honorOwnerBinding: boolean,
+): ReadonlySet<string> {
   const names = new Set<string>();
   for (const [fieldName, field] of Object.entries(entity.fields)) {
-    if (isPersonalDataField(field)) names.add(fieldName);
+    const exempt = honorOwnerBinding && isOwnerBoundField(field, entity);
+    if (isPersonalDataField(field) && !exempt) names.add(fieldName);
   }
   return names;
 }
 
+// escapeHatch and r.systemScope() can write around the entity's write map
+// (db.global(), systemDb, SYSTEM identity), so the map no longer vouches for the row.
+function canWriteAroundExecutor(feature: FeatureDefinition, handler: WriteHandlerDef): boolean {
+  return handler.escapeHatch !== undefined || feature.systemScope;
+}
+
+// Owner binding counts only for a handler mapped to one entity.
 function candidatePersonalFieldNames(
   feature: FeatureDefinition,
   handlerName: string,
+  handler: WriteHandlerDef,
 ): ReadonlySet<string> {
   const mappedEntityName = feature.handlerEntityMappings?.[handlerName];
   const entities = feature.entities ?? {};
   if (mappedEntityName) {
     const entity = entities[mappedEntityName];
-    return entity ? personalFieldNames(entity) : new Set();
+    const honorOwnerBinding = !canWriteAroundExecutor(feature, handler);
+    return entity ? personalFieldNames(entity, honorOwnerBinding) : new Set();
   }
   const names = new Set<string>();
   for (const entity of Object.values(entities)) {
-    for (const name of personalFieldNames(entity)) names.add(name);
+    for (const name of personalFieldNames(entity, false)) names.add(name);
   }
   return names;
 }
@@ -52,8 +102,16 @@ function hasOpenToAll(access: AccessRule): boolean {
   return "openToAll" in access;
 }
 
-function hasPublicIntake(access: AccessRule): boolean {
-  return "publicIntake" in access && access.publicIntake === true;
+// Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
+function declaredPersonalData(access: AccessRule): unknown {
+  if (!("openToAll" in access)) return undefined;
+  const openToAll: unknown = access.openToAll;
+  if (typeof openToAll !== "object" || openToAll === null) return undefined;
+  return "personalData" in openToAll ? openToAll.personalData : undefined;
+}
+
+function declaresTenantMembersPersonalData(access: AccessRule): boolean {
+  return declaredPersonalData(access) === "tenant-members";
 }
 
 function validateOpenToAllReason(
@@ -86,19 +144,32 @@ function validateEscapeHatchReason(
   );
 }
 
-function validatePublicIntakeOnlyOnWrite(
+function validatePersonalDataOnlyOnWrite(
   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;
+  // skip: write handlers may declare personalData, or it wasn't declared here
+  if (kind === "write" || declaredPersonalData(access) === undefined) 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).",
+      "openToAll.personalData — it only applies to write handlers, whose input is " +
+      "checked for personal-data fields.",
+  );
+}
+
+function validatePersonalDataValue(
+  feature: FeatureDefinition,
+  handlerName: string,
+  access: AccessRule,
+): void {
+  const declared = declaredPersonalData(access);
+  // skip: nothing declared, or the one supported value
+  if (declared === undefined || declared === "tenant-members") return;
+  throw new Error(
+    `[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+      `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`,
   );
 }
 
@@ -108,20 +179,22 @@ function validateOpenToAllPersonalData(
   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 openToAll declared, or the handler declares tenant members may write personal data
+  if (!hasOpenToAll(access) || declaresTenantMembersPersonalData(access)) return;
+  const inputKeys = collectZodObjectKeys(handler.schema);
+  const personalNames = candidatePersonalFieldNames(feature, handlerName, handler);
+  const offending = [...inputKeys].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.",
+      `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} that are ` +
+      "not bound to the caller. Choose one: (1) bind rows to the caller — every role in the " +
+      'entity\'s access.write is from("user:id", "<ownerField>") for a personal: { of: "<ownerField>" } ' +
+      'field, or from("user:id", "id") for a personal: "self" field, with no escapeHatch on the ' +
+      "handler and no r.systemScope() on its feature; (2) restrict access to roles; (3) declare " +
+      '{ openToAll: { reason: "<why any signed-in tenant member may write this personal data>", ' +
+      'personalData: "tenant-members" } }.',
   );
 }
 
@@ -129,15 +202,16 @@ export function validateAccessDeclarations(feature: FeatureDefinition): void {
   for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
     validateOpenToAllReason(feature, "write", handlerName, handler.access);
     validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
+    validatePersonalDataValue(feature, handlerName, handler.access);
     validateOpenToAllPersonalData(feature, handlerName, handler);
   }
   for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
     validateOpenToAllReason(feature, "query", handlerName, handler.access);
     validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
-    validatePublicIntakeOnlyOnWrite(feature, "query", handlerName, handler.access);
+    validatePersonalDataOnlyOnWrite(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);
+    validatePersonalDataOnlyOnWrite(feature, "stream", handlerName, handler.access);
   }
 }

package/src/engine/boot-validator/global-tenancy.ts

@@ -0,0 +1,17 @@
+import type { FeatureDefinition } from "../types";
+
+// Boot-time twin of event-store-executor-context.ts's buildExecutorContext check —
+// surfaces the systemStream invariant once across all features before any dispatch.
+export function validateGlobalTenancyEntities(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      if (entity.tenancy === "global" && entity.systemStream !== true) {
+        throw new Error(
+          `Feature "${feature.name}" entity "${entityName}": tenancy: "global" entities must ` +
+            "also declare systemStream: true — a global aggregate's event stream must live on " +
+            "the system tenant, not the creating tenant's.",
+        );
+      }
+    }
+  }
+}

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

@@ -36,6 +36,7 @@ import {
 } from "./entity-handler";
 import { validateEntityListScreens } from "./entity-list-screens";
 import { validateGdprStoragePersistence } from "./gdpr-storage";
+import { validateGlobalTenancyEntities } from "./global-tenancy";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import {
   collectKnownRoles,
@@ -238,6 +239,7 @@ export function validateBoot(
   validateRelatedListSectionQueries(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
+  validateGlobalTenancyEntities(features);
   validateFeatureBootChecks(features);
 
   if (hasEncryptedFields) {

package/src/engine/boot-validator/zod-shape.ts

@@ -1,4 +1,23 @@
-import { ZodArray, ZodDefault, ZodNullable, ZodObject, ZodOptional, type ZodType } from "zod";
+import {
+  ZodArray,
+  ZodCatch,
+  ZodDefault,
+  ZodIntersection,
+  ZodLazy,
+  ZodNonOptional,
+  ZodNullable,
+  ZodObject,
+  ZodOptional,
+  ZodPipe,
+  ZodPrefault,
+  ZodReadonly,
+  ZodRecord,
+  ZodTuple,
+  type ZodType,
+  ZodUnion,
+  ZodXor,
+} from "zod";
+import type { $ZodType } from "zod/v4/core";
 
 // Drills through wrapper types (.nullable(), .optional(), .default()) a
 // handler's schema may use around its actual object/array shape — e.g. a
@@ -49,3 +68,75 @@ export function getZodRowShape(schema: ZodType | undefined): Record<string, ZodT
     ? getZodObjectShape(rowsArray.element as ZodType)
     : undefined;
 }
+
+type SingleInnerSchema =
+  | ZodOptional
+  | ZodNullable
+  | ZodDefault
+  | ZodPrefault
+  | ZodNonOptional
+  | ZodCatch
+  | ZodReadonly
+  | ZodLazy;
+
+const SINGLE_INNER_SCHEMA_CLASSES = [
+  ZodOptional,
+  ZodNullable,
+  ZodDefault,
+  ZodPrefault,
+  ZodNonOptional,
+  ZodCatch,
+  ZodReadonly,
+  ZodLazy,
+] as const;
+
+function isSingleInnerSchema(schema: $ZodType): schema is SingleInnerSchema {
+  return SINGLE_INNER_SCHEMA_CLASSES.some((schemaClass) => schema instanceof schemaClass);
+}
+
+function combinatorChildSchemas(schema: $ZodType): readonly $ZodType[] {
+  if (schema instanceof ZodUnion || schema instanceof ZodXor) return schema.options;
+  if (schema instanceof ZodIntersection) return [schema.def.left, schema.def.right];
+  // z.preprocess() carries the accepted shape on `out`, .transform() on `in`.
+  if (schema instanceof ZodPipe) return [schema.in, schema.out];
+  return [];
+}
+
+function childSchemas(schema: $ZodType): readonly $ZodType[] {
+  if (schema instanceof ZodObject) return Object.values(schema.shape);
+  if (schema instanceof ZodArray) return [schema.element];
+  if (schema instanceof ZodRecord) return [schema.valueType];
+  if (schema instanceof ZodTuple) {
+    const { items, rest } = schema.def;
+    return rest ? [...items, rest] : items;
+  }
+  if (isSingleInnerSchema(schema)) return [schema.unwrap()];
+  return combinatorChildSchemas(schema);
+}
+
+// A z.lazy() getter that builds a fresh schema per call never revisits a node.
+const MAX_WALKED_SCHEMAS = 10_000;
+
+// Object keys at any depth, so a field nested in an intersection, union or an
+// update's `changes` object is found too.
+export function collectZodObjectKeys(schema: $ZodType | undefined): ReadonlySet<string> {
+  const keys = new Set<string>();
+  if (schema === undefined) return keys;
+  const visited = new Set<$ZodType>();
+  const pending: $ZodType[] = [schema];
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    if (visited.has(next)) continue;
+    if (visited.size >= MAX_WALKED_SCHEMAS) {
+      throw new Error(
+        `collectZodObjectKeys: schema has more than ${MAX_WALKED_SCHEMAS} nodes — ` +
+          "a z.lazy() getter probably returns a new schema on every call; hoist it into a constant.",
+      );
+    }
+    visited.add(next);
+    if (next instanceof ZodObject) {
+      for (const key of Object.keys(next.shape)) keys.add(key);
+    }
+    pending.push(...childSchemas(next));
+  }
+  return keys;
+}

package/src/engine/feature-ast/__tests__/read-optional-access-rule.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { readOptionalAccessRule } from "../extractors/hooks";
+
+describe("readOptionalAccessRule — openToAll.personalData", () => {
+  test("keeps personalData: tenant-members on the object form", () => {
+    expect(
+      readOptionalAccessRule({
+        openToAll: { reason: "members edit their team roster", personalData: "tenant-members" },
+      }),
+    ).toEqual({
+      openToAll: { reason: "members edit their team roster", personalData: "tenant-members" },
+    });
+  });
+
+  test("drops an unknown personalData value", () => {
+    expect(
+      readOptionalAccessRule({
+        openToAll: { reason: "signup", personalData: "public-intake" },
+      }),
+    ).toEqual({ openToAll: { reason: "signup" } });
+  });
+
+  test("the deprecated openToAll: true form carries no personalData", () => {
+    expect(readOptionalAccessRule({ openToAll: true, personalData: "tenant-members" })).toEqual({
+      openToAll: true,
+    });
+  });
+});

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

@@ -42,12 +42,16 @@ 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, ...publicIntake };
+    return { openToAll: true };
   }
-  if (isPlainObject(value["openToAll"]) && typeof value["openToAll"]["reason"] === "string") {
-    return { openToAll: { reason: value["openToAll"]["reason"] }, ...publicIntake };
+  const openToAll = value["openToAll"];
+  if (isPlainObject(openToAll) && typeof openToAll["reason"] === "string") {
+    const personalData =
+      openToAll["personalData"] === "tenant-members"
+        ? { personalData: "tenant-members" as const }
+        : {};
+    return { openToAll: { reason: openToAll["reason"], ...personalData } };
   }
   return undefined;
 }

package/src/engine/feature-ui-extensions.ts

@@ -1,5 +1,5 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
-import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
+import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { LifecycleHookTypes } from "./constants";
 import type { FeatureBuilderState } from "./feature-builder-state";
 import { resolveName } from "./handler-helpers";
@@ -143,7 +143,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       const wrapped: LifecycleHookFn | ValidationHookFn =
         type === "validation"
           ? fn
-          : bindHookIdentitySwitchGrant(fn as LifecycleHookFn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
+          : bindHookEscapeHatchGrant(fn as LifecycleHookFn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
 
       // Entity-wide target ("all write/query handlers of this entity") —
       // replaces the old r.entityHook(type, entity, fn).

package/src/engine/index.ts

@@ -4,6 +4,7 @@ export { hasAccess } from "./access";
 export {
   isPrincipalStatusPlugin,
   isTenantLifecycleStatusPlugin,
+  type PrincipalProfile,
   type PrincipalStatus,
   type PrincipalStatusPlugin,
   TENANT_TEARDOWN_STATUSES,
@@ -410,6 +411,7 @@ export type {
   ListSortSpec,
   LongTextFindability,
   ManyToManyRelation,
+  MemberReader,
   MetricNavigate,
   MetricSpec,
   MspErrorMode,
@@ -432,6 +434,7 @@ export type {
   OnDeleteStrategy,
   OpenToAllAccessRule,
   OpenToAllDeclaration,
+  OpenToAllPersonalData,
   ParentRefDef,
   PersonalAnnotations,
   PersonalAnnotationsLongText,
@@ -477,6 +480,7 @@ export type {
   SecretsEditSection,
   SelectFieldDef,
   SessionUser,
+  SessionUserOrigin,
   StreamHandlerDef,
   StreamHandlerFn,
   Subscribe,

package/src/engine/registry-validate.ts

@@ -1,5 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
-import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
+import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
   RegistryState,
@@ -126,10 +126,10 @@ export function applyExtensionUsages(state: RegistryState): void {
     // RegistrarExtensionRegistration and use that here.
     const extOwner = "*";
     // Extensions have no declaration site for escapeHatch, so SYSTEM is always denied
-    // (system-identity-switch.ts) — bindHookIdentitySwitchGrant(..., undefined) below.
+    // (system-identity-switch.ts) — bindHookEscapeHatchGrant(..., undefined) below.
     if (ext.hooks) {
       if (ext.hooks.postSave) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.postSave,
           `postSave hook of extension "${usage.extensionName}"`,
           undefined,
@@ -143,7 +143,7 @@ export function applyExtensionUsages(state: RegistryState): void {
         state.entityPostSaveHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.preDelete) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.preDelete,
           `preDelete hook of extension "${usage.extensionName}"`,
           undefined,
@@ -157,7 +157,7 @@ export function applyExtensionUsages(state: RegistryState): void {
         state.entityPreDeleteHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.postDelete) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.postDelete,
           `postDelete hook of extension "${usage.extensionName}"`,
           undefined,
@@ -172,7 +172,7 @@ export function applyExtensionUsages(state: RegistryState): void {
       }
       // preSave on extensions: store as handler hook for all CRUD handlers of this entity
       if (ext.hooks.preSave) {
-        const wrapped = bindHookIdentitySwitchGrant(
+        const wrapped = bindHookEscapeHatchGrant(
           ext.hooks.preSave,
           `preSave hook of extension "${usage.extensionName}"`,
           undefined,

package/src/engine/types/index.ts

@@ -171,6 +171,7 @@ export type {
   HandlerRef,
   JobContext,
   JobRunnerRef,
+  MemberReader,
   NameOrRef,
   NotifyFactory,
   NotifyFn,
@@ -178,6 +179,7 @@ export type {
   NotifyPriority,
   OpenToAllAccessRule,
   OpenToAllDeclaration,
+  OpenToAllPersonalData,
   QualifiedEventName,
   QueryEvent,
   QueryHandlerDef,
@@ -185,6 +187,7 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  SessionUserOrigin,
   StreamHandlerDef,
   StreamHandlerFn,
   TryAppendEventFn,

package/src/entrypoint/index.ts

@@ -38,7 +38,7 @@ import { buildServer, withFileProviderResolver } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
-import type { AppContext, DispatchWriteRef, JobRunIn, Registry, RunIn } from "../engine/types";
+import type { AppContext, JobRunIn, Registry, RunIn } from "../engine/types";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner";
 import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
@@ -47,6 +47,7 @@ import type { ObservabilityOptions, ObservabilityProvider } from "../observabili
 import { createNoopProvider } from "../observability";
 import type { EventDedup, EventDispatcher } from "../pipeline";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher";
+import { dispatcherToWriteRef } from "../pipeline/dispatcher";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
 
 // Shared fields across all three modes. A caller that swaps between
@@ -206,18 +207,6 @@ function contextWithObservability(
   };
 }
 
-// Adapts the command-dispatcher's positional (type, payload, user) calls to
-// DispatchWriteRef's (user, qn, payload) shape — JobContext.write/queryAs
-// pass identity explicitly per call (boot-time singleton), while Dispatcher
-// takes it last (request-scoped closure caller). Same underlying pipeline,
-// different argument order.
-function dispatcherToWriteRef(dispatcher: Dispatcher): DispatchWriteRef {
-  return {
-    write: (user, qn, payload) => dispatcher.write(qn, payload, user),
-    queryAs: (user, qn, payload) => dispatcher.query(qn, payload, user),
-  };
-}
-
 // buildApiServer shapes ServerOptions from API-mode caller-options.
 // AllInOneEntrypointOptions extends ApiEntrypointOptions, so structural
 // subtyping makes the all-in-one path a valid caller without an explicit

package/src/errors/i18n/de.yaml

@@ -97,6 +97,26 @@ system_identity_switch_denied:
     (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
     oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
 
+member_resolution_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` konnte für `userId`
+    keine aktive Mitgliedschaft im Tenant des Aufrufers auflösen (kein
+    Mitglied, Principal gesperrt, oder der Tenant befindet sich im Teardown).
+    Bewusst generisch — `details` verrät nie, welche Prüfung fehlgeschlagen ist.
+
+member_resolution_read_only:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein über `ctx.queryAsMember` erreichter Query-Handler
+    hat versucht zu schreiben (`ctx.write`/`writeAs`/`appendEvent`/
+    `jobRunner`/...). Aufgelöste Member-Principals sind nur lesend — es gibt
+    kein `writeAsMember`.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -94,6 +94,25 @@ system_identity_switch_denied:
     (or on the `r.hook(...)` call, if the switch happens inside a hook), or
     move the logic into an `r.systemScope()` feature or a job.
 
+member_resolution_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: `ctx.queryAsMember(userId, ...)` could not resolve an
+    active membership for `userId` in the caller's tenant (not a member,
+    principal blocked, or the tenant is in teardown). Deliberately generic —
+    `details` never says which check failed.
+
+member_resolution_read_only:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a query handler reached via `ctx.queryAsMember` tried
+    to write (`ctx.write`/`writeAs`/`appendEvent`/`jobRunner`/...). Resolved
+    member principals are read-only — there is no `writeAsMember`.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -42,6 +42,14 @@ export const FrameworkReasons = {
   // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
   // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
   systemIdentitySwitchDenied: "system_identity_switch_denied",
+
+  // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
+  // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
+  memberResolutionDenied: "member_resolution_denied",
+
+  // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
+  // write — a resolved member principal is read-only by construction.
+  memberResolutionReadOnly: "member_resolution_read_only",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/jobs/job-runner.ts

@@ -10,6 +10,7 @@ import {
   type DispatchWriteRef,
   type JobContext,
   type JobRunIn,
+  type MemberReader,
   type Registry,
   type SessionUser,
   SYSTEM_TENANT_ID,
@@ -552,6 +553,9 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             tenantId,
           })
         : context.derivatives;
+    // Per-job-run reader, created lazily on queryAsMember's first call and
+    // cached for the rest of this run.
+    let memberReader: MemberReader | undefined;
     const jobContext: JobContext = {
       ...context,
       // Same union as configDb above — job runners are always constructed
@@ -597,6 +601,16 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         }
         return dispatchWriteRef.queryAs(user, qn, payload);
       },
+      queryAsMember: (userId: string, qn: string, payload: unknown) => {
+        if (!dispatchWriteRef) {
+          throw new Error(
+            "JobContext.queryAsMember called before dispatcher attached — call attachDispatcher() first",
+          );
+        }
+        // Lazy per-run reader, mirroring the handler-context reader.
+        memberReader ??= dispatchWriteRef.createMemberReader(tenantId);
+        return memberReader(userId, qn, payload);
+      },
     };
 
     await options.onJobStart?.(jobName, jobId, meta);