@cosmicdrift/kumiko-framework 0.221.0 → 0.222.0

package/src/jobs/job-runner.ts

@@ -206,10 +206,20 @@ function parseRedisOpts(url: string): { host: string; port: number; db?: number
 // would otherwise hang start() forever with no health endpoint to notice.
 const BOOT_REDIS_TIMEOUT_MS = 10_000;
 
-function timeoutReject(ms: number, message: string): Promise<never> {
-  return new Promise((_, reject) => {
-    setTimeout(() => reject(new Error(message)), ms);
+function timeoutReject(
+  ms: number,
+  message: string,
+): { promise: Promise<never>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), ms);
   });
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== undefined) clearTimeout(timer);
+    },
+  };
 }
 
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
@@ -592,13 +602,15 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // upsertJobScheduler()/add() below when the lane has a cron/boot job.
       // Racing a timeout against it keeps an unreachable Redis from hanging
       // start() forever — there's no worker health endpoint to notice.
-      await Promise.race([
-        worker.waitUntilReady(),
-        timeoutReject(
-          bootRedisTimeoutMs,
-          `job-runner: Redis not reachable within ${bootRedisTimeoutMs}ms (lane=${consumerLane})`,
-        ),
-      ]);
+      const bootTimeout = timeoutReject(
+        bootRedisTimeoutMs,
+        `job-runner: Redis not reachable within ${bootRedisTimeoutMs}ms (lane=${consumerLane})`,
+      );
+      try {
+        await Promise.race([worker.waitUntilReady(), bootTimeout.promise]);
+      } finally {
+        bootTimeout.cancel();
+      }
 
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the

package/src/pipeline/__tests__/tenant-timezone-cache.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantId } from "../../engine/types/identifiers";
+import { createTenantTimezoneCache } from "../tenant-timezone-cache";
+
+const tenantA = "tenant-a" as TenantId;
+const tenantB = "tenant-b" as TenantId;
+
+describe("TenantTimezoneCache", () => {
+  test("miss on an unset tenant", () => {
+    const cache = createTenantTimezoneCache();
+    expect(cache.get(tenantA)).toBeUndefined();
+  });
+
+  test("hit returns the cached value, including a cached 'no override' (undefined)", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, undefined);
+
+    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
+    // Distinct from a miss: tenantB was looked up and confirmed unset.
+    expect(cache.get(tenantB)).toEqual({ value: undefined });
+  });
+
+  test("invalidate() drops only the given tenant", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, "Europe/Berlin");
+
+    cache.invalidate(tenantA);
+
+    expect(cache.get(tenantA)).toBeUndefined();
+    expect(cache.get(tenantB)).toEqual({ value: "Europe/Berlin" });
+  });
+
+  test("clear() drops every tenant", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, "Europe/Berlin");
+
+    cache.clear();
+
+    expect(cache.size()).toBe(0);
+    expect(cache.get(tenantA)).toBeUndefined();
+    expect(cache.get(tenantB)).toBeUndefined();
+  });
+
+  test("entry expires after ttlMs", () => {
+    let t = 1_000_000;
+    const cache = createTenantTimezoneCache({ ttlMs: 1000, now: () => t });
+    cache.set(tenantA, "Asia/Tokyo");
+
+    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
+
+    t += 1500;
+    expect(cache.get(tenantA)).toBeUndefined();
+  });
+
+  test("LRU: evicts oldest tenant when maxEntries is reached", () => {
+    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
+    cache.set("a" as TenantId, "UTC");
+    cache.set("b" as TenantId, "UTC");
+    expect(cache.size()).toBe(2);
+
+    cache.set("c" as TenantId, "UTC");
+    expect(cache.size()).toBe(2);
+    expect(cache.get("a" as TenantId)).toBeUndefined();
+    expect(cache.get("c" as TenantId)).toEqual({ value: "UTC" });
+  });
+
+  test("LRU: touching an entry (get) moves it to the 'most recent' end", () => {
+    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
+    cache.set("a" as TenantId, "UTC");
+    cache.set("b" as TenantId, "UTC");
+    cache.get("a" as TenantId); // touch a — b is now the oldest
+
+    cache.set("c" as TenantId, "UTC");
+
+    expect(cache.get("b" as TenantId)).toBeUndefined();
+    expect(cache.get("a" as TenantId)).toEqual({ value: "UTC" });
+  });
+
+  test("default maxEntries is 1000", () => {
+    const cache = createTenantTimezoneCache();
+    for (let i = 0; i < 1001; i++) {
+      cache.set(`tenant-${i}` as TenantId, "UTC");
+    }
+    expect(cache.size()).toBe(1000);
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -75,13 +75,22 @@ import {
 } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import type { TenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Framework/pipeline stays bundled-features-free, so this can't import the
 // `tenant` feature — the literal below IS the coupling to its `timezone`
 // config key. Renaming that key (or the "tenant" feature name) must update
 // this constant too; tenant-timezone-boot.integration.test.ts boots the real
 // createTenantFeature() and would catch a drift.
-const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+export const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+
+// Same bundled-features-free constraint as above — these name the config
+// feature's write handlers so dispatch-write.ts can invalidate
+// TENANT_TIMEZONE_CONFIG_KEY's cache entry on a successful write without
+// importing the `config` feature. tenant-timezone-boot.integration.test.ts
+// exercises both against the real config feature.
+export const CONFIG_WRITE_SET_TYPE = "config:write:set";
+export const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
 
 export type BatchCommand = {
   readonly type: string;
@@ -110,6 +119,7 @@ export type DispatchContext = {
   sseBroker: SseBroker | undefined;
   tableCache: Map<string, ReturnType<typeof buildEntityTable>>;
   transitionCache: Map<string, ReturnType<typeof defineTransitions>>;
+  tenantTimezoneCache: TenantTimezoneCache;
   tracer: ReturnType<typeof getFallbackTracer>;
   meter: ReturnType<typeof getFallbackMeter>;
 };
@@ -606,7 +616,34 @@ export async function buildHandlerContext(
   // comes from SessionUser.timezone (set at login), else falls back to
   // tenant (createTzContext's own default). An app-injected GeoTzProvider
   // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
-  const tenantTz = config !== undefined ? await config(TENANT_TIMEZONE_CONFIG_KEY) : undefined;
+  //
+  // Resolving this via `config()` is a config-table SELECT on every single
+  // dispatch (fw#2462) — ctx.tenantTimezoneCache memoizes it per tenant.
+  // dispatch-write.ts invalidates on config:write:set/reset for this key.
+  // Only populate from a tx-free read (tx === undefined): a write-path
+  // lookup runs inside the caller's own open transaction, and caching a
+  // value read there could memoize state from a write earlier in that same
+  // transaction before it's known to commit. Reads always consult the
+  // cache regardless of tx, since serving a slightly stale cached value on
+  // the write path is harmless (bounded by ttlMs) and avoids reintroducing
+  // the SELECT on the hot path this fix targets.
+  let tenantTz: unknown;
+  if (config === undefined) {
+    tenantTz = undefined;
+  } else {
+    const cachedTz = ctx.tenantTimezoneCache.get(user.tenantId);
+    if (cachedTz) {
+      tenantTz = cachedTz.value;
+    } else {
+      tenantTz = await config(TENANT_TIMEZONE_CONFIG_KEY);
+      if (tx === undefined) {
+        ctx.tenantTimezoneCache.set(
+          user.tenantId,
+          typeof tenantTz === "string" ? tenantTz : undefined,
+        );
+      }
+    }
+  }
   // Guarded against garbage: an unvalidated string here (free-form config
   // key, legacy JWT claim predating validation) blows up every ctx.tz call
   // for the whole tenant with a RangeError. Fall back to UTC/tenant instead

package/src/pipeline/dispatch-write.ts

@@ -3,6 +3,7 @@ import { selectRowForUpdateById } from "../db/queries/entity-read";
 import { asEntityTableMeta, selectMany } from "../db/query";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder";
 import { hasAccess } from "../engine/access";
+import { ConfigScopes } from "../engine/constants";
 import { checkWriteFieldRoles } from "../engine/field-access";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
 import type { HandlerContext, SessionUser, WriteResult } from "../engine/types";
@@ -22,9 +23,12 @@ import { assertNoSecretLeak } from "../secrets";
 import type { DispatchContext } from "./dispatch-shared";
 import {
   buildHandlerContext,
+  CONFIG_WRITE_RESET_TYPE,
+  CONFIG_WRITE_SET_TYPE,
   checkFeatureEnabled,
   enforceRateLimit,
   runHandlerInstrumented,
+  TENANT_TIMEZONE_CONFIG_KEY,
 } from "./dispatch-shared";
 import {
   type AfterCommitHook,
@@ -73,6 +77,42 @@ function getTransitions(
   return transitions;
 }
 
+// A successful config:write:set/reset returns { key, scope, ... } — see
+// bundled-features/src/config/handlers/{set,reset}.write.ts. Narrows the
+// otherwise-`unknown` WriteResult.data so invalidateTenantTimezoneCache
+// below can check `key` without an unchecked cast.
+function isConfigWriteResultForKey(
+  data: unknown,
+  key: string,
+): data is { key: string; scope?: string } {
+  if (typeof data !== "object" || data === null || !("key" in data)) return false;
+  return (data as { key: unknown }).key === key; // @cast-boundary engine-payload
+}
+
+// fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
+// value per tenant. A successful write to that key must drop the stale
+// entry — tenant/user scope only affects the writing tenant, system scope
+// changes the fallback every tenant without an override reads, so the
+// whole cache is dropped instead of just one entry.
+function invalidateTenantTimezoneCache(
+  ctx: DispatchContext,
+  type: string,
+  user: SessionUser,
+  result: WriteResult,
+): void {
+  // skip: failed write, nothing to invalidate
+  if (!result.isSuccess) return;
+  // skip: not a config:write:set/reset dispatch
+  if (type !== CONFIG_WRITE_SET_TYPE && type !== CONFIG_WRITE_RESET_TYPE) return;
+  // skip: write was for a different config key
+  if (!isConfigWriteResultForKey(result.data, TENANT_TIMEZONE_CONFIG_KEY)) return;
+  if (result.data.scope === ConfigScopes.system) {
+    ctx.tenantTimezoneCache.clear();
+  } else {
+    ctx.tenantTimezoneCache.invalidate(user.tenantId);
+  }
+}
+
 // Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
 // (they see the tx via ctx.db when batch/write opens a transaction).
 // afterCommit hooks are queued into `afterCommitHooks` for the caller to
@@ -450,6 +490,14 @@ async function executeWriteInner(
       const eventData = (parsed.data ?? {}) as DbRow; // @cast-boundary engine-payload
       afterCommitHooks.push(() => jobRunner.handleEvent(type, eventData, user));
     }
+
+    invalidateTenantTimezoneCache(ctx, type, user, result);
+    // Again after commit: a query landing between the drop above and the
+    // commit would read the pre-write row (tx not yet visible) and
+    // repopulate the cache with the stale value for a full TTL.
+    afterCommitHooks.push(async () => {
+      invalidateTenantTimezoneCache(ctx, type, user, result);
+    });
   }
 
   // Response-guard: block Secret<> leaks in write responses (SaveContext

package/src/pipeline/dispatcher.ts

@@ -13,6 +13,7 @@ import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import { createTenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -92,6 +93,9 @@ export function createDispatcher(
   // Pre-build tables and transition maps for auto-guard (avoid per-request allocation)
   const tableCache = new Map<string, ReturnType<typeof buildEntityTable>>();
   const transitionCache = new Map<string, ReturnType<typeof defineTransitions>>();
+  // One per dispatcher instance (not a module-level singleton) so caches
+  // never leak across separately-booted apps or test stacks.
+  const tenantTimezoneCache = createTenantTimezoneCache();
 
   const dispatcherTracer = context.tracer ?? getFallbackTracer();
   const dispatcherMeter = context.meter ?? getFallbackMeter();
@@ -109,6 +113,7 @@ export function createDispatcher(
     sseBroker,
     tableCache,
     transitionCache,
+    tenantTimezoneCache,
     tracer: dispatcherTracer,
     meter: dispatcherMeter,
   };

package/src/pipeline/tenant-timezone-cache.ts

@@ -0,0 +1,92 @@
+// Per-dispatcher in-process cache for the resolved tenant:config:timezone
+// value (fw#2462). dispatch-shared.ts's buildHandlerContext resolves that
+// key on every dispatch to build ctx.tz — without a cache that's a config
+// SELECT (sometimes two, cascade + fallback) per request, often inside an
+// open write transaction. A tenant-keyed TTL cache removes the steady-state
+// cost; dispatch-write.ts invalidates entries synchronously on
+// config:write:set/reset for this key, so the TTL below only covers writes
+// that bypass that path (migrations, seeds, direct DB edits).
+
+import type { TenantId } from "../engine/types/identifiers";
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 1000;
+
+export type TenantTimezoneCacheOptions = {
+  readonly ttlMs?: number;
+  // Cap on distinct tenants cached. On overflow, least-recently-used
+  // entries are evicted — mirrors secrets/dek-cache.ts.
+  readonly maxEntries?: number;
+  readonly now?: () => number;
+};
+
+export type TenantTimezoneCacheEntry = {
+  // The raw resolved config value, or undefined when the tenant has no
+  // override — undefined here is a cached fact ("looked up, no value"),
+  // distinct from a cache miss (get() returning undefined below).
+  readonly value: string | undefined;
+};
+
+export type TenantTimezoneCache = {
+  // Returns undefined on a cache miss (never looked up, or expired).
+  get(tenantId: TenantId): TenantTimezoneCacheEntry | undefined;
+  set(tenantId: TenantId, value: string | undefined): void;
+  invalidate(tenantId: TenantId): void;
+  // Drops every tenant's entry — used when a system-scope write changes
+  // the key, since the system row is the fallback default for every
+  // tenant without its own override (a system-scope change can affect
+  // all of them at once).
+  clear(): void;
+  size(): number;
+};
+
+export function createTenantTimezoneCache(
+  opts: TenantTimezoneCacheOptions = {},
+): TenantTimezoneCache {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const now = opts.now ?? (() => Date.now());
+  // Map insertion order doubles as LRU order: touch = delete+re-insert.
+  const entries = new Map<TenantId, { value: string | undefined; expiresAt: number }>();
+
+  function evictOldestIfFull(): void {
+    // skip: cache has room, nothing to evict
+    if (entries.size < maxEntries) return;
+    const oldestKey = entries.keys().next().value;
+    // skip: defensive — only reachable if maxEntries is 0 (cache disabled) and entries is empty
+    if (oldestKey === undefined) return;
+    entries.delete(oldestKey);
+  }
+
+  return {
+    get(tenantId) {
+      const hit = entries.get(tenantId);
+      if (!hit) return undefined;
+      if (hit.expiresAt <= now()) {
+        entries.delete(tenantId);
+        return undefined;
+      }
+      entries.delete(tenantId);
+      entries.set(tenantId, hit);
+      return { value: hit.value };
+    },
+
+    set(tenantId, value) {
+      entries.delete(tenantId);
+      evictOldestIfFull();
+      entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+    },
+
+    invalidate(tenantId) {
+      entries.delete(tenantId);
+    },
+
+    clear() {
+      entries.clear();
+    },
+
+    size() {
+      return entries.size;
+    },
+  };
+}

package/src/schema-cli.ts

@@ -14,13 +14,11 @@ import {
   assertValidMigrationName,
   baselineMigrations,
   createDbConnection,
-  type DbConnection,
   diffReplayAgainstSnapshot,
   fetchAppliedMigrations,
   generateMigration,
   loadMigrationsFromDir,
   loadSnapshotJson,
-  readRebuildMarker,
   rebuildTablesFromDiff,
   type renderTablesDdl,
   replayMigrationsDir,
@@ -33,12 +31,8 @@ import { validateBoot } from "./engine/boot-validator";
 import { createRegistry } from "./engine/registry";
 import type { FeatureDefinition } from "./engine/types/feature";
 import { createEventsTable } from "./event-store";
-import { buildProjectionTableIndex } from "./migrations";
-import {
-  createEventConsumerStateTable,
-  createProjectionStateTable,
-  rebuildProjection,
-} from "./pipeline";
+import { queueRebuildsFromMarkers, runPendingRebuilds } from "./migrations";
+import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline";
 import { ensureTemporalPolyfill } from "./time";
 
 export type SchemaCliOut = {
@@ -86,33 +80,6 @@ function nextSequenceNumber(migrationsDir: string): number {
   return max + 1;
 }
 
-// Maps changed tables to their projections (via the app registry) and replays
-// the events. Tables without a registered projection are skipped.
-async function rebuildAffectedProjections(
-  db: DbConnection,
-  changedTables: readonly string[],
-  features: readonly FeatureDefinition[],
-  out: SchemaCliOut,
-): Promise<void> {
-  const registry = createRegistry(features);
-  const tableToProjection = buildProjectionTableIndex(registry);
-
-  const projections = new Set<string>();
-  for (const table of changedTables) {
-    const name = tableToProjection.get(table);
-    if (name) projections.add(name);
-  }
-  // skip: no changed table maps to a registered projection — nothing to rebuild.
-  if (projections.size === 0) return;
-
-  out.log(`  Rebuild ${projections.size} Projection(s)…`);
-  for (const name of projections) {
-    const r = await rebuildProjection(name, { db, registry });
-    out.log(`    ↻ ${name} (${r.eventsProcessed} events, ${r.durationMs}ms)`);
-  }
-  out.log("");
-}
-
 export type RunSchemaCliOptions = {
   /** Composed app features. When given, `apply` rebuilds the projections whose
    *  tables a freshly applied migration changed (via its `.rebuild.json`
@@ -370,17 +337,36 @@ export async function runSchemaCli(
         out.log("");
 
         // Projection-rebuild for tables a freshly applied migration changed
-        // (marker NNNN_<name>.rebuild.json from `generate`). Without it read_*
-        // projections stay stale after a schema change. Needs the composed
+        // (marker NNNN_<name>.rebuild.json from `generate`). Needs the composed
         // feature set → only when the caller passed `features` (the app bin);
-        // the dev CLI omits it and applies migrations only.
-        if (options.features && result.applied.length > 0) {
-          const changedTables = new Set<string>();
-          for (const id of result.applied) {
-            for (const table of readRebuildMarker(migrationsDir, id)) changedTables.add(table);
+        // the dev CLI omits it and applies migrations only. Runs unconditionally
+        // (not gated on result.applied.length > 0): a persistent queue
+        // (kumiko_pending_rebuilds) survives a failed/crashed rebuild from an
+        // earlier apply, so a later apply with zero new migrations still must
+        // retry it — otherwise a failed rebuild is silently never retried,
+        // since the migration itself is already tracked applied (#2464).
+        if (options.features) {
+          const thisRunTables = await queueRebuildsFromMarkers(db, {
+            migrationsDir,
+            appliedIds: result.applied,
+          });
+          const registry = createRegistry(options.features);
+          const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
+          if (rebuildRun.rebuilt.length > 0) {
+            out.log(`  Rebuild ${rebuildRun.rebuilt.length} Projection(s)…`);
+            for (const r of rebuildRun.rebuilt) {
+              out.log(`    ↻ ${r.projection} (${r.eventsProcessed} events)`);
+            }
+            out.log("");
           }
-          if (changedTables.size > 0) {
-            await rebuildAffectedProjections(db, [...changedTables], options.features, out);
+          if (rebuildRun.failed.length > 0) {
+            throw new Error(
+              `Projection rebuild failed for: ${rebuildRun.failed
+                .map((f) => `${f.projection} (${f.error})`)
+                .join(
+                  "; ",
+                )}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`,
+            );
           }
         }
         return 0;

package/src/scripts/codemod/pii-personal-migration.ts

@@ -77,7 +77,7 @@ const OVERRIDES_ARG_INDEX_1 = new Set(["createEmbeddedField", "createEmbeddedLis
 
 const FIELD_FACTORY_RE = /^create\w*Field$/;
 
-type ReportEntry = { readonly file: string; readonly line: number; readonly reason: string };
+type ReportEntry = { readonly file: string; readonly line: number; readonly note: string };
 type FindBucket = "exact" | "fuzzy" | "none" | "secret" | "ref" | "personal-false" | "no-find";
 
 const reports: ReportEntry[] = [];
@@ -92,11 +92,11 @@ const counts: Record<FindBucket, number> = {
   "no-find": 0,
 };
 
-function report(node: Node, reason: string): void {
+function report(node: Node, note: string): void {
   reports.push({
     file: node.getSourceFile().getFilePath(),
     line: node.getStartLineNumber(),
-    reason,
+    note,
   });
 }
 
@@ -374,8 +374,8 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
     newLookupableSites.push({
       file: obj.getSourceFile().getFilePath(),
       line: subject.prop.getStartLineNumber(),
-      // find: "fuzzy" newly adds lookupable (was searchable-only) — needs a _bidx column migration
-      reason: "fuzzy_search_needs_bidx_migration",
+      // Guard keys on property name `reason`; this is console copy, not an error code.
+      note: "needs a `_bidx` column migration",
     });
   }
 
@@ -469,11 +469,11 @@ async function main(): Promise<void> {
   }
   console.log(`\nNewly gains lookupable (needs a _bidx migration): ${newLookupableSites.length}`);
   for (const r of newLookupableSites) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
   }
   console.log(`\nReported (not transformed): ${reports.length}`);
   for (const r of reports) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
   }
 }
 

package/src/stack/__tests__/request-helper.test.ts

@@ -103,7 +103,7 @@ describe("createRequestHelper", () => {
       ),
     );
     const http = createRequestHelper(app, jwtStub().jwt);
-    expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
+    await expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
       'Expected write "todo.create" to succeed but got error: internal_error (DbError: connection lost)',
     );
   });
@@ -119,7 +119,7 @@ describe("createRequestHelper", () => {
 
     const succeeding = appRecording(() => Response.json({ isSuccess: true, data: {} }));
     const http2 = createRequestHelper(succeeding.app, jwtStub().jwt);
-    expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
+    await expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
       'Expected query "q.type" to fail but it succeeded',
     );
   });

package/src/testing/file-provider-contract.ts

@@ -90,6 +90,25 @@ export function describeFileProviderContract(
       await expect(it.next()).rejects.toThrow();
     });
 
+    test("list returns only keys under the given prefix", async () => {
+      const group = `contract/list-${crypto.randomUUID()}`;
+      const keyA = `${group}/a.txt`;
+      const keyB = `${group}/b.txt`;
+      const outsideKey = `contract/list-${crypto.randomUUID()}/c.txt`;
+      writtenKeys.push(keyA, keyB, outsideKey);
+      await provider.write(keyA, bytes("a"));
+      await provider.write(keyB, bytes("b"));
+      await provider.write(outsideKey, bytes("c"));
+
+      const listed = await provider.list(`${group}/`);
+      expect(new Set(listed)).toEqual(new Set([keyA, keyB]));
+    });
+
+    test("list on a prefix with no matches returns an empty array", async () => {
+      const listed = await provider.list(`contract/list-missing-${crypto.randomUUID()}/`);
+      expect(listed).toEqual([]);
+    });
+
     test("getSignedUrl, when implemented, returns a URL string", async () => {
       // skip: getSignedUrl is optional on the contract — feature-detected
       if (!provider.getSignedUrl) return;

package/src/upgrade-cli.ts

@@ -271,10 +271,15 @@ type UpgradeMarkerCodemod = {
   readonly codemod: string;
   readonly title: string;
 };
+type UpgradeMarkerManual = {
+  readonly version: string;
+  readonly title: string;
+};
 type UpgradeMarker = {
   readonly version: string;
   readonly appliedAt: string;
   readonly codemods: readonly UpgradeMarkerCodemod[];
+  readonly pendingManual?: readonly UpgradeMarkerManual[];
 };
 
 function writeUpgradeMarker(targetDir: string, marker: UpgradeMarker): void {
@@ -324,6 +329,7 @@ function markerVersionForPending(
 // failure — no partial marker. Writes the marker whenever dryRun is false —
 // even with zero pending entries, so an already-current app still gets a
 // bootstrap marker recording its installed version (fw#2299).
+// kumiko-lint-ignore complexity-budget sequential codemod runner with zero-pending bootstrap marker
 async function applyCodemods(
   out: UpgradeCliOut,
   pending: readonly ChangelogEntry[],
@@ -352,7 +358,7 @@ async function applyCodemods(
   const codemodEntries = breaking
     .filter(hasCodemod)
     .sort((a, b) => compareVersions(a.version, b.version));
-  const manualEntries = breaking.filter((e) => !e.codemod);
+  const manualEntries = breaking.filter((e) => !hasCodemod(e));
 
   for (const e of manualEntries) {
     out.log(`  ⚠ ${e.version} · ${e.title} — no codemod, manual migration required`);
@@ -407,14 +413,19 @@ async function applyCodemods(
   }
 
   const latestVersion = markerVersionForPending(pending, manualEntries, markerVersion);
+  const pendingManual = manualEntries.map((e) => ({ version: e.version, title: e.title }));
   writeUpgradeMarker(targetDir, {
     version: latestVersion,
     appliedAt: Temporal.Now.instant().toString(),
     codemods: ran,
+    ...(pendingManual.length > 0 && { pendingManual }),
   });
   out.log(
     `  ✓ Applied ${ran.length} codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`,
   );
+  if (pendingManual.length > 0) {
+    out.log(`  ⚠ ${pendingManual.length} breaking change(s) still need manual migration.`);
+  }
   return 0;
 }