@ocap/types - npm Package Compare versions

Comparing version 1.30.21 to 1.30.22

interfaces/ledger.ts

@@ -162,2 +162,38 @@ // core/types/interfaces/ledger.ts
 // ============================================================================
+// Health Metrics
+// ============================================================================
+
+/**
+ * Ledger health snapshot used by /ledger-health monitoring endpoint.
+ *
+ * Designed to surface the "stuck checkpoint" failure mode (see ledger.ts
+ * createCheckpointIfNeeded): if any entry in the pending range stays
+ * finalized=0, createCheckpoint is permanently skipped and lag grows
+ * unbounded.
+ */
+export interface ILedgerHealth {
+  /** Latest entry sequence in the ledger */
+  latestSequence: number;
+
+  /** Latest checkpoint (null if none created yet) */
+  latestCheckpoint: {
+    height: number;
+    sequence: number;
+    timestamp: number;
+  } | null;
+
+  /** latestSequence - latestCheckpoint.sequence (0 if no checkpoint) */
+  checkpointLag: number;
+
+  /** ms since latest checkpoint.timestamp (null if no checkpoint) */
+  checkpointAgeMs: number | null;
+
+  /** Count of entries with finalized=0 in the pending range (after latest checkpoint) */
+  unfinalizedCount: number;
+
+  /** Timestamp (ms) of oldest unfinalized entry in pending range, null if none */
+  oldestUnfinalizedTimestamp: number | null;
+}
+
+// ============================================================================
 // Configuration Types
@@ -276,2 +312,10 @@ // ============================================================================
 
+  /**
+   * Count unfinalized entries and find oldest timestamp in range.
+   * Used by the health endpoint to detect stuck checkpoints.
+   *
+   * @returns count and oldest timestamp (null if count=0)
+   */
+  getUnfinalizedStats(fromSeq: number, toSeq: number): Promise<{ count: number; oldestTimestamp: number | null }>;
+
   // Checkpoint operations
@@ -347,2 +391,5 @@ saveCheckpoint(checkpoint: ICheckpoint): Promise<void>;
 
+  // Monitoring
+  getHealth(): Promise<ILedgerHealth>;
+
   // Lifecycle
@@ -349,0 +396,0 @@ initialize(): Promise<void>;

package.json

 {
   "name": "@ocap/types",
-  "version": "1.30.21",
+  "version": "1.30.22",
   "description": "Typescript definitions generated from protobuf",
@@ -5,0 +5,0 @@ "keywords": [

No alert changes

Improved metrics

Total package byte prevSize

160592

0.99%

Lines of code

5367

0.71%

No dependency changes