@cosmicdrift/kumiko-framework 0.52.0 → 0.55.0

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

@@ -56,6 +56,36 @@ export type ConfigFeatureSchema = {
 
 // Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
 const SCOPE_ORDER: Record<ConfigScope, number> = { system: 10, tenant: 20, user: 30 };
+const SCOPES_BROAD_TO_DEEP: readonly ConfigScope[] = ["system", "tenant", "user"];
+
+const audienceNavShortId = (scope: ConfigScope): string => `audience-${scope}`;
+
+// Die generierten Audience-Parent-Navs (qualifiziert). Eine App platziert die
+// Settings-Gruppe INLINE, indem sie einen dieser QNs in ihre `r.workspace.nav`
+// aufnimmt — buildAppSchema expandiert dann die Kinder der Audience hinein und
+// unterdrückt den Standalone-Switcher. Der Boot-Validator kennt genau diese drei
+// QNs als Ausnahme (generiert, nicht via `r.nav()` registriert).
+export const SETTINGS_HUB_AUDIENCE_NAV_QNS: readonly string[] = SCOPES_BROAD_TO_DEEP.map(
+  (scope) => `${SETTINGS_HUB_FEATURE}:nav:${audienceNavShortId(scope)}`,
+);
+
+// An einem Scope BREITER als der Home-Scope eines Keys darf nur eine für DIESE
+// Ebene privilegierte Rolle den (Cascade-)Default setzen — SystemAdmin auf
+// system, TenantAdmin/Admin auf tenant. Am Home-Scope gilt das volle write-Set
+// (unverändertes Verhalten). So liefert ein tenant-Home-Key wie SMTP zusätzlich
+// einen SystemAdmin-only Plattform-Screen; ein Key, dessen write-Set keine
+// dieser Rollen nennt, bekommt keinen breiteren Screen (write-Set = opt-in).
+const ELEVATED_ROLES: Record<ConfigScope, readonly string[]> = {
+  system: ["SystemAdmin"],
+  tenant: ["TenantAdmin", "Admin"],
+  user: [],
+};
+
+// Der interne Maschinen-Akteur (access.system). Ein Key, den NUR diese Rolle
+// schreiben darf, ist provisioned-not-user-facing: er gehört nicht in den
+// menschlichen Hub (sonst rendert ein Feld, das der sichtbare Mensch nicht
+// speichern kann). `as const` für Literal-Verengung am Vergleich.
+const MACHINE_WRITE_ROLE = "system" as const;
 
 type MaskedKey = {
   readonly qn: string;
@@ -64,6 +94,8 @@ type MaskedKey = {
   readonly def: ConfigKeyDefinition;
 };
 
+type ScopedKey = { readonly key: MaskedKey; readonly roles: readonly string[] };
+
 export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema {
   const masked = collectMaskedKeys(registry);
   if (masked.length === 0) return { screens: [], navs: [] };
@@ -71,37 +103,60 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
   const screens: ScreenDefinition[] = [];
   const navs: NavDefinition[] = [];
 
-  for (const scope of scopesPresent(masked)) {
-    const scopeKeys = masked.filter((k) => k.def.scope === scope);
+  for (const scope of SCOPES_BROAD_TO_DEEP) {
+    const visible = scopedKeysAt(masked, scope);
+    if (visible.length === 0) continue;
 
     // Audience-Parent: Gruppierungs-Knoten ohne Screen.
     navs.push({
-      id: `audience-${scope}`,
+      id: audienceNavShortId(scope),
       label: `config.settings.${scope}`,
       order: SCOPE_ORDER[scope],
-      access: unionEditAccess(scopeKeys.map((k) => k.def)),
+      access: rolesToAccess(visible.flatMap((v) => v.roles)),
     });
 
-    for (const feature of featuresPresent(scopeKeys)) {
-      const group = scopeKeys.filter((k) => k.feature === feature);
-      const ordered = sortByMaskOrder(group);
+    for (const feature of featuresPresent(visible.map((v) => v.key))) {
+      const group = visible.filter((v) => v.key.feature === feature);
+      const ordered = sortByMaskOrder(group.map((v) => v.key));
+      const access = rolesToAccess(group.flatMap((v) => v.roles));
       const shortId = `${feature}-${scope}`;
 
-      screens.push(buildScreen(shortId, scope, feature, ordered));
+      screens.push(buildScreen(shortId, scope, feature, ordered, access));
       navs.push({
         id: shortId,
         label: `${feature}.settings`,
-        parent: `audience-${scope}`,
+        parent: audienceNavShortId(scope),
         screen: shortId,
-        order: minMaskOrder(group),
-        access: unionEditAccess(group.map((k) => k.def)),
+        order: minMaskOrder(ordered),
+        access,
       });
     }
   }
 
+  // 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) };
 }
 
+// Keys, die an `scope` sichtbar sind, gepaart mit ihren effektiven Schreib-
+// Rollen AN diesem Scope (Home = volles write; breiter = elevated ∩ write).
+function scopedKeysAt(masked: readonly MaskedKey[], scope: ConfigScope): ScopedKey[] {
+  const out: ScopedKey[] = [];
+  for (const key of masked) {
+    const roles = effectiveWriteRoles(key.def, scope);
+    if (roles.some((r) => r !== MACHINE_WRITE_ROLE)) out.push({ key, roles });
+  }
+  return out;
+}
+
+function effectiveWriteRoles(def: ConfigKeyDefinition, scope: ConfigScope): string[] {
+  if (SCOPE_ORDER[scope] > SCOPE_ORDER[def.scope]) return [];
+  if (scope === def.scope) return [...def.access.write];
+  const elevated = ELEVATED_ROLES[scope];
+  return def.access.write.filter((r) => elevated.includes(r));
+}
+
 // navMembers tragen die QUALIFIZIERTEN Nav-QNs (siehe build-app-schema.test:
 // admin.navMembers === ["orders:nav:list", ...]). Die generierten Navs leben
 // unter SETTINGS_HUB_FEATURE, also `config:nav:<shortId>`. Sortiert = stabile
@@ -130,6 +185,7 @@ function buildScreen(
   scope: ConfigScope,
   feature: string,
   keys: readonly MaskedKey[],
+  access: AccessRule,
 ): ConfigEditScreenDefinition {
   const configKeys: Record<string, string> = {};
   const fields: Record<string, FieldDefinition> = {};
@@ -152,7 +208,7 @@ function buildScreen(
     fields,
     fieldLabels,
     layout: { sections: [section] },
-    access: unionEditAccess(keys.map((k) => k.def)),
+    access,
   };
 }
 
@@ -189,11 +245,6 @@ function collectMaskedKeys(registry: Registry): MaskedKey[] {
   return out;
 }
 
-function scopesPresent(keys: readonly MaskedKey[]): ConfigScope[] {
-  const set = new Set<ConfigScope>(keys.map((k) => k.def.scope));
-  return [...set].sort((a, b) => (SCOPE_ORDER[a] ?? 0) - (SCOPE_ORDER[b] ?? 0));
-}
-
 function featuresPresent(keys: readonly MaskedKey[]): string[] {
   return [...new Set(keys.map((k) => k.feature))].sort();
 }
@@ -219,10 +270,12 @@ function minMaskOrder(keys: readonly MaskedKey[]): number {
 // AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
 // per Key gegated.
 function unionEditAccess(defs: readonly ConfigKeyDefinition[]): AccessRule {
-  const roles = new Set<string>();
-  for (const def of defs) {
-    for (const role of def.access.write) roles.add(role);
-  }
-  if (roles.has("all")) return { openToAll: true };
-  return { roles: [...roles] };
+  return rolesToAccess(defs.flatMap((d) => [...d.access.write]));
+}
+
+// `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt
+// server-seitig per Key gegated.
+function rolesToAccess(roles: readonly string[]): AccessRule {
+  if (roles.includes("all")) return { openToAll: true };
+  return { roles: [...new Set(roles)] };
 }

package/src/engine/schema-builder.ts

@@ -3,6 +3,31 @@ import { assertUnreachable } from "../utils";
 import type { EmbeddedSubFieldDef, EntityDefinition, FieldDefinition } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
 
+// Lexikografischer ISO-Vergleich — exakt für `yyyy-mm-dd` (date) und korrekt
+// für ISO-Datetime in konsistenter Repräsentation (gleiche Offset-/Präzisions-
+// Form). Bewusst ohne Date-API (no-date-api-Guard); die Tag-genaue Grenze
+// reicht für min/max-Use-Cases (z.B. Geburtsdatum nicht in der Zukunft).
+function withDateBounds(
+  schema: z.ZodTypeAny,
+  min: string | undefined,
+  max: string | undefined,
+): z.ZodTypeAny {
+  if (min === undefined && max === undefined) return schema;
+  const message =
+    min !== undefined && max !== undefined
+      ? `must be between ${min} and ${max}`
+      : min !== undefined
+        ? `must be on or after ${min}`
+        : `must be on or before ${max}`;
+  return schema.refine(
+    (value: unknown) =>
+      typeof value === "string" &&
+      (min === undefined || value >= min) &&
+      (max === undefined || value <= max),
+    { message },
+  );
+}
+
 function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
   switch (subField.type) {
     case "text":
@@ -104,14 +129,17 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       return z.record(z.string(), z.unknown());
     }
     case "date": {
-      return z.string().date();
+      const schema = z.string().date();
+      return withDateBounds(schema, field.min, field.max);
     }
     case "timestamp": {
       // Wenn locatedBy gesetzt: Wall-Clock OHNE Offset (ISO-Datetime ohne `Z`).
       // Sonst: ISO-UTC-Datetime (mit `Z`). Beide werden über z.iso.datetime
       // gegen das ISO-8601-Schema validiert; die Präzision (mit/ohne Offset)
       // hängt von locatedBy ab.
-      return field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
+      const schema =
+        field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
+      return withDateBounds(schema, field.min, field.max);
     }
     case "tz": {
       // IANA-Zonenname. Validierung gegen Intl.supportedValuesOf("timeZone")

package/src/engine/types/fields.ts

@@ -354,6 +354,14 @@ export type DateFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
+  /** Erlaubte Datumsgrenzen als ISO `yyyy-mm-dd` (z.B. Geburtsdatum nicht
+   *  in der Zukunft: `max` = heute). Begrenzt den Picker und wird vom
+   *  Zod-Schema beim Write durchgesetzt. */
+  readonly min?: string;
+  readonly max?: string;
+  /** Format/Locale-Override für Anzeige und Eingabe-Parsing (z.B.
+   *  "de-DE"). Default = App-Locale. */
+  readonly locale?: string;
 } & PiiAnnotations;
 
 // UTC-Instant (Temporal.Instant). Für Ereignisse die zu einem bestimmten
@@ -382,6 +390,14 @@ export type TimestampFieldDef = {
    *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
    */
   readonly locatedBy?: string;
+  /** Erlaubte Grenzen als ISO-Datetime. Begrenzt den Picker auf
+   *  Tages-Granularität; die exakte Uhrzeit-Grenze setzt das Zod-Schema
+   *  beim Write durch. */
+  readonly min?: string;
+  readonly max?: string;
+  /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
+   *  App-Locale. */
+  readonly locale?: string;
 } & PiiAnnotations;
 
 // IANA-Zonenname (z.B. "Europe/Berlin", "America/Los_Angeles").
@@ -420,6 +436,14 @@ export type LocatedTimestampFieldDef = {
   readonly filterable?: boolean;
   readonly sensitive?: boolean;
   readonly access?: FieldAccess;
+  /** Erlaubte Grenzen als ISO-Datetime (Wall-Clock). Begrenzt den Picker
+   *  auf Tages-Granularität; die exakte Uhrzeit-Grenze setzt das Zod-Schema
+   *  beim Write durch. */
+  readonly min?: string;
+  readonly max?: string;
+  /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
+   *  App-Locale. */
+  readonly locale?: string;
 } & PiiAnnotations;
 
 export type FileFieldDef = {

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

@@ -11,8 +11,10 @@
 //   - never-rebuilt projection has sensible default state
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { DbConnection, DbTx } from "../../db/connection";
 import { integer, table as pgTable, uuid } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { fenceLiveTable, swapShadowIntoLive } from "../../db/queries/shadow-swap";
 import { asRawClient, insertOne, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
@@ -175,7 +177,8 @@ describe("rebuildProjection — happy path", () => {
     });
 
     expect(result.eventsProcessed).toBe(2);
-    // Not 999+2, not 999 — TRUNCATE + replay.
+    // Not 999+2, not 999 — the shadow is built empty and swapped over the
+    // stale live table.
     expect(await getCount(group)).toBe(2);
   });
 
@@ -245,7 +248,7 @@ describe("rebuildProjection — state table lifecycle", () => {
 });
 
 describe("rebuildProjection — error path", () => {
-  test("apply throw rolls TRUNCATE + partial replay back, marks status=failed", async () => {
+  test("apply throw rolls the shadow + partial replay back, marks status=failed", async () => {
     const group = "00000000-0000-4000-8000-000000000030";
     await appendCreatedEvent(group, "keeper-1");
     await appendCreatedEvent(group, "keeper-2");
@@ -275,9 +278,9 @@ describe("rebuildProjection — error path", () => {
       rebuildProjection(brokenName, { db: testDb.db, registry: brokenRegistry }),
     ).rejects.toThrow("boom");
 
-    // Old counter rows are gone (TRUNCATE is inside the TX but this is a
-    // DIFFERENT projection). Verify our original projection's rows WERE
-    // preserved because the broken rebuild targets a different name.
+    // The broken rebuild targets a DIFFERENT projection name; its shadow
+    // rolled back and never swapped. Our original projection's rows are
+    // untouched either way.
     expect(await getCount(group)).toBe(2);
 
     // State of the broken projection is "failed" with the error message.
@@ -314,9 +317,10 @@ describe("rebuildProjection — error path", () => {
       rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry: brokenRegistry }),
     ).rejects.toThrow("poisoned");
 
-    // CRITICAL: the old counter rows survive. TRUNCATE happened INSIDE the
-    // transaction, so the rollback restored them. Without this the rebuild
-    // would be worse than not rebuilding at all.
+    // CRITICAL: the old counter rows survive. The shadow rebuild replays into
+    // a separate table and only swaps as the last step — a throw mid-replay
+    // rolls the shadow back and the live table was never touched. Without this
+    // the rebuild would be worse than not rebuilding at all.
     expect(await getCount(group)).toBe(3);
 
     // State reflects the failure.
@@ -502,7 +506,7 @@ describe("rebuildProjection — meter emission", () => {
 });
 
 describe("rebuildProjection — cancellation", () => {
-  test("pre-aborted signal: rebuild throws, TRUNCATE rolls back, projection state preserved", async () => {
+  test("pre-aborted signal: rebuild throws, shadow rolls back, projection state preserved", async () => {
     // Setup: events on the log + a clean rebuild → projection has known
     // counter state. Then call rebuildProjection with a pre-aborted
     // controller. The first throwIfAborted() inside the apply loop
@@ -546,3 +550,237 @@ describe("rebuildProjection — cancellation", () => {
     expect(after).toBe(before);
   });
 });
+
+describe("rebuildProjection — online shadow-swap mechanics", () => {
+  // Self-contained fixtures: a separate projection so the count-sensitive
+  // list/progress tests above keep seeing exactly one registered projection.
+  const swapEntity = createEntity({
+    table: "read_swap_indexed",
+    fields: { label: createTextField({ required: true }) },
+  });
+  const swapTable = buildEntityTable("swap-indexed", swapEntity);
+  // Empty apply: a 0-event rebuild still builds the shadow + swaps it in, so
+  // this exercises the table-recreation + swap path without wiring events.
+  const swapProjection: ProjectionDefinition = {
+    name: "swap-indexed-proj",
+    source: "swap-indexed",
+    table: swapTable,
+    apply: {},
+  };
+  const swapFeature = defineFeature("swaptest", (r) => {
+    r.entity("swap-indexed", swapEntity);
+    r.projection(swapProjection);
+  });
+  const swapRegistry = createRegistry([swapFeature]);
+  const swapProjName = "swaptest:projection:swap-indexed-proj";
+
+  test("swap moves the shadow into public with canonical index names", async () => {
+    await unsafeCreateEntityTable(testDb.db, swapEntity, "swap-indexed");
+    await rebuildProjection(swapProjName, { db: testDb.db, registry: swapRegistry });
+
+    // The tenant_id index carries its canonical name after SET SCHEMA. Future
+    // migrations DROP/CREATE INDEX by exactly this name, so a rename here would
+    // silently break them — this is the index-rename trap the shadow-schema
+    // approach dissolves.
+    const idx = await asRawClient(testDb.db).unsafe<{ indexname: string }>(
+      `SELECT indexname FROM pg_indexes WHERE schemaname = 'public' AND tablename = 'read_swap_indexed' ORDER BY indexname`,
+    );
+    expect(idx.map((r) => r.indexname)).toContain("read_swap_indexed_tenant_id_idx");
+
+    // Nothing left behind in the shadow schema — the table moved out via SET SCHEMA.
+    const leftover = await asRawClient(testDb.db).unsafe<{ tablename: string }>(
+      `SELECT tablename FROM pg_tables WHERE schemaname = 'kumiko_rebuild' AND tablename = 'read_swap_indexed'`,
+    );
+    expect(leftover).toHaveLength(0);
+  });
+
+  test("cleans a stale shadow table left by a crashed rebuild", async () => {
+    await unsafeCreateEntityTable(testDb.db, swapEntity, "swap-indexed");
+    // A crashed prior rebuild leaves a shadow with the wrong shape behind.
+    await asRawClient(testDb.db).unsafe(`CREATE SCHEMA IF NOT EXISTS kumiko_rebuild`);
+    await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS kumiko_rebuild.read_swap_indexed`);
+    await asRawClient(testDb.db).unsafe(
+      `CREATE TABLE kumiko_rebuild.read_swap_indexed (stale int)`,
+    );
+
+    // Rebuild drops the stale shadow before building the real one — succeeds.
+    await rebuildProjection(swapProjName, { db: testDb.db, registry: swapRegistry });
+
+    const cols = await asRawClient(testDb.db).unsafe<{ column_name: string }>(
+      `SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'read_swap_indexed'`,
+    );
+    const colNames = cols.map((c) => c.column_name);
+    expect(colNames).not.toContain("stale");
+    expect(colNames).toContain("tenant_id");
+  });
+
+  test("live table stays readable + intact during replay (no lock until swap)", async () => {
+    const group = "00000000-0000-4000-8000-0000000000d1";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(2);
+
+    // A probe apply reads the LIVE table from a SEPARATE pooled connection
+    // (default search_path = public) on its first invocation, while the rebuild
+    // tx is mid-replay against its shadow. An in-place TRUNCATE would hold an
+    // ACCESS EXCLUSIVE lock and deadlock this read; the shadow swap leaves the
+    // live table unlocked, so it returns the pre-swap rows promptly.
+    let liveDuringReplay: number | undefined = -1;
+    const probeFeature = defineFeature("probetest", (r) => {
+      r.entity("rebuild-item", itemEntity);
+      r.projection({
+        ...itemsPerGroupProjection,
+        apply: {
+          "rebuild-item.created": defineApply<ItemCreated>(async (event, tx) => {
+            if (liveDuringReplay === -1) liveDuringReplay = await getCount(group);
+            await bump(tx, event.payload.groupId, event.tenantId, 1);
+          }),
+        },
+      });
+    });
+    const probeRegistry = createRegistry([probeFeature]);
+
+    await rebuildProjection("probetest:projection:items-per-group", {
+      db: testDb.db,
+      registry: probeRegistry,
+    });
+
+    expect(liveDuringReplay).toBe(2);
+    expect(await getCount(group)).toBe(2);
+  });
+
+  test("warm-pool writes succeed after the swap changes the table OID", async () => {
+    // The swap replaces the physical table (new OID) — TRUNCATE never did.
+    // A live write through the same long-lived pool AFTER the swap (the
+    // steady-state apply path, typed query API) must still resolve the
+    // swapped relation, including across a second rebuild + swap.
+    const group = "00000000-0000-4000-8000-0000000000e1";
+    await appendCreatedEvent(group, "a");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const other = "00000000-0000-4000-8000-0000000000e2";
+    await insertOne(testDb.db, itemsPerGroupTable, {
+      groupId: other,
+      tenantId: admin.tenantId,
+      itemCount: 5,
+    });
+    expect(await getCount(other)).toBe(5);
+
+    await appendCreatedEvent(group, "b");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(2);
+  });
+});
+
+describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
+  test("a write committed during the replay window survives the swap (Phase 1 lost it)", async () => {
+    const group = "00000000-0000-4000-8000-0000000000f1";
+    await appendCreatedEvent(group, "a"); // event id 1
+    await appendCreatedEvent(group, "b"); // event id 2
+
+    let injected = 0;
+    await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+      // 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 () => {
+        injected++;
+        await appendCreatedEvent(group, "c"); // event id 3, separate connection
+      },
+    });
+
+    expect(injected).toBe(1); // seam ran exactly once
+    // 2 bulk + 1 caught-up tail. Under Phase 1's up-front SELECT this is 2.
+    expect(await getCount(group)).toBe(3);
+  });
+
+  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
+    // REPEATABLE READ the loop would be silently inert — pin the isolation.
+    const group = "00000000-0000-4000-8000-0000000000f2";
+    const db = testDb.db as DbConnection; // @cast-boundary test-harness (TestDb.db is intentionally unknown)
+    await db.begin(async (tx: DbTx) => {
+      const before = await asRawClient(tx).unsafe<{ n: number }>(
+        `SELECT count(*)::int AS n FROM "read_rebuild_items_per_group"`,
+      );
+      // Separate pooled connection commits a row mid-transaction.
+      await insertOne(testDb.db, itemsPerGroupTable, {
+        groupId: group,
+        tenantId: admin.tenantId,
+        itemCount: 1,
+      });
+      const after = await asRawClient(tx).unsafe<{ n: number }>(
+        `SELECT count(*)::int AS n FROM "read_rebuild_items_per_group"`,
+      );
+      expect(after[0]?.n ?? 0).toBe((before[0]?.n ?? 0) + 1);
+    });
+  });
+
+  test("a write blocked through the fence+swap is atomic with its partner write (cutover semantics)", async () => {
+    // Drive the cutover primitive directly (fenceLiveTable + swapShadowIntoLive):
+    // a concurrent tx does a partner write + a projection apply that BLOCKS on
+    // the fence and is carried through DROP + SET SCHEMA (the live table's OID
+    // changes). However Postgres resolves the dropped-OID write, the partner
+    // write and the apply share one tx → both commit or both roll back. The
+    // empirical outcome (errors vs. retargets) is logged for the changeset note.
+    const group = "00000000-0000-4000-8000-0000000000f3";
+    await asRawClient(testDb.db).unsafe(
+      `CREATE TABLE IF NOT EXISTS "cutover_probe" (id int primary key)`,
+    );
+    await asRawClient(testDb.db).unsafe(`DELETE FROM "cutover_probe"`);
+
+    // Pre-build a shadow under the canonical name so SET SCHEMA can move it into
+    // public — mirrors what buildShadowTable produces for a real rebuild.
+    await asRawClient(testDb.db).unsafe(`CREATE SCHEMA IF NOT EXISTS kumiko_rebuild`);
+    await asRawClient(testDb.db).unsafe(
+      `DROP TABLE IF EXISTS kumiko_rebuild."read_rebuild_items_per_group"`,
+    );
+    await asRawClient(testDb.db).unsafe(
+      `CREATE TABLE kumiko_rebuild."read_rebuild_items_per_group" (LIKE public."read_rebuild_items_per_group" INCLUDING ALL)`,
+    );
+
+    let bOutcome = "pending";
+    let bDone: Promise<void> | null = null;
+    const db = testDb.db as DbConnection; // @cast-boundary test-harness (TestDb.db is intentionally unknown)
+    await db.begin(async (atx: DbTx) => {
+      await fenceLiveTable(atx, "read_rebuild_items_per_group", 10_000);
+
+      // Connection B: partner write + a projection apply that blocks on the fence.
+      bDone = db
+        .begin(async (btx: DbTx) => {
+          await asRawClient(btx).unsafe(`INSERT INTO "cutover_probe" (id) VALUES (1)`);
+          await bump(btx, group, admin.tenantId, 1); // ROW EXCLUSIVE → blocks on the fence
+        })
+        .then(() => {
+          bOutcome = "committed";
+        })
+        .catch((e: unknown) => {
+          bOutcome = `errored: ${e instanceof Error ? e.message : String(e)}`;
+        });
+
+      // Let B reach its lock-wait before we swap the table out from under it.
+      // NOT awaiting bDone here: B can only finish once A commits (releases the
+      // fence) — awaiting it inside the tx would deadlock.
+      await new Promise((r) => setTimeout(r, 300));
+      await swapShadowIntoLive(atx, "read_rebuild_items_per_group");
+    });
+    if (bDone) await bDone; // A committed → B unblocks and resolves
+
+    console.log(`[#363 cutover] blocked writer outcome: ${bOutcome}`);
+
+    // Load-bearing invariant: partner write present ⟺ projection row present.
+    const probe = await asRawClient(testDb.db).unsafe<{ n: number }>(
+      `SELECT count(*)::int AS n FROM "cutover_probe" WHERE id = 1`,
+    );
+    const probePresent = (probe[0]?.n ?? 0) > 0;
+    const rowPresent = (await getCount(group)) !== undefined;
+    expect(probePresent).toBe(rowPresent);
+
+    await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "cutover_probe"`);
+  });
+});

package/src/pipeline/msp-rebuild.ts

@@ -1,4 +1,3 @@
-import { extractTableName } from "../db";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import {
   markConsumerRebuildFailed,
@@ -6,7 +5,12 @@ import {
   selectConsumerForUpdate,
   updateConsumerRebuildCursor,
 } from "../db/queries/event-consumer";
-import { truncateTable } from "../db/queries/table-ops";
+import {
+  buildShadowTable,
+  ensureRebuildSchema,
+  rebuildMetaOrThrow,
+  swapShadowIntoLive,
+} from "../db/queries/shadow-swap";
 import { selectMany } from "../db/query";
 import type { Registry, TenantId } from "../engine/types";
 import { InternalError } from "../errors";
@@ -20,11 +24,12 @@ import type { MultiStreamApplyContext } from "./multi-stream-apply-context";
 import type { RebuildResult } from "./projection-rebuild";
 
 // Rebuild a multi-stream projection (MSP) from the event log. Symmetric to
-// `rebuildProjection` for single-stream projections — same single-TX
-// TRUNCATE+replay semantics — but wired against the dispatcher's consumer
-// state row (cursor, not projection-state). MSPs are async-live and
-// cursor-driven; rebuild resets the cursor to 0 and rematerializes the
-// projection table in chronological event order.
+// `rebuildProjection` for single-stream projections — same single-TX online
+// shadow-swap (build in a private schema, replay, swap into public; the live
+// table is never locked during replay, see db/queries/shadow-swap) — but wired
+// against the dispatcher's consumer state row (cursor, not projection-state).
+// MSPs are async-live and cursor-driven; rebuild resets the cursor to 0 and
+// rematerializes the projection table in chronological event order.
 //
 // Why separate from rebuildProjection:
 //   - MSP apply signature includes a 3rd ctx arg (MultiStreamApplyContext
@@ -44,9 +49,10 @@ import type { RebuildResult } from "./projection-rebuild";
 // During the rebuild TX:
 //   - FOR UPDATE lock on the consumer row blocks concurrent live passes
 //     (SKIP LOCKED from the dispatcher backs off silently).
-//   - TRUNCATE the projection table.
-//   - Stream events matching apply-keys, invoke apply(event, tx, ctx).
+//   - Build the shadow table; replay events matching apply-keys into it via
+//     apply(event, tx, ctx) with search_path pointed at the shadow schema.
 //   - Advance cursor to last processed event id, status=idle.
+//   - Swap the shadow into public (brief ACCESS EXCLUSIVE, not the replay).
 //
 // Failure: outer catch writes status="dead" + lastError so ops sees the
 // failure after the TX rolled back. Use restartConsumer to clear dead.
@@ -104,18 +110,19 @@ export async function rebuildMultiStreamProjection(
     });
   }
 
+  const meta = rebuildMetaOrThrow(msp.table, mspName);
+
   const startedAt = Date.now();
   let eventsProcessed = 0;
   let lastProcessedEventId = 0n;
 
   try {
+    await ensureRebuildSchema(db);
     await db.begin(async (tx: DbTx) => {
       await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
 
-      const mspTable = msp.table as NonNullable<typeof msp.table>;
-      const tableName = extractTableName(mspTable, "msp-rebuild");
-      await truncateTable(tx, tableName);
+      await buildShadowTable(tx, meta);
 
       const subscribedTypes = Object.keys(msp.apply);
       if (subscribedTypes.length > 0) {
@@ -173,6 +180,7 @@ export async function rebuildMultiStreamProjection(
         SHARED_INSTANCE_SENTINEL,
         lastProcessedEventId,
       );
+      await swapShadowIntoLive(tx, meta.tableName);
     });
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e);