@cosmicdrift/kumiko-framework 0.122.2 → 0.122.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.122.2",
+  "version": "0.122.4",
   "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.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.122.4",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli-temporal-polyfill.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import * as timeModule from "../time";
+
+function captureOut(): { out: SchemaCliOut; log: string[]; err: string[] } {
+  const log: string[] = [];
+  const err: string[] = [];
+  return { out: { log: (l) => log.push(l), err: (l) => err.push(l) }, log, err };
+}
+
+describe("runSchemaCli — Temporal polyfill", () => {
+  let appCwd: string;
+
+  afterEach(() => {
+    if (appCwd) rmSync(appCwd, { recursive: true, force: true });
+  });
+
+  test("calls ensureTemporalPolyfill on every invocation", async () => {
+    // runProdApp/runDevApp call ensureTemporalPolyfill() at boot; the
+    // standalone CLI (migrate-db initContainer, `bun kumiko.js schema apply`)
+    // never goes through that boot path. Without this, a projection rebuild's
+    // tz/timestamp coercion throws "Temporal is not defined" on any runtime
+    // that lacks native Temporal — deterministically, since the crashed
+    // process still records the migration as applied and the rebuild is
+    // never retried on the next run.
+    //
+    // Asserting on globalThis.Temporal directly doesn't work here: the test
+    // harness's own preload (test-setup/base.preload.ts) already calls
+    // ensureTemporalPolyfill() once per process, and its idempotency cache
+    // (a module-level flag, not re-derived from globalThis) short-circuits
+    // any later call regardless of what a test does to globalThis.Temporal in
+    // between. Spying on the imported binding sidesteps that cache entirely.
+    appCwd = mkdtempSync(join(tmpdir(), "kumiko-schema-cli-temporal-"));
+    mkdirSync(join(appCwd, "kumiko"), { recursive: true });
+    const spy = spyOn(timeModule, "ensureTemporalPolyfill");
+    try {
+      const cap = captureOut();
+      const code = await runSchemaCli([], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(spy).toHaveBeenCalled();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

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__/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/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?.();
 

package/src/schema-cli.ts

@@ -36,6 +36,7 @@ import {
   createProjectionStateTable,
   rebuildProjection,
 } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
 
 export type SchemaCliOut = {
   readonly log: (line: string) => void;
@@ -126,6 +127,13 @@ export async function runSchemaCli(
   out: SchemaCliOut,
   options: RunSchemaCliOptions = {},
 ): Promise<number> {
+  // runProdApp/runDevApp install this at boot; the standalone CLI (the
+  // migrate-db initContainer, `bun kumiko.js schema apply`) never goes through
+  // that boot path, so a projection rebuild's tz/timestamp coercion throws
+  // "Temporal is not defined" — deterministically, on every rebuild-marker
+  // migration, since the crashed process still records the migration as
+  // applied and the rebuild is never retried.
+  await ensureTemporalPolyfill();
   const sub = argv[0];
   const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
   const migrationsDir = resolvePath(appCwd, "kumiko/migrations");