@cosmicdrift/kumiko-framework 0.266.0 → 0.268.0

package/src/db/table-builder.ts

@@ -29,6 +29,7 @@ import {
   moneyAmount,
   table as pgTable,
   plainDate,
+  type SchemaTable,
   SQL_EXPR_BRAND,
   type SqlExpression,
   serial,
@@ -505,6 +506,32 @@ function stampGlobalTenancyMeta<E extends EntityDefinition>(
   };
 }
 
+/**
+ * Stamps `tenancy: "global"` onto a `table()`/SchemaTable's meta in place.
+ * Throws if the table has a `tenant_id` column or no EntityTableMeta to stamp.
+ */
+export function declareGlobalTenancy<T extends SchemaTable>(table: T): T & TenancyBrand<"global"> {
+  const meta = (table as unknown as Record<symbol, EntityTableMeta | undefined>)[
+    KUMIKO_META_SYMBOL
+  ];
+  if (!meta) {
+    throw new Error("declareGlobalTenancy(): table has no EntityTableMeta to stamp.");
+  }
+  if (meta.columns.some((c) => c.name === "tenant_id")) {
+    throw new Error(
+      `declareGlobalTenancy("${meta.tableName}"): tables with a "tenant_id" column cannot be ` +
+        'declared tenancy: "global" — a global table\'s rows carry the system tenant, not a ' +
+        "per-row tenant identity.",
+    );
+  }
+  (table as unknown as Record<symbol, EntityTableMeta>)[KUMIKO_META_SYMBOL] = {
+    ...meta,
+    tenancy: "global",
+  };
+  // @cast-boundary type-brand — TenancyBrand<"global"> is a phantom marker with no runtime representation.
+  return table as T & TenancyBrand<"global">;
+}
+
 export function buildEntityTable<E extends EntityDefinition>(
   entityName: string,
   entity: E,

package/src/db/tenant-db.ts

@@ -137,17 +137,48 @@ function tableNameOf(table: Table | EntityTableMeta): string {
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
 }
 
+// A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
+function hasGrant(decl: EscapeHatchDeclaration | undefined): boolean {
+  return decl !== undefined && decl.reason.trim().length > 0;
+}
+
+function isForeignTenantId(tenantIdValue: unknown): boolean {
+  return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}
+
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
 // or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.
-function hasTenantColumn(table: Table): boolean {
+function hasTenantColumn(table: Table | EntityTableMeta): boolean {
   const meta = asEntityTableMeta(table);
   if (meta) return meta.columns.some((c) => c.name === "tenant_id");
   return (table as Record<string, unknown>)["tenantId"] !== undefined;
 }
 
+// Grants for TenantDb's two escape hatches: db.global()'s write methods
+// (write-handler-only) and ctx.db.unsafeRaw() (handler or hook, re-granted per hook).
+export type TenantDbGrants = {
+  readonly globalWrites?: EscapeHatchDeclaration;
+  readonly unsafeRaw?: EscapeHatchDeclaration;
+};
+
+const unsafeRawRebinders = new WeakMap<
+  TenantDb,
+  (grant: EscapeHatchDeclaration | undefined) => TenantDb
+>();
+
+// Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
+// createTenantDb pass through unchanged, without touching any property (ctx.db may be a throwing Proxy).
+export function withUnsafeRawGrant(
+  tenantDb: TenantDb,
+  grant: EscapeHatchDeclaration | undefined,
+): TenantDb {
+  const rebind = unsafeRawRebinders.get(tenantDb);
+  return rebind ? rebind(grant) : tenantDb;
+}
+
 export function createTenantDb(
   db: DbRunner,
   tenantId: TenantId,
@@ -155,8 +186,7 @@ export function createTenantDb(
   tracer?: Tracer,
   meter?: Meter,
   signal?: AbortSignal,
-  // Gates db.global(table)'s write methods; write-path-only (see dispatch-shared.ts buildHandlerContext).
-  escapeHatch?: EscapeHatchDeclaration,
+  grants?: TenantDbGrants,
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
 
@@ -215,7 +245,7 @@ export function createTenantDb(
   // (e.g. exclude SYSTEM reference rows at the DB instead of post-filtering
   // after a limit). Values outside the scope are dropped; if nothing valid
   // remains, the full enforced scope applies — widening is never possible.
-  function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
+  function readWhere(table: Table | EntityTableMeta, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
     const allowed = [tenantId, SYSTEM_TENANT_ID];
     const requested = where?.["tenantId"];
@@ -242,7 +272,7 @@ export function createTenantDb(
   }
 
   function missingEscapeHatch(table: Table | EntityTableMeta): AccessDeniedError | undefined {
-    if (escapeHatch && escapeHatch.reason.trim().length > 0) return undefined;
+    if (hasGrant(grants?.globalWrites)) return undefined;
     return new AccessDeniedError({
       message:
         `db.global(${tableNameOf(table)}): write rejected — declare ` +
@@ -251,6 +281,15 @@ export function createTenantDb(
     });
   }
 
+  function foreignTenantOnGlobalWrite(
+    table: Table | EntityTableMeta,
+    tenantIdValue: unknown,
+    message: string = `db.global(${tableNameOf(table)}): tenantId "${String(tenantIdValue)}" is not SYSTEM_TENANT_ID — a "global" table's rows must carry the system tenant, not an arbitrary tenant's id.`,
+  ): AccessDeniedError | undefined {
+    if (!isForeignTenantId(tenantIdValue)) return undefined;
+    return new AccessDeniedError({ message });
+  }
+
   function globalTable<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
     table: TTable,
   ): GlobalTableDb<TTable> {
@@ -273,7 +312,8 @@ export function createTenantDb(
       insertOne<T = Record<string, unknown>>(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
         if (denied) return Promise.reject(denied);
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
       },
@@ -281,7 +321,8 @@ export function createTenantDb(
         set: Record<string, unknown>,
         where: WhereObject,
       ): Promise<readonly T[]> {
-        const denied = missingEscapeHatch(table);
+        const denied =
+          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -308,14 +349,28 @@ export function createTenantDb(
     } as GlobalTableDb<TTable>;
   }
 
-  return {
+  const tenantDb: TenantDb = {
     tenantId,
     mode,
     raw: db,
     global: globalTable,
 
+    unsafeRaw(reason: string): DbRunner {
+      if (reason.trim().length === 0) {
+        throw new Error("unsafeRaw requires a non-empty reason");
+      }
+      if (!hasGrant(grants?.unsafeRaw)) {
+        throw new AccessDeniedError({
+          message:
+            'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+            "the handler or hook to allow unsafeRaw.",
+        });
+      }
+      return db;
+    },
+
     selectMany<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where?: WhereObject,
       options?: SelectOptions,
     ): Promise<readonly T[]> {
@@ -324,7 +379,7 @@ export function createTenantDb(
     },
 
     fetchOne<T = Record<string, unknown>>(
-      table: Table,
+      table: Table | EntityTableMeta,
       where: WhereObject,
     ): Promise<T | undefined> {
       const filter = readWhere(table, where) ?? {};
@@ -335,6 +390,19 @@ export function createTenantDb(
       table: Table,
       values: Record<string, unknown>,
     ): Promise<T | undefined> {
+      if (
+        mode === "tenant" &&
+        hasTenantColumn(table) &&
+        asEntityTableMeta(table)?.tenancy === "global"
+      ) {
+        const denied = foreignTenantOnGlobalWrite(
+          table,
+          tenantId,
+          `insertOne(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+            "use db.global(table) with escapeHatch instead.",
+        );
+        if (denied) return Promise.reject(denied);
+      }
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -367,6 +435,11 @@ export function createTenantDb(
       return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
     },
   };
+
+  unsafeRawRebinders.set(tenantDb, (grant) =>
+    createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }),
+  );
+  return tenantDb;
 }
 
 export { asRawClient };

package/src/engine/active-membership.ts

@@ -10,12 +10,26 @@ import type { TenantId } from "./types/identifiers";
 // with a since-deleted row should not silently treat it as active.
 export type PrincipalStatus = "active" | "blocked" | "unknown";
 
+// Global-roles/timezone/locale snapshot ctx.queryAsMember needs to mint a
+// resolved principal's SessionUser, without exposing its own table.
+export type PrincipalProfile = {
+  readonly globalRoles: readonly string[];
+  readonly timezone?: string;
+  readonly locale?: string;
+};
+
 // Registered via r.useExtension(EXT_PRINCIPAL_STATUS, "user", principalStatusPlugin).
 export type PrincipalStatusPlugin = {
   readonly resolveStatus: (
     userId: string,
     deps: { readonly db: DbConnection },
   ) => Promise<PrincipalStatus>;
+  // Required so a missing provider fails closed (InternalError) instead of
+  // silently minting empty global roles for ctx.queryAsMember.
+  readonly resolveProfile: (
+    userId: string,
+    deps: { readonly db: DbConnection },
+  ) => Promise<PrincipalProfile | null>;
 };
 
 // `null` means the tenant has no lifecycle row (never entered teardown).
@@ -38,7 +52,7 @@ function hasResolveStatusFn(v: unknown): v is { readonly resolveStatus: unknown
 }
 
 export function isPrincipalStatusPlugin(v: unknown): v is PrincipalStatusPlugin {
-  return hasResolveStatusFn(v);
+  return hasResolveStatusFn(v) && "resolveProfile" in v && typeof v.resolveProfile === "function";
 }
 
 export function isTenantLifecycleStatusPlugin(v: unknown): v is TenantLifecycleStatusPlugin {

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

@@ -0,0 +1,58 @@
+// fw#2858 — a `tenancy: "global"` entity's event stream must live on
+// SYSTEM_TENANT_ID (systemStream: true); otherwise it would silently fork
+// one stream per creating tenant while still being writable/readable
+// cross-tenant via db.global(table).
+
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import { createEntity, createTextField } from "../../factories";
+import { validateGlobalTenancyEntities } from "../global-tenancy";
+
+const textField = () =>
+  createTextField({
+    required: true,
+    maxLength: 64,
+    personal: false,
+    reason: "technical_reference",
+  });
+
+describe("validateGlobalTenancyEntities", () => {
+  test("a tenancy: 'global' entity WITHOUT systemStream: true throws", () => {
+    const entity = createEntity({
+      table: "read_fw2858_global_no_stream",
+      tenancy: "global",
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-global-no-stream", (r) => {
+      r.entity("fw2858GlobalNoStream", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).toThrow(/systemStream/);
+  });
+
+  test("a tenancy: 'global' entity WITH systemStream: true passes", () => {
+    const entity = createEntity({
+      table: "read_fw2858_global_with_stream",
+      tenancy: "global",
+      systemStream: true,
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-global-with-stream", (r) => {
+      r.entity("fw2858GlobalWithStream", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).not.toThrow();
+  });
+
+  test("a tenant-tenancy entity without systemStream is never checked", () => {
+    const entity = createEntity({
+      table: "read_fw2858_tenant_entity",
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2858-tenant-entity", (r) => {
+      r.entity("fw2858TenantEntity", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).not.toThrow();
+  });
+});

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/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,
@@ -478,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,
@@ -186,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);

package/src/pipeline/__tests__/dispatcher-utils.test.ts

@@ -51,6 +51,23 @@ describe("dispatcherSpanAttributes", () => {
       "kumiko.feature": "feat",
     });
   });
+
+  test("includes kumiko.user_origin when the user has one", () => {
+    const user = {
+      id: "u1",
+      tenantId: "tenant-1",
+      roles: [],
+      origin: "member-resolution" as const,
+    };
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs["kumiko.user_origin"]).toBe("member-resolution");
+  });
+
+  test("omits kumiko.user_origin when the user has none", () => {
+    const user = createSystemUser("tenant-1");
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs["kumiko.user_origin"]).toBeUndefined();
+  });
 });
 
 describe("prefixValidationPath", () => {

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

@@ -19,7 +19,6 @@ const globalStoreTable = defineUnmanagedTable({
       primaryKey: true,
       defaultSql: "gen_random_uuid()",
     },
-    { name: "tenant_id", pgType: "uuid", notNull: true },
     { name: "note", pgType: "text", notNull: true },
   ],
 });
@@ -36,7 +35,6 @@ const escapeHatchFeature = defineFeature("escape-hatch-probe", (r) => {
     escapeHatch: { reason: "fw#2855 integration test — declared cross-tenant write" },
     handler: async (event, ctx) => {
       const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
-        tenantId: event.user.tenantId,
         note: event.payload.note,
       });
       return { isSuccess: true as const, data: row };
@@ -49,7 +47,6 @@ const escapeHatchFeature = defineFeature("escape-hatch-probe", (r) => {
     access: { roles: ["User"] },
     handler: async (event, ctx) => {
       const row = await ctx.db.global(globalStoreTable).insertOne<{ id: string }>({
-        tenantId: event.user.tenantId,
         note: event.payload.note,
       });
       return { isSuccess: true as const, data: row };