@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/db/queries/event-store.ts

@@ -1,354 +0,0 @@
-import {
-  constraintOf,
-  isLockNotAvailable,
-  isTableAlreadyExists,
-  isUniqueViolation,
-} from "../pg-error";
-import type { AnyDb } from "../query";
-import { asRawClient, unsafeReadRetrying } from "../query";
-
-// Gap-finality (event-dispatcher pending_gaps) needs every holder of an
-// event id to already have a *real* xact id by the time it inserts — Postgres
-// assigns those lazily on first write, so a bare INSERT alone doesn't
-// guarantee one exists yet for comparison against a later snapshot's
-// xmin/xmax. pg_current_xact_id() forces the allocation.
-export async function claimXactId(db: AnyDb): Promise<void> {
-  await asRawClient(db).unsafe(`SELECT pg_current_xact_id()`);
-}
-
-/** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
-export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void> {
-  await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
-}
-
-// Tenant-scoped partial unique index over metadata.idempotencyKey.
-// Expression index straight on the jsonb column — no dedicated key column,
-// so it needs no INSERT-path change and covers admin-api's raw appends too
-// (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
-// on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
-// installs that predate the index without a table rebuild.
-//
-// CONCURRENTLY (not a plain CREATE): a non-concurrent build takes a SHARE
-// lock for the full table scan on kumiko_events — the hottest table in the
-// framework — blocking every append() for however long that scan takes on
-// an existing installation's event history. CONCURRENTLY avoids that at the
-// cost of needing to tolerate two failure modes a plain build doesn't have.
-// Neither CREATE nor DROP ... CONCURRENTLY may run inside a transaction —
-// no caller of this function (dev-server, schema-cli.ts, stack/db.ts) may
-// wrap it in one, or Postgres raises 25001.
-// undefined = index doesn't exist at all (nothing to drop, CREATE below
-// handles it); false = exists but INVALID (crashed mid-build, needs DROP +
-// rebuild); true = exists and valid.
-async function indexValidity(client: ReturnType<typeof asRawClient>): Promise<boolean | undefined> {
-  const rows = await client.unsafe(
-    `SELECT i.indisvalid FROM pg_class c JOIN pg_index i ON i.indexrelid = c.oid ` +
-      `WHERE c.relname = 'events_idempotency_uq' AND i.indrelid = '"kumiko_events"'::regclass`,
-  );
-  return (rows[0] as { indisvalid?: boolean } | undefined)?.indisvalid;
-}
-
-export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
-  const client = asRawClient(db);
-
-  try {
-    // 1) A prior CONCURRENTLY build that got killed mid-flight (crash, deploy
-    //    restart) leaves an INVALID index: the catalog entry exists, so
-    //    IF NOT EXISTS below would silently skip forever, but the index is
-    //    incomplete and not plannable for queries — it does NOT mean the
-    //    constraint enforces nothing; Postgres keeps maintaining an INVALID
-    //    index on every insert, it just refuses to use it for planning.
-    //    Detect + rebuild it. Scoped to kumiko_events specifically (indrelid),
-    //    not just the relname, so a same-named index in another schema can't
-    //    false-positive this DROP.
-    if ((await indexValidity(client)) === false) {
-      await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS "events_idempotency_uq"`);
-    }
-
-    await client.unsafe(
-      `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
-        `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
-        `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
-    );
-  } catch (e) {
-    if (isBenignConcurrentIndexBuildRace(e)) {
-      // "Benign" only means the losing side of a race, not that the index
-      // actually landed valid — a lock_timeout on the CREATE (55P03) backs
-      // off the same way a genuine duplicate-build race does, but leaves no
-      // valid index at all. Re-check before declaring victory instead of
-      // trusting the error class alone.
-      // skip: sibling pod already built a valid index — this race loser is done.
-      if ((await indexValidity(client)) === true) return;
-      console.warn(
-        `ensureIdempotencyKeyIndex: backed off on a "benign" race (${String(e)}) but ` +
-          `"events_idempotency_uq" is still missing/invalid afterward — likely a ` +
-          `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`,
-      );
-      throw e;
-    }
-    throw duplicateIdempotencyKeyErrorOr(e);
-  }
-}
-
-// Two pods booting concurrently against the same DB (rolling deploy): both
-// see the index missing/invalid and both start a DROP/CREATE CONCURRENTLY
-// build. The loser typically does NOT get the plain duplicate-relation
-// no-op IF NOT EXISTS normally gives — it can instead see a unique-violation
-// on Postgres' own pg_class catalog insert (23505, constraint
-// pg_class_relname_nsp_index) or a lock-not-available (55P03) from the
-// racing DDL. Both are benign: the other pod's build wins and this one just
-// backs off. A 23505 against "events_idempotency_uq" itself is NOT this
-// race — see duplicateIdempotencyKeyErrorOr.
-function isBenignConcurrentIndexBuildRace(e: unknown): boolean {
-  if (isTableAlreadyExists(e) || isLockNotAvailable(e)) return true;
-  return isUniqueViolation(e) && constraintOf(e) === "pg_class_relname_nsp_index";
-}
-
-// A 23505 against "events_idempotency_uq" means real duplicate
-// metadata->>'idempotencyKey' values for the same tenant already exist —
-// CONCURRENTLY still enforces uniqueness on live inserts against the
-// not-yet-valid index. That needs an operator to find + resolve the
-// duplicates, not a crash-loop on every subsequent boot, so re-throw a
-// distinguishable error instead of the raw driver error.
-function duplicateIdempotencyKeyErrorOr(e: unknown): unknown {
-  if (isUniqueViolation(e) && constraintOf(e) === "events_idempotency_uq") {
-    return new Error(
-      "ensureIdempotencyKeyIndex: duplicate metadata->>'idempotencyKey' values exist for at least " +
-        "one tenant in kumiko_events — CREATE UNIQUE INDEX CONCURRENTLY cannot complete. Find and " +
-        "resolve the duplicate idempotencyKey rows, then restart to retry.",
-      { cause: e },
-    );
-  }
-  return e;
-}
-
-export type SubsequentEventInsertParams = {
-  readonly aggregateId: string;
-  readonly aggregateType: string;
-  readonly tenantId: string;
-  readonly newVersion: number;
-  readonly type: string;
-  readonly eventVersion: number;
-  // Plain objects, NOT pre-stringified JSON: Bun.SQL encodes a JS string
-  // bound to ::jsonb as a JSON string scalar (double-encoding) — every
-  // version>1 event written between 2026-05-25 and this fix carried
-  // payload/metadata as jsonb strings instead of objects.
-  readonly payload: Record<string, unknown>;
-  readonly metadata: Record<string, unknown>;
-  readonly createdBy: string;
-  readonly expectedVersion: number;
-};
-
-export type SubsequentEventInsertRow = {
-  readonly id: string | bigint;
-  readonly created_at: Date | string;
-};
-
-/** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
-export async function insertSubsequentEventRow(
-  db: AnyDb,
-  params: SubsequentEventInsertParams,
-): Promise<SubsequentEventInsertRow | undefined> {
-  const rows = (await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_events" (
-       aggregate_id, aggregate_type, tenant_id, version,
-       type, event_version, payload, metadata, created_by
-     )
-     SELECT $1::uuid, $2, $3::uuid, $4,
-            $5, $6, $7::jsonb,
-            $8::jsonb, $9
-     WHERE EXISTS (
-       SELECT 1 FROM "kumiko_events"
-       WHERE aggregate_id = $1::uuid
-         AND version = $10
-         AND tenant_id = $3::uuid
-     )
-     RETURNING id, created_at`,
-    [
-      params.aggregateId,
-      params.aggregateType,
-      params.tenantId,
-      params.newVersion,
-      params.type,
-      params.eventVersion,
-      params.payload,
-      params.metadata,
-      params.createdBy,
-      params.expectedVersion,
-    ],
-  )) as ReadonlyArray<SubsequentEventInsertRow>;
-  return rows[0];
-}
-
-export async function selectStreamMaxVersion(
-  db: AnyDb,
-  aggregateId: string,
-  tenantId: string,
-): Promise<number> {
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`,
-    [aggregateId, tenantId],
-  )) as ReadonlyArray<{ v: number | null }>;
-  return rows[0]?.v ?? 0;
-}
-
-/** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
-export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number> {
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`,
-    [aggregateId],
-  )) as ReadonlyArray<{ v: number | null }>;
-  return rows[0]?.v ?? 0;
-}
-
-export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,
-    [],
-  )) as ReadonlyArray<{ max: bigint | string | number | null }>;
-  const raw = rows[0]?.max;
-  if (typeof raw === "bigint") return raw;
-  if (raw === null || raw === undefined) return 0n;
-  return BigInt(raw);
-}
-
-/** Head event id for lag metrics — alias for selectEventsHighWaterMark. */
-// @wrapper-known semantic-alias
-export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
-  return selectEventsHighWaterMark(db);
-}
-
-export async function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null> {
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT "id" FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT 1`,
-    [afterId],
-  )) as ReadonlyArray<{ id: string | bigint }>;
-  const row = rows[0];
-  if (!row) return null;
-  return typeof row.id === "bigint" ? row.id : BigInt(row.id);
-}
-
-export type SaveSnapshotParams = {
-  readonly aggregateId: string;
-  readonly tenantId: string;
-  readonly aggregateType: string;
-  readonly version: number;
-  // Plain object — see SubsequentEventInsertParams on why pre-stringified
-  // JSON double-encodes under Bun.SQL's ::jsonb binding.
-  readonly state: Record<string, unknown>;
-  readonly snapshotVersion: number;
-};
-
-// kumiko_snapshots predates snapshot_version — idempotent heal for existing
-// installs, run from the same ensure path as table creation.
-export async function ensureSnapshotVersionColumn(db: AnyDb): Promise<void> {
-  await asRawClient(db).unsafe(
-    `ALTER TABLE "kumiko_snapshots" ADD COLUMN IF NOT EXISTS "snapshot_version" integer NOT NULL DEFAULT 1`,
-  );
-}
-
-export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_snapshots"
-       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state", "snapshot_version")
-     VALUES ($1, $2, $3, $4, $5::jsonb, $6)
-     ON CONFLICT ("aggregate_id", "version") DO UPDATE SET
-       "state" = $5::jsonb,
-       "aggregate_type" = $3,
-       "snapshot_version" = $6,
-       "created_at" = now()`,
-    [
-      params.aggregateId,
-      params.tenantId,
-      params.aggregateType,
-      params.version,
-      params.state,
-      params.snapshotVersion,
-    ],
-  );
-}
-
-export type ArchiveStreamParams = {
-  readonly tenantId: string;
-  readonly aggregateId: string;
-  readonly aggregateType: string;
-  readonly archivedBy: string;
-  readonly reason: string | null;
-};
-
-export async function upsertArchivedStream(db: AnyDb, params: ArchiveStreamParams): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_archived_streams"
-       ("tenant_id", "aggregate_id", "aggregate_type", "archived_by", "reason")
-     VALUES ($1, $2, $3, $4, $5)
-     ON CONFLICT ("tenant_id", "aggregate_id") DO UPDATE SET
-       "archived_at" = now(),
-       "archived_by" = $4,
-       "aggregate_type" = $3,
-       "reason" = $5`,
-    [params.tenantId, params.aggregateId, params.aggregateType, params.archivedBy, params.reason],
-  );
-}
-
-export type PendingIdRange = { readonly from: bigint; readonly to: bigint };
-
-// Per-consumer turn fetch: the plain `id > cursor` window plus any ranges the
-// consumer is still watching as pending gaps (ids invisible on an earlier
-// turn that may have become visible since). Raw SQL — the typed builder's
-// WhereObject is an AND of fields, it can't express this OR.
-export async function selectPendingAndNewEventRows(
-  db: AnyDb,
-  cursor: bigint,
-  pendingRanges: readonly PendingIdRange[],
-  batchSize: number,
-): Promise<ReadonlyArray<Record<string, unknown>>> {
-  if (pendingRanges.length === 0) {
-    return unsafeReadRetrying(
-      db,
-      `SELECT * FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT $2`,
-      [cursor, batchSize],
-    );
-  }
-  return unsafeReadRetrying(
-    db,
-    // UNION ALL of two primary-key range scans: an `id > $1 OR EXISTS (…)`
-    // predicate can't use the index and would seq-scan kumiko_events per turn.
-    // Ranges sit below $1, so the branches never overlap.
-    `(SELECT e.* FROM unnest($2::bigint[], $3::bigint[]) AS g(f, t)
-       CROSS JOIN LATERAL (
-         SELECT * FROM "kumiko_events" WHERE "id" BETWEEN g.f AND g.t ORDER BY "id" ASC LIMIT $4
-       ) e)
-     UNION ALL
-     (SELECT * FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT $4)
-     ORDER BY "id" ASC LIMIT $4`,
-    [
-      cursor,
-      pendingRanges.map((r) => r.from.toString()),
-      pendingRanges.map((r) => r.to.toString()),
-      batchSize,
-    ],
-  );
-}
-
-// Smallest committed-and-visible id inside any pending range — lets
-// skipPoisonEvent (event-dispatcher-admin.ts) tell a live poison apart from
-// a still-invisible gap without pulling full rows.
-export async function selectSmallestVisibleIdInRanges(
-  db: AnyDb,
-  pendingRanges: readonly PendingIdRange[],
-): Promise<bigint | null> {
-  if (pendingRanges.length === 0) return null;
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT MIN("id")::text AS id FROM "kumiko_events"
-     WHERE EXISTS (
-       SELECT 1 FROM unnest($1::bigint[], $2::bigint[]) AS g(f, t) WHERE "id" BETWEEN g.f AND g.t
-     )`,
-    [pendingRanges.map((r) => r.from.toString()), pendingRanges.map((r) => r.to.toString())],
-  )) as ReadonlyArray<{ id: string | null }>;
-  const id = rows[0]?.id;
-  return id === null || id === undefined ? null : BigInt(id);
-}

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

@@ -1,104 +0,0 @@
-import type { AnyDb } from "../query";
-import { asRawClient, unsafeReadRetrying } from "../query";
-
-export async function markProjectionRebuilding(db: AnyDb, projectionName: string): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_projections" ("name", "status") VALUES ($1, 'rebuilding')
-     ON CONFLICT ("name") DO UPDATE SET
-       "status" = 'rebuilding',
-       "last_error" = NULL,
-       "updated_at" = now()`,
-    [projectionName],
-  );
-}
-
-// Cursor-paged read for the live-tail catch-up loop: one batch of events
-// strictly newer than `afterId`, ascending. Each call is a fresh SELECT, so
-// under READ COMMITTED it sees events committed by concurrent writers since the
-// previous batch — that is what lets the rebuild drain the tail to ~0 lag.
-export async function selectEventsForProjectionRebuildBatch(
-  db: AnyDb,
-  aggregateTypes: readonly string[],
-  eventTypes: readonly string[],
-  afterId: bigint,
-  limit: number,
-): Promise<ReadonlyArray<Record<string, unknown>>> {
-  // Archived streams don't replay (Marten-aligned): their aggregates are
-  // frozen ops-tombstones — replaying them would resurrect rows (or, for
-  // stranded duplicate-aggregates like fw#832, collide on unique indexes).
-  return (await unsafeReadRetrying(
-    db,
-    `SELECT * FROM "kumiko_events" e
-     WHERE e."aggregate_type" = ANY($1::text[])
-       AND e."type" = ANY($2::text[])
-       AND e."id" > $3
-       AND NOT EXISTS (
-         SELECT 1 FROM "kumiko_archived_streams" a
-          WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
-       )
-     ORDER BY e."id" ASC
-     LIMIT $4`,
-    [aggregateTypes, eventTypes, afterId, limit],
-  )) 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> {
-  // Same archived-streams exclusion as the batch query — the #443 recompute
-  // compares this count against applied events; a filter mismatch would make
-  // every rebuild with an archived stream loop the full-re-replay forever.
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT count(*)::bigint AS n FROM "kumiko_events" e
-     WHERE e."aggregate_type" = ANY($1::text[])
-       AND e."type" = ANY($2::text[])
-       AND NOT EXISTS (
-         SELECT 1 FROM "kumiko_archived_streams" a
-          WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
-       )`,
-    [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,
-  lastProcessedEventId: bigint,
-): Promise<void> {
-  await asRawClient(db).unsafe(
-    `UPDATE "kumiko_projections" SET
-       "last_processed_event_id" = $1,
-       "status" = 'idle',
-       "last_rebuild_at" = now(),
-       "last_error" = NULL,
-       "updated_at" = now()
-     WHERE "name" = $2`,
-    [lastProcessedEventId, projectionName],
-  );
-}
-
-export async function markProjectionRebuildFailed(
-  db: AnyDb,
-  projectionName: string,
-  errorMessage: string,
-): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_projections" ("name", "status", "last_error") VALUES ($1, 'failed', $2)
-     ON CONFLICT ("name") DO UPDATE SET
-       "status" = 'failed',
-       "last_error" = $2,
-       "updated_at" = now()`,
-    [projectionName, errorMessage],
-  );
-}

package/src/db/queries/raw-sql.ts

@@ -1,28 +0,0 @@
-import type { AnyDb } from "../query";
-import { asRawClient, unsafeReadRetrying } from "../query";
-
-/** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
- *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
- *  for SELECT-only paths. */
-export async function executeRawQuery<T = Record<string, unknown>>(
-  db: AnyDb,
-  sqlText: string,
-  params: readonly unknown[] = [],
-): Promise<readonly T[]> {
-  return (await asRawClient(db).unsafe(sqlText, params)) as readonly T[];
-}
-
-/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
- *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
-// @wrapper-known semantic-alias
-export async function executeRawQueryRead<T = Record<string, unknown>>(
-  db: AnyDb,
-  sqlText: string,
-  params: readonly unknown[] = [],
-): Promise<readonly T[]> {
-  return unsafeReadRetrying<T>(db, sqlText, params);
-}
-
-export async function pingDatabase(db: AnyDb): Promise<void> {
-  await asRawClient(db).unsafe("SELECT 1");
-}

package/src/db/queries/seed-context.ts

@@ -1,62 +0,0 @@
-import type { AnyDb } from "../query";
-import { unsafeReadRetrying } from "../query";
-
-export type SeedUserRow = {
-  readonly id: string;
-  readonly email: string;
-  readonly tenantId: string;
-};
-
-export type SeedMembershipDbRow = {
-  readonly user_id: string;
-  readonly tenant_id: string;
-  readonly stream_tenant_id: string;
-  readonly roles: string;
-};
-
-export type SeedTenantDbRow = {
-  readonly id: string;
-  readonly name: string;
-  readonly tenant_key: string;
-};
-
-export async function selectUserByEmail(db: AnyDb, email: string): Promise<SeedUserRow | null> {
-  const rows = (await unsafeReadRetrying(
-    db,
-    `SELECT id::text AS id, email, tenant_id::text AS tenant_id
-     FROM read_users
-     WHERE email = $1
-     LIMIT 1`,
-    [email],
-  )) as readonly { id: string; email: string; tenant_id: string }[];
-  const row = rows[0];
-  if (!row) return null;
-  return { id: row.id, email: row.email, tenantId: row.tenant_id };
-}
-
-export async function selectMembershipsOfUser(
-  db: AnyDb,
-  userId: string,
-): Promise<readonly SeedMembershipDbRow[]> {
-  return (await unsafeReadRetrying(
-    db,
-    `SELECT m.user_id::text AS user_id,
-            m.tenant_id::text AS tenant_id,
-            e.tenant_id::text AS stream_tenant_id,
-            m.roles
-     FROM read_tenant_memberships m
-     JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
-     WHERE m.user_id = $1`,
-    [userId],
-  )) as readonly SeedMembershipDbRow[];
-}
-
-export async function selectAllTenants(db: AnyDb): Promise<readonly SeedTenantDbRow[]> {
-  return (await unsafeReadRetrying(
-    db,
-    `SELECT id::text AS id, name, key AS tenant_key
-     FROM read_tenants
-     ORDER BY inserted_at`,
-    [],
-  )) as readonly SeedTenantDbRow[];
-}