@cosmicdrift/kumiko-framework 0.288.0 → 0.290.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.288.0",
+  "version": "0.290.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.288.0",
-    "@cosmicdrift/kumiko-types": "0.288.0",
+    "@cosmicdrift/kumiko-http": "0.290.0",
+    "@cosmicdrift/kumiko-types": "0.290.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.288.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.290.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/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/request-context.ts

@@ -38,6 +38,12 @@ 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;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -55,3 +61,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/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.

package/src/changes.json

@@ -1,4 +1,79 @@
 [
+  {
+    "version": "0.290.0",
+    "type": "improvement",
+    "title": "Event-Attribution: metadata.feature + metadata.handler auf jedem Event",
+    "detail": "event-store.append() stempelt Feature und Handler-Namen aus dem Ausfuehrungsscope (requestContext) auf jedes geschriebene Event. Dispatch-Handler, Entity-Executor-Writes, MSP-Applies und Jobs sind damit ohne Signaturaenderung attribuiert; Appends ausserhalb eines Scopes tragen UNATTRIBUTED_ORIGIN. appendRaw/appendRawBatch bleiben unveraendert."
+  },
+  {
+    "version": "0.290.0",
+    "type": "fix",
+    "title": "Section readers see groups[].fields",
+    "detail": "Boot-guard and E2E-generator now flatten section.groups via sectionFieldSpecs instead of iterating section.fields only: a function renderer inside groups[].fields fails at boot, and generated E2E specs cover group fields (required fields, fill ops, text assertions)."
+  },
+  {
+    "version": "0.290.0",
+    "type": "improvement",
+    "title": "The tenant-teardown 410 gate is derived from the mounted tenantLifecycleStatus provider (fw#2881).",
+    "detail": "buildServer now resolves the EXT_TENANT_LIFECYCLE_STATUS extension point itself, so every server with tenant-lifecycle mounted rejects requests against a tenant in teardown with 410 tenant_unavailable — prod, dev and test stacks can no longer drift because one entrypoint forgot the wiring. An explicit auth.resolveTenantLifecycleStatus still takes precedence and stays the escape hatch. A mounted provider without context.db is a boot error instead of a silently skipped gate."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "appendProvenanceEvent enforces event.tenantId === db.tenantId",
+    "detail": "`appendProvenanceEvent(db, event)` checked the event type namespace but wrote `event.tenantId` unverified while granting itself the framework-fixed unsafeRaw reason internally. Since `createLLMProviderForTenant(ctx, tenantId, …)` takes the tenantId as an argument, that made the entry point a cross-tenant write door with no escapeHatch declaration behind it.\nThe check now runs after `unsafeRawForDeclaredStep` — so a holder not built by `createTenantDb` still fails closed with `InternalError` first — and before the savepoint, so a rejected append leaves no row. It is unconditional, including `mode: \"system\"`: `crossTenantRebinders` keeps the original tenantId and only flips the mode, so a system-scoped db must not append provenance for a foreign tenant either.\n`appendProvenanceEvent` deliberately keeps `withUnsafeRawGrant` + `unsafeRawForDeclaredStep` instead of resolving the runner through the ungated `tenantDbRunner`, because that grant path is the choke point the member-read lock in kumiko-framework#2927 hooks into.",
+    "migration": "appendProvenanceEvent rejects with AccessDeniedError when event.tenantId does not match the tenantId of the passed TenantDb. Provenance for a foreign tenant has no path left through this entry point — a caller that needs it declares its own escapeHatch path instead. Blast radius checked: every known call site in kumiko-enterprise passes event.user.tenantId through, so no call site changes."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "Boot fails when an anonymous-accessible handler declares no rateLimit",
+    "detail": "validateAnonymousRateLimit (packages/framework/src/engine/boot-validator/entity-handler.ts) previously returned early when a handler declared no rateLimit at all, so an anonymous, internet-facing handler with zero throttling passed boot silently while one with a merely wrong bucket (rateLimit.per=\"user\") was rejected. The check now runs for every handler whose access.roles includes \"anonymous\": it still skips openToAll handlers (they never admit anonymous) and rateLimit: { disabled: true, reason } declarations, but a handler with access.roles including \"anonymous\" and no rateLimit at all now throws at boot, naming the handler.",
+    "migration": "Every handler whose access.roles includes \"anonymous\" needs a rateLimit declaration: either rateLimit: { per: \"ip\" | \"ip+handler\", limit, windowSeconds } (per must not be \"user\"/\"user+handler\" — anonymous callers share user.id=\"anonymous\", so a user-keyed bucket is a single global tap), or the documented exception rateLimit: { disabled: true, reason: \"...\" } for a handler that must not be rate-limited. This PR fixes the eight bundled-features handlers that tripped this at authoring time: compliance-profiles:query:sub-processors, template-resolver:query:by-slug, template-resolver:query:by-tenant, managed-pages:query:by-slug, managed-pages:query:by-tenant-published, managed-pages:query:branding, auth-email-password:query:signup-registration-status, seo:query:config."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "ctx.db.unsafeRaw is denied under ctx.queryAsMember",
+    "migration": "Query handlers reached through ctx.queryAsMember can no longer call ctx.db.unsafeRaw — not even for reads. Move them to the ctx.db query APIs, or stop calling them via queryAsMember. Consequence for kumiko-enterprise: ai-call provenance writes under queryAsMember now fail closed; withProvenance swallows the error and counts provenance_drop_total."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Drawer gains a modal prop for non-modal side panels",
+    "detail": "Drawer accepts modal (default true, behavior unchanged). With modal={false} the overlay and the focus trap are gone, so the page behind stays interactive and its text can be selected and copied; Escape still closes, a click beside the panel does not."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Entity graph traversal helpers for cross-tenant ownership changes",
+    "detail": "physicalColumnName is now exported from @cosmicdrift/kumiko-framework/db (was framework-internal). storageKeyStemPrefix (files/file-handle.ts) gives the prefix that covers a stored file's key plus every derive()d variant. StorageProviderHookCtx (EXT_STORAGE_PROVIDER destroy hooks) gains db: DbRunner — the tenant-destroy stage runner already carried it for this hook family unconditionally, this only widens the declared type to match. TenantDataHookCtx (EXT_TENANT_DATA destroy hooks) gains fileProviderResolver and log, threaded through from the same stage runner. Built for the tenant-handover bundled feature (kumiko-framework#3035); no behavior change for existing hook implementations that don't read the new fields."
+  },
+  {
+    "version": "0.289.0",
+    "type": "fix",
+    "title": "EventDispatcher gains drain() for race-free test teardown",
+    "detail": "New `EventDispatcher.drain(): Promise<void>` waits out a pass already in flight (the timer tick or LISTEN/NOTIFY wake-up a suite's own `.start()` triggered) without touching the timer or the LISTEN subscription — unlike `stop()`, the dispatcher keeps running afterwards. `stack/table-helpers.ts`'s `resetEventStore` now calls it before truncating `kumiko_events` and the other framework tables, so a beforeEach/afterEach reset can no longer race a pass this same dispatcher started (kumiko-framework#3017): every suite that calls `resetEventStore` after starting the dispatcher (directly or via `jobs`) inherits the fix automatically. No behavior change for suites that never start the dispatcher — `drain()` is then a no-op, since nothing is ever in flight."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "Event-store executor writes accept a declarative `expect:` precondition",
+    "detail": "`expect: { field: value }` on an executor write applies the change only if those fields still hold at write time, turning a check-then-act sequence into one step. Values are scalars (string/number/boolean/null) compared with strict equality; several fields mean AND, and the first mismatch names its field. A failed precondition raises the new `PreconditionFailedError` instead of writing.\nThe precondition fields and the `version` used for the append are read in one query, so a concurrent writer cannot slip between the check and the append — reading them separately reproduced a ~40% failure rate under real concurrency. The version is taken from the event stream itself, not from the projection row: a projection `version` is only in step for rows the executor wrote, so a row seeded directly would otherwise be checked against a predecessor that never existed."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "PLATFORM_KEK can now be resolved from a Key Manager ciphertext at boot",
+    "detail": "New `resolvePlatformKeks` (packages/framework/src/crypto/kek-source.ts) decrypts `PLATFORM_KEK_CIPHERTEXT` / `PLATFORM_KEK_PREVIOUS_CIPHERTEXT` through Scaleway Key Manager when the matching plaintext (`PLATFORM_KEK` / `PLATFORM_KEK_PREVIOUS`) is absent, so the KEK no longer has to sit in the pod env in the clear. Each slot resolves independently: a plaintext value always wins over its ciphertext sibling with no request made, which keeps a KEK rollback bootable without a network call. `resolveKmsWiringAsync` and `requireKmsWiringAsync` wrap the existing sync `resolveKmsWiring` / `requireKmsWiring` with this resolution step; the sync functions and every other exported signature are unchanged. `PLATFORM_KEK` plaintext stays fully valid and keeps precedence — this is purely additive. Boot now logs one line per configured slot naming the source it used (`source=plaintext-env`, `source=key-manager keyId=… region=…`, and explicitly `(ciphertext present and ignored)` when a leftover plaintext wins), because a half-finished cutover otherwise boots green and looks exactly like a finished one. The line carries no key material and no token; `options.log` redirects it, the default is `console.info`."
+  },
+  {
+    "version": "0.289.0",
+    "type": "breaking",
+    "title": "requiredKeysFromScreen reads section.groups — group field labels and group titles are i18n-required",
+    "detail": "`requiredKeysFromScreen` (packages/framework/src/i18n/required-surface-keys.ts) read only `section.fields` in all six `EditFieldsSection` branches (`entityEdit`, `actionForm`, `secretMint` mint + confirm layout, `configEdit`, `projectionDetail`), so a field declared through `section.groups` never reached the required-key set and `groups[].title` was never required at all — while `computeEditViewModel` translates a group title exactly like a section title. `validateI18nSurfaceKeys` therefore let a screen boot with untranslated group field labels and group titles, the one error class that guard exists for.\nThe new `sectionFieldSpecs` in packages/framework/src/engine/screen-helpers.ts returns the union of `section.fields` and `section.groups[].fields` (a union, unlike the boot-validator's either-or `flattenFieldsOrGroups`, which runs after the fields-XOR-groups check) and is used at all six branches; each branch now also pushes every `groups[].title` alongside `section.title`, honoring the same `treatDotFormAsKey` option. The `writeForm` branch in `projectionDetail` is unchanged — `EditWriteFormSection` has no `groups`.",
+    "migration": "The i18n boot guard now demands translations it silently skipped before. An app whose entityEdit/actionForm/secretMint/configEdit/projectionDetail screens declare fields through `layout.sections[].groups` can newly fail boot with `required translation key missing: \"<feature>:entity:<entity>:field:<name>\"`. Add the missing field-label keys (or a `fieldLabels` override, where that screen type supports one) for every field declared under `groups[].fields`. Colon-form `groups[].title` values are now required too — add the key, or keep the title as literal display text (no colon, no `i18nKey()`) if it is not meant to be translated. Dot-form group titles behave exactly like dot-form section titles: only required when the caller passes `treatDotFormAsKey`."
+  },
   {
     "version": "0.287.0",
     "type": "improvement",

package/src/compliance/__tests__/sub-processors.test.ts

@@ -113,6 +113,16 @@ describe("KUMIKO_SUB_PROCESSORS", () => {
           "sccRequired": false,
           "status": "active",
         },
+        {
+          "appliesTo": [
+            "all-tiers",
+          ],
+          "name": "Scaleway SAS",
+          "optInOnly": false,
+          "region": "EU (France)",
+          "sccRequired": false,
+          "status": "active",
+        },
       ]
     `);
   });

package/src/compliance/sub-processors.ts

@@ -4,7 +4,10 @@
 // Plattform-Betrieb einsetzt. Wird oeffentlich exposed unter
 //   /api/compliance/sub-processors        (JSON, Sprint 1)
 //   /api/compliance/sub-processors.rss    (RSS, Sprint 1)
-//   kumiko.rocks/subprocessors               (HTML, Marketing-Repo)
+//
+// Separate from the public marketing overview (kumiko.rocks/subprocessors),
+// which is compiled independently from templates/legal/_shared/subprocessors/
+// catalog.*.md. The two lists are not synced.
 //
 // Tenant-Admins muessen ueber Add/Change/Remove informiert werden mit
 // Lead-Time aus dem Compliance-Profile (typisch 30d). Cron-Job kommt
@@ -132,6 +135,16 @@ export const KUMIKO_SUB_PROCESSORS: readonly SubProcessor[] = [
     appliesTo: ["all-tiers"],
     status: "active",
   },
+  {
+    name: "Scaleway SAS",
+    purpose:
+      "Offsite Backup Mirror (Object Storage); planned: platform key custody (Key Manager) and Transactional Email",
+    region: "EU (France)",
+    dpa: "https://www.scaleway.com/en/contracts/",
+    addedAt: "2026-09-18",
+    appliesTo: ["all-tiers"],
+    status: "active",
+  },
 ];
 
 /**

package/src/crypto/__tests__/blind-index.test.ts

@@ -25,7 +25,7 @@ const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
 const userLikeEntity = createEntity({
   fields: {
     email: createTextField({ required: true, personal: "self", find: "exact" }),
-    role: createTextField(),
+    role: createTextField({ personal: false, reason: "test_fixture" }),
   },
   table: "bidx_users",
 });