@cosmicdrift/kumiko-framework 0.57.2 → 0.59.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.57.2",
+  "version": "0.59.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.55.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.57.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -3,7 +3,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
-import { createDbConnection, tableExists } from "../db";
+import { tableExists } from "../db";
+import { asRawClient } from "../db/query";
 import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
 import { ensureTemporalPolyfill } from "../time/polyfill";
 
@@ -192,24 +193,34 @@ describe("runSchemaCli — DB-backed paths", () => {
     // entity-read tables after `apply`, so runProdApp's first event-store access
     // hit "relation kumiko_events does not exist". `apply` now ensures the
     // framework-infra tables (idempotent) so a greenfield deploy boots.
+    //
+    // createTestDb's beforeAll already materialized kumiko_events/_snapshots/
+    // _archived_streams via createEventsTable — without dropping all five infra
+    // tables first, 3/5 assertions would be tautological (green even if `apply`
+    // never created them). Drop → assert-absent reproduces greenfield in the
+    // shared DB; apply recreates them, so the end-state matches the other tests.
+    const infraTables = [
+      "public.kumiko_events",
+      "public.kumiko_snapshots",
+      "public.kumiko_archived_streams",
+      "public.kumiko_event_consumers",
+      "public.kumiko_projections",
+    ];
+    await asRawClient(testDb.db).unsafe(
+      `DROP TABLE IF EXISTS "kumiko_events", "kumiko_snapshots", "kumiko_archived_streams", ` +
+        `"kumiko_event_consumers", "kumiko_projections" CASCADE`,
+    );
+    for (const table of infraTables) {
+      expect(await tableExists(testDb.db, table)).toBe(false);
+    }
+
     const appCwd = freshAppCwd();
     writeSchemaFile(appCwd, "tbl_infra");
     await runSchemaCli(["generate", "infra_test"], appCwd, captureOut().out);
     await runSchemaCli(["apply"], appCwd, captureOut().out);
 
-    const { db, close } = createDbConnection(dbUrl);
-    try {
-      for (const table of [
-        "public.kumiko_events",
-        "public.kumiko_snapshots",
-        "public.kumiko_archived_streams",
-        "public.kumiko_event_consumers",
-        "public.kumiko_projections",
-      ]) {
-        expect(await tableExists(db, table)).toBe(true);
-      }
-    } finally {
-      await close();
+    for (const table of infraTables) {
+      expect(await tableExists(testDb.db, table)).toBe(true);
     }
     rmSync(appCwd, { recursive: true, force: true });
   });

package/src/api/__tests__/origin-middleware.test.ts

@@ -16,6 +16,21 @@ import {
   originMiddleware,
 } from "../origin-middleware";
 
+function isErrorBody(v: unknown): v is { error: { code: string } } {
+  if (typeof v !== "object" || v === null || !("error" in v)) return false;
+  const err = (v as { error: unknown }).error;
+  return (
+    typeof err === "object" && err !== null && typeof (err as { code: unknown }).code === "string"
+  );
+}
+
+async function readErrorCode(res: Response): Promise<string> {
+  const body: unknown = await res.json();
+  if (!isErrorBody(body))
+    throw new Error(`expected { error: { code } }, got ${JSON.stringify(body)}`);
+  return body.error.code;
+}
+
 const JWT_SECRET = "origin-middleware-test-secret-min-32-characters-long";
 const ALLOWED = "https://admin.example.eu";
 const DISALLOWED = "https://tenant.example.eu";
@@ -123,8 +138,7 @@ describe("originMiddleware", () => {
       headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
     });
     expect(res.status).toBe(403);
-    const body = (await res.json()) as { error: { code: string } };
-    expect(body.error.code).toBe("origin_not_allowed");
+    expect(await readErrorCode(res)).toBe("origin_not_allowed");
   });
 
   // The guard runs as /api/* middleware before routing, so a disallowed-origin
@@ -140,9 +154,7 @@ describe("originMiddleware", () => {
       headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, Origin: DISALLOWED },
     });
     expect(res.status).toBe(403);
-    expect(((await res.json()) as { error: { code: string } }).error.code).toBe(
-      "origin_not_allowed",
-    );
+    expect(await readErrorCode(res)).toBe("origin_not_allowed");
   });
 
   test("disallowed origin is blocked even as a simple text/plain request", async () => {
@@ -198,7 +210,6 @@ describe("originMiddleware", () => {
       headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}`, "Sec-Fetch-Site": "cross-site" },
     });
     expect(res.status).toBe(403);
-    const body = (await res.json()) as { error: { code: string } };
-    expect(body.error.code).toBe("origin_not_allowed");
+    expect(await readErrorCode(res)).toBe("origin_not_allowed");
   });
 });

package/src/db/__tests__/schema-inspection.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import type { DbConnection } from "../connection";
+import { columnNamesOf, tableExists } from "../schema-inspection";
+
+describe("schema-inspection — resolveUnsafeClient guard", () => {
+  // A db handle without `.unsafe` on $client / session.client / itself used to
+  // reach the query call as `undefined` and crash callers with an opaque
+  // "unsafe is not a function". The guard must surface a named, actionable error.
+  const noUnsafe = {} as unknown as DbConnection;
+
+  test("tableExists throws a named error when no .unsafe fn resolves", async () => {
+    await expect(tableExists(noUnsafe, "public.x")).rejects.toThrow(
+      /resolveUnsafeClient: no `\.unsafe/,
+    );
+  });
+
+  test("columnNamesOf throws the same named error", async () => {
+    await expect(columnNamesOf(noUnsafe, "x")).rejects.toThrow(/resolveUnsafeClient: no `\.unsafe/);
+  });
+});

package/src/db/event-store-executor.ts

@@ -930,6 +930,12 @@ export function createEventStoreExecutor(
       const tableInfo = extractTableInfo(table);
       const rows = rawRows.map((r) => coerceRow(rehydrateCompoundTypes(r, entity), tableInfo));
 
+      // list rows (and their cache entries) carry the READ-ROW version, not the
+      // authoritative stream version detail() applies. That is intentional —
+      // it's display-only and must never be used as an optimistic-lock base;
+      // edit flows reload via detail(), which reconciles the stream version.
+      // Sourcing a lock base from a list row would reintroduce the #336
+      // version_conflict. (#336)
       if (entityCache && entityName && rows.length > 0) {
         await entityCache.mset(
           user.tenantId,

package/src/db/schema-inspection.ts

@@ -12,7 +12,14 @@ function resolveUnsafeClient(db: DbConnection | DbTx): UnsafeFn {
     unsafe?: UnsafeFn;
   };
   const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
-  return (client as { unsafe: UnsafeFn }).unsafe;
+  const fn = (client as { unsafe?: UnsafeFn }).unsafe;
+  if (fn === undefined) {
+    throw new Error(
+      "resolveUnsafeClient: no `.unsafe(sql, params)` fn on the db connection " +
+        "(checked $client, session.client, db itself) — schema-inspection needs the raw postgres escape hatch.",
+    );
+  }
+  return fn;
 }
 
 // True when `<fullyQualifiedName>` refers to an existing relation in the

package/src/db/table-builder.ts

@@ -409,6 +409,17 @@ export function buildBaseColumns(softDelete: boolean, idType: "serial" | "uuid"
   return base;
 }
 
+const ROW_META_BASE: ReadonlySet<string> = new Set(Object.keys(buildBaseColumns(false)));
+const ROW_META_WITH_SOFT_DELETE: ReadonlySet<string> = new Set(Object.keys(buildBaseColumns(true)));
+
+// Row-meta columns exist on every row without being declared entity fields, so the
+// boot-validator must treat them as known when an action picks/maps/gates on them.
+// softDelete-only columns stay unknown for non-softDelete entities — gating on them
+// there is a real misconfiguration, not a row-meta reference.
+export function rowMetaFieldNames(softDelete: boolean): ReadonlySet<string> {
+  return softDelete ? ROW_META_WITH_SOFT_DELETE : ROW_META_BASE;
+}
+
 export type BuildEntityTableOptions = {
   readonly featureName?: string;
   // Relations declared for this entity. When present, every belongsTo

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

@@ -2008,6 +2008,82 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- row-meta allowlist: ALLE Base-Columns, nicht nur id/version (#331, #323) ---
+  // buildBaseColumns legt tenantId/insertedAt/modifiedAt/...-Spalten auf jede Row;
+  // pick/map/visible darauf ist legitim und darf den Boot nicht killen. softDelete-
+  // Spalten (isDeleted/...) existieren NUR auf softDelete-Entities — darauf zu picken
+  // ist sonst eine echte Fehlkonfiguration und muss weiter werfen.
+  describe("entityList rowAction row-meta allowlist (#331, #323)", () => {
+    function makeFeature(opts: {
+      pick?: readonly string[];
+      visibleField?: string;
+      softDelete?: boolean;
+    }) {
+      return defineFeature("shop", (r) => {
+        r.entity(
+          "product",
+          createEntity({
+            fields: { name: createTextField() },
+            softDelete: opts.softDelete ?? false,
+          }),
+        );
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            {
+              id: "archive",
+              label: "actions.archive",
+              handler: "shop:write:archive",
+              ...(opts.pick ? { payload: { pick: [...opts.pick] } } : {}),
+              ...(opts.visibleField ? { visible: { field: opts.visibleField, eq: true } } : {}),
+            },
+          ],
+        });
+        r.writeHandler(
+          "archive",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+      });
+    }
+
+    test("pick mit Base-Column tenantId → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ pick: ["id", "tenantId"] })])).not.toThrow();
+    });
+
+    test("visible.field auf Row-Meta (version) → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ visibleField: "version" })])).not.toThrow();
+    });
+
+    test("visible.field auf id → kein Throw (Aggregat-id immer vorhanden)", () => {
+      expect(() => validateBoot([makeFeature({ visibleField: "id" })])).not.toThrow();
+    });
+
+    test("visible.field auf unknown Field → Throw", () => {
+      expect(() => validateBoot([makeFeature({ visibleField: "ghost" })])).toThrow(
+        /visible\.field references unknown field "ghost"/,
+      );
+    });
+
+    test("softDelete-Entity: pick isDeleted → kein Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ pick: ["id", "isDeleted"], softDelete: true })]),
+      ).not.toThrow();
+    });
+
+    test("Nicht-softDelete-Entity: pick isDeleted → Throw (Spalte existiert nicht)", () => {
+      expect(() =>
+        validateBoot([makeFeature({ pick: ["id", "isDeleted"], softDelete: false })]),
+      ).toThrow(/references unknown field "isDeleted"/);
+    });
+  });
+
   // --- toolbarAction navigate + writeHandler Validierung (Tier 2.7e-2) ---
   describe("entityList toolbarAction navigate (Tier 2.7e-2)", () => {
     function makeFeature(targetScreen: string, withTarget: boolean) {

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -254,8 +254,31 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
       r.config({ keys: { apiKey: createTenantConfig("text", { mask: { title: "a.key" } }) } });
     });
     const out = buildConfigFeatureSchema(createRegistry([adminOnly]));
-    expect(out.workspace?.definition.access).toEqual({
-      roles: ["TenantAdmin", "Admin", "SystemAdmin"],
+    const acc = out.workspace?.definition.access;
+    expect(acc && "roles" in acc ? [...acc.roles].sort() : acc).toEqual([
+      "Admin",
+      "SystemAdmin",
+      "TenantAdmin",
+    ]);
+  });
+
+  test("workspace access excludes the machine-only 'system' role when a machine key is masked", () => {
+    // A masked machine-only key (write defaults to ["system"]) is excluded from
+    // every human nav — its "system" role must not leak into the switcher gate
+    // just because it sits in the hub next to a human-writable key (#406/1).
+    const mixed = defineFeature("mixedhub", (r) => {
+      r.config({
+        keys: {
+          label: createTenantConfig("text", { mask: { title: "m.label" } }),
+          internalFlag: createSystemConfig("boolean", { mask: { title: "m.flag" } }),
+        },
+      });
     });
+    const out = buildConfigFeatureSchema(createRegistry([mixed]));
+    const acc = out.workspace?.definition.access;
+    expect(acc).toBeDefined();
+    const roles = acc && "roles" in acc ? acc.roles : [];
+    expect(roles).not.toContain("system");
+    expect([...roles].sort()).toEqual(["Admin", "SystemAdmin", "TenantAdmin"]);
   });
 });

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -162,6 +162,17 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
     expect(warnSpy).toHaveBeenCalledTimes(1);
   });
 
+  test("collision dedup is scoped per registry — separate registries each warn", async () => {
+    // Identical contributor-vs-base collision in two independent registries. A
+    // module-global dedup Set would warn for the first and silence the second
+    // (and leak across tests); per-registry scoping must warn once for EACH.
+    const r1 = registryWith(() => ({ title: "from-contributor" }));
+    const r2 = registryWith(() => ({ title: "from-contributor" }));
+    await buildSearchDocument("thing", "t1", { title: "real-value" }, r1);
+    await buildSearchDocument("thing", "t1", { title: "real-value" }, r2);
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
+
   test("contributor-vs-contributor collision warns with the right message", async () => {
     const feature = defineFeature("test", (r) => {
       const thing = r.entity(

package/src/engine/boot-validator/screens-nav.ts

@@ -1,3 +1,4 @@
+import { rowMetaFieldNames } from "../../db/table-builder";
 import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
@@ -31,6 +32,7 @@ function validateActionFieldRefs(
   actionId: string,
   action: RowAction | ToolbarAction,
   fieldNames: ReadonlySet<string>,
+  rowMeta: ReadonlySet<string>,
 ): void {
   // ToolbarAction.payload ist ein STATISCHER Record (kein Row-Context) —
   // nur echte pick/map-Extractoren werden gegen die Feldnamen geprüft.
@@ -49,9 +51,7 @@ function validateActionFieldRefs(
     }
     const sources = "pick" in extractor ? extractor.pick : Object.values(extractor.map);
     for (const source of sources) {
-      // Row-Meta ist immer da, ohne Entity-Field zu sein: id (Aggregat-Id)
-      // und version (optimistic lock — Standard-pick für Lifecycle-Writes).
-      if (source === "id" || source === "version") continue;
+      if (rowMeta.has(source)) continue;
       if (!fieldNames.has(source)) {
         throw new Error(
           `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
@@ -62,7 +62,12 @@ function validateActionFieldRefs(
   };
   checkExtractor("payload", payload);
   checkExtractor("params", params);
-  if (visible !== undefined && typeof visible !== "boolean" && !fieldNames.has(visible.field)) {
+  if (
+    visible !== undefined &&
+    typeof visible !== "boolean" &&
+    !rowMeta.has(visible.field) &&
+    !fieldNames.has(visible.field)
+  ) {
     throw new Error(
       `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
         `visible.field references unknown field "${visible.field}". Known fields: ${known()}.`,
@@ -304,6 +309,7 @@ export function validateScreens(
     }
 
     const fieldNames = new Set(Object.keys(entityDef.fields));
+    const rowMeta = rowMetaFieldNames(entityDef.softDelete ?? false);
     if (screen.type === "entityList") {
       // Empty column list would render as a blank table — almost always the
       // sign of an in-progress screen the author forgot to fill in. Fail
@@ -437,6 +443,7 @@ export function validateScreens(
             action.id,
             action,
             fieldNames,
+            rowMeta,
           );
         }
       }
@@ -469,6 +476,7 @@ export function validateScreens(
             action.id,
             action,
             fieldNames,
+            rowMeta,
           );
         }
       }

package/src/engine/build-config-feature-schema.ts

@@ -132,7 +132,7 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
   // Alle masked Keys maschinen-only → kein menschlicher Hub, kein (leerer)
   // Settings-Switcher.
   if (navs.length === 0) return { screens, navs };
-  return { screens, navs, workspace: buildSettingsWorkspace(navs, masked) };
+  return { screens, navs, workspace: buildSettingsWorkspace(navs) };
 }
 
 // Keys, die an `scope` sichtbar sind, gepaart mit ihren effektiven Schreib-
@@ -157,10 +157,7 @@ function effectiveWriteRoles(def: ConfigKeyDefinition, scope: ConfigScope): stri
 // admin.navMembers === ["orders:nav:list", ...]). Die generierten Navs leben
 // unter SETTINGS_HUB_FEATURE, also `config:nav:<shortId>`. Sortiert = stabile
 // Landing-Screen-Wahl (firstNavScreenId iteriert navMembers der Reihe nach).
-function buildSettingsWorkspace(
-  navs: readonly NavDefinition[],
-  masked: readonly MaskedKey[],
-): WorkspaceSchema {
+function buildSettingsWorkspace(navs: readonly NavDefinition[]): WorkspaceSchema {
   const navMembers = navs.map((n) => `${SETTINGS_HUB_FEATURE}:nav:${n.id}`).sort();
   return {
     definition: {
@@ -168,9 +165,12 @@ function buildSettingsWorkspace(
       label: "config.settings.title",
       icon: "settings",
       order: 1000,
-      // Union der Schreib-Rollen aller Hub-Keys — sonst sieht ein
-      // unprivilegierter User einen leeren "Settings"-Switcher-Eintrag.
-      access: unionEditAccess(masked.map((k) => k.def)),
+      // Union der Zugriffs-Regeln der bereits generierten (machine-gefilterten)
+      // Hub-Navs — sonst sieht ein unprivilegierter User einen leeren
+      // "Settings"-Switcher. Aus den Navs statt aus `masked`, damit die
+      // machine-only "system"-Rolle (die in keinem Nav steht) nicht ins
+      // Switcher-Gate leakt.
+      access: unionAccessRules(navs.map((n) => n.access)),
     },
     navMembers,
   };
@@ -265,8 +265,16 @@ function minMaskOrder(keys: readonly MaskedKey[]): number {
 // opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
 // AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
 // per Key gegated.
-function unionEditAccess(defs: readonly ConfigKeyDefinition[]): AccessRule {
-  return rolesToAccess(defs.flatMap((d) => [...d.access.write]));
+// Union der Navs-Access-Regeln: ein openToAll-Nav öffnet das ganze Gate, sonst
+// die Vereinigung der Rollen. undefined-access-Navs tragen nichts bei.
+function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRule {
+  const roles: string[] = [];
+  for (const rule of rules) {
+    if (rule === undefined) continue;
+    if ("openToAll" in rule) return { openToAll: true };
+    roles.push(...rule.roles);
+  }
+  return rolesToAccess(roles);
 }
 
 // `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -30,7 +30,9 @@ import {
   unsafePushTables,
 } from "../../stack";
 import {
+  clearPendingRebuilds,
   enqueueProjectionRebuild,
+  listPendingRebuildRows,
   listPendingRebuilds,
   queueRebuildsFromMarkers,
   runPendingRebuilds,
@@ -161,6 +163,36 @@ describe("pending-rebuilds queue", () => {
     expect(await listPendingRebuilds(testDb.db)).toEqual([]);
   });
 
+  test("clear is scoped to the snapshot migration_id — a concurrent re-queue survives (#328)", async () => {
+    // Snapshot read: table queued for migration 0001.
+    writeRebuildMarker(markerDir, "0001_counts.sql", ["read_pending_counts"]);
+    await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0001_counts"],
+    });
+    const snapshot = await listPendingRebuildRows(testDb.db);
+    expect(snapshot).toEqual([{ tableName: "read_pending_counts", migrationId: "0001_counts" }]);
+
+    // A concurrent apply re-queues the SAME table for a NEWER migration between
+    // the snapshot read and the clear (upsert bumps migration_id, keeps the slot).
+    writeRebuildMarker(markerDir, "0002_counts.sql", ["read_pending_counts"]);
+    await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0002_counts"],
+    });
+
+    // Clearing against the OLD snapshot must NOT drop the freshly re-queued entry.
+    await clearPendingRebuilds(testDb.db, snapshot);
+    expect(await listPendingRebuilds(testDb.db)).toEqual(["read_pending_counts"]);
+    expect(await listPendingRebuildRows(testDb.db)).toEqual([
+      { tableName: "read_pending_counts", migrationId: "0002_counts" },
+    ]);
+
+    // Clearing against the CURRENT snapshot does drain it.
+    await clearPendingRebuilds(testDb.db, await listPendingRebuildRows(testDb.db));
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+  });
+
   test("no markers, no queue → noop", async () => {
     const run = await runPendingRebuilds(testDb.db, registry);
     expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] });

package/src/migrations/pending-rebuilds.ts

@@ -59,19 +59,33 @@ export async function queueRebuildsFromMarkers(
   return [...queued];
 }
 
-type PendingRebuildRow = { readonly tableName: string };
+type PendingRebuildRow = { readonly tableName: string; readonly migrationId: string };
 
-export async function listPendingRebuilds(db: DbConnection): Promise<readonly string[]> {
+export async function listPendingRebuildRows(
+  db: DbConnection,
+): Promise<readonly PendingRebuildRow[]> {
   await createPendingRebuildsTable(db);
   const rows = await selectMany<PendingRebuildRow>(db, pendingRebuildsTable, undefined, {
     orderBy: [{ col: "queuedAt" }, { col: "tableName" }],
   });
-  return rows.map((row) => row.tableName);
+  return rows.map((row) => ({ tableName: row.tableName, migrationId: row.migrationId }));
+}
+
+export async function listPendingRebuilds(db: DbConnection): Promise<readonly string[]> {
+  return (await listPendingRebuildRows(db)).map((row) => row.tableName);
 }
 
-async function clearPendingRebuilds(db: DbConnection, tables: readonly string[]): Promise<void> {
-  for (const tableName of tables) {
-    await deleteMany(db, pendingRebuildsTable, { tableName });
+// Clears against the (table_name, migration_id) snapshot the caller read, not
+// table_name alone: a concurrent queueRebuildsFromMarkers can re-queue the same
+// table for a NEWER migration (upsert bumps migration_id, keeps the slot)
+// between the read and the clear. Scoping the delete to the snapshot's
+// migration_id leaves that fresh re-queue intact instead of dropping it. (#328)
+export async function clearPendingRebuilds(
+  db: DbConnection,
+  rows: readonly PendingRebuildRow[],
+): Promise<void> {
+  for (const { tableName, migrationId } of rows) {
+    await deleteMany(db, pendingRebuildsTable, { tableName, migrationId });
   }
 }
 
@@ -111,10 +125,20 @@ export async function runPendingRebuilds(
   registry: Registry,
   options: RunPendingRebuildsOptions = {},
 ): Promise<PendingRebuildRun> {
-  const pending = await listPendingRebuilds(db);
-  if (pending.length === 0) {
+  const pendingRows = await listPendingRebuildRows(db);
+  if (pendingRows.length === 0) {
     return { rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] };
   }
+  // (table → migration) snapshot read together with the table list; the clear
+  // below scopes its DELETE to this migration_id so a concurrent re-queue for a
+  // newer migration survives instead of being dropped (#328).
+  const migrationByTable = new Map(pendingRows.map((r) => [r.tableName, r.migrationId]));
+  const snapshotRows = (tables: readonly string[]): readonly PendingRebuildRow[] =>
+    tables.flatMap((tableName) => {
+      const migrationId = migrationByTable.get(tableName);
+      return migrationId === undefined ? [] : [{ tableName, migrationId }];
+    });
+  const pending = pendingRows.map((r) => r.tableName);
 
   const tableToProjection = buildProjectionTableIndex(registry);
   const thisRun = new Set(options.thisRunTables ?? []);
@@ -141,7 +165,7 @@ export async function runPendingRebuilds(
   // nicht im Liegenlassen.
   const drained = [...unmapped, ...unresolvedManaged];
   if (drained.length > 0) {
-    await clearPendingRebuilds(db, drained);
+    await clearPendingRebuilds(db, snapshotRows(drained));
   }
 
   if (unresolvedManaged.length > 0) {
@@ -156,7 +180,7 @@ export async function runPendingRebuilds(
   for (const [projection, tables] of byProjection) {
     try {
       const result = await rebuildProjection(projection, { db, registry });
-      await clearPendingRebuilds(db, tables);
+      await clearPendingRebuilds(db, snapshotRows(tables));
       rebuilt.push({ projection, eventsProcessed: result.eventsProcessed });
     } catch (e) {
       failed.push({ projection, error: e instanceof Error ? e.message : String(e) });

package/src/pipeline/__tests__/projection-rebuild.integration.test.ts

@@ -687,7 +687,7 @@ describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
       // Fires after the unlocked bulk drain (events 1+2 applied) and before the
       // fence. A 3rd event committed here is exactly the write Phase 1's single
       // up-front SELECT missed — the fenced final drain must pick it up.
-      onBeforeFence: async () => {
+      __test_onBeforeFence: async () => {
         injected++;
         await appendCreatedEvent(group, "c"); // event id 3, separate connection
       },
@@ -698,6 +698,58 @@ describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
     expect(await getCount(group)).toBe(3);
   });
 
+  test("KNOWN LIMITATION (#443): a lower-id write committed late during replay is currently LOST", async () => {
+    // bigserial assigns ids at INSERT (pre-commit); a cross-aggregate write can
+    // commit an id BELOW the cursor the unlocked drain already advanced past, and
+    // the fenced final drain (`WHERE id > cursor`) never revisits it. This
+    // characterization test pins that data-loss deterministically. No clean fix
+    // preserves the online (short-fence) property — see #443. When the fix lands,
+    // flip groupX's assertion to toBe(1).
+    const db = testDb.db as DbConnection; // @cast-boundary test-harness (TestDb.db is intentionally unknown)
+    const groupX = "00000000-0000-4000-8000-000000000201";
+    const groupY = "00000000-0000-4000-8000-000000000202";
+    const aggX = "00000000-0000-4000-8000-0000000002a1";
+
+    // Connection A inserts aggregate X's event (grabs the LOW id) but holds its
+    // tx open — uncommitted, so the rebuild's READ COMMITTED scan can't see it.
+    let releaseX!: () => void;
+    const xGate = new Promise<void>((resolve) => {
+      releaseX = resolve;
+    });
+    let markXInserted!: () => void;
+    const xInserted = new Promise<void>((resolve) => {
+      markXInserted = resolve;
+    });
+    const xDone = db.begin(async (xtx: DbTx) => {
+      await asRawClient(xtx).unsafe(
+        `INSERT INTO "kumiko_events"
+           (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+         VALUES ($1::uuid, 'rebuild-item', $2::uuid, 0, 'rebuild-item.created', $3::jsonb, '{}'::jsonb, 'test')`,
+        [aggX, admin.tenantId, JSON.stringify({ groupId: groupX })],
+      );
+      markXInserted();
+      await xGate;
+    });
+    await xInserted;
+
+    // Aggregate Y commits AFTER X grabbed its id → Y carries the HIGHER id.
+    await appendCreatedEvent(groupY, "y");
+
+    await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+      __test_onBeforeFence: async () => {
+        // X commits now: its low id becomes visible, but below the cursor that
+        // already advanced past Y's higher id.
+        releaseX();
+        await xDone;
+      },
+    });
+
+    expect(await getCount(groupY)).toBe(1);
+    expect(await getCount(groupX)).toBeUndefined(); // BUG (#443): should be 1
+  });
+
   test("the rebuild tx sees concurrently-committed rows (READ COMMITTED, not a frozen snapshot)", async () => {
     // The catch-up loop only works if each fresh SELECT in the rebuild tx sees
     // rows other connections committed since the previous batch. Under

package/src/pipeline/projection-rebuild.ts

@@ -110,6 +110,10 @@ function rowToStoredEvent(row: StoredEventRow): StoredEvent {
 //   - The shadow is rebuilt from EntityTableMeta, so an index hand-added in a
 //     migration but absent from meta is not reconstructed.
 //   - Requires CREATE privilege to provision the shared rebuild schema.
+//   - A cross-aggregate write that COMMITS with an event id below the cursor
+//     after the cursor already passed it is lost from the rebuild (id-order
+//     != commit-order; bigserial assigns ids pre-commit). Only reachable
+//     during a concurrent rebuild; recovered by the next rebuild. #443.
 
 export type RebuildResult = {
   readonly projection: string;
@@ -141,8 +145,10 @@ type RebuildDeps = {
   readonly fenceLockTimeoutMs?: number;
   // Test-only seam: fires once after the unlocked bulk drain and before the
   // cutover fence. Lets a concurrency test inject a committed write into the
-  // replay window deterministically. Undefined in production.
-  readonly onBeforeFence?: () => void | Promise<void>;
+  // replay window deterministically. The `__test_` prefix marks it test-only:
+  // a production caller passing a slow callback here would hold the
+  // ACCESS-EXCLUSIVE fence for the callback's duration, blocking every writer.
+  readonly __test_onBeforeFence?: () => void | Promise<void>;
 };
 
 export async function rebuildProjection(
@@ -224,7 +230,7 @@ export async function rebuildProjection(
 
         // Test seam: inject a mid-replay committed write here to prove the
         // fenced final drain catches it instead of losing it at swap.
-        await deps.onBeforeFence?.();
+        await deps.__test_onBeforeFence?.();
 
         // Fence the live table, then drain the final delta. Once ACCESS
         // EXCLUSIVE is held no concurrent apply can commit a new event, so this

package/src/pipeline/system-hooks.ts

@@ -96,18 +96,31 @@ function reconstructStateForSearch(
 }
 
 // buildSearchDocument runs per save — without dedup a colliding contributor
-// key would spam one warn line per write on the hotpath.
-const warnedKeyCollisions = new Set<string>();
-function warnOncePerKeyCollision(entityName: string, key: string, isBaseField: boolean): void {
-  const dedupKey = `${entityName}:${key}`;
-  if (!warnedKeyCollisions.has(dedupKey)) {
-    warnedKeyCollisions.add(dedupKey);
-    const collidesWith = isBaseField ? `Stammfield "${key}"` : `earlier contributor key "${key}"`;
-    console.warn(
-      `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
-        `${collidesWith} — keeping the first value. Rename the contributor key.`,
-    );
+// key would spam one warn line per write on the hotpath. Scoped per registry
+// (not module-global) so each app/test instance dedups independently: a
+// process-wide Set would silence the warning for every later registry once any
+// registry hit a given collision, and would leak dedup-state across tests.
+const warnedKeyCollisionsByRegistry = new WeakMap<Registry, Set<string>>();
+function warnOncePerKeyCollision(
+  registry: Registry,
+  entityName: string,
+  key: string,
+  isBaseField: boolean,
+): void {
+  let warned = warnedKeyCollisionsByRegistry.get(registry);
+  if (!warned) {
+    warned = new Set<string>();
+    warnedKeyCollisionsByRegistry.set(registry, warned);
   }
+  const dedupKey = `${entityName}:${key}`;
+  // skip: already warned for this entity:key collision — dedup the hotpath
+  if (warned.has(dedupKey)) return;
+  warned.add(dedupKey);
+  const collidesWith = isBaseField ? `base field "${key}"` : `earlier contributor key "${key}"`;
+  console.warn(
+    `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+      `${collidesWith} — keeping the first value. Rename the contributor key.`,
+  );
 }
 
 // Build a SearchDocument from raw field-state. Parallel to the old
@@ -169,7 +182,7 @@ export async function buildSearchDocument(
     const contributed = await contribute({ entityName, entityId, state });
     for (const [key, value] of Object.entries(contributed)) {
       if (Object.hasOwn(fields, key)) {
-        warnOncePerKeyCollision(entityName, key, baseFieldKeys.has(key));
+        warnOncePerKeyCollision(registry, entityName, key, baseFieldKeys.has(key));
         continue;
       }
       fields[key] = value;