envio 3.5.0-alpha.2 → 3.5.0-rc.0

package/src/Config.res

@@ -30,12 +30,16 @@ type sourceConfig =
   | EvmSourceConfig({hypersync: option<string>, rpcs: array<evmRpcConfig>})
   | FuelSourceConfig({hypersync: string})
   | SvmSourceConfig({hypersync: option<string>, rpc: option<string>})
+  // A `simulate` run: the items the test fed in, parsed against the chain's
+  // registrations. The source itself is built with the chain's address store,
+  // like every other source, so it can apply the same gates.
+  | SimulateSourceConfig({items: array<Internal.item>, endBlock: int})
   // For tests: pass custom sources directly
   | CustomSources(array<Source.t>)
 
 type chain = {
   name: string,
-  id: int,
+  id: ChainId.t,
   startBlock: int,
   endBlock?: int,
   maxReorgDepth: int,
@@ -73,6 +77,10 @@ type t = {
   shouldRollbackOnReorg: bool,
   shouldSaveFullHistory: bool,
   storage: storage,
+  // Widest scalar the internal chain-id columns need, resolved by the CLI from
+  // the maximum active chain id. Older configs predate the field, and every id
+  // they can express fits an INTEGER.
+  chainIdMode: ChainId.mode,
   chainMap: ChainMap.t<chain>,
   defaultChain: option<chain>,
   ecosystem: Ecosystem.t,
@@ -98,13 +106,13 @@ module EnvioAddresses = {
   let name = "envio_addresses"
   let index = -1
 
-  let makeId = (~chainId, ~address) => {
-    chainId->Int.toString ++ "-" ++ address->Address.toString
+  let makeId = (~chainId: ChainId.t, ~address) => {
+    chainId->ChainId.toString ++ "-" ++ address->Address.toString
   }
 
   type t = {
     id: string,
-    @as("chain_id") chainId: int,
+    @as("chain_id") chainId: ChainId.t,
     @as("registration_block") registrationBlock: int,
     // -1 when the address was registered from a block handler (no log index)
     @as("registration_log_index") registrationLogIndex: int,
@@ -123,7 +131,7 @@ module EnvioAddresses = {
 
   let schema = S.schema(s => {
     id: s.matches(S.string),
-    chainId: s.matches(S.int),
+    chainId: s.matches(ChainId.schema),
     registrationBlock: s.matches(S.int),
     registrationLogIndex: s.matches(S.int),
     contractName: s.matches(S.string),
@@ -133,7 +141,7 @@ module EnvioAddresses = {
     name,
     ~fields=[
       Table.mkField("id", String, ~isPrimaryKey=true, ~fieldSchema=S.string),
-      Table.mkField("chain_id", Int32, ~fieldSchema=S.int),
+      Table.mkField("chain_id", ChainId, ~fieldSchema=ChainId.schema),
       Table.mkField("registration_block", Int32, ~fieldSchema=S.int),
       // -1 sentinel when registered from a block handler (no log index)
       Table.mkField("registration_log_index", Int32, ~fieldSchema=S.int),
@@ -185,7 +193,7 @@ let chainContractSchema = S.schema(s =>
 
 let publicConfigChainSchema = S.schema(s =>
   {
-    "id": s.matches(S.int),
+    "id": s.matches(ChainId.schema),
     "startBlock": s.matches(S.int),
     "endBlock": s.matches(S.option(S.int)),
     "maxReorgDepth": s.matches(S.option(S.int)),
@@ -455,7 +463,7 @@ let parseEntitiesFromJson = (
         )
       )
 
-    let compositeIndices =
+    let compositeIndexes =
       entityJson["compositeIndices"]
       ->Option.getOr([])
       ->Array.map(ci =>
@@ -470,7 +478,7 @@ let parseEntitiesFromJson = (
     let table = Table.mkTable(
       entityName,
       ~fields=Array.concat(fields, derivedFields),
-      ~compositeIndices,
+      ~compositeIndexes,
       ~description=?entityJson["description"],
     )
 
@@ -548,6 +556,7 @@ let publicConfigSchema = S.schema(s =>
     "rollbackOnReorg": s.matches(S.option(S.bool)),
     "saveFullHistory": s.matches(S.option(S.bool)),
     "rawEvents": s.matches(S.option(S.bool)),
+    "chainIdMode": s.matches(S.option(ChainId.modeSchema)),
     "storage": s.matches(publicConfigStorageSchema),
     "evm": s.matches(S.option(publicConfigEvmSchema)),
     "fuel": s.matches(S.option(publicConfigEcosystemSchema)),
@@ -690,7 +699,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     ~contractName,
     ~events: option<array<_>>,
     ~abi,
-    ~chainId: int,
+    ~chainId: ChainId.t,
     ~addresses: array<string>,
     ~svmDefinedTypes: JSON.t=JSON.Null,
   ) => {
@@ -724,11 +733,11 @@ let fromPublic = (publicConfigJson: JSON.t) => {
           | [pid] => pid->SvmTypes.Pubkey.fromStringUnsafe
           | [] =>
             JsError.throwWithMessage(
-              `SVM program ${contractName} on chain ${chainId->Int.toString} is missing a program_id`,
+              `SVM program ${contractName} on chain ${chainId->ChainId.toString} is missing a program_id`,
             )
           | _ =>
             JsError.throwWithMessage(
-              `SVM program ${contractName} on chain ${chainId->Int.toString} has multiple addresses; a program is uniquely identified by a single program_id`,
+              `SVM program ${contractName} on chain ${chainId->ChainId.toString} has multiple addresses; a program is uniquely identified by a single program_id`,
             )
           }
           let widenedEventItem =
@@ -878,8 +887,8 @@ let fromPublic = (publicConfigJson: JSON.t) => {
             | Some(existingContractName) =>
               JsError.throwWithMessage(
                 existingContractName === contract.name
-                  ? `Address ${addressString} is listed multiple times for the contract ${contract.name} on chain ${chainId->Int.toString}. Please remove the duplicate from your config.`
-                  : `Address ${addressString} on chain ${chainId->Int.toString} is configured for multiple contracts: ${existingContractName} and ${contract.name}. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`,
+                  ? `Address ${addressString} is listed multiple times for the contract ${contract.name} on chain ${chainId->ChainId.toString}. Please remove the duplicate from your config.`
+                  : `Address ${addressString} on chain ${chainId->ChainId.toString} is configured for multiple contracts: ${existingContractName} and ${contract.name}. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`,
               )
             | None => contractNameByAddress->Dict.set(addressString, contract.name)
             }
@@ -969,7 +978,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
   let chainMap =
     chains
     ->Array.map(chain => {
-      (ChainMap.Chain.makeUnsafe(~chainId=chain.id), chain)
+      (chain.id, chain)
     })
     ->ChainMap.fromArrayUnsafe
 
@@ -1027,6 +1036,7 @@ let fromPublic = (publicConfigJson: JSON.t) => {
     shouldRollbackOnReorg: publicConfig["rollbackOnReorg"]->Option.getOr(true),
     shouldSaveFullHistory: publicConfig["saveFullHistory"]->Option.getOr(false),
     storage: globalStorage,
+    chainIdMode: publicConfig["chainIdMode"]->Option.getOr(Int32),
     chainMap,
     defaultChain: chains->Array.get(0),
     enableRawEvents: publicConfig["rawEvents"]->Option.getOr(false),
@@ -1092,15 +1102,14 @@ let normalizeSimulateAddress = (config: t, address: Address.t): Address.t =>
 // returns that chain's per-chain event config (matters for where-callback
 // probe detection, which runs with the chain's real id). Without `chainId`,
 // falls back to the first chain that declares this event.
-let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<int>=?) => {
+let getEventConfig = (config: t, ~contractName, ~eventName, ~chainId: option<ChainId.t>=?) => {
   let chains = switch chainId {
   | Some(chainId) =>
-    let chain = ChainMap.Chain.makeUnsafe(~chainId)
-    switch config.chainMap->ChainMap.get(chain) {
+    switch config.chainMap->ChainMap.get(chainId) {
     | chainConfig => [chainConfig]
     | exception _ =>
       JsError.throwWithMessage(
-        `Chain ${chainId->Int.toString} is not configured. Add it to config.yaml or pass a configured chain.`,
+        `Chain ${chainId->ChainId.toString} is not configured. Add it to config.yaml or pass a configured chain.`,
       )
     }
   | None => config.chainMap->ChainMap.values
@@ -1122,14 +1131,12 @@ let shouldSaveHistory = (config, ~isInReorgThreshold) =>
 let shouldPruneHistory = (config, ~isInReorgThreshold) =>
   !config.shouldSaveFullHistory && (config.shouldRollbackOnReorg && isInReorgThreshold)
 
-let getChain = (config, ~chainId) => {
-  let chain = ChainMap.Chain.makeUnsafe(~chainId)
-  config.chainMap->ChainMap.has(chain)
-    ? chain
+let getChain = (config, ~chainId) =>
+  config.chainMap->ChainMap.has(chainId)
+    ? chainId
     : JsError.throwWithMessage(
-        "No chain with id " ++ chain->ChainMap.Chain.toString ++ " found in config.yaml",
+        "No chain with id " ++ chainId->ChainId.toString ++ " found in config.yaml",
       )
-}
 
 // A CLI command payload already contains the resolved JSON; priming lets
 // downstream callers skip the NAPI `getConfigJson` round-trip. Calling
@@ -1267,7 +1274,17 @@ let diffPaths = (~stored: JSON.t, ~current: JSON.t): array<string> => {
 
   switch (stored, current) {
   | (Object(sObj), Object(cObj)) =>
-    let tiers = [["version"], ["name"], ["storage"], ["evm", "fuel", "svm"], ["entities"]]
+    // chainIdMode sits right after version: it decides the physical type of
+    // every chain-id column, so a change to it is reported on its own rather
+    // than buried under the chain diffs that always accompany it.
+    let tiers = [
+      ["version"],
+      ["chainIdMode"],
+      ["name"],
+      ["storage"],
+      ["evm", "fuel", "svm"],
+      ["entities"],
+    ]
     let firstHit = tiers->Array.reduce(None, (acc, tier) =>
       switch acc {
       | Some(_) => acc

package/src/Config.res.mjs

@@ -8,6 +8,7 @@ import * as Fuel from "./sources/Fuel.res.mjs";
 import * as Table from "./db/Table.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
+import * as ChainId from "./ChainId.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as Internal from "./Internal.res.mjs";
@@ -24,7 +25,7 @@ import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_excep
 let name = "envio_addresses";
 
 function makeId(chainId, address) {
-  return chainId.toString() + "-" + address;
+  return ChainId.toString(chainId) + "-" + address;
 }
 
 function getAddress(entity) {
@@ -34,7 +35,7 @@ function getAddress(entity) {
 
 let schema = S$RescriptSchema.schema(s => ({
   id: s.m(S$RescriptSchema.string),
-  chain_id: s.m(S$RescriptSchema.int),
+  chain_id: s.m(ChainId.schema),
   registration_block: s.m(S$RescriptSchema.int),
   registration_log_index: s.m(S$RescriptSchema.int),
   contract_name: s.m(S$RescriptSchema.string)
@@ -42,7 +43,7 @@ let schema = S$RescriptSchema.schema(s => ({
 
 let table = Table.mkTable(name, undefined, [
   Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("chain_id", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("chain_id", "ChainId", ChainId.schema, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
   Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
   Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
   Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
@@ -98,7 +99,7 @@ let chainContractSchema = S$RescriptSchema.schema(s => ({
 }));
 
 let publicConfigChainSchema = S$RescriptSchema.schema(s => ({
-  id: s.m(S$RescriptSchema.int),
+  id: s.m(ChainId.schema),
   startBlock: s.m(S$RescriptSchema.int),
   endBlock: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
   maxReorgDepth: s.m(S$RescriptSchema.option(S$RescriptSchema.int)),
@@ -331,11 +332,11 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
       return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], prop.linkedEntity, prop.description, prop.postgresDbName, prop.clickhouseDbName);
     });
     let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField, df.description));
-    let compositeIndices = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
+    let compositeIndexes = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
       fieldName: f.fieldName,
       direction: f.direction === "Asc" ? "Asc" : "Desc"
     })));
-    let table = Table.mkTable(entityName, compositeIndices, fields.concat(derivedFields), entityJson.description);
+    let table = Table.mkTable(entityName, compositeIndexes, fields.concat(derivedFields), entityJson.description);
     let getApiFieldName = prop => {
       let match = prop.linkedEntity;
       if (match !== undefined) {
@@ -400,6 +401,7 @@ let publicConfigSchema = S$RescriptSchema.schema(s => ({
   rollbackOnReorg: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   saveFullHistory: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   rawEvents: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  chainIdMode: s.m(S$RescriptSchema.option(ChainId.modeSchema)),
   storage: s.m(publicConfigStorageSchema),
   evm: s.m(S$RescriptSchema.option(publicConfigEvmSchema)),
   fuel: s.m(S$RescriptSchema.option(publicConfigEcosystemSchema)),
@@ -528,7 +530,7 @@ function fromPublic(publicConfigJson) {
           case "svm" :
             let len = addresses.length;
             let programId = len !== 1 ? (
-                len !== 0 ? Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + chainId.toString() + ` has multiple addresses; a program is uniquely identified by a single program_id`) : Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + chainId.toString() + ` is missing a program_id`)
+                len !== 0 ? Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + ChainId.toString(chainId) + ` has multiple addresses; a program is uniquely identified by a single program_id`) : Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + ChainId.toString(chainId) + ` is missing a program_id`)
               ) : addresses[0];
             let s = eventItem.svm;
             let svm = s !== undefined ? Primitive_option.valFromOption(s) : Stdlib_JsError.throwWithMessage(`SVM instruction ` + contractName + `.` + eventName + ` is missing the "svm" descriptor in internal config`);
@@ -591,7 +593,7 @@ function fromPublic(publicConfigJson) {
       contract.addresses.forEach(address => {
         let existingContractName = contractNameByAddress[address];
         if (existingContractName !== undefined) {
-          return Stdlib_JsError.throwWithMessage(existingContractName === contract.name ? `Address ` + address + ` is listed multiple times for the contract ` + contract.name + ` on chain ` + chainId.toString() + `. Please remove the duplicate from your config.` : `Address ` + address + ` on chain ` + chainId.toString() + ` is configured for multiple contracts: ` + existingContractName + ` and ` + contract.name + `. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`);
+          return Stdlib_JsError.throwWithMessage(existingContractName === contract.name ? `Address ` + address + ` is listed multiple times for the contract ` + contract.name + ` on chain ` + ChainId.toString(chainId) + `. Please remove the duplicate from your config.` : `Address ` + address + ` on chain ` + ChainId.toString(chainId) + ` is configured for multiple contracts: ` + existingContractName + ` and ` + contract.name + `. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`);
         } else {
           contractNameByAddress[address] = contract.name;
           return;
@@ -677,7 +679,7 @@ function fromPublic(publicConfigJson) {
     };
   });
   let chainMap = ChainMap.fromArrayUnsafe(chains.map(chain => [
-    ChainMap.Chain.makeUnsafe(chain.id),
+    chain.id,
     chain
   ]));
   let allEnums = parseEnumsFromJson(Stdlib_Option.getOr(publicConfig.enums, {}));
@@ -709,6 +711,7 @@ function fromPublic(publicConfigJson) {
     shouldRollbackOnReorg: Stdlib_Option.getOr(publicConfig.rollbackOnReorg, true),
     shouldSaveFullHistory: Stdlib_Option.getOr(publicConfig.saveFullHistory, false),
     storage: globalStorage,
+    chainIdMode: Stdlib_Option.getOr(publicConfig.chainIdMode, "int32"),
     chainMap: chainMap,
     defaultChain: chains[0],
     ecosystem: ecosystem,
@@ -765,14 +768,14 @@ function normalizeSimulateAddress(config, address) {
 function getEventConfig(config, contractName, eventName, chainId) {
   let chains;
   if (chainId !== undefined) {
-    let chain = ChainMap.Chain.makeUnsafe(chainId);
+    let chainId$1 = Primitive_option.valFromOption(chainId);
     let exit = 0;
     let chainConfig;
     try {
-      chainConfig = ChainMap.get(config.chainMap, chain);
+      chainConfig = ChainMap.get(config.chainMap, chainId$1);
       exit = 1;
     } catch (exn) {
-      chains = Stdlib_JsError.throwWithMessage(`Chain ` + chainId.toString() + ` is not configured. Add it to config.yaml or pass a configured chain.`);
+      chains = Stdlib_JsError.throwWithMessage(`Chain ` + ChainId.toString(chainId$1) + ` is not configured. Add it to config.yaml or pass a configured chain.`);
     }
     if (exit === 1) {
       chains = [chainConfig];
@@ -808,11 +811,10 @@ function shouldPruneHistory(config, isInReorgThreshold) {
 }
 
 function getChain(config, chainId) {
-  let chain = ChainMap.Chain.makeUnsafe(chainId);
-  if (ChainMap.has(config.chainMap, chain)) {
-    return chain;
+  if (ChainMap.has(config.chainMap, chainId)) {
+    return chainId;
   } else {
-    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainMap.Chain.toString(chain) + " found in config.yaml");
+    return Stdlib_JsError.throwWithMessage("No chain with id " + ChainId.toString(chainId) + " found in config.yaml");
   }
 }
 
@@ -983,6 +985,7 @@ function diffPaths(stored, current) {
   if (typeof stored === "object" && stored !== null && !Array.isArray(stored) && typeof current === "object" && current !== null && !Array.isArray(current)) {
     let tiers = [
       ["version"],
+      ["chainIdMode"],
       ["name"],
       ["storage"],
       [

package/src/ContractRegisterContext.res

@@ -36,7 +36,7 @@ let contractRegisterChainTraps: Utils.Proxy.traps<contractRegisterParams> = {
     switch prop {
     | "id" =>
       let eventItem = params.item->Internal.castUnsafeEventItem
-      eventItem.chain->ChainMap.Chain.toChainId->(Utils.magic: int => unknown)
+      eventItem.chainId->(Utils.magic: ChainId.t => unknown)
     | _ =>
       // Look up the contract name directly in config contracts across all chains.
       let contractName = prop

package/src/ContractRegisterContext.res.mjs

@@ -19,7 +19,7 @@ function makeAddFunction(params, contractName) {
 
 let contractRegisterChainTraps_get = (params, prop) => {
   if (prop === "id") {
-    return params.item.chain;
+    return params.item.chainId;
   }
   let isValidContract = ChainMap.values(params.config.chainMap).some(chain => chain.contracts.some(c => c.name === prop));
   if (isValidContract) {

package/src/Core.res

@@ -21,6 +21,7 @@ type fromUserApiOptions = {
 type fromUserApiResult = {
   config: string,
   indexerTypes: Null.t<string>,
+  indexerCode: Null.t<string>,
 }
 
 type addon = {

package/src/CrossChainState.res

@@ -7,9 +7,13 @@ type t = {
   chainStates: dict<ChainState.t>,
   // Chain ids in a stable order, so the cross-chain loops iterate the chains
   // without allocating a values array on every tick.
-  chainIds: array<int>,
+  chainIds: array<ChainId.t>,
   // True once every chain has caught up to head/endBlock. Monotonic during a run.
   mutable isRealtime: bool,
+  // True once every chain has caught up and there's nothing left to process,
+  // but before the deferred schema indexes and `ready_at` are committed. The
+  // gap between this and `isRealtime` is the FinalizingIndexes phase.
+  mutable isCaughtUp: bool,
   mutable isInReorgThreshold: bool,
   // Indexer-wide fetch buffer pool (item count), shared across all chains.
   targetBufferSize: int,
@@ -32,6 +36,7 @@ let make = (
     chainStates,
     chainIds: chainStates->Dict.valuesToArray->Array.map(cs => (cs->ChainState.chainConfig).id),
     isRealtime,
+    isCaughtUp: isRealtime,
     isInReorgThreshold,
     targetBufferSize,
   }
@@ -40,12 +45,13 @@ let make = (
 // Resolve a chain's state by id. The id always comes from `chainIds`, which is
 // derived from `chainStates`, so the entry is guaranteed present.
 let getChainState = (crossChainState: t, chainId) =>
-  crossChainState.chainStates->Utils.Dict.dangerouslyGetByIntNonOption(chainId)->Option.getUnsafe
+  crossChainState.chainStates->ChainId.Dict.dangerouslyGetNonOption(chainId)->Option.getUnsafe
 
 // --- Accessors. ---
 
 let chainStates = (crossChainState: t) => crossChainState.chainStates
 let isRealtime = (crossChainState: t) => crossChainState.isRealtime
+let isCaughtUp = (crossChainState: t) => crossChainState.isCaughtUp
 let isInReorgThreshold = (crossChainState: t) => crossChainState.isInReorgThreshold
 let targetBufferSize = (crossChainState: t) => crossChainState.targetBufferSize
 
@@ -129,10 +135,11 @@ let enterReorgThreshold = (crossChainState: t) => {
   crossChainState.isInReorgThreshold = true
 }
 
-// Commit each progressed chain's batch progress, then decide readiness for the
-// whole indexer. A chain is marked caught up only once EVERY chain is caught up
-// (reached endblock or fetched/processed to head) with no processable events
-// left — so no chain flips to ready while another is still backfilling.
+// Commit each progressed chain's batch progress, then record whether the whole
+// indexer has caught up (every chain reached endblock or processed to head,
+// with no processable events left). Catching up doesn't make the indexer ready:
+// the deferred schema indexes still have to be created, which `markReady`
+// below concludes once they're committed.
 let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampName: string) => {
   let chainIds = crossChainState.chainIds
 
@@ -145,15 +152,14 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
     }
   }
 
-  let indexerCaughtUp = crossChainState->nextItemIsNone && everyChainCaughtUp.contents
+  crossChainState.isCaughtUp =
+    crossChainState.isCaughtUp || (crossChainState->nextItemIsNone && everyChainCaughtUp.contents)
 
+  // A run resumed with every chain already stamped ready needs no finalize —
+  // the indexes were committed together with those stamps.
   let allChainsReady = ref(true)
   for i in 0 to chainIds->Array.length - 1 {
-    let cs = crossChainState->getChainState(chainIds->Array.getUnsafe(i))
-    if indexerCaughtUp {
-      cs->ChainState.markReady
-    }
-    if !(cs->ChainState.isReady) {
+    if !(crossChainState->getChainState(chainIds->Array.getUnsafe(i))->ChainState.isReady) {
       allChainsReady := false
     }
   }
@@ -161,6 +167,70 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
   crossChainState.isRealtime = crossChainState.isRealtime || allChainsReady.contents
 }
 
+// Every chain has buffered up to its head (or endblock) with nothing
+// processable left. Derived from current state rather than from the flag a
+// progressed batch sets, because a run that reached the head and died before
+// finalizing resumes with no batch to process — nothing would ever set it.
+let isSettledAtHead = (crossChainState: t) => {
+  let settled = ref(crossChainState->nextItemIsNone)
+  for i in 0 to crossChainState.chainIds->Array.length - 1 {
+    if (
+      !(
+        crossChainState
+        ->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
+        ->ChainState.isFetchingAtHead
+      )
+    ) {
+      settled := false
+    }
+  }
+  settled.contents
+}
+
+// Enter the FinalizingIndexes phase without a batch, for the resume above.
+let markCaughtUpIfSettled = (crossChainState: t) =>
+  if crossChainState->isSettledAtHead {
+    crossChainState.isCaughtUp = true
+  }
+
+// The same resume, decided from persisted values at construction instead of from
+// the fetch frontier. A run that reached the head and died before finalizing has
+// no batch to process on resume, and by the time the first height lands the head
+// may have moved on — at which point no chain looks at head any more and the
+// indexes it still owes would wait out another whole backfill. Deciding here,
+// before any source request, keeps that debt tied to the progress that was
+// actually committed. Skipped once every chain carries `ready_at`: those indexes
+// were committed together with the stamps.
+let markCaughtUpOnResume = (crossChainState: t) => {
+  let everyChainCaughtUp = ref(crossChainState.chainIds->Array.length > 0)
+  let everyChainReady = ref(true)
+  for i in 0 to crossChainState.chainIds->Array.length - 1 {
+    let cs = crossChainState->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
+    if !(cs->ChainState.isDurablyCaughtUp) {
+      everyChainCaughtUp := false
+    }
+    if !(cs->ChainState.isReady) {
+      everyChainReady := false
+    }
+  }
+
+  if everyChainCaughtUp.contents && !everyChainReady.contents && crossChainState->nextItemIsNone {
+    crossChainState.isCaughtUp = true
+  }
+}
+
+// Concludes the FinalizingIndexes phase: stamps every chain with the `ready_at`
+// already committed alongside the deferred schema indexes and switches the
+// indexer to realtime.
+let markReady = (crossChainState: t, ~readyAt) => {
+  for i in 0 to crossChainState.chainIds->Array.length - 1 {
+    crossChainState
+    ->getChainState(crossChainState.chainIds->Array.getUnsafe(i))
+    ->ChainState.markReady(~readyAt)
+  }
+  crossChainState.isRealtime = true
+}
+
 // --- Fetch control. ---
 
 // Chains ordered furthest-behind first by fetch-frontier progress, so the
@@ -226,7 +296,7 @@ let idleOrWaitAction = (cs: ChainState.t) =>
 // 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>,
+  ~dispatchChain: (~chainId: ChainId.t, ~action: FetchState.nextQuery) => promise<unit>,
 ) => {
   let targetBudget = crossChainState.targetBufferSize->Int.toFloat
   let remaining = ref(
@@ -274,14 +344,14 @@ let checkAndFetch = async (
       // hold the whole pool. (The general can't-fetch-yet rule, including
       // blockLag, lives in FetchState.getNextQuery — this branch only
       // short-circuits the unambiguous no-height case.)
-      actionByChain->Utils.Dict.setByInt(chainId, FetchState.WaitingForNewBlock)
+      actionByChain->ChainId.Dict.set(chainId, FetchState.WaitingForNewBlock)
     } else if remaining.contents < minimumAdmissionBudget {
       // More than 90% of the target pool is ready or reserved. Don't admit new
       // queries until a full admission unit becomes free. No wake-up poll is
       // needed: a saturated pool means some chain holds ready items or
       // in-flight reservations, so a batch completion or landing response is
       // guaranteed to schedule another tick that revisits this chain.
-      actionByChain->Utils.Dict.setByInt(chainId, FetchState.NothingToQuery)
+      actionByChain->ChainId.Dict.set(chainId, FetchState.NothingToQuery)
     } else {
       let isCold = cs->ChainState.effectiveDensity === None
       let chainTargetItems =
@@ -296,12 +366,12 @@ let checkAndFetch = async (
       | _ => None
       }
       switch cs->ChainState.getNextQuery(~chainTargetItems, ~maxTargetBlock?) {
-      | WaitingForNewBlock as action => actionByChain->Utils.Dict.setByInt(chainId, action)
+      | WaitingForNewBlock as action => actionByChain->ChainId.Dict.set(chainId, action)
       | NothingToQuery =>
         // A chain below its head can emit no query when its budget went to
         // more-behind chains or the cross-chain alignment clamped its range to
         // nothing — idleOrWaitAction keeps it polling for new blocks.
-        actionByChain->Utils.Dict.setByInt(chainId, idleOrWaitAction(cs))
+        actionByChain->ChainId.Dict.set(chainId, idleOrWaitAction(cs))
       | Ready(queries) => {
           let consumed =
             queries->Array.reduce(0., (acc, query: FetchState.query) =>
@@ -325,7 +395,7 @@ let checkAndFetch = async (
             "partitions": partitions,
           })
 
-          actionByChain->Utils.Dict.setByInt(chainId, FetchState.Ready(queries))
+          actionByChain->ChainId.Dict.set(chainId, FetchState.Ready(queries))
           // Mark the queries in flight and reserve their size against the
           // shared budget; released as each response lands in
           // handleQueryResult.
@@ -339,12 +409,10 @@ let checkAndFetch = async (
   let promises = []
   for i in 0 to crossChainState.chainIds->Array.length - 1 {
     let chainId = crossChainState.chainIds->Array.getUnsafe(i)
-    switch actionByChain->Utils.Dict.dangerouslyGetByIntNonOption(chainId) {
+    switch actionByChain->ChainId.Dict.dangerouslyGetNonOption(chainId) {
     | Some(NothingToQuery)
     | None => ()
-    | Some(action) =>
-      let chain = ChainMap.Chain.makeUnsafe(~chainId)
-      promises->Array.push(dispatchChain(~chain, ~action))
+    | Some(action) => promises->Array.push(dispatchChain(~chainId=chainId, ~action))
     }
   }
   let _ = await promises->Promise.all