@ocap/types 1.30.21 → 1.30.22

package/interfaces/ledger.ts

@@ -158,6 +158,42 @@ export interface IMerkleProof {
   root: string;
 }
 
+// ============================================================================
+// 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
 // ============================================================================
@@ -272,6 +308,14 @@ export interface ILedgerStorage {
    */
   hasUnfinalizedInRange(fromSeq: number, toSeq: number): Promise<boolean>;
 
+  /**
+   * 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
   saveCheckpoint(checkpoint: ICheckpoint): Promise<void>;
   getCheckpointByHeight(height: number): Promise<ICheckpoint | null>;
@@ -342,6 +386,9 @@ export interface ILedger {
   getMerkleProof(sequence: number): Promise<IMerkleProof>;
   verifyMerkleProof(proof: IMerkleProof): boolean;
 
+  // Monitoring
+  getHealth(): Promise<ILedgerHealth>;
+
   // Lifecycle
   initialize(): Promise<void>;
   close(): Promise<void>;

package/package.json

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