@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/pipeline/msp-rebuild.ts

@@ -1,306 +0,0 @@
-import type { DbConnection, DbRunner, DbTx } from "../db/connection";
-import {
-  markConsumerRebuildFailed,
-  resetConsumerForMspRebuild,
-  selectConsumerForUpdate,
-  selectEventIdHorizonWithMissingRanges,
-  selectSnapshotXmax,
-  updateConsumerRebuildCursor,
-} from "../db/queries/event-consumer";
-import {
-  assertLiveColumnsMatchMeta,
-  assertLiveTableHasNoRowLevelSecurity,
-  buildShadowTable,
-  ensureRebuildSchema,
-  rebuildMetaOrThrow,
-  swapShadowIntoLive,
-} from "../db/queries/shadow-swap";
-import { runInSavepoint, selectMany } from "../db/query";
-import type { Registry, TenantId } from "../engine/types";
-import { InternalError } from "../errors";
-import { eventsTable, type StoredEvent, upcastStoredEvent } from "../event-store";
-import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
-import {
-  createRebuildDeadLetterTable,
-  recordRebuildDeadLetters,
-  type SkippedApply,
-} from "../event-store/rebuild-dead-letter";
-import { upcastStoredEvents } from "../event-store/upcaster";
-import { emitProjectionRebuild } from "../observability/standard-metrics";
-import type { Meter } from "../observability/types/metric";
-import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state";
-import type { MultiStreamApplyContext } from "./multi-stream-apply-context";
-import { capPendingGapsBelowCursor, subtractSortedIdsFromRanges } from "./pending-gap-ranges";
-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 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
-//     for saga follow-ups). Rebuild passes a RESTRICTED ctx that allows
-//     loadAggregate but rejects appendEvent — the events a saga would emit
-//     already live in the log, replaying them would be a double-write.
-//   - Event selection is type-only (no aggregateType filter). MSPs subscribe
-//     by event-type; source aggregate is irrelevant.
-//   - State lives in kumiko_event_consumers (cursor row for the dispatcher),
-//     not in kumiko_projections.
-//
-// Side-effect-only MSPs (no `table`) cannot be rebuilt. Replaying would
-// re-invoke the side-effect (webhook, notification, external sync) and
-// produce duplicates by design. The function rejects up-front with a
-// pointer at the consumer skip/restart ops surface.
-//
-// During the rebuild TX:
-//   - FOR UPDATE lock on the consumer row blocks concurrent live passes
-//     (SKIP LOCKED from the dispatcher backs off silently).
-//   - 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).
-//
-// Handoff to the live dispatcher (#3231): the replay horizon (MAX(id) at the
-// time selectEventIdHorizonWithMissingRanges ran) plus the id gaps open below
-// it in that same snapshot are read up front and the replay is bounded to
-// `id <= horizon`. A transaction holding a lower id can still be in-flight
-// during replay — its row is invisible here and, once committed, would sit
-// below the cursor with no live-dispatcher gap tracking to ever revisit it.
-// Seeding pending_gaps closes that: ids actually read during replay are
-// carved out (delivered here, so a live pass must never redeliver them), and
-// whatever survives is capped below the written cursor — the live dispatcher
-// owns everything from `id > cursor` onward on its own. Those surviving
-// ranges are the shape of the snapshot taken before the replay, but their
-// xmax is read after the replay — a later xmax can only delay when the live
-// dispatcher burns the gap, never make it burn a still-in-flight range early.
-//
-// Failure: outer catch writes status="dead" + lastError so ops sees the
-// failure after the TX rolled back. Use restartConsumer to clear dead.
-//
-// PRECONDITION (online-rebuild data-safety): an MSP `apply` MUST write ONLY its
-// own primary table. Replay runs with search_path pointed at the shadow schema,
-// so writes to the primary table land in the shadow — but a write to ANY OTHER
-// table (e.g. a saga side-effect on a second read-model) falls through to
-// `public`, i.e. the LIVE table, and runs concurrently with the live pipeline's
-// incremental applies to that same table → double-write corruption. The old
-// TRUNCATE path held ACCESS EXCLUSIVE and narrowed (not closed) this window; the
-// shadow-swap removes that brake entirely. Multi-table apply is not statically
-// detectable here (apply is an opaque callback), so this is enforced by
-// contract, not by a guard. See db/queries/shadow-swap.ts "Boundary".
-
-export type MspRebuildDeps = {
-  readonly db: DbConnection;
-  readonly registry: Registry;
-  // Optional framework meter; emits kumiko_projection_rebuild_* with a
-  // projection=<mspName> label (same metric namespace as single-stream —
-  // one rebuild series per projection, regardless of flavor).
-  readonly meter?: Meter;
-  // Test-hook — independent of `meter`, fires on success only.
-  readonly onMetrics?: (result: RebuildResult) => void;
-};
-
-function createRebuildCtx(
-  registry: Registry,
-  db: DbRunner,
-  tenantId: TenantId,
-): MultiStreamApplyContext {
-  // Both surfaces throw — rebuild MUST NOT emit. We share one impl.
-  const refuseAppend = async (args: { readonly type: string }) => {
-    throw new InternalError({
-      message: `rebuildMultiStreamProjection: ctx.appendEvent("${args.type}") is not supported during rebuild. The events your saga would emit already live in the event log — rebuild only derives read-model state. If you need to retroactively emit events, do so via a dedicated write-handler, not via the apply path.`,
-    });
-  };
-  return {
-    registry,
-    appendEvent: refuseAppend as MultiStreamApplyContext["appendEvent"], // @cast-boundary engine-bridge
-    unsafeAppendEvent: refuseAppend,
-    loadAggregate: async (aggregateId, options) => {
-      const events = options?.asOf
-        ? await loadAggregateAsOf(db, aggregateId, tenantId, options.asOf)
-        : await loadAggregate(db, aggregateId, tenantId);
-      return upcastStoredEvents(events, registry.getEventUpcasters(), { db, tenantId });
-    },
-  };
-}
-
-export async function rebuildMultiStreamProjection(
-  mspName: string,
-  deps: MspRebuildDeps,
-): Promise<RebuildResult> {
-  const { db, registry } = deps;
-  const msp = registry.getAllMultiStreamProjections().get(mspName);
-  if (!msp) {
-    throw new InternalError({
-      message: `MultiStreamProjection "${mspName}" is not registered. Known: ${
-        [...registry.getAllMultiStreamProjections().keys()].join(", ") || "(none)"
-      }`,
-    });
-  }
-  if (!msp.table) {
-    throw new InternalError({
-      message: `MultiStreamProjection "${mspName}" has no backing table — it is a pure side-effect consumer (webhooks, notifications, external sync). Rebuild would re-invoke those side-effects by replaying the log. For poison events use bun kumiko consumer skip / restart; there is no analogous "rebuild" concept for side-effect sinks.`,
-    });
-  }
-
-  const meta = rebuildMetaOrThrow(msp.table, mspName);
-
-  // Declared per-projection (MspErrorMode): the rebuild policy falls back to
-  // continuous when omitted — previously declared but never honored here.
-  const skipApplyErrors =
-    (msp.errorMode?.rebuild ?? msp.errorMode?.continuous)?.skipApplyErrors === true;
-
-  const startedAt = Date.now();
-  let eventsProcessed = 0;
-  let lastProcessedEventId = 0n;
-  const skipped: SkippedApply[] = [];
-
-  try {
-    await ensureRebuildSchema(db);
-    // Outside the rebuild tx, like the schema: idempotent DDL colliding
-    // inside the tx would roll the whole replay back.
-    if (skipApplyErrors) await createRebuildDeadLetterTable(db);
-    const replayedIds: bigint[] = [];
-    await db.begin(async (tx: DbTx) => {
-      await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
-      await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
-
-      const { horizon, gaps: seededGaps } = await selectEventIdHorizonWithMissingRanges(tx);
-
-      await assertLiveColumnsMatchMeta(tx, meta, mspName);
-      await assertLiveTableHasNoRowLevelSecurity(tx, meta.tableName, mspName);
-      await buildShadowTable(tx, meta);
-
-      const subscribedTypes = Object.keys(msp.apply);
-      if (subscribedTypes.length > 0) {
-        type EventRow = {
-          id: bigint;
-          aggregateId: string;
-          aggregateType: string;
-          tenantId: TenantId;
-          version: number;
-          type: string;
-          eventVersion: number;
-          payload: Record<string, unknown>;
-          metadata: import("../event-store/event-store").EventMetadata;
-          createdAt: Temporal.Instant;
-          createdBy: string;
-        };
-        // Events past `horizon` are the live dispatcher's to deliver via
-        // `id > cursor` — bounding the replay here is what keeps the two
-        // paths from ever double-applying the same event.
-        const events = await selectMany<EventRow>(
-          tx,
-          eventsTable,
-          { type: [...subscribedTypes], id: { lte: horizon } },
-          { orderBy: { col: "id", direction: "asc" } },
-        );
-
-        const upcasters = registry.getEventUpcasters();
-        for (const row of events) {
-          const raw: StoredEvent = {
-            id: String(row.id),
-            aggregateId: row.aggregateId,
-            aggregateType: row.aggregateType,
-            tenantId: row.tenantId,
-            version: row.version,
-            type: row.type,
-            eventVersion: row.eventVersion,
-            payload: row.payload,
-            metadata: row.metadata,
-            createdAt: row.createdAt,
-            createdBy: row.createdBy,
-          };
-          const storedEvent = await upcastStoredEvent(raw, upcasters, {
-            db: tx,
-            tenantId: row.tenantId,
-          });
-          replayedIds.push(row.id);
-          const applyFn = msp.apply[row.type];
-          if (!applyFn) continue;
-          if (skipApplyErrors) {
-            // Driver-native savepoint: a throwing SQL statement would
-            // otherwise poison the rebuild tx (25P02) AND make the driver
-            // reject the whole begin() even after a caught error. Apply +
-            // ctx run on the savepoint-scoped handle.
-            try {
-              await runInSavepoint(tx, async (sp) => {
-                const rebuildCtx = createRebuildCtx(registry, sp as DbRunner, row.tenantId);
-                await applyFn(storedEvent, sp as DbRunner, rebuildCtx);
-              });
-            } catch (e) {
-              skipped.push({ event: storedEvent, error: e });
-            }
-          } else {
-            const rebuildCtx = createRebuildCtx(registry, tx, row.tenantId);
-            await applyFn(storedEvent, tx, rebuildCtx);
-          }
-          eventsProcessed++;
-          lastProcessedEventId = row.id;
-        }
-      }
-
-      if (skipped.length > 0) {
-        await recordRebuildDeadLetters(tx, mspName, skipped);
-      }
-      // Every id actually read this replay (applied or skip-applied) is
-      // resolved — a live pass must never redeliver it. Anything surviving
-      // that subtraction is capped below the written cursor: a gap at or
-      // above it is the live dispatcher's own `id > cursor` territory, not
-      // pending_gaps'. No events replayed (cursor stays 0) means no gap can
-      // sit below it either.
-      const survivingGaps = subtractSortedIdsFromRanges(seededGaps, replayedIds);
-      const cappedGaps = capPendingGapsBelowCursor(survivingGaps, lastProcessedEventId);
-      const postReplayXmax = cappedGaps.length > 0 ? await selectSnapshotXmax(tx) : null;
-      const pendingGaps =
-        postReplayXmax === null
-          ? cappedGaps
-          : cappedGaps.map((gap) => ({ ...gap, xmax: postReplayXmax }));
-      await updateConsumerRebuildCursor(
-        tx,
-        mspName,
-        SHARED_INSTANCE_SENTINEL,
-        lastProcessedEventId,
-        pendingGaps,
-      );
-      await swapShadowIntoLive(tx, meta.tableName);
-    });
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    await markConsumerRebuildFailed(db, mspName, SHARED_INSTANCE_SENTINEL, message);
-    if (deps.meter) {
-      emitProjectionRebuild(
-        deps.meter,
-        { projection: mspName, success: false },
-        (Date.now() - startedAt) / 1000,
-        0,
-      );
-    }
-    throw e;
-  }
-
-  const result: RebuildResult = {
-    projection: mspName,
-    eventsProcessed,
-    eventsSkipped: skipped.length,
-    lastProcessedEventId,
-    durationMs: Date.now() - startedAt,
-    // countColumnDrift is single-table (public.<t> vs kumiko_rebuild.<t>) and
-    // not wired into the multi-stream rebuild path — MSPs don't run the
-    // implicit-projection ghost-row guard either. #916 scope is single-table.
-    columnDriftCount: 0,
-  };
-  if (deps.meter) {
-    emitProjectionRebuild(
-      deps.meter,
-      { projection: mspName, success: true },
-      result.durationMs / 1000,
-      eventsProcessed,
-    );
-  }
-  deps.onMetrics?.(result);
-  return result;
-}

package/src/pipeline/multi-stream-apply-context.ts

@@ -1,85 +0,0 @@
-import type { DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
-import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
-import type { SecretsContext } from "@cosmicdrift/kumiko-types/secrets-types";
-import type { DbRunner } from "../db/connection";
-import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
-import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
-import { upcastStoredEvents } from "../event-store/upcaster";
-import type { FileContext } from "../files/file-handle";
-import { appendDomainEventCore } from "./append-event-core";
-
-export type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
-
-export type MultiStreamApplyContextDeps = {
-  readonly registry: Registry;
-  // Same DbRunner the applyFn receives as its 2nd arg. In the server's MSP
-  // consumer wiring (api/server.ts) that's the unbound pool, not the
-  // dispatcher's cursor tx — a throw does NOT roll back appends/inline
-  // projections already made; apply must be idempotent for the retry.
-  readonly db: DbRunner;
-  // tenantId + userId of the TRIGGERING event. appendEvent stamps these
-  // onto the new event so the causal chain stays tenant-consistent and
-  // the downstream audit-trail can reconstruct the acting principal.
-  readonly tenantId: TenantId;
-  readonly userId: string;
-  // MSP's owning feature (prefix of its qualified name). Enforced at
-  // emit-site: the MSP cannot ctx.appendEvent a type owned by another
-  // feature. Cross-feature reactions are fine inbound (this MSP is
-  // subscribed to events from any feature), but outbound appends must
-  // stay within the MSP's own feature.
-  readonly callerFeature?: string;
-  // Same FileContext the outer AppContext carries, passed through so
-  // MSP applies can reach binaries without another wiring indirection.
-  readonly files?: FileContext;
-  // Same DerivativesContext the outer AppContext carries — mirrors `files`.
-  readonly derivatives?: DerivativesContext;
-  // Same SecretsContext the outer AppContext carries, mirrors `files`.
-  readonly secrets?: SecretsContext;
-};
-
-export function createMultiStreamApplyContext(
-  deps: MultiStreamApplyContextDeps,
-): MultiStreamApplyContext {
-  return {
-    registry: deps.registry,
-    ...(deps.files ? { files: deps.files } : {}),
-    ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
-    ...(deps.secrets ? { secrets: deps.secrets } : {}),
-    appendEvent: (async (args: AppendEventArgs) => {
-      await appendDomainEventCore(
-        {
-          registry: deps.registry,
-          db: deps.db,
-          tenantId: deps.tenantId,
-          userId: deps.userId,
-          callSiteLabel: "MSP-apply ctx.appendEvent",
-          ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
-        },
-        args,
-      );
-    }) as AppendEventFn, // @cast-boundary engine-bridge
-    unsafeAppendEvent: async (args) => {
-      await appendDomainEventCore(
-        {
-          registry: deps.registry,
-          db: deps.db,
-          tenantId: deps.tenantId,
-          userId: deps.userId,
-          callSiteLabel: "MSP-apply ctx.unsafeAppendEvent",
-          ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
-        },
-        args,
-      );
-    },
-
-    loadAggregate: async (aggregateId, options) => {
-      const events = options?.asOf
-        ? await loadAggregateAsOf(deps.db, aggregateId, deps.tenantId, options.asOf)
-        : await loadAggregate(deps.db, aggregateId, deps.tenantId);
-      return upcastStoredEvents(events, deps.registry.getEventUpcasters(), {
-        db: deps.db,
-        tenantId: deps.tenantId,
-      });
-    },
-  };
-}

package/src/pipeline/pending-gap-ranges.ts

@@ -1,120 +0,0 @@
-import type { PendingIdRange } from "../db/queries/event-store";
-import type { PendingGapEntry } from "./event-consumer-state";
-
-export function toIdRanges(gaps: readonly PendingGapEntry[]): PendingIdRange[] {
-  return gaps.map((g) => ({ from: BigInt(g.from), to: BigInt(g.to) }));
-}
-
-export function rangeContainsId(range: PendingGapEntry, id: bigint): boolean {
-  return id >= BigInt(range.from) && id <= BigInt(range.to);
-}
-
-// A range is only provably burnt (rolled back, not just slow) once it's
-// certain the fetch would have surfaced any of its ids had they been
-// visible. LIMIT can cut a fetch off before reaching the range's ids —
-// `to < maxFetchedId` proves the scan passed the range regardless of the
-// cutoff, since ORDER BY id ASC LIMIT N always includes every matching id
-// below the largest one it did return.
-export function isRangeFullyCoveredByFetch(
-  range: PendingGapEntry,
-  truncated: boolean,
-  maxFetchedId: bigint | null,
-): boolean {
-  if (!truncated) return true;
-  if (maxFetchedId === null) return false;
-  return BigInt(range.to) < maxFetchedId;
-}
-
-// A gap is burnt when none of its ids showed up in this turn's fetch, the
-// fetch is proven to have covered it, and its recorded xmax is behind this
-// turn's xmin (every xact that could still produce a row has finished).
-export function partitionBurntGaps(
-  gaps: readonly PendingGapEntry[],
-  fetchedIds: readonly bigint[],
-  truncated: boolean,
-  xminNow: string,
-): { readonly burnt: PendingGapEntry[]; readonly surviving: PendingGapEntry[] } {
-  const maxFetchedId = fetchedIds.at(-1) ?? null;
-  const burnt: PendingGapEntry[] = [];
-  const surviving: PendingGapEntry[] = [];
-  for (const gap of gaps) {
-    const hasVisibleId = fetchedIds.some((id) => rangeContainsId(gap, id));
-    const isBurnt =
-      !hasVisibleId &&
-      isRangeFullyCoveredByFetch(gap, truncated, maxFetchedId) &&
-      BigInt(gap.xmax) <= BigInt(xminNow);
-    (isBurnt ? burnt : surviving).push(gap);
-  }
-  return { burnt, surviving };
-}
-
-// Carves `excludeIds` (delivered or skip-applied this turn) out of `range`,
-// yielding 0-2 sub-ranges. xmax is preserved on every surviving piece.
-export function splitRangeExcludingIds(
-  range: PendingGapEntry,
-  excludeIds: readonly bigint[],
-): PendingGapEntry[] {
-  const from = BigInt(range.from);
-  const to = BigInt(range.to);
-  const inRange = excludeIds
-    .filter((id) => id >= from && id <= to)
-    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-  if (inRange.length === 0) return [range];
-  const parts: PendingGapEntry[] = [];
-  let cursor = from;
-  for (const id of inRange) {
-    if (id > cursor)
-      parts.push({ from: cursor.toString(), to: (id - 1n).toString(), xmax: range.xmax });
-    cursor = id + 1n;
-  }
-  if (cursor <= to) parts.push({ from: cursor.toString(), to: to.toString(), xmax: range.xmax });
-  return parts;
-}
-
-// Same carve-out as splitRangeExcludingIds, but for many ranges against many
-// ids at once — an MSP rebuild's replay reads events in ascending id order,
-// so a single forward pointer over `sortedIds` (both inputs already sorted,
-// ranges non-overlapping) avoids scanning the full id list per range.
-export function subtractSortedIdsFromRanges(
-  ranges: readonly PendingGapEntry[],
-  sortedIds: readonly bigint[],
-): PendingGapEntry[] {
-  if (sortedIds.length === 0) return [...ranges];
-  const result: PendingGapEntry[] = [];
-  let cursor = 0;
-  for (const range of ranges) {
-    const from = BigInt(range.from);
-    const to = BigInt(range.to);
-    let id = sortedIds[cursor];
-    while (id !== undefined && id < from) {
-      cursor++;
-      id = sortedIds[cursor];
-    }
-    const idsInRange: bigint[] = [];
-    while (id !== undefined && id <= to) {
-      idsInRange.push(id);
-      cursor++;
-      id = sortedIds[cursor];
-    }
-    result.push(...splitRangeExcludingIds(range, idsInRange));
-  }
-  return result;
-}
-
-// Ranges above the written cursor belong to the live dispatcher's own
-// `id > cursor` territory; a range straddling it is truncated at cursor - 1.
-export function capPendingGapsBelowCursor(
-  gaps: readonly PendingGapEntry[],
-  cursor: bigint,
-): PendingGapEntry[] {
-  if (cursor <= 0n) return [];
-  const capped: PendingGapEntry[] = [];
-  for (const gap of gaps) {
-    const from = BigInt(gap.from);
-    if (from >= cursor) continue;
-    const to = BigInt(gap.to);
-    const cappedTo = to >= cursor ? cursor - 1n : to;
-    capped.push({ ...gap, to: cappedTo.toString() });
-  }
-  return capped;
-}