@cosmicdrift/kumiko-framework 0.266.0 → 0.269.0

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

@@ -0,0 +1,103 @@
+// fw#2858 — a write/query handler's `escapeHatch` also gates ctx.db.unsafeRaw(reason):
+// WITH it the raw query succeeds, WITHOUT it the same handler rejects with access_denied.
+// Real HTTP calls + setupTestStack — never createTestDispatcher. Modelled exactly on
+// escape-hatch.integration.test.ts (fw#2855).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { executeRawQuery } from "../../db/queries/raw-sql";
+import { defineFeature } from "../../engine";
+import { createTestUser, setupTestStack, type TestStack } from "../../stack";
+
+const unsafeRawFeature = defineFeature("unsafe-raw-probe", (r) => {
+  r.writeHandler({
+    name: "write-with-hatch",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    escapeHatch: { reason: "fw#2858 integration test — declared unsafeRaw write" },
+    handler: async (_event, ctx) => {
+      const runner = ctx.db.unsafeRaw("fw#2858 integration test — declared unsafeRaw write");
+      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
+      return { isSuccess: true as const, data: { one: rows[0]?.one } };
+    },
+  });
+
+  r.writeHandler({
+    name: "write-without-hatch",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    handler: async (_event, ctx) => {
+      const runner = ctx.db.unsafeRaw("no escapeHatch declared — must throw before this runs");
+      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
+      return { isSuccess: true as const, data: { one: rows[0]?.one } };
+    },
+  });
+
+  r.queryHandler({
+    name: "query-with-hatch",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    escapeHatch: { reason: "fw#2858 integration test — declared unsafeRaw query" },
+    handler: async (_query, ctx) => {
+      const runner = ctx.db.unsafeRaw("fw#2858 integration test — declared unsafeRaw query");
+      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
+      return { one: rows[0]?.one };
+    },
+  });
+
+  r.queryHandler({
+    name: "query-without-hatch",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    handler: async (_query, ctx) => {
+      const runner = ctx.db.unsafeRaw("no escapeHatch declared — must throw before this runs");
+      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
+      return { one: rows[0]?.one };
+    },
+  });
+});
+
+let stack: TestStack;
+const user = createTestUser({
+  id: 92,
+  tenantId: "11111111-0000-4000-8000-000000000092",
+  roles: ["User"],
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [unsafeRawFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("write/query handler escapeHatch gates ctx.db.unsafeRaw()", () => {
+  test("write WITH escapeHatch: unsafeRaw succeeds", async () => {
+    const result = await stack.http.writeOk<{ one: number }>(
+      "unsafe-raw-probe:write:write-with-hatch",
+      {},
+      user,
+    );
+    expect(result.one).toBe(1);
+  });
+
+  test("write WITHOUT escapeHatch: unsafeRaw fails with access_denied", async () => {
+    const err = await stack.http.writeErr("unsafe-raw-probe:write:write-without-hatch", {}, user);
+    expect(err.code).toBe("access_denied");
+  });
+
+  test("query WITH escapeHatch: unsafeRaw succeeds", async () => {
+    const result = await stack.http.queryOk<{ one: number }>(
+      "unsafe-raw-probe:query:query-with-hatch",
+      {},
+      user,
+    );
+    expect(result.one).toBe(1);
+  });
+
+  test("query WITHOUT escapeHatch: unsafeRaw fails with access_denied", async () => {
+    const err = await stack.http.queryErr("unsafe-raw-probe:query:query-without-hatch", {}, user);
+    expect(err.code).toBe("access_denied");
+  });
+});

package/src/pipeline/active-membership.ts

@@ -76,7 +76,9 @@ async function findMembership(
   return rawMemberships.find((m) => m.tenantId === tenantId);
 }
 
-function resolvePrincipalPlugin(registry: Registry): PrincipalStatusPlugin {
+// Exported so member-reader.ts (ctx.queryAsMember) can reach the registered
+// PrincipalStatusPlugin's resolveProfile without duplicating this lookup.
+export function resolvePrincipalPlugin(registry: Registry): PrincipalStatusPlugin {
   const usages = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS);
   if (usages.length !== 1) {
     throw new InternalError({

package/src/pipeline/dispatch-shared.ts

@@ -16,13 +16,16 @@ import type {
   FetchForWritingArgs,
   HandlerContext,
   JobRunnerRef,
+  MemberReader,
   Registry,
   SessionUser,
   WriteResult,
 } from "../engine/types";
 import type { TenantId } from "../engine/types/identifiers";
 import {
+  AccessDeniedError,
   FeatureDisabledError,
+  FrameworkReasons,
   InternalError,
   VersionConflictError,
   type WriteErrorInfo,
@@ -76,7 +79,12 @@ import {
 } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
-import { createGatedIdentitySwitch, systemIdentitySwitchDenied } from "./system-identity-switch";
+import { createMemberReaderFn } from "./member-reader";
+import {
+  createGatedIdentitySwitch,
+  createGatedMemberReader,
+  systemIdentitySwitchDenied,
+} from "./system-identity-switch";
 import type { TenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Framework/pipeline stays bundled-features-free, so this can't import the
@@ -151,6 +159,8 @@ async function appendDomainEvent(
   tx: DbTx | undefined,
   callerFeature: string | undefined,
 ): Promise<void> {
+  // Sink behind every append surface, so a resolved member stays read-only even via fetchForWriting handles.
+  if (user.origin === "member-resolution") throw memberResolutionReadOnlyDenied();
   const { registry } = ctx;
   const dbSource = resolveDbSource(ctx, tx);
   if (!dbSource) {
@@ -196,6 +206,59 @@ function createSystemScopedDbGuard(
   });
 }
 
+export function memberResolutionReadOnlyDenied(): AccessDeniedError {
+  return new AccessDeniedError({
+    message: "a resolved member principal (ctx.queryAsMember) cannot write — read-only",
+    details: { reason: FrameworkReasons.memberResolutionReadOnly },
+  });
+}
+
+async function denyMemberResolutionWrite(): Promise<never> {
+  throw memberResolutionReadOnlyDenied();
+}
+
+// JobRunnerRef's declared type only carries handleEvent, but callers
+// routinely bracket-access a fuller runner — a Proxy denies ANY property read.
+function denyingJobRunnerProxy(): JobRunnerRef {
+  return new Proxy({} as JobRunnerRef, {
+    get() {
+      throw memberResolutionReadOnlyDenied();
+    },
+  });
+}
+
+// Every write/side-effect surface throws, so "no writeAsMember" holds even
+// if a handler tries ctx.write directly on a resolved member principal.
+function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext {
+  return {
+    ...handlerContext,
+    // `db` itself stays open — same access the member's own HTTP request has;
+    // raw ctx.db writes inside a queried handler are not blocked by this.
+    dbOutsideTransaction: undefined,
+    write: denyMemberResolutionWrite,
+    writeAs: denyMemberResolutionWrite,
+    appendEvent: denyMemberResolutionWrite as AppendEventFn, // @cast-boundary engine-bridge
+    unsafeAppendEvent: denyMemberResolutionWrite,
+    tryAppendEvent: denyMemberResolutionWrite,
+    fetchForWriting: denyMemberResolutionWrite,
+    archiveStream: denyMemberResolutionWrite,
+    restoreStream: denyMemberResolutionWrite,
+    snapshotAggregate: denyMemberResolutionWrite,
+    queryAsMember: denyMemberResolutionWrite,
+    resolveActiveMembership: denyMemberResolutionWrite,
+    scheduleAfterCommit: () => {
+      throw memberResolutionReadOnlyDenied();
+    },
+    // A read as a member gets no system-scope DB, preSave pipeline or file storage.
+    runPreSave: undefined,
+    systemDb: undefined,
+    files: undefined,
+    derivatives: undefined,
+    ...(handlerContext.jobRunner && { jobRunner: denyingJobRunnerProxy() }),
+    ...(handlerContext.notify && { notify: denyMemberResolutionWrite }),
+  };
+}
+
 export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
@@ -211,13 +274,13 @@ 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;
-  // Broader than `escapeHatch` above — a query handler can't reach db.global() but can still opt in here.
-  const allowSystemIdentity =
-    isSystem ||
-    (registry.getWriteHandler(type)?.escapeHatch ?? registry.getQueryHandler(type)?.escapeHatch) !==
-      undefined;
+  // global() writes are write-handler-only; SYSTEM identity switch and unsafeRaw accept write, query or stream escapeHatch.
+  const writeEscapeHatch = registry.getWriteHandler(type)?.escapeHatch;
+  const handlerEscapeHatch =
+    writeEscapeHatch ??
+    registry.getQueryHandler(type)?.escapeHatch ??
+    registry.getStreamHandler(type)?.escapeHatch;
+  const hasIdentitySwitchGrant = isSystem || handlerEscapeHatch !== undefined;
   const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
@@ -226,7 +289,7 @@ export async function buildHandlerContext(
       context.tracer,
       context.meter,
       signal,
-      escapeHatch,
+      { globalWrites: writeEscapeHatch, unsafeRaw: handlerEscapeHatch },
     );
   // Propagate the request's AbortSignal so every TenantDb query throws when
   // the client has disconnected — handlers with many sequential queries skip
@@ -315,17 +378,33 @@ export async function buildHandlerContext(
     : () => createNoopMetricsHandle();
 
   // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
-  // queryAs/writeAs switch identity; SYSTEM needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
+  // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
   const bridgeSink = afterCommitHooks ?? [];
   const scheduleAfterCommit = (hook: AfterCommitHook): void => {
     bridgeSink.push(hook);
   };
-  const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, allowSystemIdentity, {
-    queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-      executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
-    writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-      executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
-  });
+  const identitySwitch = createGatedIdentitySwitch(
+    `handler "${type}"`,
+    user,
+    hasIdentitySwitchGrant,
+    {
+      queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+        executeQuery(ctx, targetType, payload, asUser, tx), // @wrapper-known semantic-alias
+      writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
+        executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
+    },
+  );
+  // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
+  // on first actual use, not on every HandlerContext build.
+  let ungatedMemberReader: MemberReader | undefined;
+  const queryAsMember = createGatedMemberReader(
+    `handler "${type}"`,
+    hasIdentitySwitchGrant,
+    (userId, qn, payload) => {
+      ungatedMemberReader ??= createMemberReaderFn(ctx, user.tenantId, tx);
+      return ungatedMemberReader(userId, qn, payload);
+    },
+  );
   const bridge = {
     query: (targetType: string, payload: unknown) =>
       executeQuery(ctx, targetType, payload, user, tx), // @wrapper-known semantic-alias
@@ -600,10 +679,13 @@ export async function buildHandlerContext(
     // Internally queries memberships as SYSTEM, so it needs the same grant
     // as a SYSTEM queryAs/writeAs (r.systemScope() or escapeHatch).
     resolveActiveMembership: (userId: string, tenantId: TenantId) => {
-      if (!allowSystemIdentity) throw systemIdentitySwitchDenied(`handler "${type}"`);
+      if (!hasIdentitySwitchGrant) throw systemIdentitySwitchDenied(`handler "${type}"`);
       return resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY); // @wrapper-known semantic-alias
     },
 
+    // Needs the same grant as a SYSTEM queryAs.
+    queryAsMember,
+
     // Feature-effective check for in-handler opt-in logic. Scope:
     // **current user's tenant** — for cross-tenant lookups (rare,
     // SysAdmin operations) read effectiveFeatures(otherTenantId) directly.
@@ -688,7 +770,7 @@ export async function buildHandlerContext(
     user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
   const locale = reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
 
-  return {
+  const handlerContext = {
     ...context,
     registry,
     db: exposedDb,
@@ -740,6 +822,11 @@ export async function buildHandlerContext(
     ...(includeDeleted && { includeDeleted: true }),
     ...bridge,
   } as HandlerContext; // @cast-boundary engine-bridge
+
+  // A resolved member principal is read-only by construction.
+  return user.origin === "member-resolution"
+    ? applyMemberResolutionReadOnly(handlerContext)
+    : handlerContext;
 }
 
 // Wrap handler execution in a dispatcher.handler span AND emit the standard
@@ -967,7 +1054,7 @@ export async function enforceRateLimit(
 // hooks run OUTSIDE any request transaction (login is itself the root
 // operation, not a nested call) and read-only — so the TenantDb is
 // scoped as "tenant" and no tx is threaded through. Cross-tenant lookups
-// go through queryAs(otherUser, ...); SYSTEM is always denied (no escapeHatch declaration site here).
+// are denied: queryAs only reaches the claims user itself (no escapeHatch declaration site here).
 function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthClaimsContext {
   const { appContext: context } = ctx;
   const dbSource = resolveDbSource(ctx, undefined);
@@ -984,7 +1071,7 @@ function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthCl
         secrets: context.secrets,
       })
     : undefined;
-  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", false, {
+  const identitySwitch = createGatedIdentitySwitch("r.authClaims hook", user, false, {
     queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
       executeQuery(ctx, qn, payload, asUser), // @wrapper-known semantic-alias
     writeAs: async () => {

package/src/pipeline/dispatch-stream.ts

@@ -7,6 +7,7 @@ import {
   type DispatchContext,
   enforceRateLimit,
   ensureFeatureEnabled,
+  memberResolutionReadOnlyDenied,
   runStreamInstrumented,
 } from "./dispatch-shared";
 
@@ -35,6 +36,12 @@ async function* executeStreamInner(
   const handler = registry.getStreamHandler(type);
   if (!handler) throw new NotFoundError("handler", type);
 
+  // A resolved member principal (ctx.queryAsMember) is read-only — streams
+  // are excluded the same way executeWriteInner excludes writes.
+  if (user.origin === "member-resolution") {
+    throw memberResolutionReadOnlyDenied();
+  }
+
   await ensureFeatureEnabled(ctx, type, user.tenantId);
 
   if (handler.rateLimit !== undefined) {
@@ -96,11 +103,8 @@ async function* executeStreamInner(
     }
   } finally {
     unsubscribeAccessInvalidation?.();
-    // Consumer break / throw — always close the handler generator so its
-    // finally (cleanup) runs (for-await would do this). Do NOT swallow
-    // return() errors — close-time cleanup failures must surface to
-    // runStreamInstrumented (#1543). Skip the await after access-revoke
-    // abandonment (overlapping next+return deadlocks — see above).
+    // Close the generator so cleanup runs; skip awaiting return() after
+    // access-revoke abandonment — overlapping next()+return() can deadlock.
     if (iterator !== undefined && !abandonedForInvalidation) {
       await iterator.return?.(undefined);
     }

package/src/pipeline/dispatch-write.ts

@@ -27,6 +27,7 @@ import {
   CONFIG_WRITE_SET_TYPE,
   checkFeatureEnabled,
   enforceRateLimit,
+  memberResolutionReadOnlyDenied,
   runHandlerInstrumented,
   TENANT_TIMEZONE_CONFIG_KEY,
 } from "./dispatch-shared";
@@ -327,6 +328,12 @@ async function executeWriteInner(
   const handler = registry.getWriteHandler(type);
   if (!handler) return writeFailure(new NotFoundError("handler", type));
 
+  // Defense in depth — covers runBatch and a spread-copied user that kept
+  // `origin`, beyond buildHandlerContext's own ctx.write replacement.
+  if (user.origin === "member-resolution") {
+    return writeFailure(memberResolutionReadOnlyDenied());
+  }
+
   // Feature-toggle gate: disabled handlers must short-circuit before any
   // rate-limit/access/validation work — see executeQueryInner comment.
   const disabledErr = await checkFeatureEnabled(ctx, type, user.tenantId);

package/src/pipeline/dispatcher-utils.ts

@@ -49,6 +49,7 @@ export function dispatcherSpanAttributes(
     "kumiko.tenant_id": user.tenantId,
   };
   if (feature) attrs["kumiko.feature"] = feature;
+  if (user.origin) attrs["kumiko.user_origin"] = user.origin;
   return attrs;
 }
 

package/src/pipeline/dispatcher.ts

@@ -6,7 +6,9 @@ import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extensio
 import type {
   ActiveMembershipResult,
   AppContext,
+  DispatchWriteRef,
   JobRunnerRef,
+  MemberReader,
   Registry,
   SessionUser,
   WriteResult,
@@ -23,6 +25,7 @@ import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import { createMemberReaderFn } from "./member-reader";
 import { createTenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
@@ -97,8 +100,21 @@ export type Dispatcher = {
   // Membership check for interactive sign-in paths (login, MFA completion,
   // tenant switch) — single resolve implementation so callers can't independently drift.
   resolveActiveMembership(userId: string, tenantId: TenantId): Promise<ActiveMembershipResult>;
+  // Trusted server surface, ungated like resolveActiveMembership.
+  // Handler/hook ctx.queryAsMember uses buildHandlerContext's own gated reader instead.
+  createMemberReader(tenantId: TenantId): MemberReader;
 };
 
+// Adapts Dispatcher's (type, payload, user) call shape to DispatchWriteRef's
+// (user, qn, payload) — JobRunner.attachDispatcher needs the latter.
+export function dispatcherToWriteRef(dispatcher: Dispatcher): DispatchWriteRef {
+  return {
+    write: (user, qn, payload) => dispatcher.write(qn, payload, user),
+    queryAs: (user, qn, payload) => dispatcher.query(qn, payload, user),
+    createMemberReader: (tenantId) => dispatcher.createMemberReader(tenantId),
+  };
+}
+
 export function createDispatcher(
   registry: Registry,
   context: AppContext,
@@ -164,5 +180,7 @@ export function createDispatcher(
 
     resolveActiveMembership: (userId, tenantId) =>
       resolveActiveMembershipFn(ctx, userId, tenantId, INTERACTIVE_SIGN_IN_POLICY),
+
+    createMemberReader: (tenantId) => createMemberReaderFn(ctx, tenantId),
   };
 }

package/src/pipeline/index.ts

@@ -2,7 +2,7 @@ export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver";
 export { resolveAuthClaims } from "./auth-claims-resolver";
 export { createCascadeDeleteHook } from "./cascade-handler";
 export type { Dispatcher } from "./dispatcher";
-export { createDispatcher } from "./dispatcher";
+export { createDispatcher, dispatcherToWriteRef } from "./dispatcher";
 export type { DistributedLock } from "./distributed-lock";
 export { createDistributedLock } from "./distributed-lock";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache";

package/src/pipeline/member-reader.ts

@@ -0,0 +1,108 @@
+// ctx.queryAsMember — reads a query handler as a stored tenant member. The
+// resolved SessionUser never leaves this module.
+
+import type { DbConnection, DbTx } from "../db/connection";
+import { buildSessionRoles } from "../engine/membership-roles";
+import type { MemberReader, SessionUser } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types";
+import type { TenantId } from "../engine/types/identifiers";
+import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors";
+import {
+  type ActiveMembershipPolicy,
+  resolveActiveMembershipFn,
+  resolvePrincipalPlugin,
+} from "./active-membership";
+import { executeQuery } from "./dispatch-query";
+import { type DispatchContext, resolveAuthClaimsFn, resolveDbSource } from "./dispatch-shared";
+import { isSystemIdentity } from "./system-identity-switch";
+
+// Stricter than interactive sign-in: an unknown principal or a tenant
+// mid-teardown must not resolve — there is no user-facing flow to recover.
+export const BACKGROUND_READ_POLICY: ActiveMembershipPolicy = {
+  allowPendingDestruction: false,
+  allowUnknownPrincipal: false,
+};
+
+// Generic on purpose — details never carry which check failed, so a caller
+// can't probe another user's membership state via the error shape.
+function memberResolutionDenied(): AccessDeniedError {
+  return new AccessDeniedError({
+    message: "not permitted to read as this member",
+    details: { reason: FrameworkReasons.memberResolutionDenied },
+  });
+}
+
+// Membership/principal/lifecycle resolve on the root connection, outside the
+// caller's tx — only the target query runs inside it (via the `tx` argument).
+async function resolveMember(
+  ctx: DispatchContext,
+  tenantId: TenantId,
+  userId: string,
+): Promise<SessionUser> {
+  const membership = await resolveActiveMembershipFn(ctx, userId, tenantId, BACKGROUND_READ_POLICY);
+  if (membership.kind === "rejected") throw memberResolutionDenied();
+
+  const principalPlugin = resolvePrincipalPlugin(ctx.registry);
+  const dbSource = resolveDbSource(ctx, undefined);
+  if (!dbSource) {
+    throw new InternalError({
+      message: "ctx.queryAsMember requires a database connection — none is configured.",
+    });
+  }
+  // resolveDbSource(ctx, undefined) never returns a tx, only AppContext.db.
+  const db = dbSource as DbConnection; // @cast-boundary db-operator
+
+  const profile = await principalPlugin.resolveProfile(userId, { db });
+  if (!profile) throw memberResolutionDenied();
+
+  // buildSessionRoles runs stripForbiddenMembershipRoles on the membership half (rebuild-resurrected roles).
+  const roles = buildSessionRoles(profile.globalRoles, membership.membership.roles);
+  const base: SessionUser = {
+    id: userId,
+    tenantId,
+    roles,
+    ...(profile.timezone !== undefined && { timezone: profile.timezone }),
+    ...(profile.locale !== undefined && { locale: profile.locale }),
+    origin: "member-resolution",
+  };
+  // Defense in depth: buildSessionRoles strips forbidden roles only from the
+  // membership half, not globalRoles — a resolved principal must never be SYSTEM.
+  if (isSystemIdentity(base)) throw memberResolutionDenied();
+
+  const claims = await resolveAuthClaimsFn(ctx, base);
+  return Object.keys(claims).length > 0 ? { ...base, claims } : base;
+}
+
+// One reader per handler invocation (shared with its hooks) or job run; a
+// nested dispatch builds its own reader with its own cache.
+export function createMemberReaderFn(
+  ctx: DispatchContext,
+  tenantId: TenantId,
+  tx?: DbTx,
+): MemberReader {
+  if (tenantId === SYSTEM_TENANT_ID) {
+    throw new InternalError({
+      message: "queryAsMember needs a tenant-scoped context — got SYSTEM_TENANT_ID.",
+    });
+  }
+
+  // Only successful resolutions are cached — a rejected/failed resolution
+  // deletes its own entry so a transient error can't poison the rest of the run.
+  const cache = new Map<string, Promise<SessionUser>>();
+
+  function resolve(userId: string): Promise<SessionUser> {
+    const cached = cache.get(userId);
+    if (cached) return cached;
+    const pending = resolveMember(ctx, tenantId, userId);
+    cache.set(userId, pending);
+    pending.catch(() => {
+      cache.delete(userId);
+    });
+    return pending;
+  }
+
+  return async (userId, qn, payload) => {
+    const user = await resolve(userId);
+    return executeQuery(ctx, qn, payload, user, tx);
+  };
+}