@cosmicdrift/kumiko-framework 0.122.1 → 0.122.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.122.1",
+  "version": "0.122.3",
   "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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.122.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.122.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/queries/shadow-swap.ts

@@ -18,9 +18,11 @@
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
 
+import type { DbConnection, DbTx } from "../connection";
 import type { EntityTableMeta } from "../entity-table-meta";
 import { type AnyDb, asEntityTableMeta, asRawClient } from "../query";
 import { renderTableDdl } from "../render-ddl";
+import { columnNamesOf, tableExists } from "../schema-inspection";
 import { quoteTableIdent } from "./table-ops";
 
 export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
@@ -68,6 +70,41 @@ export function rebuildMetaOrThrow(table: unknown, projectionName: string): Enti
   return meta;
 }
 
+// Fence against a rebuild running with a registry that does not match the
+// migrated live schema (#835): during a rolling deploy, a pod still running
+// the previous build can pick up an async rebuild job; its shadow — built from
+// the stale EntityTableMeta — would swap away a freshly-migrated column
+// (recurrence class of #494). Compares COLUMN NAMES only; a type-/nullability-
+// only drift passes (schema regression, not data loss — the boot gate of the
+// next deploy catches it). A missing live table is fine: nothing to wipe.
+// Must run BEFORE buildShadowTable; columnNamesOf pins table_schema='public',
+// so the shadow search_path could not redirect it anyway.
+export async function assertLiveColumnsMatchMeta(
+  db: DbConnection | DbTx,
+  meta: EntityTableMeta,
+  projectionName: string,
+): Promise<void> {
+  // skip: no live table yet — nothing a stale-meta shadow could wipe
+  if (!(await tableExists(db, `public.${meta.tableName}`))) return;
+  const live = await columnNamesOf(db, meta.tableName);
+  const metaNames = new Set(meta.columns.map((c) => c.name));
+  const onlyLive = [...live].filter((c) => !metaNames.has(c));
+  const onlyMeta = [...metaNames].filter((c) => !live.has(c));
+  // skip: column sets match — this process's registry is in sync with the migrated table
+  if (onlyLive.length === 0 && onlyMeta.length === 0) return;
+  const detail = [
+    onlyLive.length > 0 ? `live-only: ${onlyLive.join(", ")}` : "",
+    onlyMeta.length > 0 ? `meta-only: ${onlyMeta.join(", ")}` : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+  throw new Error(
+    `projection-rebuild "${projectionName}": columns of live table "${meta.tableName}" do not match this process's EntityTableMeta (${detail}). ` +
+      "Rebuilding would swap away the difference. Likely cause: this pod runs a build whose registry is behind (or ahead of) the applied migrations — rolling deploy in progress? — or DDL was applied by hand. " +
+      "Rebuild aborted; retry from a pod whose code matches the migrated schema.",
+  );
+}
+
 // Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
 // Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
 // rollback), drops any leftover shadow from a crashed run, then builds the

package/src/pipeline/__tests__/event-dispatcher.integration.test.ts

@@ -159,10 +159,20 @@ describe("event-dispatcher — happy path", () => {
     await stack.eventDispatcher?.runOnce();
     expect(captureA).toHaveLength(1);
 
+    const stateBefore = await getConsumerState(stack.db, qnA);
+
     const second = await stack.eventDispatcher?.runOnce();
     expect(second?.byConsumer[qnA]).toEqual({ processed: 0, failed: 0 });
     // Still only one — consumer correctly saw "nothing new past my cursor".
     expect(captureA).toHaveLength(1);
+
+    // No pending events means no write at all — an idle pass must not touch
+    // updated_at/status, otherwise every empty poll tick burns a WAL record.
+    const stateAfter = await getConsumerState(stack.db, qnA);
+    expect(stateAfter?.updatedAt.epochMilliseconds).toEqual(
+      stateBefore?.updatedAt.epochMilliseconds,
+    );
+    expect(stateAfter?.status).toBe(stateBefore?.status);
   });
 
   test("cursor advances only past successfully-consumed events", async () => {

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

@@ -890,3 +890,51 @@ describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
     await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "cutover_probe"`);
   });
 });
+
+describe("rebuildProjection — stale-registry column fence (#835)", () => {
+  // Simulates the rolling-deploy race: a migration added a column to the live
+  // table, but the pod running the rebuild still carries the old registry
+  // (EntityTableMeta without that column). The rebuild must abort instead of
+  // swapping in a shadow that silently drops the migrated column (#494 class).
+  test("aborts when the live table has a column the registry meta lacks — data survives", async () => {
+    const group = "00000000-0000-4000-8000-000000000041";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" ADD COLUMN migrated_col text`);
+    try {
+      await raw.unsafe(
+        `UPDATE "read_rebuild_items_per_group" SET migrated_col = 'must-survive' WHERE group_id = $1::uuid`,
+        [group],
+      );
+
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/live-only: migrated_col/);
+
+      // Live table untouched: column AND its data still there.
+      const [row] = await raw.unsafe<{ migrated_col: string | null }>(
+        `SELECT migrated_col FROM "read_rebuild_items_per_group" WHERE group_id = $1::uuid`,
+        [group],
+      );
+      expect(row?.migrated_col).toBe("must-survive");
+      expect(await getCount(group)).toBe(1);
+
+      // Failure is visible to ops.
+      const state = await getProjectionState(testDb.db, qualifiedProjectionName);
+      expect(state?.status).toBe("failed");
+      expect(state?.lastError).toContain("migrated_col");
+    } finally {
+      await raw.unsafe(
+        `ALTER TABLE "read_rebuild_items_per_group" DROP COLUMN IF EXISTS migrated_col`,
+      );
+    }
+
+    // Column sets aligned again → rebuild works.
+    const result = await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(result.eventsProcessed).toBe(1);
+    expect(await getCount(group)).toBe(1);
+  });
+});

package/src/pipeline/event-dispatcher.ts

@@ -524,9 +524,16 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
           span.setAttribute("consumer.skip_reason", acquired.skip);
           return;
         }
-        await markProcessing(tx, consumer.name, instanceId);
 
         const events = await fetchPendingEvents(tx, acquired.state.lastProcessedEventId, batchSize);
+        // skip: nothing to deliver — no markProcessing/persistConsumerOutcome write,
+        // so an idle consumer doesn't burn a WAL record on every poll tick.
+        if (events.length === 0) {
+          span.setAttribute("consumer.skip_reason", "no_pending_events");
+          return;
+        }
+        await markProcessing(tx, consumer.name, instanceId);
+
         const outcome = await deliverEvents(consumer, events, context, maxAttempts, acquired.state);
         processed = outcome.processed;
         failed = outcome.failed;

package/src/pipeline/msp-rebuild.ts

@@ -6,6 +6,7 @@ import {
   updateConsumerRebuildCursor,
 } from "../db/queries/event-consumer";
 import {
+  assertLiveColumnsMatchMeta,
   buildShadowTable,
   ensureRebuildSchema,
   rebuildMetaOrThrow,
@@ -147,6 +148,7 @@ export async function rebuildMultiStreamProjection(
       await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
 
+      await assertLiveColumnsMatchMeta(tx, meta, mspName);
       await buildShadowTable(tx, meta);
 
       const subscribedTypes = Object.keys(msp.apply);

package/src/pipeline/projection-rebuild.ts

@@ -7,6 +7,7 @@ import {
   selectEventsForProjectionRebuildBatch,
 } from "../db/queries/projection-rebuild";
 import {
+  assertLiveColumnsMatchMeta,
   buildShadowTable,
   ensureRebuildSchema,
   fenceLiveTable,
@@ -260,6 +261,7 @@ export async function rebuildProjection(
     if (skipApplyErrors) await createRebuildDeadLetterTable(db);
     await db.begin(async (tx: DbTx) => {
       await markProjectionRebuilding(tx, projectionName);
+      await assertLiveColumnsMatchMeta(tx, meta, projectionName);
       await buildShadowTable(tx, meta);
       deps.__test_onBuildShadowTable?.();