@causal-order/monitor 0.0.9

package/.build/src/types/snapshots.d.ts

@@ -0,0 +1,63 @@
+import type { MonitorComponent, MonitorDeliveryMode, MonitorHealthState, MonitorReplaySessionState, MonitorReplayTargetPath, MonitorRoutingMode, MonitorSourcePath, MonitorThrottleTier } from "./events.js";
+export interface MonitorComponentHealthSnapshot {
+    component: MonitorComponent;
+    state: MonitorHealthState;
+    observedAt: bigint;
+    lastChangedAt: bigint;
+    reasonCode: string | null;
+    details: Record<string, unknown>;
+}
+export interface ReservoirStats {
+    totalPendingRows: number;
+    oldestPendingAgeMs: bigint;
+    retryWaitingRows: number;
+    earliestRetryAt: bigint | null;
+    pendingRowsBySourcePath: Record<MonitorSourcePath, number>;
+    pendingRowsByDeliveryMode: Partial<Record<MonitorDeliveryMode, number>>;
+}
+export interface ReplaySessionSnapshot {
+    state: MonitorReplaySessionState;
+    targetPath: MonitorReplayTargetPath;
+    queuedEventCount: number;
+    deliveredEventCount: number;
+    startedAt: bigint | null;
+    endedAt: bigint | null;
+    lastError: string | null;
+    nextRetryAt: bigint | null;
+    consecutiveFailureCount: number;
+    recoveryHeartbeatCount: number;
+    requiredRecoveryHeartbeats: number;
+}
+export interface MonitorSnapshot {
+    generatedAt: bigint;
+    routingMode: MonitorRoutingMode;
+    throttleTier: MonitorThrottleTier;
+    components: Record<MonitorComponent, MonitorComponentHealthSnapshot>;
+    reservoir: ReservoirStats;
+    replay: ReplaySessionSnapshot;
+}
+export type MonitorOperationalState = "healthy_live" | "degraded_live" | "buffering_only" | "replay_draining" | "replay_retry_waiting" | "recovery_confirming";
+export interface InspectedMonitorSnapshot {
+    generatedAt: bigint;
+    operationalState: MonitorOperationalState;
+    routingMode: MonitorRoutingMode;
+    throttleTier: MonitorThrottleTier;
+    unhealthyComponents: MonitorComponent[];
+    requiresOperatorAttention: boolean;
+    liveFlowGateClosed: boolean;
+    liveFlowGateReason: string | null;
+    totalPendingRows: number;
+    oldestPendingAgeMs: bigint;
+    replayReadyRows: number;
+    retryWaitingRows: number;
+    earliestRetryAt: bigint | null;
+    replayState: MonitorReplaySessionState;
+    replayBacklogRemainingRows: number;
+    replayProgressPercent: number | null;
+    replayQueuedEventCount: number;
+    replayDeliveredEventCount: number;
+    replayNextRetryAt: bigint | null;
+    replayRetryDelayMs: bigint | null;
+    replayConsecutiveFailureCount: number;
+    replayRetryBackoffActive: boolean;
+}

package/.build/src/types/snapshots.js

@@ -0,0 +1 @@
+export {};

package/.build/src/types.d.ts

@@ -0,0 +1,3 @@
+export { type MonitorComponentHealthConfig, type MonitorConfig, type MonitorHealthConfig, type MonitorReplayConfig, type MonitorReservoirConfig, type MonitorThrottleConfig, type MonitorThrottleTierConfig, type MonitorTransportConfig, } from "./types/config.js";
+export { type MonitorClock, type MonitorComponent, type MonitorDeliveryMode, type MonitorEventPayload, type MonitorHealthState, type MonitorHealthUpdate, type MonitorIngressAction, type MonitorIngressDecision, type MonitorIngressEvent, type MonitorPeerState, type MonitorPeerStateEvent, type MonitorReplaySessionState, type MonitorReplayTargetPath, type MonitorRoutingMode, type MonitorSourcePath, type MonitorThrottleTier, } from "./types/events.js";
+export { type InspectedMonitorSnapshot, type MonitorComponentHealthSnapshot, type MonitorOperationalState, type MonitorSnapshot, type ReplaySessionSnapshot, type ReservoirStats, } from "./types/snapshots.js";

package/.build/src/types.js

@@ -0,0 +1,3 @@
+export {} from "./types/config.js";
+export {} from "./types/events.js";
+export {} from "./types/snapshots.js";

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## v0.0.9
+
+- added `publish:prepare` metadata syncing so the exported package version and README release markers stay aligned with `package.json`
+- moved npm dry-run scripts onto a repo-local cache path and added `prepublishOnly` validation to harden the publish flow
+- expanded `ReservoirStats` so retry-waiting backlog is visible through `retryWaitingRows` and `earliestRetryAt`
+- expanded `inspectMonitorSnapshot()` so replay retry timing, consecutive failure streak, and active backoff state are obvious at a glance
+- verified the richer inspection surface against the existing `test:replay-safety` failure-path run
+- aligned README and roadmap language with the current `v0.0.9` runtime, validation, and operator-inspection boundary
+- enriched `inspectMonitorSnapshot()` with derived operator-facing state instead of only mirroring raw replay and reservoir fields
+- added inspection signals for `operationalState`, live-flow gate status and reason, replay-ready rows, backlog remaining rows, replay progress percentage, retry delay, and operator-attention requirement
+- added `MonitorRuntime.getInspectedSnapshot()` so downstream consumers can read the derived operator summary directly from the runtime
+- added `TransportMonitorAdapter.getInspectedSnapshot()` so adapter users do not need to compose the runtime and inspection helper manually
+- added repo-local `test:inspect-snapshot` coverage to verify the derived inspection summary through buffering and replay-retry states and to prove the direct runtime/adapter inspected snapshot path stays identical to `inspectMonitorSnapshot(getSnapshot())`
+
+## v0.0.8
+
+- hardened replay failure handling with a retry backoff so replay does not immediately thrash back into another attempt when downstream recovery is still unstable
+- kept the replay gate closed while failed backlog is waiting for retry so live flow does not reopen into a mixed backlog state during replay recovery
+- added replay snapshot evidence for `nextRetryAt` and `consecutiveFailureCount` so retry behavior is inspectable in runtime state and persisted replay session records
+- hardened SQLite prune behavior so retry-waiting replay rows survive the rolling buffer window and only dead-letter at the hard retention cutoff
+- added a repo-local `test:replay-safety` script that exercises replay failure, retry backoff, rolling-window prune safety, and hard-cutoff dead-letter behavior end to end
+
+## v0.0.7
+
+- fixed live ingress acknowledgement so events successfully forwarded on the live path are marked delivered in the SQLite reservoir instead of lingering as replay backlog
+- fixed the early replay-entry bug that could push the monitor into `replay_through_dedupe` immediately after startup or healthy forwarding
+- validated the repaired `monitor-order-outage` sequence end to end: healthy live flow, `order_buffer_only` during outage, replay only after recovery, and empty reservoir at completion
+- extended downstream `@causal-order/testing` reporting so monitor-enabled runs now summarize replay posture and compare outage recovery behavior directly
+- aligned the downstream `@causal-order/testing` package metadata to `0.2.5` and updated its published monitor peer range to `@causal-order/monitor@^0.0.7`
+
+## v0.0.6
+
+- extended `@causal-order/testing` integration so monitor is consumed as an optional first-class harness boundary instead of a side path
+- added monitor-aware runtime config, artifact paths, and scenario profiles in the testing harness
+- added dedicated outage choreography for monitor scenarios, including `dedupe` outage, `causal-order` outage, dual outage, and replay-through-recovery transitions
+- validated that the legacy non-monitor testing smoke path still passes with monitor mode disabled
+- ran a real `monitor-order-outage` scenario and used it to uncover and fix bigint serialization issues in monitor artifact and summary writing
+- fixed monitor shutdown ordering during harness finalization so final replay and heartbeat artifacts are written before the monitor closes
+
+## v0.0.5
+
+- added `TransportMonitorAdapter` as the first transport-facing integration seam
+- connected runtime routing decisions to downstream dedupe, direct-order, and buffer-only handlers
+- added replay pumping and recovery reconciliation through the adapter surface
+- added exported monitor harness metadata for `@causal-order/testing`
+- defined the first monitor harness scenario catalog and expected artifacts for ecosystem validation
+- updated README and roadmap status to reflect active implementation rather than scaffold-only status
+
+## v0.0.4
+
+- made replay coordination operational instead of snapshot-only
+- added replay lifecycle control for queue, start, batch claim, acknowledge, fail, and abort
+- enforced replay gating so live flow stays coordinated during backlog drain
+- added post-replay downstream health confirmation before reopening live flow
+- added SQLite replay row lifecycle helpers for pending, replaying, delivered, and dead-letter states
+- fixed bigint-safe SQLite payload serialization for stored and replayed events
+
+## v0.0.3
+
+- implemented the SQLite-backed reservoir with bounded retention behavior
+- added monitor schema bootstrap for ingress events, health logs, outage windows, and replay sessions
+- implemented component health tracking for `transport`, `dedupe`, and `causal-order`
+- implemented routing and throttle decision logic for:
+  - `normal`
+  - `dedupe_bypass_throttled`
+  - `order_buffer_only`
+  - `full_outage_buffer`
+  - `replay_through_dedupe`
+- added runtime ingestion and reservoir statistics APIs
+
+## v0.0.2
+
+- added the first real public runtime contract surface for `@causal-order/monitor`
+- introduced monitor config, event, routing, throttle, health, and snapshot types
+- added `createMonitorRuntime()`, `MonitorRuntime`, and `inspectMonitorSnapshot()`
+- upgraded package metadata for npm publication, including peer dependencies and build outputs
+- added repo-level ignore rules and publication-oriented package hygiene
+
+## v0.0.1
+
+- scaffolded the initial npm package metadata for `@causal-order/monitor`
+- established a minimal TypeScript build surface
+- documented the package as draft while the runtime API is still being designed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gazali Ahmad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @causal-order/monitor
+
+Health-aware buffering, replay, and operator monitoring for the `causal-order` stack.
+
+Status: `v0.0.9` published to npm.
+
+`@causal-order/monitor` sits between transport ingestion and downstream delivery so your pipeline can keep accepting events, preserve backlog, and recover in a controlled way when `@causal-order/dedupe` or `causal-order` becomes unavailable.
+
+## Install
+
+```bash
+npm install @causal-order/monitor better-sqlite3 causal-order @causal-order/dedupe @causal-order/transport
+```
+
+`better-sqlite3` is a direct runtime dependency. `causal-order`, `@causal-order/dedupe`, and `@causal-order/transport` are expected alongside this package as peers.
+
+## What It Does
+
+- buffers ingress events in SQLite so downstream outages do not immediately become data loss
+- tracks health for `transport`, `dedupe`, and `causal-order`
+- switches routing behavior when parts of the stack degrade or go offline
+- replays buffered backlog through `@causal-order/dedupe` after recovery
+- exposes snapshots and derived inspection state for operators and automation
+
+## Stability
+
+This `v0.0.9` release is the published npm package for the current monitor runtime, replay, routing, and operator-inspection surface.
+
+## When To Use It
+
+Use this package when you already have a `causal-order` pipeline and want a monitor layer that can:
+
+- keep ingesting while `causal-order` is offline
+- throttle or bypass parts of the path when `dedupe` is unhealthy
+- coordinate replay after recovery instead of mixing backlog and live flow loosely
+- give operators a compact view of backlog, replay, retry, and health state
+
+## Package Model
+
+The package gives you two main integration styles:
+
+- `createMonitorRuntime()` or `MonitorRuntime` if you want direct control over ingress, health updates, replay, and storage
+- `TransportMonitorAdapter` if you want a higher-level wrapper that calls your delivery handlers and manages replay pumping through that adapter surface
+
+Other exported building blocks include:
+
+- `HealthTracker`
+- `DeliveryRouter`
+- `ThrottleController`
+- `ReplayCoordinator`
+- `SQLiteReservoir`
+- `inspectMonitorSnapshot()`
+
+## Subpath Imports
+
+The package now exposes official subpath entrypoints so consumers can import narrower surfaces instead of always pulling from the root package:
+
+- `@causal-order/monitor/config`
+- `@causal-order/monitor/health`
+- `@causal-order/monitor/inspect`
+- `@causal-order/monitor/replay`
+- `@causal-order/monitor/routing`
+- `@causal-order/monitor/runtime`
+- `@causal-order/monitor/storage`
+- `@causal-order/monitor/throttle`
+- `@causal-order/monitor/transport`
+- `@causal-order/monitor/types`
+
+The most lightweight analyzer-friendly entrypoints are:
+
+- `@causal-order/monitor/config`
+- `@causal-order/monitor/health`
+- `@causal-order/monitor/inspect`
+- `@causal-order/monitor/routing`
+- `@causal-order/monitor/throttle`
+- `@causal-order/monitor/types`
+
+## Quick Start
+
+```ts
+import { TransportMonitorAdapter } from "@causal-order/monitor";
+
+const monitor = new TransportMonitorAdapter(
+  {
+    async deliverToDedupe(event, context) {
+      await sendToDedupe(event, context);
+    },
+    async deliverToOrder(event, context) {
+      await sendToCausalOrder(event, context);
+    },
+    async onBuffered(event, decision, rowId) {
+      console.log("buffered", { rowId, action: decision.action, eventId: event.id });
+    },
+  },
+  {
+    reservoir: {
+      databasePath: "./monitor.sqlite",
+    },
+  },
+);
+
+monitor.observeHeartbeat("transport");
+monitor.observeHeartbeat("dedupe");
+monitor.observeHeartbeat("causal-order");
+
+await monitor.ingest({
+  id: "evt-1001",
+  nodeId: "transport-a",
+  clock: {
+    physicalTimeMs: BigInt(Date.now()),
+  },
+  payload: {
+    entityId: "order-42",
+    operation: "created",
+  },
+});
+
+const snapshot = monitor.getInspectedSnapshot();
+console.log(snapshot.operationalState);
+```
+
+## Runtime Example
+
+If you want lower-level control, use the runtime directly:
+
+```ts
+import { createMonitorRuntime } from "@causal-order/monitor";
+
+const runtime = createMonitorRuntime({
+  reservoir: {
+    databasePath: "./monitor.sqlite",
+  },
+});
+
+runtime.observeHeartbeat("transport");
+runtime.observeHeartbeat("dedupe");
+runtime.observeHeartbeat("causal-order");
+
+const { rowId, decision } = runtime.ingestTransportEvent({
+  id: "evt-1001",
+  nodeId: "transport-a",
+  clock: {
+    physicalTimeMs: BigInt(Date.now()),
+  },
+  payload: {
+    entityId: "order-42",
+    operation: "created",
+  },
+});
+
+if (decision.action === "accept" && decision.deliveryMode === "normal") {
+  await sendToDedupe();
+  runtime.acknowledgeIngressDelivery([rowId]);
+}
+```
+
+## Routing And Recovery Behavior
+
+The monitor can move between a few main operating modes:
+
+- `normal`: live flow goes through dedupe as usual
+- `dedupe_bypass_throttled`: live flow can bypass dedupe with throttling when dedupe is unhealthy
+- `order_buffer_only`: events are buffered while `causal-order` is offline
+- `full_outage_buffer`: events stay buffered during broader outage conditions
+- `replay_through_dedupe`: buffered backlog drains through dedupe during recovery
+
+Recovery is intentionally conservative:
+
+- the rolling SQLite buffer defaults to `4h`
+- the maximum dual-outage retention window defaults to `6h`
+- replay returns through `@causal-order/dedupe`
+- replay failure applies a retry backoff before trying again
+- live flow stays gated while replay recovery is failed or actively draining
+
+## Configuration
+
+`createDefaultMonitorConfig()` returns the full configuration shape. Common settings:
+
+- `reservoir.databasePath`: SQLite path, `":memory:"` by default
+- `reservoir.rollingBufferWindowMs`: normal rolling retention window
+- `reservoir.fullOutageMaxWindowMs`: hard retention ceiling during deeper outages
+- `transport.heartbeatGraceMs`: heartbeat grace period before transport is considered stale
+- `health.*.degradedAfterMs` and `health.*.offlineAfterMs`: thresholds for each component
+- `throttle.*`: ingress limits for each throttle tier
+- `replay.healthConfirmationHeartbeats`: heartbeats required before replay resumes
+- `replay.pauseLiveFlowDuringReplay`: whether live flow stays gated during drain
+- `replay.retryBackoffMs`: delay before retrying a failed replay attempt
+
+## Inspection And Operator State
+
+For raw state, use:
+
+- `getSnapshot()`
+- `getReplaySnapshot()`
+- `getReservoirStats()`
+
+For operator-facing state, use:
+
+- `getInspectedSnapshot()`
+- `inspectMonitorSnapshot(snapshot)`
+
+The inspected snapshot is the easiest entry point when you want a quick read on:
+
+- current operational posture
+- whether live flow is gated
+- whether replay is ready or retry-waiting
+- backlog size and replay progress
+- whether operator attention is needed
+
+## Public Types
+
+Key exported types include:
+
+- `MonitorConfig`
+- `MonitorIngressEvent`
+- `MonitorIngressDecision`
+- `MonitorSnapshot`
+- `ReplaySessionSnapshot`
+- `ReservoirStats`
+- `InspectedMonitorSnapshot`
+
+## Version `v0.0.9`
+
+The current package line includes:
+
+- operational runtime, routing, health tracking, SQLite buffering, and replay coordination
+- retry-aware replay backoff with persisted retry horizon and failure streak visibility
+- retry-safe pruning so waiting rows survive the rolling buffer until the hard cutoff
+- derived inspection output for replay posture, backlog, gating, and operator attention
+- direct inspected snapshot access from both `MonitorRuntime` and `TransportMonitorAdapter`
+
+## Node Support
+
+- Node.js `>=20`
+- ESM package output
+
+## Validation
+
+This package is validated in-repo with:
+
+- `npm run check`
+- `npm run test:inspect-snapshot`
+- `npm run test:replay-safety`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@causal-order/monitor",
+  "version": "0.0.9",
+  "description": "Health-aware buffering, replay, and operator monitoring layer for the causal-order stack.",
+  "author": "Gazali Ahmad",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GazaliAhmad/causal-order-monitor.git"
+  },
+  "homepage": "https://github.com/GazaliAhmad/causal-order-monitor#readme",
+  "bugs": {
+    "url": "https://github.com/GazaliAhmad/causal-order-monitor/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./.build/src/index.js",
+  "module": "./.build/src/index.js",
+  "types": "./.build/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./.build/src/index.d.ts",
+      "import": "./.build/src/index.js"
+    },
+    "./config": {
+      "types": "./.build/src/config.d.ts",
+      "import": "./.build/src/config.js"
+    },
+    "./health": {
+      "types": "./.build/src/health.d.ts",
+      "import": "./.build/src/health.js"
+    },
+    "./inspect": {
+      "types": "./.build/src/inspect.d.ts",
+      "import": "./.build/src/inspect.js"
+    },
+    "./replay": {
+      "types": "./.build/src/replay.d.ts",
+      "import": "./.build/src/replay.js"
+    },
+    "./routing": {
+      "types": "./.build/src/routing.d.ts",
+      "import": "./.build/src/routing.js"
+    },
+    "./runtime": {
+      "types": "./.build/src/runtime.d.ts",
+      "import": "./.build/src/runtime.js"
+    },
+    "./storage": {
+      "types": "./.build/src/storage.d.ts",
+      "import": "./.build/src/storage.js"
+    },
+    "./throttle": {
+      "types": "./.build/src/throttle.d.ts",
+      "import": "./.build/src/throttle.js"
+    },
+    "./transport": {
+      "types": "./.build/src/transport.d.ts",
+      "import": "./.build/src/transport.js"
+    },
+    "./types": {
+      "types": "./.build/src/types.d.ts",
+      "import": "./.build/src/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    ".build/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "causal-order",
+    "event-ordering",
+    "esm",
+    "monitor",
+    "health-monitoring",
+    "sqlite",
+    "sqlite3",
+    "buffering",
+    "backpressure",
+    "replay",
+    "outage-recovery",
+    "failover",
+    "recovery",
+    "resilience",
+    "observability",
+    "event-replay",
+    "event-streams",
+    "distributed-systems",
+    "stream-processing",
+    "message-processing"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "ci": "npm run check && npm run test:inspect-snapshot && npm run test:replay-safety && npm run pack:check",
+    "prepack": "npm run publish:prepare && npm run build",
+    "prepublishOnly": "npm run ci",
+    "pack:check": "npm pack --dry-run --cache ./.local/npm-cache",
+    "publish:dry-run": "npm publish --dry-run --access public --cache ./.local/npm-cache",
+    "publish:prepare": "node scripts/prepare-publish.mjs",
+    "publish:prepare:check": "node scripts/prepare-publish.mjs --check",
+    "release:check": "npm run ci && npm run publish:dry-run",
+    "test:inspect-snapshot": "npm run build && node scripts/inspect-snapshot.mjs",
+    "test:replay-safety": "npm run build && node scripts/replay-safety.mjs"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.4.1"
+  },
+  "peerDependencies": {
+    "@causal-order/dedupe": "^1.1.1",
+    "@causal-order/transport": "^0.1.2",
+    "causal-order": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
+  }
+}