@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/db/queries/event-consumer.js

@@ -0,0 +1,261 @@
+import { asRawClient } from "../query.js";
+// Per-turn snapshot bounds for pending-gap finality (event-dispatcher.ts's
+// processConsumer). pg_current_snapshot() is this transaction's MVCC view;
+// xmin is the oldest still-in-progress xact id in it, xmax the next
+// unassigned one. Both travel as strings — bigint/xid8 doesn't round-trip
+// through the driver as a JS number.
+export async function selectSnapshotXmin(db) {
+    const rows = (await asRawClient(db).unsafe(`SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS xmin`));
+    const xmin = rows[0]?.xmin;
+    if (xmin === undefined)
+        throw new Error("selectSnapshotXmin: no row returned");
+    return xmin;
+}
+export async function selectSnapshotXmax(db) {
+    const rows = (await asRawClient(db).unsafe(`SELECT pg_snapshot_xmax(pg_current_snapshot())::text AS xmax`));
+    const xmax = rows[0]?.xmax;
+    if (xmax === undefined)
+        throw new Error("selectSnapshotXmax: no row returned");
+    return xmax;
+}
+/** Serialise against consumer-bootstrap INSERTs during event retention prune. */
+export async function lockEventConsumersShareMode(db) {
+    await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
+}
+// The MAX(id) horizon plus every currently-open id gap below it, read from a
+// single snapshot (READ COMMITTED gives each statement its own). A gap can
+// only later fill in if some transaction holding a lower id was still
+// in-flight in that same snapshot — pg_snapshot_xip is empty otherwise, so
+// the gap CTEs short-circuit and the window scan over kumiko_events never
+// runs. Used both to seed startFrom "now" (#3231) and to seed an MSP
+// rebuild's handoff to the live dispatcher (msp-rebuild.ts).
+export async function selectEventIdHorizonWithMissingRanges(db) {
+    const rows = (await asRawClient(db).unsafe(`WITH b AS (
+       SELECT COALESCE(MAX("id"), 0) AS horizon, MIN("id") AS min_id FROM "kumiko_events"
+     ),
+     r AS (
+       SELECT 1::bigint AS f, b.min_id - 1 AS t FROM b
+        WHERE b.min_id > 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
+       UNION ALL
+       SELECT w."id" + 1, w.next_id - 1
+         FROM (SELECT "id", lead("id") OVER (ORDER BY "id") AS next_id FROM "kumiko_events") w
+        WHERE w.next_id > w."id" + 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
+     )
+     SELECT b.horizon::text AS horizon,
+            pg_snapshot_xmax(pg_current_snapshot())::text AS xmax,
+            r.f::text AS gap_from,
+            r.t::text AS gap_to
+       FROM b LEFT JOIN r ON true
+      ORDER BY r.f`));
+    const first = rows[0];
+    if (first === undefined)
+        throw new Error("selectEventIdHorizonWithMissingRanges: no row returned");
+    const gaps = [];
+    for (const row of rows) {
+        if (row.gap_from === null || row.gap_to === null)
+            continue;
+        gaps.push({ from: row.gap_from, to: row.gap_to, xmax: row.xmax });
+    }
+    return { horizon: BigInt(first.horizon), gaps };
+}
+// startFrom "now" seeds the FIRST-registration cursor at the current
+// MAX(events.id) instead of the column default 0 — mounting a consumer into
+// an existing app then skips the historical log instead of replaying it. The
+// horizon and pending_gaps are read from one snapshot (selectEventIdHorizon
+// WithMissingRanges): a transaction holding a lower id can still be
+// in-flight at boot, and without seeding those gaps its event would commit
+// after the cursor already sits above it, so `id > cursor` would never
+// deliver it (#3231). The cheap existence check skips the scan entirely for
+// the (overwhelmingly common) case of an already-registered consumer.
+// ON CONFLICT DO NOTHING keeps both branches safe for an existing row: the
+// subquery only ever affects the row this statement inserts.
+export async function insertConsumerIfAbsent(db, name, instanceId, startFrom = "beginning") {
+    if (startFrom === "now") {
+        const existing = (await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`, [name, instanceId]));
+        // skip: already registered — an existing cursor is never re-seeded.
+        if (existing.length > 0)
+            return;
+        const { horizon, gaps } = await selectEventIdHorizonWithMissingRanges(db);
+        await asRawClient(db).unsafe(`INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status", "last_processed_event_id", "pending_gaps")
+       VALUES ($1, $2, 'idle', $3, $4::text::jsonb)
+       ON CONFLICT ("name", "instance_id") DO NOTHING`, [name, instanceId, horizon, JSON.stringify(gaps)]);
+    }
+    else {
+        await asRawClient(db).unsafe(`INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status") VALUES ($1, $2, 'idle')
+       ON CONFLICT ("name", "instance_id") DO NOTHING`, [name, instanceId]);
+    }
+}
+// fw#2625: a consumer that moved from delivery: "per-instance" to "shared"
+// leaves its old per-instance rows behind — no dispatcher will ever advance
+// them again, and pruneEvents stays pinned to their stale cursor forever.
+// Scoped by name + "not the shared sentinel" so a still-per-instance
+// consumer's live rows (or an already-migrated __shared__ row) are never
+// touched.
+export async function deleteOrphanedPerInstanceConsumerRows(db, consumerNames, 
+// Passed in rather than imported from event-consumer-state.ts (which
+// defines SHARED_INSTANCE_SENTINEL): that module already imports from
+// this one for the DB queries it needs, so importing back would be a
+// require cycle. The one caller lives in that same file and has the
+// constant in scope.
+sharedInstanceSentinel) {
+    // skip: nothing to delete — an empty ANY($1) would still hit the table,
+    // pointlessly, on every boot for an app with no migrated consumers yet.
+    if (consumerNames.length === 0)
+        return;
+    await asRawClient(db).unsafe(`DELETE FROM "kumiko_event_consumers"
+     WHERE "name" = ANY($1) AND "instance_id" != $2`, [consumerNames, sharedInstanceSentinel]);
+}
+// Lock-free pre-check for doPass: which (name, instance_id) pairs are
+// provably idle — no locking, no xid, no WAL. A pair only qualifies when its
+// row exists, its status isn't dead (dead must still go through
+// acquireConsumerState for auto-rearm), it has no pending_gaps, and no event
+// exists past its cursor. Paired via unnest so the two positional arrays
+// zip element-wise into rows instead of a cartesian product.
+//
+// `deadStatus` is passed in rather than imported from event-consumer-state.ts
+// (which defines ConsumerStatuses) — that module already imports from this
+// one, so importing back would be a require cycle (same pattern as
+// deleteOrphanedPerInstanceConsumerRows above).
+export async function selectProvablyIdleConsumerPairs(db, names, instanceIds, deadStatus) {
+    const rows = (await asRawClient(db).unsafe(`SELECT c."name" AS name, c."instance_id" AS instance_id
+     FROM "kumiko_event_consumers" c
+     WHERE ("name", "instance_id") = ANY (SELECT * FROM unnest($1::text[], $2::text[]))
+       AND "status" != $3
+       AND "pending_gaps" = '[]'::jsonb
+       AND NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e WHERE e."id" > c."last_processed_event_id"
+       )`, [names, instanceIds, deadStatus]));
+    return rows.map((r) => ({ name: r.name, instanceId: r.instance_id }));
+}
+export async function selectConsumerForUpdateSkipLocked(db, name, instanceId) {
+    const rows = (await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE SKIP LOCKED`, [name, instanceId]));
+    return rows[0];
+}
+export async function markConsumerProcessing(db, name, instanceId) {
+    await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET "status" = 'processing', "updated_at" = now()
+     WHERE "name" = $1 AND "instance_id" = $2`, [name, instanceId]);
+}
+// Best-effort record of an infra-level pass failure (event-dispatcher.ts's
+// processConsumer catch) — called OUTSIDE the transaction that just rolled
+// back, since that tx's own markProcessing/updateConsumerDeliveryOutcome
+// writes never committed. Must NOT touch "attempts": that counter is
+// deliverEvents' poison-pill/dead-letter budget, incremented only on a
+// handler throw inside an actual delivery pass. Spending it here would let
+// repeated infra blips (the exact case this backoff exists for) dead-letter
+// the consumer on the next real handler failure instead of after
+// maxAttempts. Visibility is covered by last_error, updated_at, and the
+// caller's console.error — status and the cursor are left as-is too, since
+// we don't know at this point whether the consumer should be "dead" (that's
+// the deliverEvents/maxAttempts contract, which never ran this pass).
+export async function recordConsumerPassFailure(db, name, instanceId, errorMessage) {
+    await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "last_error" = $1,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3`, [errorMessage, name, instanceId]);
+}
+export async function updateConsumerDeliveryOutcome(db, name, instanceId, outcome) {
+    // Advancing the cursor proves this pass wasn't poison — reset the re-arm
+    // budget so an unrelated failure down the line gets its own fresh 3
+    // chances instead of inheriting a partially-spent counter from a past,
+    // already-resolved outage.
+    const resetRearmCount = outcome.processed > 0;
+    await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "attempts" = $2,
+       "status" = $3,
+       "last_error" = $4,
+       "rearm_count" = CASE WHEN $5 THEN 0 ELSE "rearm_count" END,
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       "pending_gaps" = $6::text::jsonb,
+       "updated_at" = now()
+     WHERE "name" = $7 AND "instance_id" = $8`, [
+        outcome.cursor,
+        outcome.attempts,
+        outcome.deadLettered ? "dead" : "idle",
+        outcome.lastError,
+        resetRearmCount,
+        JSON.stringify(outcome.pendingGaps),
+        name,
+        instanceId,
+    ]);
+}
+export async function updateConsumerStatusReturning(db, name, instanceId, status) {
+    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "rearm_count" = 0, "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`, [status, name, instanceId]));
+    return rows[0];
+}
+export async function advanceConsumerPastEventReturning(db, name, instanceId, eventId) {
+    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = 0,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`, [eventId, name, instanceId]));
+    return rows[0];
+}
+export async function resetConsumerForMspRebuild(db, name, instanceId) {
+    await asRawClient(db).unsafe(`INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "last_processed_event_id", "status", "pending_gaps")
+     VALUES ($1, $2, 0, 'idle', '[]'::jsonb)
+     ON CONFLICT ("name", "instance_id") DO UPDATE SET
+       "last_processed_event_id" = 0,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "pending_gaps" = '[]'::jsonb,
+       "updated_at" = now()`, [name, instanceId]);
+}
+export async function selectConsumerForUpdate(db, name, instanceId) {
+    const rows = (await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`, [name, instanceId]));
+    return rows[0];
+}
+export async function updateConsumerRebuildCursor(db, name, instanceId, lastProcessedEventId, pendingGaps) {
+    await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       "pending_gaps" = $2::text::jsonb,
+       "updated_at" = now()
+     WHERE "name" = $3 AND "instance_id" = $4`, [lastProcessedEventId, JSON.stringify(pendingGaps), name, instanceId]);
+}
+export async function markConsumerRebuildFailed(db, name, instanceId, errorMessage) {
+    await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET "status" = 'dead', "last_error" = $1, "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3`, [errorMessage, name, instanceId]);
+}
+// Auto-revive a dead consumer once its cooldown has elapsed (called from
+// acquireConsumerState — not an ops action, so no "requireConsumerRow"
+// precondition like restartConsumer/enableConsumer). Increments rearm_count
+// so the caller can enforce a lifetime cap on automatic revivals; manual
+// restartConsumer()/enableConsumer() reset it back to 0.
+export async function rearmDeadConsumer(db, name, instanceId) {
+    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = "rearm_count" + 1,
+       "updated_at" = now()
+     WHERE "name" = $1 AND "instance_id" = $2
+     RETURNING *`, [name, instanceId]));
+    return rows[0];
+}
+// skipPoisonEvent's pending-gap branch: the poison is a pending id below the
+// cursor, so it's removed from pending_gaps directly instead of advancing
+// last_processed_event_id (advancing it here would be a regression — the
+// cursor already sits above this id).
+export async function removePendingGapReturning(db, name, instanceId, newPendingGaps) {
+    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+       "pending_gaps" = $1::text::jsonb,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = 0,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`, [JSON.stringify(newPendingGaps), name, instanceId]));
+    return rows[0];
+}

package/dist/db/queries/event-store-admin.d.ts

@@ -0,0 +1,24 @@
+import type { AnyDb } from "../query.js";
+export type RawFirstEventInsertParams = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: string;
+    readonly newVersion: number;
+    readonly type: string;
+    readonly eventVersion: number;
+    readonly payload: Record<string, unknown>;
+    readonly metadata: Record<string, unknown>;
+    readonly createdAt: string;
+    readonly createdBy: string;
+};
+export declare function insertRawFirstEvent(db: AnyDb, params: RawFirstEventInsertParams): Promise<void>;
+export type RawSubsequentEventInsertParams = RawFirstEventInsertParams & {
+    readonly expectedVersion: number;
+};
+export declare function insertRawSubsequentEvent(db: AnyDb, params: RawSubsequentEventInsertParams): Promise<boolean>;
+export declare function insertRawEventBatch(db: AnyDb, sqlValues: string, params: unknown[]): Promise<void>;
+export declare function eventPredecessorExists(db: AnyDb, aggregateId: string, tenantId: string, version: number): Promise<boolean>;
+export declare function findExistingEventVersion(db: AnyDb, sqlInClause: string, params: unknown[]): Promise<{
+    aggregateId: string;
+    version: number;
+} | undefined>;

package/dist/db/queries/event-store-admin.js

@@ -0,0 +1,71 @@
+import { asRawClient } from "../query.js";
+export async function insertRawFirstEvent(db, params) {
+    await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     VALUES ($1::uuid, $2, $3::uuid, $4, $5, $6, $7::jsonb, $8::jsonb, $9::timestamptz, $10)`, [
+        params.aggregateId,
+        params.aggregateType,
+        params.tenantId,
+        params.newVersion,
+        params.type,
+        params.eventVersion,
+        params.payload,
+        params.metadata,
+        params.createdAt,
+        params.createdBy,
+    ]);
+}
+export async function insertRawSubsequentEvent(db, params) {
+    const rows = (await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     SELECT $1::uuid, $2, $3::uuid, $4, $5, $6, $7::jsonb, $8::jsonb, $9::timestamptz, $10
+     WHERE EXISTS (
+       SELECT 1 FROM "kumiko_events"
+       WHERE aggregate_id = $1::uuid
+         AND version = $11
+         AND tenant_id = $3::uuid
+     )
+     RETURNING id`, [
+        params.aggregateId,
+        params.aggregateType,
+        params.tenantId,
+        params.newVersion,
+        params.type,
+        params.eventVersion,
+        params.payload,
+        params.metadata,
+        params.createdAt,
+        params.createdBy,
+        params.expectedVersion,
+    ]));
+    return rows.length > 0;
+}
+export async function insertRawEventBatch(db, sqlValues, params) {
+    await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     VALUES ${sqlValues}`, params);
+}
+export async function eventPredecessorExists(db, aggregateId, tenantId, version) {
+    const rows = (await asRawClient(db).unsafe(`SELECT EXISTS(
+       SELECT 1 FROM "kumiko_events"
+       WHERE aggregate_id = $1::uuid
+         AND tenant_id = $2::uuid
+         AND version = $3
+     ) AS present`, [aggregateId, tenantId, version]));
+    return rows[0]?.present === true;
+}
+export async function findExistingEventVersion(db, sqlInClause, params) {
+    const rows = (await asRawClient(db).unsafe(`SELECT aggregate_id, version FROM "kumiko_events"
+     WHERE (tenant_id, aggregate_id, version) IN (${sqlInClause})
+     LIMIT 1`, params));
+    const row = rows[0];
+    if (!row)
+        return undefined;
+    return { aggregateId: row.aggregate_id, version: row.version };
+}

package/dist/db/queries/event-store-transfer.d.ts

@@ -0,0 +1,20 @@
+import type { AnyDb } from "../query.js";
+export type TransferEventRowsParams = {
+    readonly sourceTenantId: string;
+    readonly destinationTenantId: string;
+    readonly aggregateType: string;
+    readonly aggregateIds: readonly string[];
+};
+export declare function transferEventRows(db: AnyDb, params: TransferEventRowsParams): Promise<readonly string[]>;
+export type DeleteSnapshotsForAggregatesParams = {
+    readonly tenantId: string;
+    readonly aggregateIds: readonly string[];
+};
+export declare function deleteSnapshotsForAggregates(db: AnyDb, params: DeleteSnapshotsForAggregatesParams): Promise<void>;
+export type TransferArchivedStreamRowsParams = {
+    readonly sourceTenantId: string;
+    readonly destinationTenantId: string;
+    readonly aggregateType: string;
+    readonly aggregateIds: readonly string[];
+};
+export declare function transferArchivedStreamRows(db: AnyDb, params: TransferArchivedStreamRowsParams): Promise<void>;

package/dist/db/queries/event-store-transfer.js

@@ -0,0 +1,31 @@
+// Raw SQL backing event-store/transfer.ts — the framework's own tenant-transfer
+// primitive for streams. Kept in db/queries alongside the rest of the
+// event-store's raw statements (see event-store.ts, event-store-admin.ts,
+// backfill-pii.ts): the one place in the repo allowed to write tenant_id
+// directly onto kumiko_events / kumiko_snapshots / kumiko_archived_streams.
+import { asRawClient } from "../query.js";
+// Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
+// per-event-row hits in-process instead of relying on invalid SQL.
+export async function transferEventRows(db, params) {
+    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
+        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
+        `RETURNING "aggregate_id" AS id`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]));
+    return [...new Set(rows.map((row) => row.id))];
+}
+// Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+// dropped rather than rewritten, forcing a full replay from the just-moved
+// events on next read instead of carrying the snapshot's own generation
+// bookkeeping across the tenant boundary.
+export async function deleteSnapshotsForAggregates(db, params) {
+    await asRawClient(db).unsafe(`DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2)`, [params.tenantId, params.aggregateIds]);
+}
+// An archived stream's marker must move with it — leaving it behind would
+// make the stream writable again the instant it lands in the destination
+// tenant (archive.ts's isStreamArchived check is itself tenant-scoped).
+// `aggregate_type` is part of the match, same as transferEventRows — an
+// archived marker for a DIFFERENT aggregate type that happens to share the
+// moved aggregate's id must stay in the source tenant.
+export async function transferArchivedStreamRows(db, params) {
+    await asRawClient(db).unsafe(`UPDATE "kumiko_archived_streams" SET "tenant_id" = $1 ` +
+        `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4)`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]);
+}

package/dist/db/queries/event-store.d.ts

@@ -0,0 +1,54 @@
+import type { AnyDb } from "../query.js";
+export declare function claimXactId(db: AnyDb): Promise<void>;
+/** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
+export declare function notifyPgChannel(db: AnyDb, channel: string): Promise<void>;
+export declare function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void>;
+export type SubsequentEventInsertParams = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: string;
+    readonly newVersion: number;
+    readonly type: string;
+    readonly eventVersion: number;
+    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 declare function insertSubsequentEventRow(db: AnyDb, params: SubsequentEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
+export declare function selectStreamMaxVersion(db: AnyDb, aggregateId: string, tenantId: string): Promise<number>;
+/** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
+export declare function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number>;
+export declare function selectEventsHighWaterMark(db: AnyDb): Promise<bigint>;
+/** Head event id for lag metrics — alias for selectEventsHighWaterMark. */
+export declare function selectEventsHeadId(db: AnyDb): Promise<bigint>;
+export declare function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null>;
+export type SaveSnapshotParams = {
+    readonly aggregateId: string;
+    readonly tenantId: string;
+    readonly aggregateType: string;
+    readonly version: number;
+    readonly state: Record<string, unknown>;
+    readonly snapshotVersion: number;
+};
+export declare function ensureSnapshotVersionColumn(db: AnyDb): Promise<void>;
+export declare function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void>;
+export type ArchiveStreamParams = {
+    readonly tenantId: string;
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly archivedBy: string;
+    readonly reason: string | null;
+};
+export declare function upsertArchivedStream(db: AnyDb, params: ArchiveStreamParams): Promise<void>;
+export type PendingIdRange = {
+    readonly from: bigint;
+    readonly to: bigint;
+};
+export declare function selectPendingAndNewEventRows(db: AnyDb, cursor: bigint, pendingRanges: readonly PendingIdRange[], batchSize: number): Promise<ReadonlyArray<Record<string, unknown>>>;
+export declare function selectSmallestVisibleIdInRanges(db: AnyDb, pendingRanges: readonly PendingIdRange[]): Promise<bigint | null>;