envio 3.3.0-rc.0 → 3.3.1-rc.0

package/src/CrossChainState.res

@@ -28,15 +28,13 @@ let make = (
   ~isRealtime,
   ~targetBufferSize=calculateTargetBufferSize(),
 ): t => {
-  let crossChainState = {
+  {
     chainStates,
     chainIds: chainStates->Dict.valuesToArray->Array.map(cs => (cs->ChainState.chainConfig).id),
     isRealtime,
     isInReorgThreshold,
     targetBufferSize,
   }
-  Prometheus.IndexingTargetBufferSize.set(~targetBufferSize)
-  crossChainState
 }
 
 // Resolve a chain's state by id. The id always comes from `chainIds`, which is
@@ -49,6 +47,7 @@ let getChainState = (crossChainState: t, chainId) =>
 let chainStates = (crossChainState: t) => crossChainState.chainStates
 let isRealtime = (crossChainState: t) => crossChainState.isRealtime
 let isInReorgThreshold = (crossChainState: t) => crossChainState.isInReorgThreshold
+let targetBufferSize = (crossChainState: t) => crossChainState.targetBufferSize
 
 // Ready-to-process items across every chain — the live draw against
 // targetBufferSize, which is a budget of processable events (items stuck behind
@@ -120,7 +119,6 @@ let createBatch = (
 // blockLag and flip the flag.
 let enterReorgThreshold = (crossChainState: t) => {
   Logging.info("Reorg threshold reached")
-  Prometheus.ReorgThreshold.set(~isInReorgThreshold=true)
 
   for i in 0 to crossChainState.chainIds->Array.length - 1 {
     crossChainState
@@ -160,10 +158,6 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
     }
   }
 
-  if allChainsReady.contents {
-    Prometheus.ProgressReady.setAllReady()
-  }
-
   crossChainState.isRealtime = crossChainState.isRealtime || allChainsReady.contents
 }
 
@@ -307,11 +301,11 @@ let checkAndFetch = async (
         (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
         cs->ChainState.pendingBudget
       let maxTargetBlock = switch alignment {
-      // 5% margin past the anchor's line: chains whose progress tracks the
+      // 10% margin past the anchor's line: chains whose progress tracks the
       // anchor closely would otherwise flap in and out of the clamp on every
       // small frontier move, stalling their pipeline every other tick.
       | Some((anchorChainId, progress)) if anchorChainId !== chainId =>
-        Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.05))
+        Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.1))
       | _ => None
       }
       switch cs->ChainState.getNextQuery(

package/src/CrossChainState.res.mjs

@@ -7,7 +7,6 @@ import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
 import * as FetchState from "./FetchState.res.mjs";
-import * as Prometheus from "./Prometheus.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
@@ -26,15 +25,13 @@ function make(chainStates, isInReorgThreshold, isRealtime, targetBufferSizeOpt)
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : (
       Env.targetBufferSize !== undefined ? Env.targetBufferSize : 100000
     );
-  let crossChainState = {
+  return {
     chainStates: chainStates,
     chainIds: Object.values(chainStates).map(cs => ChainState.chainConfig(cs).id),
     isRealtime: isRealtime,
     isInReorgThreshold: isInReorgThreshold,
     targetBufferSize: targetBufferSize
   };
-  Prometheus.IndexingTargetBufferSize.set(targetBufferSize);
-  return crossChainState;
 }
 
 function chainStates(crossChainState) {
@@ -49,6 +46,10 @@ function isInReorgThreshold(crossChainState) {
   return crossChainState.isInReorgThreshold;
 }
 
+function targetBufferSize(crossChainState) {
+  return crossChainState.targetBufferSize;
+}
+
 function totalReadyCount(crossChainState) {
   let total = 0;
   for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
@@ -89,7 +90,6 @@ function createBatch(crossChainState, processedCheckpointId, batchSizeTarget, is
 
 function enterReorgThreshold(crossChainState) {
   Logging.info("Reorg threshold reached");
-  Prometheus.ReorgThreshold.set(true);
   for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
     ChainState.enterReorgThreshold(crossChainState.chainStates[crossChainState.chainIds[i]]);
   }
@@ -117,9 +117,6 @@ function applyBatchProgress(crossChainState, batch, blockTimestampName) {
       allChainsReady = false;
     }
   }
-  if (allChainsReady) {
-    Prometheus.ProgressReady.setAllReady();
-  }
   crossChainState.isRealtime = crossChainState.isRealtime || allChainsReady;
 }
 
@@ -172,7 +169,7 @@ async function checkAndFetch(crossChainState, dispatchChain) {
     let chainTargetItems = (
       isCold ? Primitive_float.min(remaining.contents, minimumAdmissionBudget) : remaining.contents
     ) + ChainState.pendingBudget(cs);
-    let maxTargetBlock = alignment !== undefined && alignment[0] !== chainId ? ChainState.blockAtProgress(cs, alignment[1] + 0.05) : undefined;
+    let maxTargetBlock = alignment !== undefined && alignment[0] !== chainId ? ChainState.blockAtProgress(cs, alignment[1] + 0.1) : undefined;
     let action = ChainState.getNextQuery(cs, chainTargetItems, chunkItemsMultiplier, itemsTargetFloor, maxTargetBlock);
     if (typeof action !== "object") {
       if (action === "WaitingForNewBlock") {
@@ -230,6 +227,7 @@ export {
   chainStates,
   isRealtime,
   isInReorgThreshold,
+  targetBufferSize,
   nextItemIsNone,
   getSafeCheckpointId,
   createBatch,

package/src/CrossChainState.resi

@@ -16,6 +16,7 @@ let make: (
 let chainStates: t => dict<ChainState.t>
 let isRealtime: t => bool
 let isInReorgThreshold: t => bool
+let targetBufferSize: t => int
 
 // Derived (pure).
 let nextItemIsNone: t => bool

package/src/EffectState.res

@@ -1,6 +1,7 @@
-// Owns all per-(effect, scope) runtime state and its lifecycle. The two maps
-// have different rollback semantics, so keeping them together behind an explicit
-// `resetForRollback` makes the invariant enforced rather than remembered.
+// Owns all per-(effect, scope) runtime state and its lifecycle. A single store
+// of tables holds the cache alongside the counters and rate-limit window that
+// must outlive a rollback; `resetForRollback` clears only the cache in place so
+// that survival is structural rather than remembered.
 
 // Per-scope rate-limit window and queue. A chain-scoped effect gets one of
 // these per chain, so each chain's throughput is independent.
@@ -9,10 +10,32 @@ type effectRateLimitState = {
   durationMs: int,
   mutable availableCalls: int,
   mutable windowStartTime: float,
-  mutable queueCount: int,
   mutable nextWindowPromise: option<promise<unit>>,
 }
 
+// Per-(effect, scope) counters rendered into the envio_effect_* metrics. Live
+// on the cache table and survive a rollback because the table does, keeping the
+// prometheus counters monotonic across a reorg.
+type effectStats = {
+  effectName: string,
+  scope: Internal.chainScope,
+  // Wall-clock time with at least one call in flight.
+  mutable callSeconds: float,
+  // Cumulative per-call time; exceeds callSeconds under parallel execution.
+  mutable callSecondsTotal: float,
+  mutable callCount: float,
+  mutable activeCallsCount: int,
+  mutable prevCallStartTimerRef: Performance.timeRef,
+  mutable queueCount: int,
+  mutable queueWaitSeconds: float,
+  mutable invalidationsCount: float,
+  // Number of persisted cache rows; seeded from the db on restart. hasCache
+  // marks that the effect persists at all, so an empty table still gets a
+  // zero-valued gauge sample.
+  mutable cacheCount: int,
+  mutable hasCache: bool,
+}
+
 type effectCacheInMemTable = {
   // Cache keys whose handler output is persisted on the next write. Drained
   // each write; eviction is driven by the per-entry checkpointId instead.
@@ -30,52 +53,162 @@ type effectCacheInMemTable = {
   scope: Internal.chainScope,
   table: Table.table,
   rateLimitState: option<effectRateLimitState>,
-  // Per-scope active-call bookkeeping, surfaced through the Effect metrics.
-  mutable activeCallsCount: int,
-  mutable prevCallStartTimerRef: Performance.timeRef,
+  stats: effectStats,
+}
+
+// Cache-row count loaded from the db on restart for an effect whose in-mem
+// table hasn't been created yet this session, keyed by cache table name. Enough
+// to render envio_effect_cache until the effect runs; consumed (and removed) at
+// table creation so the table becomes the sole owner.
+type unregisteredCacheCount = {
+  effectName: string,
+  scope: Internal.chainScope,
+  count: int,
 }
 
 type t = {
-  // Cache tables keyed by cache table name. Dropped on rollback — the cache
-  // is re-derivable from the db.
-  mutable tables: dict<effectCacheInMemTable>,
-  // Rate-limit windows keyed by the same name. Survive rollback: rate limiting
-  // reflects real API throughput, not indexing progress, so a reorg must not
-  // refill an effect's budget.
-  rateLimits: dict<effectRateLimitState>,
+  // The single per-(effect, scope) store. Cache-derived fields are cleared on
+  // rollback; stats and the rate-limit window survive because the table does.
+  tables: dict<effectCacheInMemTable>,
+  unregisteredCacheCounts: dict<unregisteredCacheCount>,
 }
 
-let make = (): t => {tables: Dict.make(), rateLimits: Dict.make()}
-
-let getRateLimitState = (self: t, ~tableName, ~effect: Internal.effect) =>
-  switch effect.rateLimit {
-  | None => None
-  | Some({callsPerDuration, durationMs}) =>
-    Some(
-      switch self.rateLimits->Utils.Dict.dangerouslyGetNonOption(tableName) {
-      | Some(existing) => existing
-      | None =>
-        let created: effectRateLimitState = {
-          callsPerDuration,
-          durationMs,
-          availableCalls: callsPerDuration,
-          windowStartTime: Date.now(),
-          queueCount: 0,
-          nextWindowPromise: None,
-        }
-        self.rateLimits->Dict.set(tableName, created)
-        created
-      },
-    )
+let make = (): t => {tables: Dict.make(), unregisteredCacheCounts: Dict.make()}
+
+let setUnregisteredCacheCount = (self: t, ~effectName, ~scope, ~count) => {
+  let tableName = Internal.EffectCache.toTableName(~effectName, ~scope)
+  self.unregisteredCacheCounts->Dict.set(tableName, {effectName, scope, count})
+}
+
+// --- Metric mutations. The stats records are opaque outside this module, so
+// every counter change goes through these. ---
+
+// Track a call starting at timerRef: bump the active count and extend the
+// wall-clock callSeconds, which counts overlapping calls once.
+let startCall = (stats: effectStats, ~timerRef) => {
+  let hadActiveCalls = stats.activeCallsCount > 0
+  stats.activeCallsCount = stats.activeCallsCount + 1
+  if hadActiveCalls {
+    let elapsed = Performance.secondsBetween(~from=stats.prevCallStartTimerRef, ~to=timerRef)
+    if elapsed > 0. {
+      stats.callSeconds = stats.callSeconds +. elapsed
+    }
   }
+  stats.prevCallStartTimerRef = timerRef
+}
+
+// Finish a call started at startTimerRef: close the wall-clock interval and
+// record the call's own cumulative duration.
+let endCall = (stats: effectStats, ~startTimerRef) => {
+  stats.activeCallsCount = stats.activeCallsCount - 1
+  let newTimer = Performance.now()
+  stats.callSeconds =
+    stats.callSeconds +. Performance.secondsBetween(~from=stats.prevCallStartTimerRef, ~to=newTimer)
+  stats.prevCallStartTimerRef = newTimer
+
+  stats.callCount = stats.callCount +. 1.
+  stats.callSecondsTotal = stats.callSecondsTotal +. startTimerRef->Performance.secondsSince
+}
 
-// Get, or lazily create, the in-mem table for an (effect, scope). A recreated
-// table (e.g. after a rollback) reuses the surviving rate-limit window.
+let queueEnqueued = (stats: effectStats, ~count) => stats.queueCount = stats.queueCount + count
+
+let queueDequeued = (stats: effectStats, ~count) => stats.queueCount = stats.queueCount - count
+
+let addQueueWaitSeconds = (stats: effectStats, ~seconds) =>
+  stats.queueWaitSeconds = stats.queueWaitSeconds +. seconds
+
+// Bumps both the per-write invalidation count (consumed by the cache
+// persistence math) and the monotonic metric counter.
+let recordInvalidation = (inMemTable: effectCacheInMemTable) => {
+  inMemTable.invalidationsCount = inMemTable.invalidationsCount + 1
+  inMemTable.stats.invalidationsCount = inMemTable.stats.invalidationsCount +. 1.
+}
+
+let commitCacheCount = (inMemTable: effectCacheInMemTable, ~count) => {
+  inMemTable.stats.cacheCount = count
+  inMemTable.stats.hasCache = true
+}
+
+let statsToMetrics = (stats: effectStats): Metrics.effectMetrics => {
+  Metrics.effect: stats.effectName,
+  scope: stats.scope->Internal.EffectCache.scopeToString,
+  callSeconds: stats.callSeconds,
+  callSecondsTotal: stats.callSecondsTotal,
+  callCount: stats.callCount,
+  activeCallsCount: stats.activeCallsCount,
+  queueCount: stats.queueCount,
+  queueWaitSeconds: stats.queueWaitSeconds,
+  invalidationsCount: stats.invalidationsCount,
+  cacheCount: stats.hasCache ? Some(stats.cacheCount) : None,
+}
+
+// Full per-effect metrics for every live table, plus a cache-only entry for
+// each effect that hasn't run this session (envio_effect_cache only). Such an
+// entry is removed once its table is created, so the two never double-count the
+// same effect.
+let toMetrics = (self: t): array<Metrics.effectMetrics> => {
+  let metrics = self.tables->Utils.Dict.mapValuesToArray(t => t.stats->statsToMetrics)
+  self.unregisteredCacheCounts->Utils.Dict.forEach(({effectName, scope, count}) => {
+    metrics
+    ->Array.push({
+      Metrics.effect: effectName,
+      scope: scope->Internal.EffectCache.scopeToString,
+      callSeconds: 0.,
+      callSecondsTotal: 0.,
+      callCount: 0.,
+      activeCallsCount: 0,
+      queueCount: 0,
+      queueWaitSeconds: 0.,
+      invalidationsCount: 0.,
+      cacheCount: Some(count),
+    })
+    ->ignore
+  })
+  metrics
+}
+
+// Get, or lazily create, the in-mem table for an (effect, scope). On first
+// creation the rate-limit window is built from the effect config and any
+// matching unregistered cache count is consumed. A table recreated after a
+// rollback keeps its surviving stats and rate-limit window because the table
+// object itself survives — only its cache is cleared.
 let getTable = (self: t, ~effect: Internal.effect, ~scope: Internal.chainScope) => {
   let tableName = Internal.EffectCache.toTableName(~effectName=effect.name, ~scope)
   switch self.tables->Utils.Dict.dangerouslyGetNonOption(tableName) {
   | Some(inMemTable) => inMemTable
   | None =>
+    let stats: effectStats = {
+      effectName: effect.name,
+      scope,
+      callSeconds: 0.,
+      callSecondsTotal: 0.,
+      callCount: 0.,
+      activeCallsCount: 0,
+      prevCallStartTimerRef: %raw(`null`),
+      queueCount: 0,
+      queueWaitSeconds: 0.,
+      invalidationsCount: 0.,
+      cacheCount: 0,
+      hasCache: false,
+    }
+    switch self.unregisteredCacheCounts->Utils.Dict.dangerouslyGetNonOption(tableName) {
+    | Some({count}) =>
+      stats.cacheCount = count
+      stats.hasCache = true
+      self.unregisteredCacheCounts->Utils.Dict.deleteInPlace(tableName)
+    | None => ()
+    }
+    let rateLimitState = switch effect.rateLimit {
+    | None => None
+    | Some({callsPerDuration, durationMs}) =>
+      Some({
+        callsPerDuration,
+        durationMs,
+        availableCalls: callsPerDuration,
+        windowStartTime: Date.now(),
+        nextWindowPromise: None,
+      })
+    }
     let inMemTable: effectCacheInMemTable = {
       idsToStore: [],
       dict: Dict.make(),
@@ -84,9 +217,8 @@ let getTable = (self: t, ~effect: Internal.effect, ~scope: Internal.chainScope)
       effect,
       scope,
       table: Internal.makeCacheTable(~effectName=effect.name, ~scope),
-      rateLimitState: self->getRateLimitState(~tableName, ~effect),
-      activeCallsCount: 0,
-      prevCallStartTimerRef: %raw(`null`),
+      rateLimitState,
+      stats,
     }
     self.tables->Dict.set(tableName, inMemTable)
     inMemTable
@@ -95,6 +227,13 @@ let getTable = (self: t, ~effect: Internal.effect, ~scope: Internal.chainScope)
 
 let forEach = (self: t, fn) => self.tables->Utils.Dict.forEach(fn)
 
-// Drop the cache tables (re-derivable from the db) but keep the rate-limit
-// windows so a reorg doesn't hand an effect a fresh budget.
-let resetForRollback = (self: t) => self.tables = Dict.make()
+// Clear the cache-derived fields on every table in place. The cache is
+// re-derivable from the db, but stats and the rate-limit window must survive a
+// reorg — so the table object (their owner) is kept and only its cache reset.
+let resetForRollback = (self: t) =>
+  self.tables->Utils.Dict.forEach(t => {
+    t.dict = Dict.make()
+    t.idsToStore = []
+    t.changesCount = 0.
+    t.invalidationsCount = 0
+  })

package/src/EffectState.res.mjs

@@ -2,37 +2,98 @@
 
 import * as Utils from "./Utils.res.mjs";
 import * as Internal from "./Internal.res.mjs";
+import * as Performance from "./bindings/Performance.res.mjs";
 
 function make() {
   return {
     tables: {},
-    rateLimits: {}
+    unregisteredCacheCounts: {}
   };
 }
 
-function getRateLimitState(self, tableName, effect) {
-  let match = effect.rateLimit;
-  if (match === undefined) {
-    return;
+function setUnregisteredCacheCount(self, effectName, scope, count) {
+  let tableName = Internal.EffectCache.toTableName(effectName, scope);
+  self.unregisteredCacheCounts[tableName] = {
+    effectName: effectName,
+    scope: scope,
+    count: count
+  };
+}
+
+function startCall(stats, timerRef) {
+  let hadActiveCalls = stats.activeCallsCount > 0;
+  stats.activeCallsCount = stats.activeCallsCount + 1 | 0;
+  if (hadActiveCalls) {
+    let elapsed = Performance.secondsBetween(stats.prevCallStartTimerRef, timerRef);
+    if (elapsed > 0) {
+      stats.callSeconds = stats.callSeconds + elapsed;
+    }
   }
-  let callsPerDuration = match.callsPerDuration;
-  let existing = self.rateLimits[tableName];
-  let tmp;
-  if (existing !== undefined) {
-    tmp = existing;
-  } else {
-    let created = {
-      callsPerDuration: callsPerDuration,
-      durationMs: match.durationMs,
-      availableCalls: callsPerDuration,
-      windowStartTime: Date.now(),
-      queueCount: 0,
-      nextWindowPromise: undefined
+  stats.prevCallStartTimerRef = timerRef;
+}
+
+function endCall(stats, startTimerRef) {
+  stats.activeCallsCount = stats.activeCallsCount - 1 | 0;
+  let newTimer = Performance.now();
+  stats.callSeconds = stats.callSeconds + Performance.secondsBetween(stats.prevCallStartTimerRef, newTimer);
+  stats.prevCallStartTimerRef = newTimer;
+  stats.callCount = stats.callCount + 1;
+  stats.callSecondsTotal = stats.callSecondsTotal + Performance.secondsSince(startTimerRef);
+}
+
+function queueEnqueued(stats, count) {
+  stats.queueCount = stats.queueCount + count | 0;
+}
+
+function queueDequeued(stats, count) {
+  stats.queueCount = stats.queueCount - count | 0;
+}
+
+function addQueueWaitSeconds(stats, seconds) {
+  stats.queueWaitSeconds = stats.queueWaitSeconds + seconds;
+}
+
+function recordInvalidation(inMemTable) {
+  inMemTable.invalidationsCount = inMemTable.invalidationsCount + 1 | 0;
+  inMemTable.stats.invalidationsCount = inMemTable.stats.invalidationsCount + 1;
+}
+
+function commitCacheCount(inMemTable, count) {
+  inMemTable.stats.cacheCount = count;
+  inMemTable.stats.hasCache = true;
+}
+
+function toMetrics(self) {
+  let metrics = Utils.Dict.mapValuesToArray(self.tables, t => {
+    let stats = t.stats;
+    return {
+      effect: stats.effectName,
+      scope: Internal.EffectCache.scopeToString(stats.scope),
+      callSeconds: stats.callSeconds,
+      callSecondsTotal: stats.callSecondsTotal,
+      callCount: stats.callCount,
+      activeCallsCount: stats.activeCallsCount,
+      queueCount: stats.queueCount,
+      queueWaitSeconds: stats.queueWaitSeconds,
+      invalidationsCount: stats.invalidationsCount,
+      cacheCount: stats.hasCache ? stats.cacheCount : undefined
     };
-    self.rateLimits[tableName] = created;
-    tmp = created;
-  }
-  return tmp;
+  });
+  Utils.Dict.forEach(self.unregisteredCacheCounts, param => {
+    metrics.push({
+      effect: param.effectName,
+      scope: Internal.EffectCache.scopeToString(param.scope),
+      callSeconds: 0,
+      callSecondsTotal: 0,
+      callCount: 0,
+      activeCallsCount: 0,
+      queueCount: 0,
+      queueWaitSeconds: 0,
+      invalidationsCount: 0,
+      cacheCount: param.count
+    });
+  });
+  return metrics;
 }
 
 function getTable(self, effect, scope) {
@@ -41,6 +102,40 @@ function getTable(self, effect, scope) {
   if (inMemTable !== undefined) {
     return inMemTable;
   }
+  let stats = {
+    effectName: effect.name,
+    scope: scope,
+    callSeconds: 0,
+    callSecondsTotal: 0,
+    callCount: 0,
+    activeCallsCount: 0,
+    prevCallStartTimerRef: null,
+    queueCount: 0,
+    queueWaitSeconds: 0,
+    invalidationsCount: 0,
+    cacheCount: 0,
+    hasCache: false
+  };
+  let match = self.unregisteredCacheCounts[tableName];
+  if (match !== undefined) {
+    stats.cacheCount = match.count;
+    stats.hasCache = true;
+    Utils.Dict.deleteInPlace(self.unregisteredCacheCounts, tableName);
+  }
+  let match$1 = effect.rateLimit;
+  let rateLimitState;
+  if (match$1 !== undefined) {
+    let callsPerDuration = match$1.callsPerDuration;
+    rateLimitState = {
+      callsPerDuration: callsPerDuration,
+      durationMs: match$1.durationMs,
+      availableCalls: callsPerDuration,
+      windowStartTime: Date.now(),
+      nextWindowPromise: undefined
+    };
+  } else {
+    rateLimitState = undefined;
+  }
   let inMemTable$1 = {
     idsToStore: [],
     invalidationsCount: 0,
@@ -49,9 +144,8 @@ function getTable(self, effect, scope) {
     effect: effect,
     scope: scope,
     table: Internal.makeCacheTable(effect.name, scope),
-    rateLimitState: getRateLimitState(self, tableName, effect),
-    activeCallsCount: 0,
-    prevCallStartTimerRef: null
+    rateLimitState: rateLimitState,
+    stats: stats
   };
   self.tables[tableName] = inMemTable$1;
   return inMemTable$1;
@@ -62,7 +156,12 @@ function forEach(self, fn) {
 }
 
 function resetForRollback(self) {
-  self.tables = {};
+  Utils.Dict.forEach(self.tables, t => {
+    t.dict = {};
+    t.idsToStore = [];
+    t.changesCount = 0;
+    t.invalidationsCount = 0;
+  });
 }
 
 export {
@@ -70,5 +169,14 @@ export {
   getTable,
   forEach,
   resetForRollback,
+  startCall,
+  endCall,
+  queueEnqueued,
+  queueDequeued,
+  addQueueWaitSeconds,
+  recordInvalidation,
+  commitCacheCount,
+  setUnregisteredCacheCount,
+  toMetrics,
 }
 /* Utils Not a pure module */

package/src/EffectState.resi

@@ -3,10 +3,14 @@ type effectRateLimitState = {
   durationMs: int,
   mutable availableCalls: int,
   mutable windowStartTime: float,
-  mutable queueCount: int,
   mutable nextWindowPromise: option<promise<unit>>,
 }
 
+// Per-(effect, scope) metric counters. Survive rollback so they stay monotonic.
+// Opaque: mutation goes through the metric operations below, reads through
+// toMetrics.
+type effectStats
+
 type effectCacheInMemTable = {
   mutable idsToStore: array<string>,
   mutable invalidationsCount: int,
@@ -16,8 +20,7 @@ type effectCacheInMemTable = {
   scope: Internal.chainScope,
   table: Table.table,
   rateLimitState: option<effectRateLimitState>,
-  mutable activeCallsCount: int,
-  mutable prevCallStartTimerRef: Performance.timeRef,
+  stats: effectStats,
 }
 
 // Opaque store of all per-(effect, scope) runtime state.
@@ -30,3 +33,23 @@ let getTable: (t, ~effect: Internal.effect, ~scope: Internal.chainScope) => effe
 let forEach: (t, effectCacheInMemTable => unit) => unit
 // Drop the cache tables but keep the rate-limit windows across a rollback.
 let resetForRollback: t => unit
+
+let startCall: (effectStats, ~timerRef: Performance.timeRef) => unit
+let endCall: (effectStats, ~startTimerRef: Performance.timeRef) => unit
+let queueEnqueued: (effectStats, ~count: int) => unit
+let queueDequeued: (effectStats, ~count: int) => unit
+let addQueueWaitSeconds: (effectStats, ~seconds: float) => unit
+// Bumps both the per-write invalidation count (consumed by the cache
+// persistence math) and the monotonic metric counter.
+let recordInvalidation: effectCacheInMemTable => unit
+let commitCacheCount: (effectCacheInMemTable, ~count: int) => unit
+// Record the db cache-row count for an effect not yet created in memory this
+// session (loaded on restart). Consumed when the effect's table is created.
+let setUnregisteredCacheCount: (
+  t,
+  ~effectName: string,
+  ~scope: Internal.chainScope,
+  ~count: int,
+) => unit
+
+let toMetrics: t => array<Metrics.effectMetrics>