envio 3.3.0-alpha.12 → 3.3.0-alpha.13

package/index.d.ts

@@ -48,6 +48,13 @@ export type EffectCaller = <I, O>(
   input: I extends undefined ? undefined : I
 ) => Promise<O>;
 
+/** The chain an Effect was called on. Available only on chain-scoped effects
+ * (`crossChain: false`). */
+export type EffectChain = {
+  /** The chain id the effect handler was called on. */
+  readonly id: number;
+};
+
 /** Context passed to an Effect's handler function. */
 export type EffectContext = {
   /** Access the logger instance with the event as context. */
@@ -57,6 +64,9 @@ export type EffectContext = {
   /** Whether to cache this call's result. Defaults to the effect's `cache`
    * option; set to `false` to skip caching for this specific invocation. */
   cache: boolean;
+  /** The chain the effect was called on. Only available on effects created with
+   * `crossChain: false`; accessing it on a cross-chain effect throws. */
+  readonly chain: EffectChain;
 };
 
 /** Rate-limit window for an {@link Effect}. Strings resolve to common
@@ -82,6 +92,11 @@ export type EffectOptions<Input, Output> = {
   readonly rateLimit: RateLimit;
   /** Whether the effect should be cached. */
   readonly cache?: boolean;
+  /** Whether the effect's cache is shared across all chains. Defaults to
+   * `true`. Set to `false` to isolate the cache and rate limiting per chain and
+   * enable `context.chain.id` inside the handler. Changing this changes the
+   * effect's cache identity. */
+  readonly crossChain?: boolean;
 };
 
 /** Arguments passed to the handler function of an {@link Effect}. */
@@ -209,6 +224,10 @@ export function createEffect<
     readonly rateLimit: RateLimit;
     /** Whether the effect should be cached. */
     readonly cache?: boolean;
+    /** Whether the effect's cache is shared across all chains. Defaults to
+     * `true`. Set to `false` to isolate the cache and rate limiting per chain
+     * and enable `context.chain.id` inside the handler. */
+    readonly crossChain?: boolean;
   },
   handler: (args: EffectArgs<I>) => Promise<R>
 ): Effect<I, O>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.3.0-alpha.12",
+  "version": "3.3.0-alpha.13",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -70,10 +70,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.3.0-alpha.12",
-    "envio-linux-x64-musl": "3.3.0-alpha.12",
-    "envio-linux-arm64": "3.3.0-alpha.12",
-    "envio-darwin-x64": "3.3.0-alpha.12",
-    "envio-darwin-arm64": "3.3.0-alpha.12"
+    "envio-linux-x64": "3.3.0-alpha.13",
+    "envio-linux-x64-musl": "3.3.0-alpha.13",
+    "envio-linux-arm64": "3.3.0-alpha.13",
+    "envio-darwin-x64": "3.3.0-alpha.13",
+    "envio-darwin-arm64": "3.3.0-alpha.13"
   }
 }

package/src/ChainState.res

@@ -410,13 +410,17 @@ let isReady = (cs: t) => cs.timestampCaughtUpToHeadOrEndblock !== None
 // nudge it.
 let densityBlendWindow = 100.
 
-// The last block this chain can fetch right now: the head, or endBlock when
-// it's below the head.
+// The last block this chain can fetch right now: the lagged head
+// (knownHeight - blockLag, the frontier when a reorg-threshold blockLag holds
+// back the tip), or endBlock when it's below that head. Matching isFetchingAtHead's
+// definition of the head is what lets a chain parked at its lagged head read
+// 100% progress instead of looking behind against blocks it can't fetch.
 let fetchCeiling = (cs: t) => {
   let fetchState = cs.fetchState
+  let head = Pervasives.max(0, fetchState.knownHeight - fetchState.blockLag)
   switch fetchState.endBlock {
-  | Some(endBlock) => Pervasives.min(endBlock, fetchState.knownHeight)
-  | None => fetchState.knownHeight
+  | Some(endBlock) => Pervasives.min(endBlock, head)
+  | None => head
   }
 }
 
@@ -466,12 +470,14 @@ let targetBlock = (cs: t, ~chainTargetItems: float) => {
 }
 
 // Block range that cross-chain progress alignment maps fractions over: from
-// the first block that can hold this chain's events to the last block it can
-// fetch right now.
+// the chain's startBlock to the last block it can fetch right now. The lower
+// bound is deliberately static — anchoring it at firstEventBlock would make
+// two chains sitting at the same block read different progress fractions
+// depending on whether each has discovered its first event yet, so the
+// anchor's line could map below a follower's own frontier and stall it.
 let progressRange = (cs: t) => {
   let fetchState = cs.fetchState
-  let lower = fetchState.firstEventBlock->Option.getOr(fetchState.startBlock)
-  (lower, cs->fetchCeiling)
+  (fetchState.startBlock, cs->fetchCeiling)
 }
 
 // A degenerate range (chain already at or past its last block) maps to 1 so it
@@ -492,6 +498,12 @@ let blockAtProgress = (cs: t, ~progress) => {
   lower + Math.ceil(progress *. (upper - lower)->Int.toFloat)->Float.toInt
 }
 
+// The fetch frontier as a fraction of the alignable range — what the
+// cross-chain waterfall aligns other chains against. Based on blocks actually
+// fetched, so it holds up even while this chain's queries are in flight.
+let frontierProgress = (cs: t) =>
+  cs->progressAtBlock(~blockNumber=cs.fetchState->FetchState.bufferBlockNumber)
+
 // Propose queries sized against this chain's target block. Called by
 // CrossChainState's waterfall, furthest-behind chain first, with
 // chainTargetItems set to whatever budget remains at that point and

package/src/ChainState.res.mjs

@@ -254,11 +254,12 @@ function isReady(cs) {
 
 function fetchCeiling(cs) {
   let fetchState = cs.fetchState;
+  let head = Primitive_int.max(0, fetchState.knownHeight - fetchState.blockLag | 0);
   let endBlock = fetchState.endBlock;
   if (endBlock !== undefined) {
-    return Primitive_int.min(endBlock, fetchState.knownHeight);
+    return Primitive_int.min(endBlock, head);
   } else {
-    return fetchState.knownHeight;
+    return head;
   }
 }
 
@@ -300,14 +301,20 @@ function targetBlock(cs, chainTargetItems) {
 
 function progressRange(cs) {
   let fetchState = cs.fetchState;
-  let lower = Stdlib_Option.getOr(fetchState.firstEventBlock, fetchState.startBlock);
   return [
-    lower,
+    fetchState.startBlock,
     fetchCeiling(cs)
   ];
 }
 
-function progressAtBlock(cs, blockNumber) {
+function blockAtProgress(cs, progress) {
+  let match = progressRange(cs);
+  let lower = match[0];
+  return lower + (Math.ceil(progress * (match[1] - lower | 0)) | 0) | 0;
+}
+
+function frontierProgress(cs) {
+  let blockNumber = FetchState.bufferBlockNumber(cs.fetchState);
   let match = progressRange(cs);
   let upper = match[1];
   let lower = match[0];
@@ -318,12 +325,6 @@ function progressAtBlock(cs, blockNumber) {
   }
 }
 
-function blockAtProgress(cs, progress) {
-  let match = progressRange(cs);
-  let lower = match[0];
-  return lower + (Math.ceil(progress * (match[1] - lower | 0)) | 0) | 0;
-}
-
 function getNextQuery(cs, chainTargetItems, chunkItemsMultiplierOpt, maxTargetBlock) {
   let chunkItemsMultiplier = chunkItemsMultiplierOpt !== undefined ? chunkItemsMultiplierOpt : 1;
   let chainTargetBlock = targetBlock(cs, chainTargetItems);
@@ -782,8 +783,8 @@ export {
   hasReadyItem,
   isReadyToEnterReorgThreshold,
   targetBlock,
-  progressAtBlock,
   blockAtProgress,
+  frontierProgress,
   getNextQuery,
   dispatch,
   toChainData,

package/src/ChainState.resi

@@ -67,8 +67,8 @@ let isReadyToEnterReorgThreshold: t => bool
 
 // Fetch control.
 let targetBlock: (t, ~chainTargetItems: float) => int
-let progressAtBlock: (t, ~blockNumber: int) => float
 let blockAtProgress: (t, ~progress: float) => int
+let frontierProgress: t => float
 let getNextQuery: (
   t,
   ~chainTargetItems: float,

package/src/CrossChainState.res

@@ -169,13 +169,18 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
 
 // --- Fetch control. ---
 
-// Chains ordered furthest-behind first, so the shared buffer pool goes to the
-// chains with the most fetchable backfill work before the rest.
+// Chains ordered furthest-behind first by fetch-frontier progress, so the
+// shared buffer pool goes to the chains with the most fetchable backfill work
+// before the rest — and the same metric that sets the alignment line also
+// decides who draws budget first, so the anchor is served before any chain it
+// clamps. (Batch ordering keeps its own getProgressPercentage measure.) A chain
+// with no known height reads 100% here and sorts last, which is fine: it can't
+// fetch until its first block lands regardless of when it's visited.
 let priorityOrder = (crossChainState: t) =>
   crossChainState.chainStates
   ->Dict.valuesToArray
   ->Array.toSorted((a, b) =>
-    Float.compare(a->ChainState.getProgressPercentage, b->ChainState.getProgressPercentage)
+    Float.compare(a->ChainState.frontierProgress, b->ChainState.frontierProgress)
   )
 
 // In-flight estimated items across every chain — the live draw against
@@ -201,10 +206,14 @@ let totalReservedSize = (crossChainState: t) => {
 // automatically. Starting a new query requires at least 10% of the target pool
 // to be free. A chain visited after the budget falls below that admission unit
 // doesn't query this round — reservations release as responses land, so the
-// next tick redistributes. Chains that do get budget are additionally capped
-// at the first querying chain's target progress mapped onto their own range, so
-// no chain runs further ahead than the chain currently using the pool. Waiting
-// and idle chains do not establish this alignment line.
+// next tick redistributes. Every other chain is additionally capped at the
+// lowest-frontier-progress chain's progress mapped onto its own range, so no
+// chain runs ahead of the chain the pool is prioritizing — including on ticks
+// where that chain is mid-fetch and emits no new query. A chain with no known
+// height can't anchor this line (there's no range to measure against), a chain
+// caught up to its fetchable head reads 100% and so never anchors while another
+// is behind, and once the whole indexer has caught up (isRealtime) the clamp is
+// dropped — chains at head only trail each other by real-time block production.
 let checkAndFetch = async (
   crossChainState: t,
   ~dispatchChain: (~chain: ChainMap.Chain.t, ~action: FetchState.nextQuery) => promise<unit>,
@@ -235,11 +244,23 @@ let checkAndFetch = async (
   // gets more since a forced catch-up query there costs a head-poll roundtrip.
   let chunkItemsMultiplier = crossChainState.isRealtime ? 3. : 1.5
 
+  let prioritizedChainStates = crossChainState->priorityOrder
+
+  // Alignment anchor: the first known-height chain in priority order — which,
+  // since that order sorts by frontier progress, is the chain furthest behind
+  // by the very metric the clamp maps other chains against. Anchoring on the
+  // frontier (not on the target of whichever chain happens to query this tick)
+  // keeps the line in place while the anchor's queries are still in flight. A
+  // chain caught up to its fetchable head reads 100% and sorts past any behind
+  // chain, so it never anchors while another chain is behind.
+  let alignment = crossChainState.isRealtime
+    ? None
+    : prioritizedChainStates
+      ->Array.find(cs => cs->ChainState.knownHeight != 0)
+      ->Option.map(cs => ((cs->ChainState.chainConfig).id, cs->ChainState.frontierProgress))
+
   let actionByChain = Dict.make()
-  let maxProgress = ref(None)
-  crossChainState
-  ->priorityOrder
-  ->Array.forEach(cs => {
+  prioritizedChainStates->Array.forEach(cs => {
     let chainId = (cs->ChainState.chainConfig).id
     if remaining.contents < minimumAdmissionBudget {
       // More than 90% of the target pool is ready or reserved. Do not attempt
@@ -257,22 +278,14 @@ let checkAndFetch = async (
       let chainTargetItems =
         (isCold ? Pervasives.min(remaining.contents, coldChainBudget) : remaining.contents) +.
         cs->ChainState.pendingBudget
-      let candidateProgress = switch maxProgress.contents {
-      | None if !isCold =>
-        Some(
-          cs->ChainState.progressAtBlock(
-            ~blockNumber=cs->ChainState.targetBlock(~chainTargetItems),
-          ),
-        )
+      let maxTargetBlock = switch alignment {
+      // 5% 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))
       | _ => None
       }
-      let maxTargetBlock = switch maxProgress.contents {
-      | None => None
-      // 5% margin past the leader's line: chains whose progress tracks the
-      // leader closely would otherwise flap in and out of the clamp as
-      // leadership alternates, stalling their pipeline every other tick.
-      | Some(progress) => Some(cs->ChainState.blockAtProgress(~progress=progress +. 0.05))
-      }
       switch cs->ChainState.getNextQuery(
         ~chainTargetItems,
         ~chunkItemsMultiplier,
@@ -297,14 +310,6 @@ let checkAndFetch = async (
             : FetchState.WaitingForNewBlock
         actionByChain->Utils.Dict.setByInt(chainId, action)
       | Ready(queries) => {
-          // A density-bearing chain establishes the alignment line only after
-          // proving that it can use the pool. Waiting and idle chains leave it
-          // open for the next chain; cold-chain targets remain guesses and do
-          // not lead, as before.
-          switch candidateProgress {
-          | Some(progress) => maxProgress := Some(progress)
-          | None => ()
-          }
           let consumed =
             queries->Array.reduce(0., (acc, query: FetchState.query) =>
               acc +. query.itemsEst->Int.toFloat

package/src/CrossChainState.res.mjs

@@ -8,6 +8,7 @@ import * as ChainMap from "./ChainMap.res.mjs";
 import * as ChainState from "./ChainState.res.mjs";
 import * as Prometheus from "./Prometheus.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
 import * as SafeCheckpointTracking from "./SafeCheckpointTracking.res.mjs";
 
@@ -121,7 +122,7 @@ function applyBatchProgress(crossChainState, batch, blockTimestampName) {
 }
 
 function priorityOrder(crossChainState) {
-  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(ChainState.getProgressPercentage(a), ChainState.getProgressPercentage(b)));
+  return Object.values(crossChainState.chainStates).toSorted((a, b) => Primitive_float.compare(ChainState.frontierProgress(a), ChainState.frontierProgress(b)));
 }
 
 function totalReservedSize(crossChainState) {
@@ -140,11 +141,13 @@ async function checkAndFetch(crossChainState, dispatchChain) {
   };
   let minimumAdmissionBudget = targetBudget * 0.1;
   let chunkItemsMultiplier = crossChainState.isRealtime ? 3 : 1.5;
+  let prioritizedChainStates = priorityOrder(crossChainState);
+  let alignment = crossChainState.isRealtime ? undefined : Stdlib_Option.map(prioritizedChainStates.find(cs => ChainState.knownHeight(cs) !== 0), cs => [
+      ChainState.chainConfig(cs).id,
+      ChainState.frontierProgress(cs)
+    ]);
   let actionByChain = {};
-  let maxProgress = {
-    contents: undefined
-  };
-  priorityOrder(crossChainState).forEach(cs => {
+  prioritizedChainStates.forEach(cs => {
     let chainId = ChainState.chainConfig(cs).id;
     if (remaining.contents < minimumAdmissionBudget) {
       actionByChain[chainId] = "NothingToQuery";
@@ -158,10 +161,7 @@ async function checkAndFetch(crossChainState, dispatchChain) {
     let chainTargetItems = (
       isCold ? Primitive_float.min(remaining.contents, minimumAdmissionBudget) : remaining.contents
     ) + ChainState.pendingBudget(cs);
-    let match = maxProgress.contents;
-    let candidateProgress = match !== undefined || isCold ? undefined : ChainState.progressAtBlock(cs, ChainState.targetBlock(cs, chainTargetItems));
-    let progress = maxProgress.contents;
-    let maxTargetBlock = progress !== undefined ? ChainState.blockAtProgress(cs, progress + 0.05) : undefined;
+    let maxTargetBlock = alignment !== undefined && alignment[0] !== chainId ? ChainState.blockAtProgress(cs, alignment[1] + 0.05) : undefined;
     let action = ChainState.getNextQuery(cs, chainTargetItems, chunkItemsMultiplier, maxTargetBlock);
     if (typeof action !== "object") {
       if (action === "WaitingForNewBlock") {
@@ -173,9 +173,6 @@ async function checkAndFetch(crossChainState, dispatchChain) {
       return;
     } else {
       let queries = action._0;
-      if (candidateProgress !== undefined) {
-        maxProgress.contents = candidateProgress;
-      }
       let consumed = Stdlib_Array.reduce(queries, 0, (acc, query) => acc + query.itemsEst);
       let partitions = {};
       queries.forEach(query => {

package/src/EffectState.res

@@ -0,0 +1,100 @@
+// 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.
+
+// Per-scope rate-limit window and queue. A chain-scoped effect gets one of
+// these per chain, so each chain's throughput is independent.
+type effectRateLimitState = {
+  callsPerDuration: int,
+  durationMs: int,
+  mutable availableCalls: int,
+  mutable windowStartTime: float,
+  mutable queueCount: int,
+  mutable nextWindowPromise: option<promise<unit>>,
+}
+
+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.
+  mutable idsToStore: array<string>,
+  mutable invalidationsCount: int,
+  // Each entry is stamped with the checkpoint that referenced it (or
+  // loadedFromDbCheckpointId for db reads), so committed entries can be
+  // dropped once persisted/re-derivable, mirroring entity changes.
+  mutable dict: dict<Change.t<Internal.effectOutput>>,
+  mutable changesCount: float,
+  effect: Internal.effect,
+  // The scope this cache is for and its resolved db table (the address). The
+  // in-mem table is keyed by `table.tableName`, so a cross-chain and a
+  // chain-scoped cache for the same effect stay isolated.
+  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,
+}
+
+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>,
+}
+
+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
+      },
+    )
+  }
+
+// 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 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 inMemTable: effectCacheInMemTable = {
+      idsToStore: [],
+      dict: Dict.make(),
+      changesCount: 0.,
+      invalidationsCount: 0,
+      effect,
+      scope,
+      table: Internal.makeCacheTable(~effectName=effect.name, ~scope),
+      rateLimitState: self->getRateLimitState(~tableName, ~effect),
+      activeCallsCount: 0,
+      prevCallStartTimerRef: %raw(`null`),
+    }
+    self.tables->Dict.set(tableName, inMemTable)
+    inMemTable
+  }
+}
+
+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()

package/src/EffectState.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Utils from "./Utils.res.mjs";
+import * as Internal from "./Internal.res.mjs";
+
+function make() {
+  return {
+    tables: {},
+    rateLimits: {}
+  };
+}
+
+function getRateLimitState(self, tableName, effect) {
+  let match = effect.rateLimit;
+  if (match === undefined) {
+    return;
+  }
+  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
+    };
+    self.rateLimits[tableName] = created;
+    tmp = created;
+  }
+  return tmp;
+}
+
+function getTable(self, effect, scope) {
+  let tableName = Internal.EffectCache.toTableName(effect.name, scope);
+  let inMemTable = self.tables[tableName];
+  if (inMemTable !== undefined) {
+    return inMemTable;
+  }
+  let inMemTable$1 = {
+    idsToStore: [],
+    invalidationsCount: 0,
+    dict: {},
+    changesCount: 0,
+    effect: effect,
+    scope: scope,
+    table: Internal.makeCacheTable(effect.name, scope),
+    rateLimitState: getRateLimitState(self, tableName, effect),
+    activeCallsCount: 0,
+    prevCallStartTimerRef: null
+  };
+  self.tables[tableName] = inMemTable$1;
+  return inMemTable$1;
+}
+
+function forEach(self, fn) {
+  Utils.Dict.forEach(self.tables, fn);
+}
+
+function resetForRollback(self) {
+  self.tables = {};
+}
+
+export {
+  make,
+  getTable,
+  forEach,
+  resetForRollback,
+}
+/* Utils Not a pure module */

package/src/EffectState.resi

@@ -0,0 +1,32 @@
+type effectRateLimitState = {
+  callsPerDuration: int,
+  durationMs: int,
+  mutable availableCalls: int,
+  mutable windowStartTime: float,
+  mutable queueCount: int,
+  mutable nextWindowPromise: option<promise<unit>>,
+}
+
+type effectCacheInMemTable = {
+  mutable idsToStore: array<string>,
+  mutable invalidationsCount: int,
+  mutable dict: dict<Change.t<Internal.effectOutput>>,
+  mutable changesCount: float,
+  effect: Internal.effect,
+  scope: Internal.chainScope,
+  table: Table.table,
+  rateLimitState: option<effectRateLimitState>,
+  mutable activeCallsCount: int,
+  mutable prevCallStartTimerRef: Performance.timeRef,
+}
+
+// Opaque store of all per-(effect, scope) runtime state.
+type t
+
+let make: unit => t
+// Get, or lazily create, the in-mem table for an (effect, scope). Reuses the
+// surviving rate-limit window when the table is recreated after a rollback.
+let getTable: (t, ~effect: Internal.effect, ~scope: Internal.chainScope) => effectCacheInMemTable
+let forEach: (t, effectCacheInMemTable => unit) => unit
+// Drop the cache tables but keep the rate-limit windows across a rollback.
+let resetForRollback: t => unit

package/src/Envio.res

@@ -186,11 +186,19 @@ and effectOptions<'input, 'output> = {
   rateLimit: rateLimit,
   /** Whether the effect should be cached. */
   cache?: bool,
+  /** Whether the effect's cache is shared across all chains. Defaults to `true`.
+   Set to `false` to isolate the cache (and rate limiting) per chain and enable
+   `context.chain.id` inside the handler. */
+  crossChain?: bool,
 }
+and effectChain = {id: int}
 and effectContext = {
   log: logger,
   effect: 'input 'output. (effect<'input, 'output>, 'input) => promise<'output>,
   mutable cache: bool,
+  /** The chain the effect was called on. Only available on effects created with
+   `crossChain: false`; accessing it on a cross-chain effect throws. */
+  chain: effectChain,
 }
 and effectArgs<'input> = {
   input: 'input,
@@ -205,10 +213,23 @@ let durationToMs = (duration: rateLimitDuration) =>
   | Milliseconds(ms) => ms
   }
 
+// The name becomes both a Postgres cache-table suffix and a .envio/cache file
+// path segment. Path separators are excluded from the charset and a leading dot
+// is disallowed, so a name can never be "." / ".." or otherwise traverse out of
+// the cache dir; dots elsewhere are fine and keep existing names like
+// "token.metadata" working, since the (name, scope) <-> table <-> path mapping
+// stays reversible.
+let effectNameRe = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/
+
 let createEffect = (
   options: effectOptions<'input, 'output>,
   handler: effectArgs<'input> => promise<'output>,
 ) => {
+  if !(effectNameRe->RegExp.test(options.name)) {
+    JsError.throwWithMessage(
+      `Invalid effect name "${options.name}". Effect names may contain letters, numbers, underscores, hyphens and dots (but must not start with a dot or contain a path separator), because the name is used as the cache table name and cache file path.`,
+    )
+  }
   let outputSchema =
     S.schema(_ => options.output)->(Utils.magic: S.t<S.t<'output>> => S.t<Internal.effectOutput>)
   let itemSchema = S.schema((s): Internal.effectCacheItem => {
@@ -222,8 +243,6 @@ let createEffect = (
         Internal.effectOutput,
       >
     ),
-    activeCallsCount: 0,
-    prevCallStartTimerRef: %raw(`null`),
     // This is the way to make the createEffect API
     // work without the need for users to call S.schema themselves,
     // but simply pass the desired object/tuple/etc.
@@ -233,7 +252,6 @@ let createEffect = (
     ),
     output: outputSchema,
     storageMeta: {
-      table: Internal.makeCacheTable(~effectName=options.name),
       outputSchema,
       itemSchema,
     },
@@ -241,16 +259,16 @@ let createEffect = (
     | Some(true) => true
     | _ => false
     },
+    crossChain: switch options.crossChain {
+    | Some(false) => false
+    | _ => true
+    },
     rateLimit: switch options.rateLimit {
     | Disable => None
     | Enable({calls, per}) =>
       Some({
         callsPerDuration: calls,
         durationMs: per->durationToMs,
-        availableCalls: calls,
-        windowStartTime: Date.now(),
-        queueCount: 0,
-        nextWindowPromise: None,
       })
     },
   }->(Utils.magic: Internal.effect => effect<'input, 'output>)