@cosmicdrift/kumiko-framework 0.264.1 → 0.266.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.264.1",
+  "version": "0.266.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.264.1",
+    "@cosmicdrift/kumiko-types": "0.266.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.264.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.266.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api.test.ts

@@ -636,6 +636,10 @@ describe("POST /api/stream pre-pull race", () => {
       async resolveAuthClaims(): Promise<Record<string, unknown>> {
         return {};
       },
+      // Not exercised by this route — always "not_a_member" is fine.
+      async resolveActiveMembership() {
+        return { kind: "rejected", reason: "not_a_member" };
+      },
     };
   }
 

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -20,7 +20,7 @@ import { createJwtHelper } from "../jwt";
 const JWT_SECRET = "auth-routes-cookie-test-secret-min-32-characters";
 
 function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
-  const base: Dispatcher = {
+  const merged: Dispatcher = {
     async write(): Promise<WriteResult> {
       // Explicit `const: WriteResult` locks the `isSuccess: true` branch of
       // the union without an `as`-cast (which widens + silences the
@@ -46,8 +46,27 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Delegates to `merged.query` (not to a pre-override `base`) so the
+    // switch-tenant test's `query` override — which answers
+    // "tenant:query:memberships" — is what this sees too.
+    async resolveActiveMembership(userId, tenantId) {
+      const memberships = (await merged.query(
+        "tenant:query:memberships",
+        { userId },
+        TestUsers.user,
+      )) as ReadonlyArray<{
+        tenantId: string;
+        roles: readonly string[];
+      }>;
+      const membership = memberships.find((m) => m.tenantId === tenantId);
+      if (!membership) {
+        return { kind: "rejected", reason: "not_a_member" };
+      }
+      return { kind: "active", membership: { tenantId, roles: membership.roles } };
+    },
+    ...overrides,
   };
-  return { ...base, ...overrides };
+  return merged;
 }
 
 async function buildApp(

package/src/api/__tests__/auth-routes-invalid-body-invite.test.ts

@@ -33,6 +33,10 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Not exercised by these routes — always "not_a_member" is fine.
+    async resolveActiveMembership() {
+      return { kind: "rejected", reason: "not_a_member" };
+    },
     // Stream API added with r.streamHandler (#1446) — stub unused in these routes.
     async *stream(): AsyncGenerator<unknown> {},
   };

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -45,6 +45,10 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Not exercised by these routes — always "not_a_member" is fine.
+    async resolveActiveMembership() {
+      return { kind: "rejected", reason: "not_a_member" };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-mfa-preauth-enable-start.test.ts

@@ -46,6 +46,10 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Not exercised by these routes — always "not_a_member" is fine.
+    async resolveActiveMembership() {
+      return { kind: "rejected", reason: "not_a_member" };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-mfa-verify.test.ts

@@ -45,6 +45,10 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Not exercised by these routes — always "not_a_member" is fine.
+    async resolveActiveMembership() {
+      return { kind: "rejected", reason: "not_a_member" };
+    },
   };
   return { ...base, ...overrides };
 }

package/src/api/__tests__/auth-routes-trusted-proxy.test.ts

@@ -38,6 +38,10 @@ function failingDispatcher(): Dispatcher {
     async resolveAuthClaims(): Promise<Record<string, unknown>> {
       return {};
     },
+    // Not exercised by these routes — always "not_a_member" is fine.
+    async resolveActiveMembership() {
+      return { kind: "rejected", reason: "not_a_member" };
+    },
   };
 }
 

package/src/api/__tests__/server-boot-guards.test.ts

@@ -1,12 +1,15 @@
 // buildServer boot-time guards + httpRoute verb wiring (PUT branch).
 
 import { describe, expect, spyOn, test } from "bun:test";
+import { z } from "zod";
 import {
   createEntity,
   createFileField,
   createRegistry,
   createTextField,
   defineFeature,
+  defineQueryHandler,
+  EXT_PRINCIPAL_STATUS,
 } from "../../engine";
 import { createInMemorySearchAdapter } from "../../search";
 import { buildServer } from "../server";
@@ -203,3 +206,60 @@ describe("buildServer — search-adapter boot warning (#2051)", () => {
     }
   });
 });
+
+describe("buildServer — auth membershipQuery requires a principalStatus provider", () => {
+  const MEMBERSHIP_QN = "tenant:query:memberships";
+
+  // The registry auto-qualifies a SHORT handler name as `<feature>:query:<name>`,
+  // so the feature must be named "tenant" for MEMBERSHIP_QN to come out right.
+  const membershipQueryFeature = defineFeature("tenant", (r) => {
+    r.queryHandler(
+      defineQueryHandler({
+        name: "memberships",
+        schema: z.object({ userId: z.string() }),
+        handler: async () => [],
+        access: { roles: ["all"] },
+      }),
+    );
+  });
+
+  const principalStatusFeature = defineFeature("has-principal-status", (r) => {
+    r.extendsRegistrar(EXT_PRINCIPAL_STATUS, {});
+    r.useExtension(EXT_PRINCIPAL_STATUS, "has-principal-status", {
+      resolveStatus: async () => "active" as const,
+    });
+  });
+
+  test("throws when membershipQuery is registered but no feature provides principalStatus", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([membershipQueryFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+        auth: { membershipQuery: MEMBERSHIP_QN },
+      }),
+    ).toThrow(/no feature provides the "principalStatus" contract/);
+  });
+
+  test("boots when a feature provides principalStatus", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([membershipQueryFeature, principalStatusFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+        auth: { membershipQuery: MEMBERSHIP_QN },
+      }),
+    ).not.toThrow();
+  });
+
+  test("boots when the membershipQuery handler isn't registered at all (e.g. features:[] tests)", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+        auth: { membershipQuery: MEMBERSHIP_QN },
+      }),
+    ).not.toThrow();
+  });
+});

package/src/api/auth-middleware.ts

@@ -1,5 +1,6 @@
 import type { Context, Next } from "hono";
 import { getCookie } from "hono/cookie";
+import { TENANT_TEARDOWN_STATUSES } from "../engine/active-membership";
 import { createAnonymousUser } from "../engine/system-user";
 import type { SessionUser, TenantId } from "../engine/types";
 import { parseTenantId } from "../engine/types/identifiers";
@@ -592,12 +593,6 @@ type RejectArgs = {
   details?: Record<string, unknown>;
 };
 
-const TENANT_LIFECYCLE_BLOCKED = new Set([
-  "destroyRequested",
-  "destroying",
-  "destroyFailed",
-  "destroyed",
-]);
 const TENANT_LIFECYCLE_CANCEL_QN = "tenant-lifecycle:write:cancel-destruction";
 
 async function requestsCancelDestruction(c: Context): Promise<boolean> {
@@ -634,7 +629,7 @@ async function rejectIfTenantTeardown(
 ): Promise<Response | undefined> {
   if (!resolveTenantLifecycleStatus) return undefined;
   const lifecycle = await resolveTenantLifecycleStatus(tenantId);
-  if (!lifecycle || !TENANT_LIFECYCLE_BLOCKED.has(lifecycle.status)) return undefined;
+  if (!lifecycle || !TENANT_TEARDOWN_STATUSES.has(lifecycle.status)) return undefined;
   if (lifecycle.status === "destroyRequested" && (await requestsCancelDestruction(c))) {
     return undefined;
   }

package/src/api/auth-routes.ts

@@ -6,9 +6,16 @@ import type Redis from "ioredis";
 import { z } from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
 import { createSystemUser } from "../engine/system-user";
-import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
+import {
+  type ActiveMembershipRejection,
+  type ActiveMembershipResult,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "../engine/types";
 import { NotFoundError } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { assertUnreachable } from "../utils";
 import { parseRoles } from "../utils/serialization";
 import { Routes } from "./api-constants";
 import {
@@ -167,6 +174,19 @@ function isUnknownHandlerError(e: unknown): boolean {
   return details?.entity === "handler";
 }
 
+function switchTenantRejectionResponse(c: Context, reason: ActiveMembershipRejection): Response {
+  switch (reason) {
+    case "not_a_member":
+      return c.json({ error: "not_a_member" }, 403);
+    case "principal_blocked":
+      return c.json({ error: "principal_blocked" }, 403);
+    case "tenant_teardown":
+      return c.json({ error: "tenant_unavailable" }, 410);
+    default:
+      return assertUnreachable(reason, "ActiveMembershipRejection");
+  }
+}
+
 type MembershipRow = {
   userId: string;
   tenantId: TenantId;
@@ -1324,17 +1344,11 @@ export function createAuthRoutes(
       return c.json({ error: "already_in_tenant" }, 400);
     }
 
-    // Check membership — uses the system identity because membershipQuery is
-    // locked to the system role. The auth-route is trusted server code; it
-    // asks the question on the user's behalf, not as the user.
-    let memberships: MembershipRow[];
+    // Membership + principal-blocked + tenant-teardown in one building
+    // block — trusted server code asking on the user's behalf, same trust boundary as before.
+    let activeMembership: ActiveMembershipResult;
     try {
-      // @cast-boundary engine-payload — generic dispatcher.query result
-      memberships = (await dispatcher.query(
-        config.membershipQuery,
-        { userId: user.id },
-        createSystemUser(user.tenantId),
-      )) as MembershipRow[];
+      activeMembership = await dispatcher.resolveActiveMembership(user.id, targetTenantId);
     } catch (e) {
       // No membershipQuery wired → switching tenants is just not offered in
       // this deployment. Any other error propagates so a broken query handler
@@ -1343,10 +1357,10 @@ export function createAuthRoutes(
       return c.json({ error: "tenant_switch_not_available" }, 400);
     }
 
-    const membership = memberships.find((m) => m.tenantId === targetTenantId);
-    if (!membership) {
-      return c.json({ error: "not_a_member" }, 403);
+    if (activeMembership.kind === "rejected") {
+      return switchTenantRejectionResponse(c, activeMembership.reason);
     }
+    const membership = activeMembership.membership;
 
     // Globale Rollen aus user-feature lesen wenn userQuery wired —
     // tenant-unabhängige Rollen (SystemAdmin etc.) überleben so den

package/src/api/server.ts

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createTenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
-import { EXT_FILE_PROVIDER } from "../engine/extension-names";
+import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
 import { createAnonymousUser } from "../engine/system-user";
 import {
@@ -443,6 +443,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     ...options.dispatcherOptions,
     lifecycle,
     sseBroker,
+    ...(options.auth ? { membershipQuery: options.auth.membershipQuery } : {}),
   });
 
   // Async event-dispatcher — the replacement for the old transactional
@@ -756,6 +757,18 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // Public auth routes (login) need to be registered BEFORE the generic
   // api routes so Hono matches them first.
   if (options.auth) {
+    // A membershipQuery handler is registered but nothing fulfils
+    // principalStatus — surface that misconfig at boot instead of an InternalError on first login/switch-tenant.
+    if (
+      options.registry.getQueryHandler(options.auth.membershipQuery) &&
+      options.registry.getExtensionUsages(EXT_PRINCIPAL_STATUS).length === 0
+    ) {
+      throw new Error(
+        `[kumiko] auth membershipQuery "${options.auth.membershipQuery}" is registered but no feature ` +
+          'provides the "principalStatus" contract — mount the user feature (tenant switch and sign-in ' +
+          "need it to reject blocked principals).",
+      );
+    }
     app.route("/api", createAuthRoutes(dispatcher, jwt, options.auth));
   }
   app.route(

package/src/changes.json

@@ -1,4 +1,31 @@
 [
+  {
+    "version": "0.266.0",
+    "type": "breaking",
+    "title": "`publicIntake` is removed; an openToAll write handler declares unbound personal data with `openToAll: { reason, personalData: \"tenant-members\" }`.",
+    "detail": "`OpenToAllAccessRule.publicIntake` (`@cosmicdrift/kumiko-types/handlers`) no longer exists. `OpenToAllDeclaration` gains `personalData?: OpenToAllPersonalData`, a named union (currently only `\"tenant-members\"`, exported from `@cosmicdrift/kumiko-framework/engine` and `/ui-types`): signed-in tenant members may write personal data that no owner rule binds to the caller. The deprecated `openToAll: true` form cannot carry it. `validateAccessDeclarations` requires `personalData: \"tenant-members\"` for a write handler with `openToAll` whose input accepts a personal-data field that is not owner- or self-bound, rejects `personalData` on query and stream handlers, and rejects any other `personalData` value from untyped sources. `openToAll` never admits anonymous callers, so there is no public-intake value; anonymous personal-data intake is tracked separately. The feature-AST extractor reads `openToAll.personalData` and no longer reads `publicIntake`. Bundled `user:update` now declares `openToAll: { reason, personalData: \"tenant-members\" }`: `userEntity` has no entity-level `access.write`, and privileged actors may edit any user.",
+    "migration": "Replace `access: { openToAll: { reason: \"...\" }, publicIntake: true }` (or `openToAll: true, publicIntake: true`) with `access: { openToAll: { reason: \"<why any signed-in tenant member may write this personal data>\", personalData: \"tenant-members\" } }`. Handlers whose personal-data fields are owner- or self-bound through the entity's `access.write` need no declaration. A `publicIntake` key left in an untyped access object (pattern JSON, Designer) is ignored, so the handler fails boot until migrated. No known consumer used `publicIntake`."
+  },
+  {
+    "version": "0.266.0",
+    "type": "breaking",
+    "title": "The openToAll personal-data boot check now finds personal-data fields nested anywhere in a write handler's input schema.",
+    "detail": "`validateAccessDeclarations` (`engine/boot-validator/access-declarations.ts`) previously compared only the top-level keys of a `z.object` input schema (unwrapping `.optional()`/`.nullable()`/`.default()`) against the handler entity's personal-data fields (pii / userOwned / recordOwned); any other schema shape was skipped. It now collects object keys at every depth via `collectZodObjectKeys` (`engine/boot-validator/zod-shape.ts`): through `z.intersection`, `z.union`/`z.discriminatedUnion`/`z.xor`, `.transform()`/`z.preprocess()`/`.pipe()`/codecs, `.optional()`/`.nullable()`/`.default()`/`.prefault()`/`.nonoptional()`/`.readonly()`/`.catch()`/`z.lazy()`, nested objects (e.g. the update shape `{ id, version, changes: {...} }`), arrays, tuples and records. An update handler that accepted the same personal-data field as its create handler used to pass boot while the create handler failed. A schema with more than 10000 distinct nodes (typically a `z.lazy()` getter that returns a new schema on every call) throws at boot instead of looping. Which entity's fields are compared is unchanged: the handler's mapped entity, or every entity of the feature for an unmapped handler.",
+    "migration": "A write handler with `openToAll` whose input accepts a personal-data field of its entity inside an intersection, union, pipe/transform, nested object (update `changes`), array or record now fails boot like a top-level field always did. Known: kumiko-enterprise kumiko-credit `update` (intersection) and `bauspar:update` (`changes.name`) under `trustDomain: \"tenant\"` or with an `access` map that grants any role `\"all\"`. For each affected handler, bind the entity's rows to the caller (owner-binding entry in this release), restrict `access` to roles, or declare `openToAll: { reason: \"...\", personalData: \"tenant-members\" }`."
+  },
+  {
+    "version": "0.266.0",
+    "type": "improvement",
+    "title": "Owner- and self-bound personal-data fields no longer need a declaration on openToAll write handlers.",
+    "detail": "A personal-data field is exempt from the openToAll personal-data boot check when it is bound to the caller: the handler maps to exactly one entity, that entity's `access.write` is a non-empty `OwnershipMap` in which every role's rule is `from(\"user:id\", <column>)` on the binding column, the handler declares no `escapeHatch`, and its feature is not `r.systemScope()`. The binding column is the owner field for `personal: { of: \"<ownerField>\" }` (userOwned), and `id` for `personal: \"self\"` and `personal: { of: \"id\" }` — there the row itself is the caller. The event-store executor enforces such a map on every write: create rejects a row whose binding column is not the caller (`ownership_denied`), update checks the old and the new row, delete/restore the existing row. Not exempt: a missing or empty `access.write`, any `\"all\"` rule (also next to binding rules), a rule on another column, `user:tenantId` or claim refs, `where` rules, `self` fields on an entity without `from(\"user:id\", \"id\")`, handlers not mapped to a single entity, handlers with `escapeHatch` and handlers of `r.systemScope()` features (both can write around the executor via `db.global()`, `systemDb` or a SYSTEM identity)."
+  },
+  {
+    "version": "0.265.0",
+    "type": "improvement",
+    "title": "Active-membership building block (resolveActiveMembership) composes membership + principalStatus + tenant-lifecycle checks (fw#2872).",
+    "detail": "New `dispatcher.resolveActiveMembership(userId, tenantId)` / `ctx.resolveActiveMembership` returns an `ActiveMembershipResult` — either `active` with the raw membership roles, or `rejected` with reason `not_a_member` | `principal_blocked` | `tenant_teardown` (membership is checked first, so a non-member can't learn a foreign tenant's lifecycle/blocked state). It composes two new framework contracts, `EXT_PRINCIPAL_STATUS` (fulfilled by the bundled `user` feature) and `EXT_TENANT_LIFECYCLE_STATUS` (fulfilled by `tenant-lifecycle`), plus `TENANT_TEARDOWN_STATUSES` and the default `TENANT_MEMBERSHIPS_QUERY` handler name, and is now used by switch-tenant, login and auth-mfa verify/enable-confirm-preauth instead of each independently composing membership + status checks. `ctx.resolveActiveMembership` requires the same SYSTEM-identity grant as `ctx.queryAs`/`ctx.writeAs` with a system user (`r.systemScope()` or a declared `escapeHatch`), since it queries memberships as SYSTEM internally. Behaviourally: `POST /api/auth/switch-tenant` now answers 403 `principal_blocked` for a blocked principal and 410 `tenant_unavailable` for a target tenant in teardown (a tenant in `destroyRequested` is still allowed so its owner can cancel destruction); login skips a last-active tenant that is in teardown and falls through to the next active membership; MFA verify and enable-confirm-preauth reject a tenant in teardown; `buildServer` now throws at boot when the auth `membershipQuery` handler is registered but no feature provides the `principalStatus` contract (mount the bundled `user` feature); and `isPrincipalBlocked` now lives in `user` (still re-exported from `sessions` for existing importers).",
+    "migration": "No action for apps mounting the bundled `user` feature (runProdApp/runDevApp always do). A custom stack that registers the membership query without the `user` feature must mount `user` or register an `r.useExtension(EXT_PRINCIPAL_STATUS, ...)` provider, otherwise buildServer throws at boot. Clients of POST /api/auth/switch-tenant should handle the new 403 `principal_blocked` and 410 `tenant_unavailable` responses. A handler calling `ctx.resolveActiveMembership` needs an `escapeHatch` declaration (or `r.systemScope()`) the same way it would for a SYSTEM `queryAs`/`writeAs` call."
+  },
   {
     "version": "0.263.0",
     "type": "breaking",

package/src/engine/__tests__/hook-identity-switch-grant.test.ts

@@ -1,8 +1,12 @@
 import { describe, expect, mock, test } from "bun:test";
-import { AccessDeniedError } from "../../errors";
-import { createGatedIdentitySwitch, type QueryAsFn } from "../../pipeline/system-identity-switch";
+import { AccessDeniedError, FrameworkReasons } from "../../errors";
+import {
+  createGatedIdentitySwitch,
+  type QueryAsFn,
+  type ResolveActiveMembershipFn,
+} from "../../pipeline/system-identity-switch";
 import { createEntity, createRegistry, createSystemUser, defineFeature } from "../index";
-import type { AppContext, PostSaveHookFn, SaveContext } from "../types";
+import type { ActiveMembershipResult, AppContext, PostSaveHookFn, SaveContext } from "../types";
 import type { TenantId } from "../types/identifiers";
 
 // fw#2859: r.hook({ allOf }, ...) must get the same identity-switch gate as the handler-keyed path.
@@ -102,4 +106,81 @@ describe("r.hook({ allOf }, ...) identity-switch gate", () => {
       });
     }).toThrow(/non-empty string/);
   });
+
+  test("entity-wide hook WITHOUT escapeHatch does not inherit the handler's resolveActiveMembership grant", async () => {
+    const activeResult: ActiveMembershipResult = {
+      kind: "active",
+      membership: { tenantId: TENANT, roles: [] },
+    };
+    const ungatedResolveActiveMembership = mock(async () => activeResult);
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', true, {
+        queryAs: mock(async () => "ok") as QueryAsFn,
+        writeAs: async () => ({ isSuccess: true as const, data: null }),
+      }),
+      resolveActiveMembership: ungatedResolveActiveMembership as ResolveActiveMembershipFn,
+    };
+
+    let caught: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { resolveActiveMembership: ResolveActiveMembershipFn };
+        try {
+          await asContext.resolveActiveMembership("user-1", TENANT);
+        } catch (err) {
+          caught = err;
+        }
+      };
+      r.hook("postSave", { allOf: thing }, hookFn);
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    expect((caught as AccessDeniedError).details).toEqual({
+      reason: FrameworkReasons.systemIdentitySwitchDenied,
+    });
+    expect(ungatedResolveActiveMembership).not.toHaveBeenCalled();
+  });
+
+  test("entity-wide hook WITH escapeHatch reaches the original resolveActiveMembership even when the handler's own grant was false", async () => {
+    const activeResult: ActiveMembershipResult = {
+      kind: "active",
+      membership: { tenantId: TENANT, roles: ["User"] },
+    };
+    const ungatedResolveActiveMembership = mock(async () => activeResult);
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "test:write:thing:create"', false, {
+        queryAs: mock(async () => "ok") as QueryAsFn,
+        writeAs: async () => ({ isSuccess: true as const, data: null }),
+      }),
+      resolveActiveMembership: ungatedResolveActiveMembership as ResolveActiveMembershipFn,
+    };
+
+    let resolveResult: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { resolveActiveMembership: ResolveActiveMembershipFn };
+        resolveResult = await asContext.resolveActiveMembership("user-1", TENANT);
+      };
+      r.hook("postSave", { allOf: thing }, hookFn, {
+        escapeHatch: { reason: "test: allOf hook needs SYSTEM" },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(resolveResult).toEqual(activeResult);
+    expect(ungatedResolveActiveMembership).toHaveBeenCalledWith("user-1", TENANT);
+  });
 });

package/src/engine/active-membership.ts

@@ -0,0 +1,56 @@
+// principalStatus / tenantLifecycleStatus contracts consumed by
+// pipeline/active-membership.ts. Kept in engine/ (extension-registry surface), same split as tier-resolver-extension.ts.
+
+import type { DbConnection } from "../db/connection";
+import type { TenantId } from "./types/identifiers";
+
+// "unknown" = no persisted principal row for this userId — the caller
+// (INTERACTIVE_SIGN_IN_POLICY.allowUnknownPrincipal) decides whether that
+// counts as active or blocked; a background resolver for a stored userId
+// with a since-deleted row should not silently treat it as active.
+export type PrincipalStatus = "active" | "blocked" | "unknown";
+
+// Registered via r.useExtension(EXT_PRINCIPAL_STATUS, "user", principalStatusPlugin).
+export type PrincipalStatusPlugin = {
+  readonly resolveStatus: (
+    userId: string,
+    deps: { readonly db: DbConnection },
+  ) => Promise<PrincipalStatus>;
+};
+
+// `null` means the tenant has no lifecycle row (never entered teardown).
+export type TenantLifecycleStatusPlugin = {
+  readonly resolveStatus: (
+    tenantId: TenantId,
+    deps: { readonly db: DbConnection },
+  ) => Promise<{ readonly status: string } | null>;
+};
+
+// extension-usage `options` is engine-payload (unknown) — structurally
+// validate instead of casting blind, same pattern as isFileProviderPlugin.
+function hasResolveStatusFn(v: unknown): v is { readonly resolveStatus: unknown } {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "resolveStatus" in v &&
+    typeof v.resolveStatus === "function"
+  );
+}
+
+export function isPrincipalStatusPlugin(v: unknown): v is PrincipalStatusPlugin {
+  return hasResolveStatusFn(v);
+}
+
+export function isTenantLifecycleStatusPlugin(v: unknown): v is TenantLifecycleStatusPlugin {
+  return hasResolveStatusFn(v);
+}
+
+// Same values auth-middleware.ts used to keep as its own private
+// TENANT_LIFECYCLE_BLOCKED set — moved here so the framework's active-
+// membership check and the request-level 410 gate can't drift apart.
+export const TENANT_TEARDOWN_STATUSES: ReadonlySet<string> = new Set([
+  "destroyRequested",
+  "destroying",
+  "destroyFailed",
+  "destroyed",
+]);