@cosmicdrift/kumiko-framework 0.87.3 → 0.89.0

package/package.json

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

package/src/api/__tests__/http-cache.test.ts

@@ -41,6 +41,12 @@ describe("cacheControlHeader", () => {
     expect(cacheControlHeader({ kind: "revalidate" })).toBe("public, max-age=0, must-revalidate");
   });
 
+  test("revalidate with explicit max-age window", () => {
+    expect(cacheControlHeader({ kind: "revalidate", maxAgeSeconds: 60 })).toBe(
+      "public, max-age=60, must-revalidate",
+    );
+  });
+
   test("no-cache", () => {
     expect(cacheControlHeader({ kind: "no-cache" })).toBe("no-cache");
   });
@@ -147,4 +153,21 @@ describe("cachedResponse", () => {
     });
     expect(res.status).toBe(304);
   });
+
+  test("mismatching If-None-Match ignores If-Modified-Since (RFC 7232 §3.3)", () => {
+    const lastModified = new Date("2026-06-01T12:00:00.000Z");
+    const req = new Request("https://example.test/", {
+      headers: {
+        "if-none-match": '"stale"',
+        "if-modified-since": lastModified.toUTCString(),
+      },
+    });
+    const res = cachedResponse(req, {
+      body: "hello",
+      etag,
+      cache: { kind: "revalidate" },
+      lastModified,
+    });
+    expect(res.status).toBe(200);
+  });
 });

package/src/api/http-cache.ts

@@ -104,10 +104,12 @@ function buildResponseHeaders(init: CachedResponseInit): Record<string, string>
 export function cachedResponse(req: Request, init: CachedResponseInit): Response {
   const headers = buildResponseHeaders(init);
   const ifNoneMatch = req.headers.get("if-none-match");
-  if (etagMatches(ifNoneMatch, init.etag)) {
-    return new Response(null, { status: 304, headers });
-  }
-  if (init.lastModified !== undefined) {
+  // RFC 7232 §3.3: If-None-Match present → it alone decides; ignore If-Modified-Since.
+  if (ifNoneMatch !== null) {
+    if (etagMatches(ifNoneMatch, init.etag)) {
+      return new Response(null, { status: 304, headers });
+    }
+  } else if (init.lastModified !== undefined) {
     const ifModifiedSince = req.headers.get("if-modified-since");
     if (ifModifiedSince !== null && isNotModifiedSince(ifModifiedSince, init.lastModified)) {
       return new Response(null, { status: 304, headers });

package/src/db/queries/projection-rebuild.ts

@@ -34,6 +34,27 @@ export async function selectEventsForProjectionRebuildBatch(
   )) as ReadonlyArray<Record<string, unknown>>;
 }
 
+// Total subscribed events in the log — same source/type filter as
+// selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
+// this is the ground-truth count the rebuild must have applied; a shortfall
+// means a lower-id event committed late and the id-cursor leapt past it (#443).
+export async function countSubscribedEvents(
+  db: AnyDb,
+  aggregateTypes: readonly string[],
+  eventTypes: readonly string[],
+): Promise<bigint> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT count(*)::bigint AS n FROM "kumiko_events"
+     WHERE "aggregate_type" = ANY($1::text[])
+       AND "type" = ANY($2::text[])`,
+    [aggregateTypes, eventTypes],
+  )) as ReadonlyArray<{ n: bigint | string | number | null }>;
+  const raw = rows[0]?.n;
+  if (typeof raw === "bigint") return raw;
+  if (raw === null || raw === undefined) return 0n;
+  return BigInt(raw);
+}
+
 export async function finalizeProjectionRebuild(
   db: AnyDb,
   projectionName: string,

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

@@ -698,13 +698,13 @@ 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 () => {
+  test("(#443) a lower-id write committed late during replay is recovered under the fence", 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).
+    // the fenced final drain (`WHERE id > cursor`) never revisits it. Under the
+    // fence the subscribed-event set is final, so a count re-check detects the
+    // shortfall and re-replays the full log into a fresh shadow — groupX, whose
+    // low-id event committed late, is no longer lost. See #443.
     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";
@@ -747,7 +747,7 @@ describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
     });
 
     expect(await getCount(groupY)).toBe(1);
-    expect(await getCount(groupX)).toBeUndefined(); // BUG (#443): should be 1
+    expect(await getCount(groupX)).toBe(1); // #443 fixed: fenced count re-check re-replayed the missed low-id event
   });
 
   test("the rebuild tx sees concurrently-committed rows (READ COMMITTED, not a frozen snapshot)", async () => {

package/src/pipeline/projection-rebuild.ts

@@ -1,5 +1,6 @@
 import type { DbConnection, DbTx } from "../db/connection";
 import {
+  countSubscribedEvents,
   finalizeProjectionRebuild,
   markProjectionRebuildFailed,
   markProjectionRebuilding,
@@ -110,10 +111,11 @@ 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.
+//   - id-order != commit-order (bigserial assigns ids pre-commit), so a
+//     cross-aggregate write can COMMIT an event id BELOW the cursor after the
+//     unlocked drain already passed it. Caught under the fence: a count
+//     re-check against the (now final) event set detects the shortfall and
+//     re-replays the full log into a fresh shadow. #443.
 
 export type RebuildResult = {
   readonly projection: string;
@@ -240,6 +242,23 @@ export async function rebuildProjection(
         while ((await drainBatch(tx)) === REBUILD_BATCH_SIZE) {
           // keep draining full batches; a short batch ends the loop
         }
+
+        // Fenced → the subscribed-event set is final (every live apply blocks
+        // on the live-table lock). If fewer events were applied than exist, a
+        // lower-id event committed late during the unlocked phase and the
+        // id-cursor leapt past it (#443). Rebuild the shadow from scratch and
+        // replay the whole log under the fence: a fresh shadow means no
+        // double-apply (the rejected "re-drain into a populated shadow" hazard),
+        // and the full-replay cost is paid only on this rare detected path.
+        const expectedEvents = await countSubscribedEvents(tx, sourcesList, subscribedList);
+        if (expectedEvents > BigInt(eventsProcessed)) {
+          await buildShadowTable(tx, meta);
+          lastProcessedEventId = 0n;
+          eventsProcessed = 0;
+          while ((await drainBatch(tx)) === REBUILD_BATCH_SIZE) {
+            // re-replay the full log into the fresh shadow
+          }
+        }
       }
 
       await finalizeProjectionRebuild(tx, projectionName, lastProcessedEventId);