@cosmicdrift/kumiko-framework 0.289.0 → 0.291.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.289.0",
+  "version": "0.291.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,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.289.0",
-    "@cosmicdrift/kumiko-types": "0.289.0",
+    "@cosmicdrift/kumiko-http": "0.291.0",
+    "@cosmicdrift/kumiko-types": "0.291.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.289.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.291.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/field-access.integration.test.ts

@@ -26,10 +26,14 @@ import {
 const employeeEntity = createEntity({
   table: "fa_employees",
   fields: {
-    email: createTextField({ required: true }),
-    firstName: createTextField(),
+    email: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    firstName: createTextField({ personal: false, reason: "test_fixture" }),
     salary: createNumberField({ access: { read: ["Admin", "Accounting"], write: ["Admin"] } }),
-    notes: createTextField({ access: { read: ["Admin"], write: ["Admin"] } }),
+    notes: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      access: { read: ["Admin"], write: ["Admin"] },
+    }),
   },
 });
 

package/src/__tests__/ownership-where-write-path.integration.test.ts

@@ -45,7 +45,7 @@ const memoEntity = createEntity({
   table: "fw2626_memos",
   softDelete: true,
   fields: {
-    ownerId: createTextField({ required: true }),
+    ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
     title: createTextField({ personal: false, reason: "test_fixture", required: true }),
   },
   access: {

package/src/__tests__/ownership.integration.test.ts

@@ -37,7 +37,7 @@ const contractEntity = createEntity({
   softDelete: true,
   fields: {
     teamId: createTextField({ personal: false, reason: "test_fixture", required: true }),
-    assigneeId: createTextField(),
+    assigneeId: createTextField({ personal: false, reason: "test_fixture" }),
     title: createTextField({ personal: false, reason: "test_fixture", required: true }),
     // propA: public on read + write
     propA: createTextField({ personal: false, reason: "test_fixture" }),

package/src/__tests__/pii-personal-migration-report-codemod.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "bun:test";
+import { reportStanceForSource } from "../scripts/codemod/pii-personal-migration";
+
+function wrapField(fieldSrc: string): string {
+  return `
+const entity = createEntity({
+  table: "entity_table",
+  fields: {
+    ${fieldSrc}
+  },
+});
+`;
+}
+
+describe("reportStanceForSource", () => {
+  it("classifies an exact PII_DIRECT_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("email: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("direct");
+    expect(site?.hint).toBe("email");
+  });
+
+  it("classifies an exact PII_USER_OWNED_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("note: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("user-owned");
+    expect(site?.hint).toBe("note");
+  });
+
+  it("classifies an exact PII_USER_REFERENCE_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("authorId: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("user-reference");
+    expect(site?.hint).toBe("authorid");
+  });
+
+  it("classifies a near-miss when a hint occurs at a segment boundary", () => {
+    const [site] = reportStanceForSource(
+      wrapField("advisorDisplayName: createTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe("displayname");
+  });
+
+  it("picks the longest hint on multiple boundary matches", () => {
+    const [site] = reportStanceForSource(
+      wrapField("customerEmailAddress: createTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe("address");
+  });
+
+  // No hint entry is a substring of "performedbyuserid" itself, but its
+  // segment-aligned suffix "userid" (>= 5 chars) is a substring of the
+  // full-name hints "createdbyuserid"/"updatedbyuserid"/"assigneeuserid" —
+  // the shortest of the three, "assigneeuserid", is reported.
+  it.each([
+    ["performedByUserId", "assigneeuserid"],
+    ["portalUserId", "assigneeuserid"],
+    ["ownerUserId", "assigneeuserid"],
+  ])("classifies %s as near-miss via its segment-aligned suffix", (field, expectedHint) => {
+    const [site] = reportStanceForSource(wrapField(`${field}: createTextField({}),`), "t.ts");
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe(expectedHint);
+  });
+
+  it.each([
+    "contextId",
+    "stepKey",
+    "runId",
+    "scheduleId",
+    "costCategoryId",
+    "toolCallId",
+    "conversationId",
+    "handlerQn",
+  ])("classifies %s as unclassified — no hint containment or suffix match", (field) => {
+    const [site] = reportStanceForSource(wrapField(`${field}: createTextField({}),`), "t.ts");
+    expect(site?.stance).toBe("unclassified");
+    expect(site?.hint).toBeUndefined();
+  });
+
+  it("does not report a call already annotated with a personal stance", () => {
+    const sites = reportStanceForSource(
+      wrapField('email: createTextField({ personal: false, reason: "x" }),'),
+      "t.ts",
+    );
+    expect(sites).toHaveLength(0);
+  });
+
+  it("reports a call whose personal value is undefined", () => {
+    const sites = reportStanceForSource(
+      wrapField("email: createTextField({ personal: undefined }),"),
+      "t.ts",
+    );
+    expect(sites).toHaveLength(1);
+  });
+
+  it("does not report a call whose options literal contains a spread", () => {
+    const sites = reportStanceForSource(wrapField("email: createTextField({ ...base }),"), "t.ts");
+    expect(sites).toHaveLength(0);
+  });
+
+  it("does not report a call with a non-literal options argument", () => {
+    const sites = reportStanceForSource(wrapField("email: createTextField(options),"), "t.ts");
+    expect(sites).toHaveLength(0);
+  });
+
+  it("reports a bare createTextField() call with no arguments", () => {
+    const sites = reportStanceForSource(wrapField("stepKey: createTextField(),"), "t.ts");
+    expect(sites).toHaveLength(1);
+    expect(sites[0]?.stance).toBe("unclassified");
+    expect(sites[0]?.hint).toBeUndefined();
+    expect(sites[0]?.field).toBe("stepKey");
+  });
+
+  it("falls back to a synthetic field name and stays unclassified when there is no enclosing PropertyAssignment", () => {
+    const source = `
+const x = [createTextField({})];
+`;
+    const sites = reportStanceForSource(source, "t.ts");
+    expect(sites).toHaveLength(1);
+    expect(sites[0]?.field).toBe("createTextField(...)");
+    expect(sites[0]?.stance).toBe("unclassified");
+    expect(sites[0]?.hint).toBeUndefined();
+  });
+
+  it("resolves the entity from createEntity's table property", () => {
+    const [site] = reportStanceForSource(wrapField("email: createTextField({}),"), "t.ts");
+    expect(site?.entity).toBe("entity_table");
+  });
+
+  it("falls back to the enclosing variable name when createEntity has no table property", () => {
+    const source = `
+const fields = createEntity({
+  fields: {
+    email: createTextField({}),
+  },
+});
+`;
+    const [site] = reportStanceForSource(source, "t.ts");
+    expect(site?.entity).toBe("fields");
+  });
+
+  it("resolves entity to null when the call is not inside a createEntity call", () => {
+    const source = `
+const standalone = { email: createTextField({}) };
+`;
+    const [site] = reportStanceForSource(source, "t.ts");
+    expect(site?.entity).toBeNull();
+  });
+
+  it("captures createLongTextField the same way as createTextField", () => {
+    const [site] = reportStanceForSource(
+      wrapField("description: createLongTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.callee).toBe("createLongTextField");
+    expect(site?.stance).toBe("user-owned");
+    expect(site?.hint).toBe("description");
+  });
+});

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

@@ -10,6 +10,7 @@ import {
   defineFeature,
   defineQueryHandler,
   EXT_PRINCIPAL_STATUS,
+  EXT_TENANT_LIFECYCLE_STATUS,
 } from "../../engine";
 import { createInMemorySearchAdapter } from "../../search";
 import { buildServer } from "../server";
@@ -263,3 +264,44 @@ describe("buildServer — auth membershipQuery requires a principalStatus provid
     ).not.toThrow();
   });
 });
+
+describe("buildServer — tenant-lifecycle gate derivation", () => {
+  const lifecyclePlugin = { resolveStatus: async () => null };
+  const providerFeature = defineFeature("lifecycle-provider", (r) => {
+    r.extendsRegistrar(EXT_TENANT_LIFECYCLE_STATUS, {});
+    r.useExtension(EXT_TENANT_LIFECYCLE_STATUS, "lifecycle-provider", lifecyclePlugin);
+  });
+  const secondProviderFeature = defineFeature("lifecycle-provider-2", (r) => {
+    r.useExtension(EXT_TENANT_LIFECYCLE_STATUS, "lifecycle-provider-2", lifecyclePlugin);
+  });
+
+  test("throws when a lifecycle provider is mounted but context.db is missing", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([providerFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      }),
+    ).toThrow(/tenantLifecycleStatus provider is mounted .* but context\.db is missing/);
+  });
+
+  test("throws when two lifecycle providers are registered", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([providerFeature, secondProviderFeature]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      }),
+    ).toThrow(/multiple "tenantLifecycleStatus" providers registered/);
+  });
+
+  test("no provider mounted leaves the gate unwired", () => {
+    expect(() =>
+      buildServer({
+        registry: createRegistry([]),
+        context: {},
+        jwtSecret: JWT_SECRET,
+      }),
+    ).not.toThrow();
+  });
+});

package/src/api/__tests__/server-error-logging.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, spyOn, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { z } from "zod";
 import { createRegistry, defineFeature } from "../../engine";
+import { RateLimitError, UnprocessableError } from "../../errors";
 import { TestUsers } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time";
 import { buildServer } from "../server";
@@ -13,6 +14,10 @@ await ensureTemporalPolyfill();
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
 
+const openToAll = {
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+} as const;
+
 const boomFeature = defineFeature("boom", (r) => {
   r.queryHandler(
     "explode",
@@ -20,7 +25,38 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => {
       throw new Error("disk on fire");
     },
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    openToAll,
+  );
+  r.queryHandler(
+    "decode",
+    z.object({}),
+    async () => {
+      throw new UnprocessableError("vin_not_decodable", {
+        details: { vin: "WDB0000000SECRET" },
+      });
+    },
+    openToAll,
+  );
+  r.queryHandler(
+    "throttled",
+    z.object({}),
+    async () => {
+      throw new RateLimitError({
+        bucket: "ip:203.0.113.7",
+        limit: 1,
+        windowSeconds: 60,
+        remaining: 0,
+        retryAfterSeconds: 60,
+        resetAt: "2026-01-01T00:00:00.000Z",
+      });
+    },
+    openToAll,
+  );
+  r.queryHandler(
+    "login",
+    z.object({ email: z.email(), password: z.string().min(8) }),
+    async () => ({ ok: true }),
+    openToAll,
   );
 });
 
@@ -45,6 +81,43 @@ function apiFaultLog(calls: unknown[][]): string | undefined {
   return hit ? JSON.stringify(hit) : undefined;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+// The `[api] handler rejected` warn line logServerFault emits for 4xx.
+function apiRejectionLog(calls: unknown[][]): Record<string, unknown> | undefined {
+  const hit = calls.find(
+    (args) => typeof args[0] === "string" && args[0].includes("[api] handler rejected"),
+  );
+  return isRecord(hit?.[1]) ? hit[1] : undefined;
+}
+
+async function queryWithCapturedWarnings(
+  type: string,
+  payload: unknown,
+): Promise<{ status: number; warnings: unknown[][]; errors: unknown[][] }> {
+  const warnings: unknown[][] = [];
+  const errors: unknown[][] = [];
+  const warnSpy = spyOn(console, "warn").mockImplementation((...args) => {
+    warnings.push(args);
+  });
+  const errorSpy = spyOn(console, "error").mockImplementation((...args) => {
+    errors.push(args);
+  });
+  try {
+    const res = await app.request("/api/query", {
+      method: "POST",
+      headers: await auth(),
+      body: JSON.stringify({ type, payload }),
+    });
+    return { status: res.status, warnings, errors };
+  } finally {
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  }
+}
+
 describe("HTTP layer logs unexpected 5xx faults", () => {
   test("a throwing query 500s AND the cause stack reaches the log", async () => {
     const calls: unknown[][] = [];
@@ -67,21 +140,99 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     }
   });
 
-  test("an expected 404 does NOT log a server fault (no 4xx noise)", async () => {
-    const calls: unknown[][] = [];
-    const spy = spyOn(console, "error").mockImplementation((...args) => {
-      calls.push(args);
+  test("a 404 stays off the error level (it is a client outcome, not a server fault)", async () => {
+    const { status, errors } = await queryWithCapturedWarnings("nope:query:nothing", {});
+    expect(status).toBe(404);
+    expect(apiFaultLog(errors)).toBeUndefined();
+  });
+});
+
+describe("HTTP layer logs 4xx client faults on warn (#3077)", () => {
+  let previousLogLevel: string | undefined;
+
+  beforeEach(() => {
+    previousLogLevel = process.env["LOG_LEVEL"];
+    process.env["LOG_LEVEL"] = "info";
+  });
+
+  afterEach(() => {
+    if (previousLogLevel === undefined) delete process.env["LOG_LEVEL"];
+    else process.env["LOG_LEVEL"] = previousLogLevel;
+  });
+
+  test("a 422 leaves a log line with status, code and duration", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(status).toBe(422);
+    const logged = apiRejectionLog(warnings);
+    expect(logged).toBeDefined();
+    expect(logged?.["status"]).toBe(422);
+    expect(logged?.["code"]).toBe("unprocessable");
+    expect(logged?.["type"]).toBe("boom:query:decode");
+    expect(typeof logged?.["durationMs"]).toBe("number");
+    expect(logged?.["durationMs"]).toBeGreaterThanOrEqual(0);
+  });
+
+  test("a 429 leaves a log line", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:throttled", {});
+    expect(status).toBe(429);
+    expect(apiRejectionLog(warnings)?.["status"]).toBe(429);
+    expect(apiRejectionLog(warnings)?.["code"]).toBe("rate_limited");
+  });
+
+  test("a 400 validation failure leaves a log line", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:login", {
+      email: "nope",
+      password: "short",
     });
-    try {
-      const res = await app.request("/api/query", {
-        method: "POST",
-        headers: await auth(),
-        body: JSON.stringify({ type: "nope:query:nothing", payload: {} }),
-      });
-      expect(res.status).toBe(404);
-      expect(apiFaultLog(calls)).toBeUndefined();
-    } finally {
-      spy.mockRestore();
-    }
+    expect(status).toBe(400);
+    expect(apiRejectionLog(warnings)?.["status"]).toBe(400);
+    expect(apiRejectionLog(warnings)?.["code"]).toBe("validation_error");
+  });
+
+  test("a 404 leaves a log line and truncates the client-supplied type", async () => {
+    const longType = `ghost:query:${"x".repeat(500)}`;
+    const { status, warnings } = await queryWithCapturedWarnings(longType, {});
+    expect(status).toBe(404);
+    const loggedType = apiRejectionLog(warnings)?.["type"];
+    expect(typeof loggedType).toBe("string");
+    expect(String(loggedType).length).toBeLessThanOrEqual(120);
+  });
+
+  test("the 4xx line carries no submitted values, no message, no details, no stack", async () => {
+    const { warnings } = await queryWithCapturedWarnings("boom:query:login", {
+      email: "victim-at-example.com",
+      password: "hunter2-super-secret",
+      apiKey: "sk-live-0000000000",
+    });
+    const logged = apiRejectionLog(warnings);
+    expect(logged).toBeDefined();
+    expect(Object.keys(logged ?? {}).sort()).toEqual([
+      "code",
+      "durationMs",
+      "requestId",
+      "status",
+      "type",
+    ]);
+    const serialized = JSON.stringify(logged);
+    expect(serialized).not.toContain("victim-at-example.com");
+    expect(serialized).not.toContain("hunter2-super-secret");
+    expect(serialized).not.toContain("sk-live-0000000000");
+  });
+
+  test("a 422 does NOT reach the error level (5xx contract unchanged)", async () => {
+    const { errors } = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(apiFaultLog(errors)).toBeUndefined();
+  });
+
+  test("LOG_LEVEL=error silences the 4xx lines but keeps 5xx", async () => {
+    process.env["LOG_LEVEL"] = "error";
+
+    const rejected = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(rejected.status).toBe(422);
+    expect(apiRejectionLog(rejected.warnings)).toBeUndefined();
+
+    const exploded = await queryWithCapturedWarnings("boom:query:explode", {});
+    expect(exploded.status).toBe(500);
+    expect(apiFaultLog(exploded.errors)).toBeDefined();
   });
 });

package/src/api/request-context.ts

@@ -38,6 +38,15 @@ export type RequestContextData = {
   // request-locale.ts. Undefined when neither header carried a valid tag;
   // callers fall back further (dispatch-shared.ts's ctx.locale chain).
   readonly locale?: string;
+  // Attribution of the currently executing scope (#3043): the feature that
+  // owns it and the qualified name of the handler / MSP-consumer / job
+  // inside it. event-store.append() reads both and stamps them onto every
+  // event written under this scope.
+  readonly feature?: string;
+  readonly handler?: string;
+  // performance.now() at request entry, so a failing request can report how
+  // long it ran. Monotonic — a wall-clock step cannot make it negative.
+  readonly startedAt?: number;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -55,3 +64,25 @@ export const requestContext = {
     return generateId();
   },
 };
+
+// Enter a scope that attributes every event written inside it. Keeps the
+// surrounding request's ids so correlation survives, and mints fresh ones
+// when there is no surrounding request (job-runner, event-dispatcher) —
+// requestId/correlationId are mandatory, `get()` may be undefined.
+export function runWithOrigin<T>(
+  origin: { readonly feature?: string; readonly handler?: string },
+  fn: () => T,
+): T {
+  const current = requestContext.get();
+  const requestId = current?.requestId ?? requestContext.generateId();
+  return requestContext.run(
+    {
+      ...current,
+      requestId,
+      correlationId: current?.correlationId ?? requestId,
+      feature: origin.feature,
+      handler: origin.handler,
+    },
+    fn,
+  );
+}

package/src/api/request-id-middleware.ts

@@ -62,6 +62,7 @@ export function buildRequestContextDataFromRequest(req: Request): RequestContext
   return {
     requestId,
     correlationId,
+    startedAt: performance.now(),
     ...(signal ? { signal } : {}),
     ...(ip && ip.length > 0 ? { ip } : {}),
     ...(userAgent !== undefined ? { userAgent } : {}),
@@ -81,7 +82,7 @@ export function buildRequestContextData(c: Context): RequestContextData {
   // instead of letting req.headers.get() throw on every request.
   if (!c.req.raw) {
     const requestId = requestContext.generateId();
-    return { requestId, correlationId: requestId };
+    return { requestId, correlationId: requestId, startedAt: performance.now() };
   }
   return buildRequestContextDataFromRequest(c.req.raw);
 }

package/src/api/routes.ts

@@ -333,15 +333,47 @@ function assertPatAllowed(user: SessionUser, type: string): void {
   }
 }
 
+// Log levels that silence the 4xx tier. Checked here and not in the logger
+// because this module uses the console fallback, which pino's level never
+// reaches — LOG_LEVEL is the volume knob for client faults.
+const FAULT_LOG_SILENCED_LEVELS = new Set(["error", "fatal", "silent"]);
+
+// `type` is client-supplied on an unknown-handler 404, so cap it before it
+// reaches the log — an unbounded field would let a caller flood the sink.
+const MAX_LOGGED_TYPE_LENGTH = 120;
+
+function clientFaultLoggingEnabled(): boolean {
+  return !FAULT_LOG_SILENCED_LEVELS.has(process.env["LOG_LEVEL"] ?? "");
+}
+
+// A failing request must leave a trace even when it ends in 4xx — a paid
+// external call that 422s was invisible before (offlot#117). Status, error
+// code and duration only: message/details/stack can carry submitted values.
+function logClientFault(err: KumikoError, requestId: string | undefined, type?: string): void {
+  if (!clientFaultLoggingEnabled()) {
+    // skip: LOG_LEVEL silences the 4xx tier — the deployment opted out of client-fault volume
+    return;
+  }
+  const startedAt = requestContext.get()?.startedAt;
+  createFallbackLogger("api").warn("handler rejected", {
+    requestId,
+    type: type?.slice(0, MAX_LOGGED_TYPE_LENGTH),
+    status: err.httpStatus,
+    code: err.code,
+    ...(startedAt === undefined ? {} : { durationMs: Math.round(performance.now() - startedAt) }),
+  });
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
-// log lines, leaving ops nothing to debug (the bug this guards). 4xx are
-// expected client outcomes and stay unlogged. `type` is the only handler
+// log lines, leaving ops nothing to debug (the bug this guards). 4xx take the
+// redacted `warn` line above instead. `type` is the only handler
 // discriminator — every request hits the same /api/{query,command} path.
 function logServerFault(err: KumikoError, requestId: string | undefined, type?: string): void {
   if (err.httpStatus < 500) {
-    // skip: 4xx are expected client outcomes (not-found, validation, denied) — logging them is noise
+    logClientFault(err, requestId, type);
+    // skip: 4xx already logged on warn by logClientFault — the error level stays 5xx-only
     return;
   }
   const cause = err.cause;

package/src/api/server.ts

@@ -19,6 +19,7 @@ import {
   registerStandardMetrics,
   wrapRedisClient,
 } from "../observability";
+import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership";
 import type { DispatcherOptions } from "../pipeline/dispatcher";
 import { createDispatcher, type Dispatcher } from "../pipeline/dispatcher";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state";
@@ -43,7 +44,12 @@ import {
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS } from "./api-constants";
-import { type AnonymousAccessResolved, authMiddleware, getUser } from "./auth-middleware";
+import {
+  type AnonymousAccessResolved,
+  authMiddleware,
+  getUser,
+  type TenantLifecycleStatusResolver,
+} from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
@@ -670,12 +676,16 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // a token (or, when anonymousAccess is wired, falls through as anonymous).
   // A session-checker is forwarded when the auth-config wires one, so the
   // middleware can reject revoked sids on every request.
+  // Mounting a tenantLifecycleStatus provider is what turns the 410 on, so no
+  // entrypoint can forget the wiring; `??` short-circuits, so an explicit
+  // auth.resolveTenantLifecycleStatus remains the override.
+  const tenantLifecycleResolver =
+    options.auth?.resolveTenantLifecycleStatus ??
+    deriveTenantLifecycleResolver(options.registry, baseDb);
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
-    ...(options.auth?.resolveTenantLifecycleStatus
-      ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
-      : {}),
+    ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {
@@ -890,6 +900,22 @@ export function buildServer(options: ServerOptions): KumikoServer {
   };
 }
 
+function deriveTenantLifecycleResolver(
+  registry: Registry,
+  db: DbConnection | undefined,
+): TenantLifecycleStatusResolver | undefined {
+  const plugin = resolveTenantLifecyclePlugin(registry, "buildServer");
+  if (!plugin) return undefined;
+  if (!db) {
+    throw new Error(
+      "[kumiko] a tenantLifecycleStatus provider is mounted (tenant-lifecycle) but context.db is " +
+        "missing — the request-level teardown gate needs a DbConnection. Pass context.db, or wire " +
+        "auth.resolveTenantLifecycleStatus explicitly.",
+    );
+  }
+  return (tenantId) => plugin.resolveStatus(tenantId, { db });
+}
+
 // Scans every feature's entities for a file/image/files/images field. Short-
 // circuits on the first hit — no need to build a full inventory, we only want
 // the yes/no answer for the boot check.