@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

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

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { Queue } from "bullmq";
+import { Redis } from "ioredis";
 import * as z from "zod";
 import { requestContext } from "../../api/request-context";
 import { tenantDbRunner } from "../../db/tenant-db-runner";
@@ -13,6 +14,7 @@ import type {
   TenantId,
 } from "../../engine/types";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
+import { RedisKeys } from "../../pipeline/redis-keys";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
@@ -498,10 +500,110 @@ describe("concurrency: sequential", () => {
       expect(delta12).toBeGreaterThanOrEqual(250);
       expect(delta23).toBeGreaterThanOrEqual(250);
 
-      // FIFO inside the same lock-name: the dispatch order is preserved
-      // even though re-enqueues happen.
-      expect(entries[0]?.payload).toEqual({ n: 1 });
+      // NOT dispatch order: "sequential" is mutual exclusion, not a FIFO
+      // queue. A re-enqueued lock loser goes to the back of its
+      // queue, so it can still win the next race. What's guaranteed, and
+      // already asserted above via delta12/delta23, is that runs never
+      // overlap. Assert the complete set instead of a specific order.
+      expect(entries.map((e) => e.payload)).toEqual(
+        expect.arrayContaining([{ n: 1 }, { n: 2 }, { n: 3 }]),
+      );
+    });
+  });
+
+  test("runners with distinct queueNamePrefix do not share the sequential lock", async () => {
+    clearLog();
+    // Regression guard: the lock key used to omit queueNamePrefix, so two
+    // isolated runners sharing a Redis collided on the same lock.
+    const prefixA = `kumiko-test-lockscope-a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const prefixB = `kumiko-test-lockscope-b-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const runnerA = createJobRunner({
+      registry: createRegistry([testFeature]),
+      context: {},
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix: prefixA,
+    });
+    const runnerB = createJobRunner({
+      registry: createRegistry([testFeature]),
+      context: {},
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix: prefixB,
+    });
+    // Own client, no keyPrefix — testRedis.redis auto-prefixes SET/DEL and
+    // would write a different key than the runner's own lock connection.
+    const lockKeyA = `${RedisKeys.lock}seq:${prefixA}:worker:test:job:sequential-job`;
+    const rawRedis = new Redis(redisUrl);
+    rawRedis.on("error", () => {});
+    const queueA = new Queue(`${prefixA}-worker`, {
+      connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
     });
+    // A post-close 'error' here is otherwise unhandled and bun:test
+    // attributes it to whichever test runs next (fw#1805).
+    queueA.on("error", () => {});
+
+    try {
+      await rawRedis.set(lockKeyA, "held-by-test", "EX", 30, "NX");
+
+      await runnerA.start();
+      await runnerB.start();
+
+      await runnerA.dispatch("test:job:sequential-job", { n: 100 });
+
+      // A's handler returns successfully on a lock loss (re-enqueue, not a
+      // throw) — BullMQ records the dropped attempt as completed even
+      // though the job body never ran. Filtered by name+payload so unrelated
+      // boot/cron jobs on the same worker queue don't false-positive this.
+      await waitFor(
+        async () => {
+          const completed = await queueA.getCompleted();
+          const lostAttempts = completed.filter(
+            (job) => job.name === "test:job:sequential-job" && job.data.n === 100,
+          );
+          expect(lostAttempts.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+      expect(
+        jobLog.some((e) => e.name === "test:job:sequential-job" && e.payload["n"] === 100),
+      ).toBe(false);
+
+      // B shares no lock scope with the externally held A-key, so it must
+      // run despite A being blocked.
+      await runnerB.dispatch("test:job:sequential-job", { n: 200 });
+      await waitFor(
+        () => {
+          const entries = jobLog.filter(
+            (e) => e.name === "test:job:sequential-job" && e.payload["n"] === 200,
+          );
+          expect(entries.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+
+      // Releasing the externally held key unblocks A's own dispatch.
+      await rawRedis.del(lockKeyA);
+      await waitFor(
+        () => {
+          const entries = jobLog.filter(
+            (e) => e.name === "test:job:sequential-job" && e.payload["n"] === 100,
+          );
+          expect(entries.length).toBeGreaterThanOrEqual(1);
+        },
+        { delays: [400, 800, 1500, 3000] },
+      );
+    } finally {
+      await runnerA.stop();
+      await runnerB.stop();
+      await queueA.close();
+      await rawRedis.del(lockKeyA);
+      rawRedis.disconnect();
+      const keysA = await testRedis.redis.keys(`bull:${prefixA}-worker:*`);
+      if (keysA.length > 0) await testRedis.redis.del(...keysA);
+      const keysB = await testRedis.redis.keys(`bull:${prefixB}-worker:*`);
+      if (keysB.length > 0) await testRedis.redis.del(...keysB);
+    }
   });
 
   test("lock is released even when the handler throws", async () => {

package/src/jobs/job-runner.ts

@@ -550,7 +550,12 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       log("lock redis connection error", { error: err.message });
     });
     const lockScope = consumerLane ?? "enqueue";
-    sequentialLock = createDistributedLock(lockRedis, `${RedisKeys.lock}seq:${lockScope}:`);
+    // Scoped by queueNamePrefix like the queues themselves, so runners
+    // isolated by prefix on a shared Redis don't contend for the same lock.
+    sequentialLock = createDistributedLock(
+      lockRedis,
+      `${RedisKeys.lock}seq:${queueNamePrefix}:${lockScope}:`,
+    );
   }
   // Default lock-TTL for sequential jobs that didn't declare a timeout.
   // 5 minutes matches BullMQ's default stalledInterval — long enough for

package/src/pipeline/multi-stream-apply-context.ts

@@ -1,5 +1,6 @@
 import type { DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
 import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
+import type { SecretsContext } from "@cosmicdrift/kumiko-types/secrets-types";
 import type { DbRunner } from "../db/connection";
 import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
 import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
@@ -32,6 +33,8 @@ export type MultiStreamApplyContextDeps = {
   readonly files?: FileContext;
   // Same DerivativesContext the outer AppContext carries — mirrors `files`.
   readonly derivatives?: DerivativesContext;
+  // Same SecretsContext the outer AppContext carries, mirrors `files`.
+  readonly secrets?: SecretsContext;
 };
 
 export function createMultiStreamApplyContext(
@@ -41,6 +44,7 @@ export function createMultiStreamApplyContext(
     registry: deps.registry,
     ...(deps.files ? { files: deps.files } : {}),
     ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
+    ...(deps.secrets ? { secrets: deps.secrets } : {}),
     appendEvent: (async (args: AppendEventArgs) => {
       await appendDomainEventCore(
         {

package/src/rate-limit/__tests__/middleware.integration.test.ts

@@ -28,7 +28,16 @@ describe("globalIpRateLimit (L1)", () => {
     const app = new Hono();
     app.use(
       "/api/*",
-      globalIpRateLimit({ resolver, limit: 3, windowSeconds: 60, onFailClosed: () => {} }),
+      // trustedProxyHops: 1 — the default hops=0 ignores x-forwarded-for
+      // outright, which would collapse the bucket
+      // assertion below onto "l1:unknown" instead of the literal IP.
+      globalIpRateLimit({
+        resolver,
+        limit: 3,
+        windowSeconds: 60,
+        trustedProxyHops: 1,
+        onFailClosed: () => {},
+      }),
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
@@ -56,7 +65,13 @@ describe("globalIpRateLimit (L1)", () => {
     const app = new Hono();
     app.use(
       "/api/*",
-      globalIpRateLimit({ resolver, limit: 2, windowSeconds: 60, onFailClosed: () => {} }),
+      globalIpRateLimit({
+        resolver,
+        limit: 2,
+        windowSeconds: 60,
+        trustedProxyHops: 1,
+        onFailClosed: () => {},
+      }),
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
@@ -73,7 +88,11 @@ describe("globalIpRateLimit (L1)", () => {
     expect(otherIp.status).toBe(200);
   });
 
-  test("no x-forwarded-for: pass-through (no bucket)", async () => {
+  // The built-in resolver never returns undefined — no x-forwarded-for (or
+  // an untrusted one at hops=0) falls back to a fixed "unknown" bucket
+  // instead of skipping the middleware: skipping would fail open, letting
+  // an attacker omit/rotate the header to dodge L1 entirely.
+  test("no x-forwarded-for: still enforced via the shared 'unknown' bucket, never skipped", async () => {
     const app = new Hono();
     app.use(
       "/api/*",
@@ -81,12 +100,10 @@ describe("globalIpRateLimit (L1)", () => {
     );
     app.get("/api/probe", (c) => c.text("ok"));
 
-    // No xff header — extractIp returns undefined → middleware skips.
-    // Both calls succeed even though limit=1.
     const a = await app.request("/api/probe");
-    const b = await app.request("/api/probe");
     expect(a.status).toBe(200);
-    expect(b.status).toBe(200);
+    const b = await app.request("/api/probe");
+    expect(b.status).toBe(429);
   });
 
   test("fail-closed when resolver throws non-RateLimit error (Redis down)", async () => {

package/src/rate-limit/middleware.ts

@@ -1,5 +1,10 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { isAuthRateLimitExempt } from "../api/api-constants";
+import {
+  type ClientIpResolver,
+  clientIpSourceFromHonoContext,
+  createClientIpResolver,
+} from "../api/client-ip";
 import { requestContext } from "../api/request-context";
 import { RateLimitError, serializeError } from "../errors";
 import type { RateLimitDecision, RateLimitResolver } from "./resolver";
@@ -22,8 +27,17 @@ export type GlobalIpRateLimitOptions = {
   readonly resolver: RateLimitResolver;
   readonly limit?: number;
   readonly windowSeconds?: number;
+  // Number of trusted reverse-proxy hops for the default client-IP
+  // resolver — see createClientIpResolver. Ignored when `extractIp` is set.
+  // Default 0 (no proxy trusted).
+  readonly trustedProxyHops?: number;
+  // Shared resolver instance from buildServer — takes precedence over
+  // `trustedProxyHops` so the whole server has exactly one resolver (and
+  // one warn-once flag) rather than one per middleware.
+  // Only standalone callers (no buildServer) should rely on `trustedProxyHops`.
+  readonly clientIpResolver?: ClientIpResolver;
   // Override IP extraction — useful when behind a non-standard proxy.
-  // Default: x-forwarded-for first hop.
+  // Default: the shared resolveClientIp, honoring `trustedProxyHops`.
   readonly extractIp?: (c: Context) => string | undefined;
   // Hook for ops logging when fail-closed fires (Redis down). Default:
   // emits to console.error so the misbehaviour is loud at minimum.
@@ -33,7 +47,11 @@ export type GlobalIpRateLimitOptions = {
 export function globalIpRateLimit(opts: GlobalIpRateLimitOptions): MiddlewareHandler {
   const limit = opts.limit ?? 1000;
   const windowSeconds = opts.windowSeconds ?? 60;
-  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const clientIpResolver =
+    opts.clientIpResolver ??
+    createClientIpResolver(opts.trustedProxyHops ?? 0, "globalIpRateLimit");
+  const extractIp =
+    opts.extractIp ?? ((c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c)));
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l1-global-ip");
 
   return async (c, next) => {
@@ -73,6 +91,13 @@ export type AuthEndpointRateLimitOptions = {
   // top of IP. Default: bucket on `l2:${ip}:${path}` (IP + route),
   // which catches naive IP-flood without consuming the request body.
   readonly extractTarget?: (c: Context) => string | undefined | Promise<string | undefined>;
+  // Number of trusted reverse-proxy hops for the default client-IP
+  // resolver — see createClientIpResolver. Ignored when `extractIp` is set.
+  // Default 0 (no proxy trusted).
+  readonly trustedProxyHops?: number;
+  // See GlobalIpRateLimitOptions.clientIpResolver — same single-resolver
+  // rationale.
+  readonly clientIpResolver?: ClientIpResolver;
   readonly extractIp?: (c: Context) => string | undefined;
   readonly onFailClosed?: (err: unknown) => void;
 };
@@ -80,7 +105,11 @@ export type AuthEndpointRateLimitOptions = {
 export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): MiddlewareHandler {
   const limit = opts.limit ?? 5;
   const windowSeconds = opts.windowSeconds ?? 60;
-  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const clientIpResolver =
+    opts.clientIpResolver ??
+    createClientIpResolver(opts.trustedProxyHops ?? 0, "authEndpointRateLimit");
+  const extractIp =
+    opts.extractIp ?? ((c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c)));
   const extractTarget = opts.extractTarget;
   const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l2-auth-endpoints");
 
@@ -110,11 +139,6 @@ export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): Middl
   };
 }
 
-function defaultExtractIp(c: Context): string | undefined {
-  const xff = c.req.header("x-forwarded-for");
-  return xff?.split(",")[0]?.trim() || undefined;
-}
-
 function defaultOnFailClosed(label: string): (err: unknown) => void {
   return (err) => {
     // Loud by default — fail-closed for an unknown reason is an ops

package/src/schema-cli.ts

@@ -115,7 +115,11 @@ export async function runSchemaCli(
   // migration, since the crashed process still records the migration as
   // applied and the rebuild is never retried.
   await ensureTemporalPolyfill();
-  const sub = argv[0];
+  // `--help`/`-h`/`help` fall through to the same "no subcommand" usage
+  // branch below (undefined) — a real request for help, not a typo that
+  // should fail loud like an unrecognized subcommand does.
+  const rawSub = argv[0];
+  const sub = rawSub === "--help" || rawSub === "-h" || rawSub === "help" ? undefined : rawSub;
   const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
   const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
 

package/src/stack/__tests__/push-entity-projection-tables-column-sync.integration.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import { pushEntityProjectionTables } from "../push-entity-projection-tables";
+import { setupTestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+function freshDbName(tag: string): string {
+  return `kumiko_test_${tag}_${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+
+describe("pushEntityProjectionTables — persistent dev DB column sync", () => {
+  test("a nullable field added after the first boot is backfilled without manual DDL", async () => {
+    const dbName = freshDbName("colsync_nullable");
+    const widgetV1 = createEntity({
+      table: "colsync_nullable_widgets",
+      fields: {
+        name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+      },
+    });
+    const v1 = defineFeature("colsync-nullable", (r) => {
+      r.entity("widget", widgetV1);
+    });
+    // Owns the actual DROP DATABASE on cleanup.
+    const firstBoot = await setupTestStack({ features: [v1], dbName });
+    try {
+      await pushEntityProjectionTables(firstBoot, firstBoot.registry);
+
+      const widgetV2 = createEntity({
+        table: "colsync_nullable_widgets",
+        fields: {
+          name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+          note: createTextField({ personal: false, reason: "test_fixture" }),
+        },
+      });
+      const v2 = defineFeature("colsync-nullable", (r) => {
+        r.entity("widget", widgetV2);
+        r.writeHandler(
+          defineEntityCreateHandler("widget", widgetV2, { access: { roles: ["Admin"] } }),
+        );
+      });
+      const secondBoot = await setupTestStack({ features: [v2], dbName, persistentDb: true });
+      try {
+        await pushEntityProjectionTables(secondBoot, secondBoot.registry);
+        const created = await secondBoot.http.writeOk<{ data: { note: string } }>(
+          "colsync-nullable:write:widget:create",
+          { name: "backfilled widget", note: "backfilled via HTTP write" },
+          TestUsers.admin,
+        );
+        expect(created.data.note).toBe("backfilled via HTTP write");
+      } finally {
+        await secondBoot.cleanup();
+      }
+    } finally {
+      await firstBoot.cleanup();
+    }
+  });
+
+  test("a required field with no default added after the first boot fails with a clear, actionable error", async () => {
+    const dbName = freshDbName("colsync_required");
+    const v1 = defineFeature("colsync-required", (r) => {
+      r.entity(
+        "gadget",
+        createEntity({
+          table: "colsync_required_gadgets",
+          fields: {
+            name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+          },
+        }),
+      );
+    });
+    const firstBoot = await setupTestStack({ features: [v1], dbName });
+    try {
+      await pushEntityProjectionTables(firstBoot, firstBoot.registry);
+
+      const v2 = defineFeature("colsync-required", (r) => {
+        r.entity(
+          "gadget",
+          createEntity({
+            table: "colsync_required_gadgets",
+            fields: {
+              name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+              serial: createTextField({ personal: false, reason: "test_fixture", required: true }),
+            },
+          }),
+        );
+      });
+      const secondBoot = await setupTestStack({ features: [v2], dbName, persistentDb: true });
+      try {
+        await expect(pushEntityProjectionTables(secondBoot, secondBoot.registry)).rejects.toThrow(
+          /serial.*no default/i,
+        );
+        await expect(pushEntityProjectionTables(secondBoot, secondBoot.registry)).rejects.toThrow(
+          /dropdb/,
+        );
+      } finally {
+        await secondBoot.cleanup();
+      }
+    } finally {
+      await firstBoot.cleanup();
+    }
+  });
+});

package/src/stack/push-entity-projection-tables.ts

@@ -1,8 +1,11 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
-import { tableExists } from "../db/schema-inspection";
+import type { DbConnection } from "../db/connection";
+import type { ColumnMeta } from "../db/entity-table-meta";
+import { columnNamesOf, tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
-import { unsafePushTables } from "./table-helpers";
-import type { TestStack } from "./test-stack";
+import { addMissingColumns, tableToMeta, unsafePushTables } from "./table-helpers";
+
+type DbHolder = { readonly db: DbConnection };
 
 // biome-ignore lint/suspicious/noConsole: stack-internal status logging
 const logInfo = (msg: string): void => console.log(msg);
@@ -25,7 +28,7 @@ const logInfo = (msg: string): void => console.log(msg);
  * never call this directly.
  */
 export async function pushEntityProjectionTables(
-  stack: TestStack,
+  stack: DbHolder,
   registry: Registry,
 ): Promise<void> {
   const seen = new Set<unknown>();
@@ -37,14 +40,56 @@ export async function pushEntityProjectionTables(
     seen.add(proj.table);
     const tableRec = proj.table as unknown as Record<symbol, unknown>;
     const physical = tableRec[KUMIKO_NAME_SYMBOL] as string;
-    if (await tableExists(stack.db, `public.${physical}`)) {
-      logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+    if (!(await tableExists(stack.db, `public.${physical}`))) {
+      missing[projName] = proj.table;
       continue;
     }
-    missing[projName] = proj.table;
+    await syncExistingProjectionTable(stack, physical, proj.table);
   }
 
   if (Object.keys(missing).length > 0) {
     await unsafePushTables(stack.db, missing);
   }
 }
+
+function isUnsafeToAutoAdd(col: ColumnMeta): boolean {
+  return col.notNull && !col.primaryKey && col.defaultSql === undefined;
+}
+
+// Backfills columns a persistent dev DB predates; a required column with no
+// default can't be added safely on a table that may hold rows, so that
+// stays a boot error instead.
+async function syncExistingProjectionTable(
+  stack: DbHolder,
+  physical: string,
+  table: unknown,
+): Promise<void> {
+  const meta = tableToMeta(table);
+  const liveColumns = await columnNamesOf(stack.db, physical);
+  const missingColumns = meta.columns.filter((c) => !liveColumns.has(c.name));
+  if (missingColumns.length === 0) {
+    logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
+    // skip: live table already has every declared column
+    return;
+  }
+
+  const unsafeColumns = missingColumns.filter(isUnsafeToAutoAdd);
+  if (unsafeColumns.length > 0) {
+    const devDbName = process.env["KUMIKO_DEV_DB_NAME"] ?? "<KUMIKO_DEV_DB_NAME>";
+    throw new Error(
+      `[kumiko-stack] table "${physical}" is missing required column(s) ` +
+        `${unsafeColumns.map((c) => `"${c.name}"`).join(", ")} with no default. ` +
+        "Auto-sync only backfills nullable columns or columns with a default on an " +
+        "existing dev DB — a required column with no default can't be added safely " +
+        `once the table may hold rows. Drop the persistent dev database "${devDbName}" ` +
+        `(e.g. \`dropdb ${devDbName}\`, adjusted for your local Postgres host/port/user) ` +
+        "so the next boot recreates it from scratch.",
+    );
+  }
+
+  logInfo(
+    `[kumiko-stack] table ${physical} is missing column(s) ` +
+      `${missingColumns.map((c) => `"${c.name}"`).join(", ")} — adding`,
+  );
+  await addMissingColumns(stack.db, physical, missingColumns);
+}

package/src/stack/table-helpers.ts

@@ -67,7 +67,7 @@ function isMetaShape(v: unknown): v is EntityTableMeta {
   );
 }
 
-function tableToMeta(table: unknown): EntityTableMeta {
+export function tableToMeta(table: unknown): EntityTableMeta {
   // table() spreads column handles as enumerable props, so a field named
   // `columns`/`tableName`/`source`/… shadows the matching meta key — read the
   // canonical meta from the unshadowable symbol when present.
@@ -79,6 +79,20 @@ function tableToMeta(table: unknown): EntityTableMeta {
   throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
 }
 
+/** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
+export async function addMissingColumns(
+  db: DbConnection,
+  tableName: string,
+  columns: readonly ColumnMeta[],
+): Promise<void> {
+  for (const col of columns) {
+    const type = renderColumnType(col);
+    const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
+    const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
+    await alterTableAddColumn(db, tableName, col.name, type, defaultClause, notNull);
+  }
+}
+
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
@@ -106,14 +120,8 @@ export async function unsafePushTables(
 
     if (prev) {
       const prevCols = new Set(prev.columns.map((c) => c.name));
-      for (const col of meta.columns) {
-        if (!prevCols.has(col.name)) {
-          const type = renderColumnType(col);
-          const notNull = col.notNull && !col.primaryKey ? " NOT NULL" : "";
-          const defaultClause = col.defaultSql !== undefined ? ` DEFAULT ${col.defaultSql}` : "";
-          await alterTableAddColumn(db, meta.tableName, col.name, type, defaultClause, notNull);
-        }
-      }
+      const newCols = meta.columns.filter((c) => !prevCols.has(c.name));
+      await addMissingColumns(db, meta.tableName, newCols);
       const prevIdxNames = new Set(prev.indexes.map((i) => i.name));
       for (const idx of meta.indexes) {
         if (!prevIdxNames.has(idx.name)) {

package/src/stack/test-stack.ts

@@ -18,6 +18,7 @@ import {
   createIdempotencyGuard,
   dispatcherToWriteRef,
 } from "../pipeline";
+import { createRateLimitResolver } from "../rate-limit";
 import { createInMemorySearchAdapter } from "../search";
 import type { SearchAdapter } from "../search/types";
 import { createTestDb } from "./db";
@@ -187,6 +188,9 @@ export type TestStackOptions = {
    *  them themselves. Default true — false pushes only projection/MSP/
    *  storeTable sources, same as before fw#3102. */
   entityTables?: boolean;
+  /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
+   *  — see there. Default 0. */
+  trustedProxyHops?: number;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -417,9 +421,31 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
     const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
 
+    // buildServer only auto-wires an L3 RateLimitResolver from
+    // `context.redis` — a degradation test that nulls `redis` via
+    // extraContext (to exercise a handler's own ctx.redis-down guard) also
+    // silently strips rate-limiting, even though every handler with a
+    // `rateLimit` declaration still requires a resolver at dispatch time.
+    // Since e7bf543ad, an IP-keyed bucket key is built unconditionally
+    // (falls back to a shared "unknown" IP rather than skipping), so the
+    // missing resolver now throws instead of merely skipping enforcement.
+    // Mirrors idempotency/eventDedup above: built from the test-stack's own
+    // always-real `testRedis.redis`, independent of whatever extraContext
+    // did to `appContext.redis` — an explicit `context.rateLimit` from
+    // extraContext still wins (same precedence buildServer documents).
+    // @cast-boundary extraContext is declared Record<string, unknown> (late,
+    // dynamic extension point) — appContext's inferred type doesn't carry a
+    // `rateLimit` key, so reading it back needs the same relaxed boundary
+    // extraContext itself is typed with.
+    const explicitRateLimit = (appContext as { rateLimit?: unknown }).rateLimit;
+    const rateLimitFallback =
+      appContext.redis === undefined && explicitRateLimit === undefined
+        ? createRateLimitResolver({ redis: testRedis.redis })
+        : undefined;
+
     const server = buildServer({
       registry,
-      context: appContext,
+      context: rateLimitFallback ? { ...appContext, rateLimit: rateLimitFallback } : appContext,
       jwtSecret,
       ...(options.observability ? { observability: options.observability } : {}),
       dispatcherOptions: {
@@ -429,6 +455,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       },
       eventDedup,
       sseBroker,
+      ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
       ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
       ...(options.metrics && { metrics: options.metrics }),
       // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for

package/src/testing/real-providers.ts

@@ -1,3 +1,5 @@
+// Playwright configs load this module under plain Node via
+// @cosmicdrift/kumiko-testing/e2e, so it must stay import-free.
 export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
 const CI_FLAG = "CI";
 

package/src/ui-types/index.ts

@@ -64,7 +64,7 @@ export type {
   RoleAccessPersonalData,
   RoleAccessRule,
 } from "../engine/types/handlers";
-export { isOpenToAllGranted } from "../engine/types/handlers";
+export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav";
 export type {
   ActionFormRedirect,