@secondlayer/sdk 6.48.0 → 6.49.0

package/dist/index.d.ts

@@ -773,12 +773,21 @@ type ConsumerBatchContext<
 > = {
 	/** Checkpoint to commit alongside your rows. */
 	cursor: string | null;
-	/** Highest canonical block the sweep has reached. `null` before the first
-	*  row of a fresh consume. */
+	/** Highest canonical block a row was DELIVERED from. `null` before the
+	*  first row of a fresh consume. With a sparse filter this parks at the
+	*  last matching event — it measures event recency, not progress. */
 	height: number | null;
+	/** Highest canonical block the sweep has VERIFIED through: an empty page
+	*  is the server confirming nothing matches between the cursor and the
+	*  tip, so a caught-up tail scans to the tip even when `height` is far
+	*  below it. Rolls back with reorg rewinds. */
+	scannedHeight: number | null;
 	/** Chain tip as of this page's read. */
 	tipHeight: number;
-	/** `tipHeight - height`, floored at 0. `null` until `height` is known. */
+	/** `tipHeight - scannedHeight`, floored at 0 — the consumer's actual
+	*  backlog. `null` until a position is known. A caught-up consumer on a
+	*  quiet contract reads ~0 here while `tipHeight - height` grows — that
+	*  difference is event age, not lag. */
 	blocksBehind: number | null;
 	/**
 	* The full tip for this page — `StreamsTip` or `IndexTip` depending on the
@@ -3324,7 +3333,10 @@ interface ConsumerHealth {
 * "are we near the tip": during a genesis backfill the loop is millions of
 * blocks behind and perfectly healthy, so lag can't be the signal. A wedged
 * loop stops reporting pages and flips to 503 — that's what platforms
-* should restart on. `blocks_behind` still ships in the body for dashboards.
+* should restart on. The body carries position for dashboards:
+* `blocks_behind` is the actual backlog (`tip - scanned_height`, ~0 for a
+* caught-up tail even on a quiet contract), while `block_height` is the
+* last DELIVERED row — its distance from the tip is event age, not lag.
 */
 declare function consumerHealth(options?: {
 	staleAfterMs?: number;

package/dist/index.js

@@ -597,13 +597,24 @@ function assertSinkModeCompatible(sink, finalizedOnly) {
     throw new ValidationError("This sink declares capabilities.finalizedOnly — it cannot roll back reorged rows, and following the unfinalized tip would corrupt it at the first fork. Pass finalizedOnly: true to consume(), or use a sink that implements rollback.", 400);
   }
 }
-function batchContext(cursor, height, tip, reorgs = []) {
+function resumeHeight(cursor) {
+  if (cursor === null)
+    return null;
+  try {
+    return Cursor.parse(cursor).blockHeight;
+  } catch {
+    return null;
+  }
+}
+function batchContext(cursor, height, tip, reorgs = [], scannedHeight = null) {
   const tipHeight = tip.block_height;
+  const position = scannedHeight ?? height;
   return {
     cursor,
     height,
+    scannedHeight: position,
     tipHeight,
-    blocksBehind: height === null ? null : Math.max(0, tipHeight - height),
+    blocksBehind: position === null ? null : Math.max(0, tipHeight - position),
     tip,
     reorgs
   };
@@ -669,7 +680,8 @@ async function consumeStreamsEvents(opts) {
   const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
-  let height = null;
+  let height = resumeHeight(cursor);
+  let scanned = height;
   while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
     const envelope = await fetchPageWithRetry(() => opts.fetchEvents({
       cursor,
@@ -701,6 +713,7 @@ async function consumeStreamsEvents(opts) {
         }
         cursor = rewind;
         height = forkPoint > 0 ? forkPoint - 1 : null;
+        scanned = height;
         emptyPolls = 0;
         continue;
       }
@@ -708,7 +721,14 @@ async function consumeStreamsEvents(opts) {
     const emitted = finalizedOnly ? envelope.events.filter((event) => event.finalized) : envelope.events;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const ctx = batchContext(checkpoint, height, envelope.tip, envelope.reorgs);
+    if (emitted.length > 0) {
+      scanned = height;
+    } else if (checkpoint !== null && checkpoint !== cursor) {
+      scanned = resumeHeight(checkpoint) ?? scanned;
+    } else if (envelope.events.length === 0) {
+      scanned = envelope.tip.block_height;
+    }
+    const ctx = batchContext(checkpoint ?? cursor, height, envelope.tip, envelope.reorgs, scanned);
     opts.onProgress?.(ctx);
     let nextCursor;
     if (opts.sink) {
@@ -836,7 +856,8 @@ async function consumeIndexFeed(opts) {
   const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
-  let height = null;
+  let height = resumeHeight(cursor);
+  let scanned = height;
   while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
     const envelope = await fetchPageWithRetry(() => opts.fetchPage({
       cursor,
@@ -862,6 +883,7 @@ async function consumeIndexFeed(opts) {
         }
         cursor = rewind;
         height = forkPoint > 0 ? forkPoint - 1 : null;
+        scanned = height;
         emptyPolls = 0;
         continue;
       }
@@ -870,7 +892,14 @@ async function consumeIndexFeed(opts) {
     const emitted = finalizedOnly ? items.filter((item) => item.block_height <= envelope.tip.finalized_height) : items;
     const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
     height = emitted.at(-1)?.block_height ?? height;
-    const ctx = batchContext(checkpoint, height, envelope.tip, envelope.reorgs);
+    if (emitted.length > 0) {
+      scanned = height;
+    } else if (checkpoint !== null && checkpoint !== cursor) {
+      scanned = resumeHeight(checkpoint) ?? scanned;
+    } else {
+      scanned = finalizedOnly ? envelope.tip.finalized_height : envelope.tip.block_height;
+    }
+    const ctx = batchContext(checkpoint ?? cursor, height, envelope.tip, envelope.reorgs, scanned);
     opts.onProgress?.(ctx);
     let nextCursor;
     if (opts.sink) {
@@ -2659,6 +2688,7 @@ function consumerHealth(options = {}) {
         ok,
         checkpoint: lastCtx?.cursor ?? null,
         block_height: lastCtx?.height ?? null,
+        scanned_height: lastCtx?.scannedHeight ?? null,
         tip_height: lastCtx?.tipHeight ?? null,
         blocks_behind: lastCtx?.blocksBehind ?? null,
         idle_s: Math.floor(idleMs / 1000),
@@ -2899,5 +2929,5 @@ export {
   ApiError
 };
 
-//# debugId=AADEB8FAB0EE368C64756E2164756E21
+//# debugId=7E3377791B68431D64756E2164756E21
 //# sourceMappingURL=index.js.map