@causal-order/monitor 0.0.9

package/.build/src/runtime/MonitorRuntime.js

@@ -0,0 +1,253 @@
+import { createDefaultMonitorConfig, } from "../types/config.js";
+import { HealthTracker } from "../health/HealthTracker.js";
+import { inspectMonitorSnapshot } from "../inspect/inspectMonitorSnapshot.js";
+import { DeliveryRouter } from "../routing/DeliveryRouter.js";
+import { ReplayCoordinator } from "../replay/ReplayCoordinator.js";
+import { SQLiteReservoir } from "../storage/SQLiteReservoir.js";
+import { ThrottleController } from "../throttle/ThrottleController.js";
+export class MonitorRuntime {
+    #config;
+    #now;
+    #healthTracker;
+    #reservoir;
+    #router;
+    #replay;
+    #throttleTier;
+    constructor(config = {}) {
+        const defaults = createDefaultMonitorConfig();
+        this.#config = {
+            ...defaults,
+            ...config,
+            reservoir: {
+                ...defaults.reservoir,
+                ...config.reservoir,
+            },
+            transport: {
+                ...defaults.transport,
+                ...config.transport,
+            },
+            health: {
+                transport: {
+                    ...defaults.health.transport,
+                    ...config.health?.transport,
+                },
+                dedupe: {
+                    ...defaults.health.dedupe,
+                    ...config.health?.dedupe,
+                },
+                causalOrder: {
+                    ...defaults.health.causalOrder,
+                    ...config.health?.causalOrder,
+                },
+            },
+            throttle: {
+                ...defaults.throttle,
+                ...config.throttle,
+                open: {
+                    ...defaults.throttle.open,
+                    ...config.throttle?.open,
+                },
+                slow: {
+                    ...defaults.throttle.slow,
+                    ...config.throttle?.slow,
+                },
+                verySlow: {
+                    ...defaults.throttle.verySlow,
+                    ...config.throttle?.verySlow,
+                },
+                paused: {
+                    ...defaults.throttle.paused,
+                    ...config.throttle?.paused,
+                },
+            },
+            replay: {
+                ...defaults.replay,
+                ...config.replay,
+            },
+            now: config.now ?? defaults.now,
+        };
+        this.#now = this.#config.now ?? defaults.now;
+        this.#healthTracker = new HealthTracker(this.#config.health, this.#now);
+        this.#reservoir = new SQLiteReservoir(this.#config.reservoir, this.#now);
+        this.#router = new DeliveryRouter(new ThrottleController(this.#config.throttle));
+        this.#replay = new ReplayCoordinator(this.#config.replay, this.#reservoir, this.#now);
+        this.#throttleTier = this.#config.throttle.defaultTier;
+    }
+    getConfig() {
+        return this.#config;
+    }
+    getSnapshot() {
+        return {
+            generatedAt: this.#now(),
+            routingMode: this.#deriveRoutingMode(),
+            throttleTier: this.#throttleTier,
+            components: this.getHealthSnapshot(),
+            reservoir: this.getReservoirStats(),
+            replay: this.getReplaySnapshot(),
+        };
+    }
+    getInspectedSnapshot() {
+        return inspectMonitorSnapshot(this.getSnapshot());
+    }
+    getHealthSnapshot() {
+        return this.#healthTracker.getSnapshot();
+    }
+    getReservoirStats() {
+        return this.#reservoir.getStats();
+    }
+    getReplaySnapshot() {
+        return this.#replay.getSnapshot();
+    }
+    getIngressDecision() {
+        const decision = this.#router.decideIngress(this.#deriveRoutingMode(), this.getReservoirStats());
+        const gatedDecision = this.#config.replay.pauseLiveFlowDuringReplay && this.#replay.isGateClosed()
+            ? {
+                ...decision,
+                action: "buffer_only",
+                reason: `${decision.reason}; replay gate holding live flow`,
+            }
+            : decision;
+        this.#throttleTier = gatedDecision.throttleTier;
+        return gatedDecision;
+    }
+    updateComponentHealth(component, update) {
+        const snapshot = this.#healthTracker.updateComponentHealth(component, update);
+        this.#reservoir.recordHealthTransition(snapshot);
+        if (component === "dedupe" && snapshot.state === "offline") {
+            this.#throttleTier = "slow";
+        }
+        if (component === "causal-order" && snapshot.state === "offline") {
+            this.#throttleTier = "paused";
+        }
+        if (component === "transport" &&
+            snapshot.state === "offline" &&
+            this.getReservoirStats().totalPendingRows === 0) {
+            this.#throttleTier = "paused";
+        }
+        const components = this.#healthTracker.getSnapshot();
+        if (components.transport.state === "online" &&
+            components.dedupe.state === "online" &&
+            components["causal-order"].state === "online") {
+            this.#throttleTier = this.#config.throttle.defaultTier;
+        }
+        this.#reconcileReplayQueue();
+        return snapshot;
+    }
+    observeHeartbeat(component, observedAt = this.#now(), details = {}) {
+        const snapshot = this.#healthTracker.observeHeartbeat(component, observedAt, details);
+        this.#reservoir.recordHealthTransition(snapshot);
+        this.#replay.observeRecoveryHeartbeat(component, snapshot.state, this.#areReplayTargetsHealthy());
+        this.#reconcileReplayQueue();
+        return snapshot;
+    }
+    setThrottleTier(tier) {
+        this.#throttleTier = tier;
+        return this.#throttleTier;
+    }
+    queueReplay() {
+        return this.#replay.queueIfNeeded();
+    }
+    startReplay() {
+        if (!this.#areReplayTargetsHealthy()) {
+            throw new Error("Cannot start replay until both dedupe and causal-order are online.");
+        }
+        this.#replay.queueIfNeeded();
+        return this.#replay.start();
+    }
+    claimReplayBatch(limit = this.#config.throttle.verySlow.batchSize) {
+        if (!this.#areReplayTargetsHealthy()) {
+            throw new Error("Cannot claim replay batch until both dedupe and causal-order are online.");
+        }
+        this.#replay.queueIfNeeded();
+        return this.#replay.claimNextBatch(limit);
+    }
+    acknowledgeReplayBatch(rowIds) {
+        return this.#replay.acknowledgeBatch(rowIds);
+    }
+    acknowledgeIngressDelivery(rowIds) {
+        return this.#reservoir.markIngressRowsDelivered(rowIds);
+    }
+    failReplay(error, rowIds = []) {
+        return this.#replay.fail(error, rowIds);
+    }
+    abortReplay(reason, rowIds = []) {
+        return this.#replay.abort(reason, rowIds);
+    }
+    ingestTransportEvent(event, sourceStreamId) {
+        const decision = this.getIngressDecision();
+        const rowId = this.#reservoir.appendIngressEvent(event, {
+            sourcePath: "transport_normalized_stream",
+            sourceStreamId,
+            deliveryMode: decision.deliveryMode,
+            fullOutageActive: this.#isFullOutageActive(),
+        });
+        return { rowId, decision };
+    }
+    observeDedupeEvent(event, sourceStreamId) {
+        return this.#reservoir.appendIngressEvent(event, {
+            sourcePath: "deduped_observation",
+            sourceStreamId,
+            deliveryMode: "normal",
+            replayState: "delivered",
+            fullOutageActive: false,
+        });
+    }
+    pruneReservoir() {
+        return this.#reservoir.pruneExpired(this.#isFullOutageActive());
+    }
+    refreshHealthStates(at = this.#now()) {
+        const before = this.#healthTracker.getSnapshot();
+        const after = this.#healthTracker.refreshStates(at);
+        for (const component of ["transport", "dedupe", "causal-order"]) {
+            if (before[component].state !== after[component].state) {
+                this.#reservoir.recordHealthTransition(after[component]);
+            }
+        }
+        this.#reconcileReplayQueue();
+        return after;
+    }
+    close() {
+        this.#reservoir.close();
+    }
+    #deriveRoutingMode() {
+        const components = this.#healthTracker.getSnapshot();
+        const transport = components.transport.state;
+        const dedupe = components.dedupe.state;
+        const causalOrder = components["causal-order"].state;
+        if (this.#replay.isGateClosed()) {
+            return "replay_through_dedupe";
+        }
+        if (dedupe === "offline" && causalOrder === "offline") {
+            return "full_outage_buffer";
+        }
+        if (causalOrder === "offline") {
+            return "order_buffer_only";
+        }
+        if (dedupe === "offline") {
+            return "dedupe_bypass_throttled";
+        }
+        if (transport === "offline" && this.getReservoirStats().totalPendingRows > 0) {
+            return "order_buffer_only";
+        }
+        return "normal";
+    }
+    #isFullOutageActive() {
+        const components = this.#healthTracker.getSnapshot();
+        return (components.dedupe.state === "offline" &&
+            components["causal-order"].state === "offline");
+    }
+    #areReplayTargetsHealthy() {
+        const components = this.#healthTracker.getSnapshot();
+        return (components.dedupe.state === "online" &&
+            components["causal-order"].state === "online");
+    }
+    #reconcileReplayQueue() {
+        const backlog = this.getReservoirStats().totalPendingRows;
+        if (backlog === 0) {
+            return;
+        }
+        if (this.#areReplayTargetsHealthy()) {
+            this.#replay.queueIfNeeded();
+        }
+    }
+}

package/.build/src/runtime/createMonitorRuntime.d.ts

@@ -0,0 +1,3 @@
+import { MonitorRuntime } from "./MonitorRuntime.js";
+import type { MonitorConfig } from "../types/config.js";
+export declare function createMonitorRuntime(config?: Partial<MonitorConfig>): MonitorRuntime;

package/.build/src/runtime/createMonitorRuntime.js

@@ -0,0 +1,4 @@
+import { MonitorRuntime } from "./MonitorRuntime.js";
+export function createMonitorRuntime(config = {}) {
+    return new MonitorRuntime(config);
+}

package/.build/src/runtime.d.ts

@@ -0,0 +1,2 @@
+export { createMonitorRuntime } from "./runtime/createMonitorRuntime.js";
+export { MonitorRuntime } from "./runtime/MonitorRuntime.js";

package/.build/src/runtime.js

@@ -0,0 +1,2 @@
+export { createMonitorRuntime } from "./runtime/createMonitorRuntime.js";
+export { MonitorRuntime } from "./runtime/MonitorRuntime.js";

package/.build/src/storage/SQLiteReservoir.d.ts

@@ -0,0 +1,44 @@
+import type { MonitorReservoirConfig } from "../types/config.js";
+import type { MonitorDeliveryMode, MonitorIngressEvent, MonitorSourcePath } from "../types/events.js";
+import type { MonitorComponentHealthSnapshot, ReplaySessionSnapshot, ReservoirStats } from "../types/snapshots.js";
+interface ReservoirIngressOptions {
+    sourcePath: MonitorSourcePath;
+    deliveryMode: MonitorDeliveryMode;
+    sourceStreamId?: string | null;
+    replayState?: ReservoirReplayState;
+    retryNotBeforeMs?: bigint | null;
+    monitorIngestAt?: bigint;
+    fullOutageActive?: boolean;
+}
+type ReservoirReplayState = "pending" | "replaying" | "delivered" | "dead_letter";
+export interface ReservoirReplayEntry {
+    rowId: number;
+    event: MonitorIngressEvent;
+    sourcePath: MonitorSourcePath;
+    sourceStreamId: string | null;
+    deliveryMode: MonitorDeliveryMode;
+    replayAttempts: number;
+}
+interface PruneResult {
+    markedDeadLetter: number;
+    deletedRows: number;
+}
+export declare class SQLiteReservoir {
+    #private;
+    constructor(config: MonitorReservoirConfig, now: () => bigint);
+    appendIngressEvent(event: MonitorIngressEvent, options: ReservoirIngressOptions): number;
+    recordHealthTransition(snapshot: MonitorComponentHealthSnapshot): number;
+    recordReplaySnapshot(snapshot: ReplaySessionSnapshot): number;
+    bumpReplayAttempts(limitToStates?: ReadonlyArray<ReservoirReplayState>): number;
+    updateReplayState(fromStates: ReadonlyArray<ReservoirReplayState>, nextState: ReservoirReplayState): number;
+    claimReplayBatch(limit: number, deliveryMode?: MonitorDeliveryMode): ReservoirReplayEntry[];
+    markReplayBatchDelivered(rowIds: ReadonlyArray<number>): number;
+    markIngressRowsDelivered(rowIds: ReadonlyArray<number>): number;
+    resetReplayBatchToPending(rowIds: ReadonlyArray<number>, retryNotBeforeMs?: bigint | null): number;
+    deadLetterReplayBatch(rowIds: ReadonlyArray<number>): number;
+    pruneExpired(fullOutageActive?: boolean): PruneResult;
+    getStats(): ReservoirStats;
+    getDatabasePath(): string;
+    close(): void;
+}
+export {};

package/.build/src/storage/SQLiteReservoir.js

@@ -0,0 +1,369 @@
+import Database from "better-sqlite3";
+import { applyMonitorSchema } from "./schema.js";
+const BIGINT_SENTINEL = "__monitorBigInt";
+function toSqlBigInt(value) {
+    return value;
+}
+function parseCount(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return Number(value);
+    }
+    if (typeof value === "string") {
+        return Number(value);
+    }
+    return 0;
+}
+function parseBigInt(value) {
+    if (typeof value === "bigint") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return BigInt(value);
+    }
+    if (typeof value === "string" && value.length > 0) {
+        return BigInt(value);
+    }
+    return 0n;
+}
+function serializeJson(value) {
+    return JSON.stringify(value, (_key, currentValue) => typeof currentValue === "bigint"
+        ? {
+            [BIGINT_SENTINEL]: currentValue.toString(),
+        }
+        : currentValue);
+}
+function deserializeJson(value) {
+    return JSON.parse(value, (_key, currentValue) => {
+        if (currentValue &&
+            typeof currentValue === "object" &&
+            BIGINT_SENTINEL in currentValue &&
+            typeof currentValue[BIGINT_SENTINEL] === "string") {
+            return BigInt(currentValue[BIGINT_SENTINEL]);
+        }
+        return currentValue;
+    });
+}
+export class SQLiteReservoir {
+    #config;
+    #now;
+    #db;
+    constructor(config, now) {
+        this.#config = config;
+        this.#now = now;
+        this.#db = new Database(config.databasePath);
+        applyMonitorSchema(this.#db);
+    }
+    appendIngressEvent(event, options) {
+        const monitorIngestAt = options.monitorIngestAt ?? event.ingestedAt ?? this.#now();
+        const retentionWindowMs = options.fullOutageActive
+            ? this.#config.fullOutageMaxWindowMs
+            : this.#config.rollingBufferWindowMs;
+        const expiresAt = monitorIngestAt + retentionWindowMs;
+        const replayState = options.replayState ??
+            (options.sourcePath === "deduped_observation" ? "delivered" : "pending");
+        const result = this.#db
+            .prepare(`INSERT INTO ingress_events (
+          id,
+          monitor_ingest_at_ms,
+          source_node_id,
+          source_stream_id,
+          source_path,
+          event_id,
+          trace_id,
+          sequence,
+          logical_time_ms,
+          payload_json,
+          payload_encoding,
+          delivery_mode,
+          replay_state,
+          replay_attempts,
+          retry_not_before_ms,
+          expires_at_ms
+        ) VALUES (
+          @id,
+          @monitor_ingest_at_ms,
+          @source_node_id,
+          @source_stream_id,
+          @source_path,
+          @event_id,
+          @trace_id,
+          @sequence,
+          @logical_time_ms,
+          @payload_json,
+          @payload_encoding,
+          @delivery_mode,
+          @replay_state,
+          @replay_attempts,
+          @retry_not_before_ms,
+          @expires_at_ms
+        )`)
+            .run({
+            id: event.id,
+            monitor_ingest_at_ms: toSqlBigInt(monitorIngestAt),
+            source_node_id: event.nodeId,
+            source_stream_id: options.sourceStreamId ?? null,
+            source_path: options.sourcePath,
+            event_id: event.id,
+            trace_id: event.traceId ?? event.payload.traceId ?? null,
+            sequence: event.sequence?.toString() ?? null,
+            logical_time_ms: toSqlBigInt(event.clock.physicalTimeMs),
+            payload_json: serializeJson(event),
+            payload_encoding: "json",
+            delivery_mode: options.deliveryMode,
+            replay_state: replayState,
+            replay_attempts: 0,
+            retry_not_before_ms: options.retryNotBeforeMs === null || options.retryNotBeforeMs === undefined
+                ? null
+                : toSqlBigInt(options.retryNotBeforeMs),
+            expires_at_ms: toSqlBigInt(expiresAt),
+        });
+        return Number(result.lastInsertRowid);
+    }
+    recordHealthTransition(snapshot) {
+        const result = this.#db
+            .prepare(`INSERT INTO component_health_log (
+          recorded_at_ms,
+          component,
+          health_state,
+          reason_code,
+          details_json
+        ) VALUES (
+          @recorded_at_ms,
+          @component,
+          @health_state,
+          @reason_code,
+          @details_json
+        )`)
+            .run({
+            recorded_at_ms: toSqlBigInt(snapshot.observedAt),
+            component: snapshot.component,
+            health_state: snapshot.state,
+            reason_code: snapshot.reasonCode,
+            details_json: serializeJson(snapshot.details),
+        });
+        return Number(result.lastInsertRowid);
+    }
+    recordReplaySnapshot(snapshot) {
+        const result = this.#db
+            .prepare(`INSERT INTO replay_sessions (
+          started_at_ms,
+          ended_at_ms,
+          target_path,
+          session_state,
+          event_count_attempted,
+          event_count_delivered,
+          error_count,
+          details_json
+        ) VALUES (
+          @started_at_ms,
+          @ended_at_ms,
+          @target_path,
+          @session_state,
+          @event_count_attempted,
+          @event_count_delivered,
+          @error_count,
+          @details_json
+        )`)
+            .run({
+            started_at_ms: snapshot.startedAt === null ? null : toSqlBigInt(snapshot.startedAt),
+            ended_at_ms: snapshot.endedAt === null ? null : toSqlBigInt(snapshot.endedAt),
+            target_path: snapshot.targetPath,
+            session_state: snapshot.state,
+            event_count_attempted: snapshot.queuedEventCount,
+            event_count_delivered: snapshot.deliveredEventCount,
+            error_count: snapshot.lastError ? 1 : 0,
+            details_json: serializeJson({
+                lastError: snapshot.lastError,
+                nextRetryAt: snapshot.nextRetryAt,
+                consecutiveFailureCount: snapshot.consecutiveFailureCount,
+                recoveryHeartbeatCount: snapshot.recoveryHeartbeatCount,
+                requiredRecoveryHeartbeats: snapshot.requiredRecoveryHeartbeats,
+            }),
+        });
+        return Number(result.lastInsertRowid);
+    }
+    bumpReplayAttempts(limitToStates = []) {
+        const pendingStates = limitToStates.length === 0 ? ["pending", "replaying"] : limitToStates;
+        const placeholders = pendingStates.map(() => "?").join(", ");
+        const result = this.#db
+            .prepare(`UPDATE ingress_events
+         SET replay_attempts = replay_attempts + 1
+         WHERE replay_state IN (${placeholders})`)
+            .run(...pendingStates);
+        return result.changes;
+    }
+    updateReplayState(fromStates, nextState) {
+        const placeholders = fromStates.map(() => "?").join(", ");
+        const result = this.#db
+            .prepare(`UPDATE ingress_events
+         SET replay_state = ?
+         WHERE replay_state IN (${placeholders})`)
+            .run(nextState, ...fromStates);
+        return result.changes;
+    }
+    claimReplayBatch(limit, deliveryMode = "replay_through_dedupe") {
+        if (limit <= 0) {
+            return [];
+        }
+        const claim = this.#db.transaction((nowMs, batchLimit, nextDeliveryMode) => {
+            const rows = this.#db
+                .prepare(`SELECT
+               rowid AS row_id,
+               payload_json,
+               source_path,
+               source_stream_id,
+               replay_attempts
+             FROM ingress_events
+             WHERE replay_state = 'pending'
+               AND (retry_not_before_ms IS NULL OR retry_not_before_ms <= ?)
+             ORDER BY monitor_ingest_at_ms ASC, rowid ASC
+             LIMIT ?`)
+                .all(toSqlBigInt(nowMs), batchLimit);
+            if (rows.length === 0) {
+                return [];
+            }
+            const ids = rows.map((row) => row.row_id);
+            const placeholders = ids.map(() => "?").join(", ");
+            this.#db
+                .prepare(`UPDATE ingress_events
+             SET replay_state = 'replaying',
+                 replay_attempts = replay_attempts + 1,
+                 retry_not_before_ms = NULL,
+                 delivery_mode = ?
+             WHERE rowid IN (${placeholders})`)
+                .run(nextDeliveryMode, ...ids);
+            return rows.map((row) => ({
+                rowId: row.row_id,
+                event: deserializeJson(row.payload_json),
+                sourcePath: row.source_path,
+                sourceStreamId: row.source_stream_id,
+                deliveryMode: nextDeliveryMode,
+                replayAttempts: row.replay_attempts + 1,
+            }));
+        });
+        return claim(this.#now(), limit, deliveryMode);
+    }
+    markReplayBatchDelivered(rowIds) {
+        return this.#updateReplayRows(rowIds, "delivered", null);
+    }
+    markIngressRowsDelivered(rowIds) {
+        return this.#updateReplayRows(rowIds, "delivered", null);
+    }
+    resetReplayBatchToPending(rowIds, retryNotBeforeMs) {
+        return this.#updateReplayRows(rowIds, "pending", retryNotBeforeMs);
+    }
+    deadLetterReplayBatch(rowIds) {
+        return this.#updateReplayRows(rowIds, "dead_letter", null);
+    }
+    pruneExpired(fullOutageActive = false) {
+        const now = this.#now();
+        const rollingWindowMs = fullOutageActive
+            ? this.#config.fullOutageMaxWindowMs
+            : this.#config.rollingBufferWindowMs;
+        const rollingCutoff = now - rollingWindowMs;
+        const hardCutoff = now - this.#config.fullOutageMaxWindowMs;
+        const markResult = this.#db
+            .prepare(`UPDATE ingress_events
+         SET replay_state = 'dead_letter'
+         WHERE replay_state IN ('pending')
+           AND (
+             monitor_ingest_at_ms <= @hard_cutoff
+             OR (
+               retry_not_before_ms IS NULL
+               AND monitor_ingest_at_ms <= @rolling_cutoff
+             )
+           )`)
+            .run({
+            hard_cutoff: toSqlBigInt(hardCutoff),
+            rolling_cutoff: toSqlBigInt(rollingCutoff),
+        });
+        const deleteResult = this.#db
+            .prepare(`DELETE FROM ingress_events
+         WHERE replay_state IN ('delivered', 'dead_letter')
+           AND expires_at_ms <= ?`)
+            .run(toSqlBigInt(now));
+        return {
+            markedDeadLetter: markResult.changes,
+            deletedRows: deleteResult.changes,
+        };
+    }
+    getStats() {
+        const totalPendingRow = this.#db
+            .prepare(`SELECT COUNT(*) AS count
+         FROM ingress_events
+         WHERE replay_state IN ('pending', 'replaying')`)
+            .get();
+        const oldestPendingRow = this.#db
+            .prepare(`SELECT MIN(monitor_ingest_at_ms) AS oldest
+         FROM ingress_events
+         WHERE replay_state IN ('pending', 'replaying')`)
+            .get();
+        const retryWaitingRow = this.#db
+            .prepare(`SELECT
+           COUNT(*) AS count,
+           MIN(retry_not_before_ms) AS earliest_retry_at
+         FROM ingress_events
+         WHERE replay_state = 'pending'
+           AND retry_not_before_ms IS NOT NULL
+           AND retry_not_before_ms > ?`)
+            .get(toSqlBigInt(this.#now()));
+        const bySourceRows = this.#db
+            .prepare(`SELECT source_path, COUNT(*) AS count
+         FROM ingress_events
+         WHERE replay_state IN ('pending', 'replaying')
+         GROUP BY source_path`)
+            .all();
+        const byDeliveryRows = this.#db
+            .prepare(`SELECT delivery_mode, COUNT(*) AS count
+         FROM ingress_events
+         WHERE replay_state IN ('pending', 'replaying')
+         GROUP BY delivery_mode`)
+            .all();
+        const sourceCounts = {
+            transport_normalized_stream: 0,
+            deduped_observation: 0,
+        };
+        for (const row of bySourceRows) {
+            sourceCounts[row.source_path] = parseCount(row.count);
+        }
+        const deliveryCounts = {};
+        for (const row of byDeliveryRows) {
+            deliveryCounts[row.delivery_mode] = parseCount(row.count);
+        }
+        const oldestPendingAt = parseBigInt(oldestPendingRow.oldest);
+        const oldestPendingAgeMs = oldestPendingAt === 0n ? 0n : this.#now() - oldestPendingAt;
+        const earliestRetryAtRaw = parseBigInt(retryWaitingRow.earliest_retry_at);
+        return {
+            totalPendingRows: parseCount(totalPendingRow.count),
+            oldestPendingAgeMs,
+            retryWaitingRows: parseCount(retryWaitingRow.count),
+            earliestRetryAt: earliestRetryAtRaw === 0n ? null : earliestRetryAtRaw,
+            pendingRowsBySourcePath: sourceCounts,
+            pendingRowsByDeliveryMode: deliveryCounts,
+        };
+    }
+    getDatabasePath() {
+        return this.#config.databasePath;
+    }
+    close() {
+        this.#db.close();
+    }
+    #updateReplayRows(rowIds, nextState, retryNotBeforeMs) {
+        if (rowIds.length === 0) {
+            return 0;
+        }
+        const placeholders = rowIds.map(() => "?").join(", ");
+        const result = this.#db
+            .prepare(`UPDATE ingress_events
+         SET replay_state = ?,
+             retry_not_before_ms = ?
+         WHERE rowid IN (${placeholders})`)
+            .run(nextState, retryNotBeforeMs === null || retryNotBeforeMs === undefined
+            ? null
+            : toSqlBigInt(retryNotBeforeMs), ...rowIds);
+        return result.changes;
+    }
+}

package/.build/src/storage/schema.d.ts

@@ -0,0 +1,3 @@
+import Database from "better-sqlite3";
+export declare const MONITOR_SQLITE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS ingress_events (\n  monitor_ingest_seq INTEGER PRIMARY KEY AUTOINCREMENT,\n  id TEXT NOT NULL,\n  monitor_ingest_at_ms INTEGER NOT NULL,\n  source_node_id TEXT NOT NULL,\n  source_stream_id TEXT,\n  source_path TEXT NOT NULL,\n  event_id TEXT NOT NULL,\n  trace_id TEXT,\n  sequence TEXT,\n  logical_time_ms INTEGER NOT NULL,\n  payload_json TEXT NOT NULL,\n  payload_encoding TEXT NOT NULL DEFAULT 'json',\n  delivery_mode TEXT NOT NULL,\n  replay_state TEXT NOT NULL,\n  replay_attempts INTEGER NOT NULL DEFAULT 0,\n  retry_not_before_ms INTEGER,\n  expires_at_ms INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_ingress_events_expires_at\n  ON ingress_events(expires_at_ms);\n\nCREATE INDEX IF NOT EXISTS idx_ingress_events_replay_state\n  ON ingress_events(replay_state);\n\nCREATE INDEX IF NOT EXISTS idx_ingress_events_replay_retry\n  ON ingress_events(replay_state, retry_not_before_ms);\n\nCREATE INDEX IF NOT EXISTS idx_ingress_events_source_path\n  ON ingress_events(source_path);\n\nCREATE TABLE IF NOT EXISTS component_health_log (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  recorded_at_ms INTEGER NOT NULL,\n  component TEXT NOT NULL,\n  health_state TEXT NOT NULL,\n  reason_code TEXT,\n  details_json TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_component_health_log_component_time\n  ON component_health_log(component, recorded_at_ms);\n\nCREATE TABLE IF NOT EXISTS outage_windows (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  started_at_ms INTEGER NOT NULL,\n  ended_at_ms INTEGER,\n  dedupe_state TEXT NOT NULL,\n  causal_order_state TEXT NOT NULL,\n  buffer_mode TEXT NOT NULL,\n  notes_json TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS replay_sessions (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  started_at_ms INTEGER,\n  ended_at_ms INTEGER,\n  target_path TEXT NOT NULL,\n  session_state TEXT NOT NULL,\n  event_count_attempted INTEGER NOT NULL DEFAULT 0,\n  event_count_delivered INTEGER NOT NULL DEFAULT 0,\n  error_count INTEGER NOT NULL DEFAULT 0,\n  details_json TEXT NOT NULL\n);\n";
+export declare function applyMonitorSchema(db: InstanceType<typeof Database>): void;