@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/api/server.ts

@@ -2,7 +2,9 @@ import { Hono, type MiddlewareHandler } from "hono";
 import { ROLES } from "../auth/roles";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
+import { buildAppSchema } from "../engine/build-app-schema";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names";
+import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles";
 import { runsInLane } from "../engine/run-in";
 import { ANONYMOUS_ROLE, createAnonymousUser, createSystemUser } from "../engine/system-user";
 import {
@@ -11,12 +13,13 @@ import {
   isFileField,
   type Registry,
   type RunIn,
+  type SessionUser,
   type TenantId,
   type WriteResult,
 } from "../engine/types";
 import { createFileContext } from "../files/file-handle";
 import type { FileRoutesOptions } from "../files/file-routes";
-import { createFileRoutes } from "../files/file-routes";
+import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes";
 import { makeFileProviderResolver } from "../files/provider-resolver";
 import type { Lifecycle } from "../lifecycle";
 import {
@@ -52,8 +55,9 @@ import {
 } from "../rate-limit";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config";
 import type { SearchAdapter } from "../search/types";
+import type { AppSchema } from "../ui-types/app-schema";
 import { assertUnreachable, generateId } from "../utils";
-import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS } from "./api-constants";
+import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants";
 import {
   type AnonymousAccessResolved,
   authMiddleware,
@@ -61,6 +65,12 @@ import {
   type TenantLifecycleStatusResolver,
 } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes, type LoginRateLimiter } from "./auth-routes";
+import {
+  assertValidTrustedProxyHops,
+  type ClientIpResolver,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+} from "./client-ip";
 import { csrfMiddleware } from "./csrf-middleware";
 import {
   type ExtraRouteDefinition,
@@ -69,9 +79,11 @@ import {
   ExtraRouteRejection,
   type SystemDispatchArgs,
 } from "./extra-route";
+import { computeStrongEtag, etagMatches } from "./http-cache";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, normalizeOrigin, originMiddleware } from "./origin-middleware";
+import { patRouteGuard } from "./pat-route-guard";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
@@ -102,6 +114,12 @@ export type ServerOptions = {
   eventDedup?: EventDedup;
   sseBroker?: SseBroker;
   auth?: AuthRoutesConfig;
+  // Number of trusted reverse-proxy hops for client-IP resolution — feeds
+  // requestIdMiddleware's `ip`, the L1/L2
+  // rate-limit middleware below, and createAuthRoutes. Wins over the
+  // deprecated `auth.trustedProxyHops`. Default 0 = trust no proxy header,
+  // only the socket address (or "unknown") counts — see client-ip.ts.
+  trustedProxyHops?: number;
   // No `files` option: file-storage is wired by mounting `file-foundation` +
   // a `file-provider-*` feature. Upload routes, ctx.files and the GDPR jobs
   // resolve the provider per-tenant through that single source (issue #608).
@@ -294,6 +312,17 @@ export function withFileProviderResolver(registry: Registry, context: AppContext
 }
 
 export function buildServer(options: ServerOptions): KumikoServer {
+  // Single effective hop-count for every IP-derived rate-limit + requestMeta
+  // below — the top-level option wins over the deprecated
+  // `auth.trustedProxyHops` fallback.
+  const trustedProxyHops = options.trustedProxyHops ?? options.auth?.trustedProxyHops ?? 0;
+  assertValidTrustedProxyHops(trustedProxyHops, "buildServer");
+  // Exactly ONE resolver for the whole server — the warn-once flag must fire
+  // once per boot, not once per consumer (requestIdMiddleware, L1, L2,
+  // auth-routes each sharing this same instance rather than building a
+  // private one).
+  const clientIpResolver = createClientIpResolver(trustedProxyHops, "buildServer");
+
   // File-storage is resolved per-tenant through file-foundation: a mounted
   // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
   // uploads, ctx.files and the GDPR jobs.
@@ -588,6 +617,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
         ...(mspFiles && { files: mspFiles }),
+        ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
         ...(mspFiles && {
           derivatives: createDerivativesContext({
             files: mspFiles,
@@ -668,7 +698,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     registerMetricsRoute(app, observability.meter, options.metrics);
   }
 
-  app.use("/api/*", requestIdMiddleware());
+  app.use("/api/*", requestIdMiddleware({ resolver: clientIpResolver }));
 
   // Cap JSON bodies before rate-limit/auth/observability even run. Header-
   // check is O(1); oversized requests never allocate memory for a full body
@@ -691,12 +721,19 @@ export function buildServer(options: ServerOptions): KumikoServer {
     if (options.rateLimit?.global) {
       app.use(
         "/api/*",
-        globalIpRateLimit({ ...options.rateLimit.global, resolver: rateLimitResolver }),
+        globalIpRateLimit({
+          ...options.rateLimit.global,
+          resolver: rateLimitResolver,
+          clientIpResolver,
+        }),
       );
     }
     if (options.rateLimit?.auth) {
       const { path: l2Path = "/api/auth/*", ...l2Opts } = options.rateLimit.auth;
-      app.use(l2Path, authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver }));
+      app.use(
+        l2Path,
+        authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver, clientIpResolver }),
+      );
     }
   }
   // Observability span wraps everything that follows (auth, routes).
@@ -746,6 +783,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return jwtGuard(c, next);
   });
 
+  // Fail-closed PAT scoping: a PAT-authenticated caller (user.pat set by
+  // jwtGuard's tokenVerifier above) may only reach the dispatcher routes —
+  // everywhere else on /api/* is off-limits regardless of granted scopes.
+  const patRouteGuardMiddleware = patRouteGuard();
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
+    return patRouteGuardMiddleware(c, next);
+  });
+
   // Without anonymousAccess a missing token 401s instead of falling through as anonymous.
   const sessionOnlyGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
@@ -799,9 +845,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
     return csrfGuard(c, next);
   });
 
-  // Same order as /api/* above: auth → PAT → origin → CSRF.
+  // Same order as /api/* above: auth → PAT route scope → PAT rate-limit → origin → CSRF.
   const sessionOnlyHttpRouteGuards: readonly MiddlewareHandler[] = [
     sessionOnlyGuard,
+    patRouteGuardMiddleware,
     ...(patRateLimitGuard ? [patRateLimitGuard] : []),
     ...(originGuard ? [originGuard] : []),
     csrfGuard,
@@ -822,7 +869,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
           "need it to reject blocked principals).",
       );
     }
-    app.route("/api", createAuthRoutes(dispatcher, jwt, options.auth));
+    app.route(
+      "/api",
+      createAuthRoutes(dispatcher, jwt, { ...options.auth, resolver: clientIpResolver }),
+    );
   }
   app.route(
     "/api",
@@ -832,6 +882,47 @@ export function buildServer(options: ServerOptions): KumikoServer {
   );
   app.route("/api", createSseRoute(sseBroker));
 
+  // GET /api/schema — the only way a client obtains the AppSchema. Behind
+  // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user
+  // also gets rejected below — the schema never reaches an unauthenticated
+  // caller. The FULL schema is built lazily once — the registry is
+  // immutable for this server's lifetime, so it's the same on every
+  // request — then projected per caller-role-set (fw#3314: a role only
+  // sees the screens/navs/workspaces/content-collections it may reach,
+  // not the whole app's schema) and cached per role key. Tenant is
+  // deliberately NOT part of the key: the projection depends only on
+  // roles, and per-tenant caching would grow unboundedly across tenants
+  // that share the same role set.
+  let fullSchema: AppSchema | undefined;
+  const projectedSchemaCache = new Map<string, { readonly json: string; readonly etag: string }>();
+  app.get(`/api${Routes.schema}`, (c) => {
+    const user = getUser(c);
+    if (isMissingOrAnonymousUser(user)) {
+      return unauthenticatedResponse(c);
+    }
+    const roleKey = JSON.stringify([...new Set(user?.roles ?? [])].sort());
+    let cached = projectedSchemaCache.get(roleKey);
+    if (cached === undefined) {
+      if (fullSchema === undefined) {
+        fullSchema = buildAppSchema(options.registry, {
+          searchAdapterMissing: !options.context.searchAdapter,
+        });
+      }
+      const projected = projectAppSchemaForRoles(fullSchema, user?.roles ?? []);
+      const json = JSON.stringify(projected);
+      cached = { json, etag: computeStrongEtag(json) };
+      projectedSchemaCache.set(roleKey, cached);
+    }
+    const cacheHeaders = { "Cache-Control": "private, no-cache", ETag: cached.etag };
+    if (etagMatches(c.req.header("If-None-Match") ?? null, cached.etag)) {
+      return c.body(null, 304, cacheHeaders);
+    }
+    return c.body(cached.json, 200, {
+      "Content-Type": "application/json; charset=utf-8",
+      ...cacheHeaders,
+    });
+  });
+
   // Mount upload/download routes whenever a file provider is resolvable (a
   // file-provider plugin is mounted, or a resolver was injected). They resolve
   // the provider per-tenant through file-foundation — no `files` option; route
@@ -881,7 +972,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
           // would leak it into the response. The forced tenant already
           // comes from bypassing the HTTP layer entirely; no elevated
           // role is needed or wanted on top of that.
-          systemQuery: makeSystemQuery(c, dispatcher),
+          systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
+          clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
         });
       mountHonoRoute(
         app,
@@ -941,6 +1033,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         secrets: contextWithObservability.secrets,
         dispatchSystemWrite,
         dispatchSystemQuery,
+        clientIpResolver,
       });
       mountHonoRoute(app, route.method, route.path, honoHandler);
     }
@@ -1057,9 +1150,10 @@ function makeSystemQuery(
   // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
   c: import("hono").Context<any, any>,
   dispatcher: Dispatcher,
+  clientIpResolver?: ClientIpResolver,
 ): (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown> {
   return (type, payload, tenantId) =>
-    requestContext.run(requestContext.get() ?? buildRequestContextData(c), () =>
+    requestContext.run(requestContext.get() ?? buildRequestContextData(c, clientIpResolver), () =>
       dispatcher.query(type, payload, createAnonymousUser(tenantId)),
     );
 }
@@ -1103,6 +1197,27 @@ function makeAnonymousWrite(
   };
 }
 
+// Shared by entry:"user" extra routes and GET /api/schema — both require a
+// real, signed-in principal and reject the synthesised anonymousAccess user
+// (SessionUser.roles includes ANONYMOUS_ROLE) the same way.
+function isMissingOrAnonymousUser(user: SessionUser | undefined): boolean {
+  return !user || user.roles.includes(ANONYMOUS_ROLE);
+}
+
+function unauthenticatedResponse(c: import("hono").Context): Response {
+  return c.json(
+    {
+      error: {
+        code: "unauthenticated",
+        httpStatus: 401,
+        message: "this route requires a signed-in user",
+        i18nKey: "auth.errors.missingToken",
+      },
+    },
+    401,
+  );
+}
+
 function isKnownExtraRouteEntry(entry: unknown): entry is ExtraRouteEntry {
   return (
     entry === ExtraRouteEntries.anonymous ||
@@ -1146,6 +1261,7 @@ type ExtraRouteHonoHandlerDeps = {
   readonly secrets: import("../secrets").SecretsContext | undefined;
   readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
   readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+  readonly clientIpResolver: ClientIpResolver;
 };
 
 function buildExtraRouteHonoHandler(
@@ -1159,24 +1275,15 @@ function buildExtraRouteHonoHandler(
         route.handler(c, {
           app: shared.app,
           registry: shared.registry,
-          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           write: makeAnonymousWrite(c, shared.dispatcher),
+          clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
         });
     case ExtraRouteEntries.user:
       return async (c) => {
         const user = getUser(c);
-        if (!user || user.roles.includes(ANONYMOUS_ROLE)) {
-          return c.json(
-            {
-              error: {
-                code: "unauthenticated",
-                httpStatus: 401,
-                message: "this route requires a signed-in user",
-                i18nKey: "auth.errors.missingToken",
-              },
-            },
-            401,
-          );
+        if (isMissingOrAnonymousUser(user)) {
+          return unauthenticatedResponse(c);
         }
         return route.handler(c, {
           app: shared.app,
@@ -1220,7 +1327,7 @@ function buildExtraRouteHonoHandler(
           app: shared.app,
           registry: shared.registry,
           secrets: shared.secrets,
-          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           dispatchSystemWrite: shared.dispatchSystemWrite,
           dispatchSystemQuery: shared.dispatchSystemQuery,
         });
@@ -1282,20 +1389,3 @@ function entitiesWithSearchableScreen(registry: Registry): readonly string[] {
   }
   return [...entities];
 }
-
-// Upload-route policy carried by createFilesFeature(opts?) — read from the
-// feature's exports so buildServer applies it without a parallel ServerOptions
-// surface. Absent feature / opts → defaults in createFileRoutes.
-function readFilesRouteOptions(
-  registry: Registry,
-): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize"> {
-  const exp = registry.features.get("files")?.exports;
-  if (exp && typeof exp === "object" && "routeOptions" in exp) {
-    const ro = (exp as { routeOptions?: unknown }).routeOptions;
-    if (ro && typeof ro === "object") {
-      // @cast-boundary feature-exports: engine-payload (unknown) → known shape
-      return ro as Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;
-    }
-  }
-  return {};
-}

package/src/changes.json

@@ -1,4 +1,125 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-schema gained --help/-h/help",
+    "detail": "Prints usage listing the available subcommands and exits 0.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "parseTrustedProxyHopsEnv/TRUSTED_PROXY_HOPS_ENV factored out of runProdApp for runDevApp and consumer tooling to share",
+    "detail": "`packages/framework/src/api/client-ip.ts` gained\n`parseTrustedProxyHopsEnv(raw, context)` and the\n`TRUSTED_PROXY_HOPS_ENV = \"KUMIKO_TRUSTED_PROXY_HOPS\"` constant (both\nexported via the `api` barrel), moved out of `runProdApp`'s inline\nparsing. Same validation and error message as before.",
+    "migration": "No action needed; runProdApp's behavior and error message are unchanged."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "AnonymousExtraRouteDeps gained clientIp, resolved by the server's trustedProxyHops-aware resolver",
+    "detail": "`AnonymousExtraRouteDeps.clientIp: string`, populated the same way as the\nhttpRoute path via `shared.clientIpResolver.resolve\n(clientIpSourceFromHonoContext(c))`. `ExtraRouteHonoHandlerDeps\n.clientIpResolver` is now required (its only caller always supplied it).",
+    "migration": "Anonymous extra routes that need the caller's IP should read\n`deps.clientIp` instead of reading `X-Forwarded-For` (or any other\nheader) themselves — the latter is attacker-controlled unless you also\nknow the exact trusted-hop count. Tests that build an\n`AnonymousExtraRouteDeps` literal by hand must add a `clientIp` string."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "feature-ast resolves imported constants and registrar wrappers without building a TypeScript program",
+    "detail": "Imported `const` initializers (named imports, aliases, `export { X as Y }`,\nre-export chains, `export *`) and imported registrar-wrapper functions are\nresolved through `ts.resolveModuleName` plus a syntactic export walk.\nSame-file lookups walk enclosing block scopes instead of the file top level. Parse\noutput is unchanged; parsing a feature file drops from hundreds of\nmilliseconds to a few milliseconds."
+  },
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "webhook.send step auth secretRef renamed to secret; MultiStreamApplyContext gained an optional secrets field",
+    "detail": "`r.step.webhook.send`'s `auth` union renamed `secretRef` → `secret` (see\nthe step-dispatcher entry for the full rationale). `MultiStreamApplyContext`\n(and `createMultiStreamApplyContext`'s deps) gained an optional\n`secrets?: SecretsContext` field, mirroring `files`/`derivatives` — present\nwhen the app booted with the secrets feature, letting a saga/process-\nmanager MSP apply read a tenant secret with its own audit context. The\nserver's MSP consumer wiring now threads the boot-time `AppContext.secrets`\nthrough automatically; `rebuildMultiStreamProjection`'s rebuild context\ndeliberately does not carry `secrets` (rebuild must stay side-effect-free).",
+    "migration": "Rename `auth.secretRef` → `auth.secret` at every `r.step.webhook.send`\ncall site. No action needed for `MultiStreamApplyContext` consumers that\ndon't read `ctx.secrets` — the field is optional and additive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "New event-store primitive transferAggregateStreams for tenant-to-tenant aggregate moves",
+    "detail": "`transferAggregateStreams(db, { sourceTenantId, destinationTenantId,\naggregateType, aggregateIds, transferredBy })` (event-store/transfer.ts)\nmoves an aggregate's events, drops its snapshot, and carries its archive\nmarker from one tenant to another, then appends one\n`kumiko:system:aggregate.transferred` system event per moved aggregate\n(own fresh stream, destination tenant, payload carries aggregateType/\naggregateId/sourceTenantId/destinationTenantId). An id with no events\nunder the given tenant/aggregateType is left untouched and gets no event.\nBacked by db/queries/event-store-transfer.ts.",
+    "migration": "No action for existing consumers — this is a new, additive primitive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "fix",
+    "title": "upgrade-cli now collects every package's changes.json, not just framework's",
+    "detail": "`findCoreChangelogFile(cwd): string | null` is replaced by\n`findPackageChangelogFiles(cwd): string[]`. In the framework repo itself\nit collects every `packages/<dir>/src/changes.json` except\n`packages/bundled-features` (bundled features are already collected per\nfeature dir). In a consumer repo it walks up to 10 levels looking for\n`node_modules/@cosmicdrift/*/src/changes.json`, skipping\n`kumiko-bundled-features`, deduping by package name (nearest\n`node_modules` wins) and by realpath (symlinked workspace copies).",
+    "migration": "No action needed — `kumiko upgrade` now surfaces more relevant breaking\nchanges than before, it never hides ones it previously showed."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "Centralized client-IP resolver replaces the old first-XFF-entry heuristic",
+    "detail": "New `trustedProxyHops` option on `ServerOptions` (default 0 — trusts no\nproxy header, only the socket address counts). Precedence:\n`options.trustedProxyHops ?? options.auth?.trustedProxyHops ?? 0`.\n`requestContext.ip` is now always set for an HTTP request (falls back to\n\"unknown\" instead of being left undefined), so `rateLimit: { per: \"ip\" }`\nhandlers reached via `r.httpRoute`/`extraRoutes` systemQuery are never\nsilently unthrottled. `rate-limit/middleware.ts`'s `globalIpRateLimit`/\n`authEndpointRateLimit` and `auth-routes.ts`'s `createAuthRoutes` gained a\n`trustedProxyHops`/`clientIpResolver` option and now share the server's\none resolver instance instead of each building their own.",
+    "migration": "Apps deployed behind a reverse-proxy/ingress that appends to\nX-Forwarded-For must set `trustedProxyHops` (buildServer/runProdApp/\nrunDevApp top-level option) to the number of trusted hops — usually `1`\nfor a single ingress. Without it, every client collapses into one shared\nrate-limit bucket (safe default, but likely too strict for real traffic).\nApps not behind a proxy need no change; `trustedProxyHops` defaults to 0.\n\nIntegration tests that call an `ip`/`ip+handler`-rate-limited handler\nrepeatedly through `stack.http.raw`/`stack.app.request` (no real socket)\nnow share one \"unknown\" bucket instead of skipping the bucket entirely —\na previously-passing test suite can start seeing 429s. Fix by flushing\nthe rate-limit namespace between test cases (`stack.redis.flushNamespace()`\nin `beforeEach`), or by setting `setupTestStack({ trustedProxyHops: 1 })`\nand sending a distinct `X-Forwarded-For` per test case. Also check any\ntest that nulls `context.redis` via `extraContext` to exercise a\nhandler's own redis-down guard: `setupTestStack` now keeps the L3\nrate-limit resolver alive from its own always-real Redis in that case\n(an explicit `context.rateLimit` still wins), so a handler-declared\n`rateLimit` is enforced instead of throwing `InternalError` for a missing\nresolver."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Upload requests are now size-checked before the body is buffered",
+    "detail": "`POST /api/files` previously ran `parseBody()` on the full multipart request before any size check, so the body was parsed in full before the configured `maxUploadSize` ever ruled it out. It now rejects requests over the configured limit (checked upfront via `Content-Length`, and while streaming for chunked bodies) with a 413 before parsing. `runProdApp` and the dev server now also derive `Bun.serve`'s request-body cap from that same `maxUploadSize`/field `maxSize` configuration instead of Bun's own 128 MiB default; `buildBunServeOptions` keeps a lower fixed fallback for direct callers, overridable via `runProdApp`'s new `maxRequestBodySize` option."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Dev-boot backfills nullable columns a persistent dev DB is missing",
+    "detail": "`pushEntityProjectionTables` (packages/framework/src/stack) now diffs an\nexisting implicit-projection table's live columns against the entity's\ncurrent column set via `columnNamesOf`, backfilling anything nullable or\ndefaulted through the newly extracted `addMissingColumns` helper (shared\nwith `unsafePushTables`'s existing column-diff loop). A missing required\ncolumn with no default throws instead, naming the column and the\npersistent dev DB (`KUMIKO_DEV_DB_NAME`) to drop so the next boot\nrecreates it. Covers implicit `r.entity()`-derived projection tables,\nwhich is what the reporting app's read-model table used. `setupTestStack`'s\nown explicit `r.projection()`/`r.storeTable()` push loop (test-stack.ts)\nhas the same skip-existing behavior and is not yet patched."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Boot validator checks a metric's cross-screen navigate tab",
+    "detail": "A projectionDetail metric whose `navigate` sets `screen` or `entity` plus\n`tab` now fails boot when the target is not a projectionDetail with\nlayout.mode \"tabs\" or has no section with that id. Previously only a\nsame-screen `tab` was checked."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "Personal Access Tokens are now scoped to the dispatcher routes only",
+    "migration": "A caller using a PAT for SSE, file upload/download, /api/auth/*, a feature\nr.httpRoute, or an entry:\"user\" extraRoute now gets a 403 and needs a\nsession-cookie or JWT credential for those calls instead. The dispatcher\nroutes (/api/write, /api/batch, /api/query, /api/command, /api/stream) are\nunaffected."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "No user-reference-name warning for owner fields referenced via personal.of",
+    "detail": "The `PII_USER_REFERENCE_NAME_HINTS` boot warning checked each field in isolation, so an owner field such as `authorId` kept warning even when a content field on the same entity already declared `personal: { of: \"authorId\" }`, the exact silencing condition the warning itself names. The validator now collects the owner fields referenced via `personal.of` per entity first and skips the warning for them. Fields with a user-reference-typical name that no `personal.of` references still warn."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "New GET /api/schema route",
+    "detail": "Behind the existing `/api/*` auth guard. A signed-in, non-anonymous user\ngets the built `AppSchema` as JSON with `Cache-Control: private, no-cache`\nand a strong `ETag`; a matching `If-None-Match` gets a bodyless 304 (still\nbehind the same auth check, so an anonymous request with a stolen/guessed\nETag still 401s instead of getting a 304). Anonymous or missing auth gets\nthe same 401 `unauthenticated` response shape as every other non-public\nroute."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "GET /api/schema now returns a per-role projection instead of the full AppSchema to every authenticated user",
+    "detail": "`buildAppSchema`'s output previously shipped every screen, nav, workspace and content-collection to any signed-in caller, regardless of role — a screen's own `access` rule only ever hid it in the UI, never removed it from the payload a curious client could still read. `projectAppSchemaForRoles` now strips every screen/nav/workspace/content-collection reference the caller's roles can't see (screens, nav entries, row/toolbar/related-list actions, entityEdit redirects, dashboard panels and metric navigation targets, tree actions, workspace nav membership) before the route serializes a response, closing empty parent nav sections and workspaces left with no surviving members along the way. Entities and translations are still shipped in full — the projection is a UI-visibility concern, not an entity-authorization concern; the dispatcher's `hasAccess` default-deny check is unchanged.\nThe route now builds the full schema lazily once per process and caches the projected JSON/ETag per canonical (deduplicated, sorted) role set — tenant is deliberately not part of the cache key, since the projection only depends on roles.\n`isUiAccessGranted` is the new shared default-visible UI predicate in `@cosmicdrift/kumiko-types`, re-exported through `framework/ui-types`. The renderer's `screenAccessAllows` is now an alias of it, and headless nav resolution and renderer-web's workspace filter call it directly instead of carrying their own copies.\nA deep link to a screen the caller's roles no longer receive now shows the \"screen not found\" banner instead of the access-denied banner, because the screen is no longer part of that caller's schema."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "Sequential-job lock key scoped by queueNamePrefix; contract clarified as mutual exclusion, not FIFO",
+    "detail": "The per-name Redis SETNX lock behind `concurrency: \"sequential\"` used a fixed `kumiko:lock:seq:<lane>:` key, unlike the queues themselves, which are scoped by `queueNamePrefix`. Two runners sharing a Redis but isolated by distinct prefixes (e.g. per-test-run prefixes) could collide on the same lock key even though their queues never saw each other's jobs. The key is now `kumiko:lock:seq:<queueNamePrefix>:<lane>:`. Separately, `JobDefinition.concurrency`'s doc comment and the integration test now state the contract precisely: \"sequential\" guarantees same-name dispatches never run concurrently, but does not guarantee they run in dispatch order. A lock loser is re-enqueued to the back of its queue, so a later dispatch can still complete before an earlier one. See fw#3265 for the local repro evidence backing this."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "Real-provider helpers under the import-free subpath testing/real-providers",
+    "detail": "`@cosmicdrift/kumiko-framework/testing/real-providers` exports `requireRealProviders`, `isRealProviderRun` and `REAL_PROVIDERS_ENV` without pulling in the `./testing` barrel and its Bun-only dependencies, so code that loads under Node can use them."
+  },
+  {
+    "version": "0.320.0",
+    "type": "improvement",
+    "title": "Boot validator checks the target tab of toolbar navigate actions",
+    "detail": "A ToolbarAction with kind \"navigate\" and `tab` fails boot when its target\nis not a projectionDetail with layout.mode \"tabs\" or has no section with\nthat id. The check covers entityList, projectionList and relatedList\nsection toolbars."
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "HttpRouteHandlerDeps carries the resolved clientIp",
+    "detail": "`r.httpRoute` handlers get a new `clientIp: string` dep, resolved once per\nrequest via `buildServer`'s existing shared `clientIpResolver` (the same\ninstance `requestIdMiddleware` and the L1/L2 rate limits use), instead of\neach handler parsing `X-Forwarded-For`/`X-Real-IP` itself with no\nknowledge of the deployment's actual `trustedProxyHops`. `UNKNOWN_CLIENT_IP`\nis now exported from `@cosmicdrift/kumiko-framework/api` so callers can\ndetect the resolver's no-value sentinel without hardcoding the string."
+  },
   {
     "version": "0.318.0",
     "type": "improvement",

package/src/db/queries/event-store-transfer.ts

@@ -0,0 +1,73 @@
+// Raw SQL backing event-store/transfer.ts — the framework's own tenant-transfer
+// primitive for streams. Kept in db/queries alongside the rest of the
+// event-store's raw statements (see event-store.ts, event-store-admin.ts,
+// backfill-pii.ts): the one place in the repo allowed to write tenant_id
+// directly onto kumiko_events / kumiko_snapshots / kumiko_archived_streams.
+
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type TransferEventRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
+// per-event-row hits in-process instead of relying on invalid SQL.
+export async function transferEventRows(
+  db: AnyDb,
+  params: TransferEventRowsParams,
+): Promise<readonly string[]> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
+      `RETURNING "aggregate_id" AS id`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  )) as ReadonlyArray<{ id: string }>;
+  return [...new Set(rows.map((row) => row.id))];
+}
+
+export type DeleteSnapshotsForAggregatesParams = {
+  readonly tenantId: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+// dropped rather than rewritten, forcing a full replay from the just-moved
+// events on next read instead of carrying the snapshot's own generation
+// bookkeeping across the tenant boundary.
+export async function deleteSnapshotsForAggregates(
+  db: AnyDb,
+  params: DeleteSnapshotsForAggregatesParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2)`,
+    [params.tenantId, params.aggregateIds],
+  );
+}
+
+export type TransferArchivedStreamRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// An archived stream's marker must move with it — leaving it behind would
+// make the stream writable again the instant it lands in the destination
+// tenant (archive.ts's isStreamArchived check is itself tenant-scoped).
+// `aggregate_type` is part of the match, same as transferEventRows — an
+// archived marker for a DIFFERENT aggregate type that happens to share the
+// moved aggregate's id must stay in the source tenant.
+export async function transferArchivedStreamRows(
+  db: AnyDb,
+  params: TransferArchivedStreamRowsParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_archived_streams" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4)`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  );
+}

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -365,6 +365,53 @@ describe("validateBoot — PII annotations", () => {
     expect(matchingWarn).toBeUndefined();
   });
 
+  const userReferenceHintWarningFor = (fieldName: string) =>
+    warnSpy.mock.calls.find((args: unknown[]) => {
+      const message = String(args[0]);
+      return (
+        message.includes(`Field "${fieldName}"`) && message.includes("user-reference-typical name")
+      );
+    });
+
+  function defineCommentFeatureWithBodyOwnedBy(ownerFieldName: "authorId" | "ownerId") {
+    return defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            email: createTextField({ personal: "self", find: "none" }),
+          },
+        }),
+      );
+      stubListHandler(r, "user");
+      r.entity(
+        "comment",
+        createEntity({
+          fields: {
+            body: createLongTextField({ personal: { of: ownerFieldName }, find: "none" }),
+            authorId: { type: "reference", entity: "user" },
+            ownerId: { type: "reference", entity: "user" },
+          },
+        }),
+      );
+    });
+  }
+
+  test("owner field referenced by another field's personal.of does not trigger the user-reference-name warning", () => {
+    validateBoot([defineCommentFeatureWithBodyOwnedBy("authorId")]);
+    expect(userReferenceHintWarningFor("authorId")).toBeUndefined();
+    const anyAuthorIdWarning = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes('Field "authorId"'),
+    );
+    expect(anyAuthorIdWarning).toBeUndefined();
+  });
+
+  test("user-reference-named field not referenced by any personal.of still warns", () => {
+    validateBoot([defineCommentFeatureWithBodyOwnedBy("ownerId")]);
+    expect(userReferenceHintWarningFor("authorId")).toBeDefined();
+    expect(userReferenceHintWarningFor("ownerId")).toBeUndefined();
+  });
+
   test("allowPlaintext marker silences PII-name heuristic warning", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(