envio 3.5.0-alpha.1 → 3.5.0-alpha.2

package/src/Metrics.res

@@ -98,12 +98,19 @@ type sourceHeightMetrics = {
 
 type t = {
   startTime: Date.t,
+  // Wall clock when this snapshot was built, so a scrape can be dated.
+  metricTime: Date.t,
+  // Measured monotonically, not as metricTime - startTime: a wall-clock
+  // correction would otherwise skew the counter shares derived from it.
+  elapsedSeconds: float,
   targetBufferSize: int,
   isInReorgThreshold: bool,
   rollbackEnabled: bool,
   maxBatchSize: int,
   preloadSeconds: float,
   processingSeconds: float,
+  processingStalledOnFetchSeconds: float,
+  processingStalledOnStorageWriteSeconds: float,
   rollbackSeconds: float,
   rollbackCount: int,
   rollbackEventsCount: float,
@@ -241,6 +248,24 @@ let renderMetrics = (b: builder, metrics: t) => {
     byLabels->Dict.toArray
   }
 
+  b->single(
+    ~name="envio_process_start_time_seconds",
+    ~help="Start time of the process since unix epoch in seconds.",
+    ~kind="gauge",
+    ~value=metrics.startTime->Date.getTime /. 1000.,
+  )
+  b->single(
+    ~name="envio_process_metric_time_seconds",
+    ~help="The time these metrics were collected. Use it to tell how fresh a snapshot is, or to measure rates between two snapshots.",
+    ~kind="gauge",
+    ~value=metrics.metricTime->Date.getTime /. 1000.,
+  )
+  b->single(
+    ~name="envio_process_elapsed_seconds",
+    ~help="How long the indexer has been running. Divide a cumulative seconds metric by this to get the share of the run it took, eg envio_processing_seconds for time spent in event handlers.",
+    ~kind="gauge",
+    ~value=metrics.elapsedSeconds,
+  )
   b->single(
     ~name="envio_preload_seconds",
     ~help="Cumulative time spent on preloading entities during batch processing.",
@@ -253,6 +278,18 @@ let renderMetrics = (b: builder, metrics: t) => {
     ~kind="counter",
     ~value=metrics.processingSeconds,
   )
+  b->single(
+    ~name="envio_processing_stalled_on_fetch_seconds",
+    ~help="Time the indexer had nothing to process while waiting for events to be fetched. A high rate means fetching is the bottleneck: check the data-source latency and whether it can be queried with more concurrency. Waiting at the chain head for new blocks is not counted.",
+    ~kind="counter",
+    ~value=metrics.processingStalledOnFetchSeconds,
+  )
+  b->single(
+    ~name="envio_processing_stalled_on_storage_write_seconds",
+    ~help="Time the indexer paused processing because too many changes were still waiting to be written. A high rate means storage writes are the bottleneck: check envio_storage_write_seconds and the database performance.",
+    ~kind="counter",
+    ~value=metrics.processingStalledOnStorageWriteSeconds,
+  )
   b->series(
     ~name="envio_progress_ready",
     ~help="Whether the chain is fully synced to the head.",
@@ -346,12 +383,6 @@ let renderMetrics = (b: builder, metrics: t) => {
     ~entries=chains,
     ~value=m => m.sourceBlockNumber->Int.toFloat,
   )
-  b->single(
-    ~name="envio_process_start_time_seconds",
-    ~help="Start time of the process since unix epoch in seconds.",
-    ~kind="gauge",
-    ~value=metrics.startTime->Date.getTime /. 1000.,
-  )
   b->series(
     ~name="envio_indexing_concurrency",
     ~help="The number of executing concurrent queries to the chain data-source.",

package/src/Metrics.res.mjs

@@ -108,8 +108,13 @@ function renderMetrics(b, metrics) {
     }
   });
   let sources = Object.entries(byLabels$1);
+  single(b, "envio_process_start_time_seconds", "Start time of the process since unix epoch in seconds.", "gauge", metrics.startTime.getTime() / 1000);
+  single(b, "envio_process_metric_time_seconds", "The time these metrics were collected. Use it to tell how fresh a snapshot is, or to measure rates between two snapshots.", "gauge", metrics.metricTime.getTime() / 1000);
+  single(b, "envio_process_elapsed_seconds", "How long the indexer has been running. Divide a cumulative seconds metric by this to get the share of the run it took, eg envio_processing_seconds for time spent in event handlers.", "gauge", metrics.elapsedSeconds);
   single(b, "envio_preload_seconds", "Cumulative time spent on preloading entities during batch processing.", "counter", metrics.preloadSeconds);
   single(b, "envio_processing_seconds", "Cumulative time spent executing event handlers during batch processing.", "counter", metrics.processingSeconds);
+  single(b, "envio_processing_stalled_on_fetch_seconds", "Time the indexer had nothing to process while waiting for events to be fetched. A high rate means fetching is the bottleneck: check the data-source latency and whether it can be queried with more concurrency. Waiting at the chain head for new blocks is not counted.", "counter", metrics.processingStalledOnFetchSeconds);
+  single(b, "envio_processing_stalled_on_storage_write_seconds", "Time the indexer paused processing because too many changes were still waiting to be written. A high rate means storage writes are the bottleneck: check envio_storage_write_seconds and the database performance.", "counter", metrics.processingStalledOnStorageWriteSeconds);
   series(b, "envio_progress_ready", "Whether the chain is fully synced to the head.", "gauge", chains, m => {
     if (m.isReady) {
       return 1;
@@ -129,7 +134,6 @@ function renderMetrics(b, metrics) {
   series(b, "envio_fetching_block_range_events_total", "Cumulative number of events fetched across all block range operations.", "counter", chains, m => m.blockRangeFetchedEvents);
   series(b, "envio_fetching_block_range_size", "Cumulative number of blocks covered across all block range fetch operations.", "counter", chains, m => m.blockRangeFetchedBlocks);
   series(b, "envio_indexing_known_height", "The latest known block number reported by the active indexing source. This value may lag behind the actual chain height, as it is updated only when needed.", "gauge", chains, m => m.sourceBlockNumber);
-  single(b, "envio_process_start_time_seconds", "Start time of the process since unix epoch in seconds.", "gauge", metrics.startTime.getTime() / 1000);
   series(b, "envio_indexing_concurrency", "The number of executing concurrent queries to the chain data-source.", "gauge", chains, m => m.concurrency);
   series(b, "envio_indexing_partitions", "The number of partitions used to split fetching logic by addresses and block ranges.", "gauge", chains, m => m.partitionsCount);
   series(b, "envio_indexing_idle_seconds", "The time the indexer source syncing has been idle. A high value may indicate the source sync is a bottleneck.", "counter", chains, m => m.idleSeconds);

package/src/Persistence.res

@@ -121,7 +121,7 @@ type storage = {
   getRollbackData: (
     ~entityConfig: Internal.entityConfig,
     ~rollbackTargetCheckpointId: Internal.checkpointId,
-  ) => promise<(array<string>, array<unknown>)>,
+  ) => promise<(array<EntityId.t>, array<unknown>)>,
   // Write batch to storage
   writeBatch: (
     ~batch: Batch.t,

package/src/PgStorage.res

@@ -158,7 +158,10 @@ let getEntityHistory = (~entityConfig: Internal.entityConfig): EntityHistory.pgE
         ~fields=dataFields->Array.concat([checkpointIdField, actionField]),
       )
 
-      let setChangeSchema = EntityHistory.makeSetUpdateSchema(entityConfig.schema)
+      let setChangeSchema = EntityHistory.makeSetUpdateSchema(
+        ~idSchema=entityConfig.table->Table.getIdSchema,
+        entityConfig.schema,
+      )
 
       {
         EntityHistory.table,
@@ -355,8 +358,8 @@ let makeDeleteByIdQuery = (~pgSchema, ~tableName) => {
   `DELETE FROM "${pgSchema}"."${tableName}" WHERE id = $1;`
 }
 
-let makeDeleteByIdsQuery = (~pgSchema, ~tableName) => {
-  `DELETE FROM "${pgSchema}"."${tableName}" WHERE id = ANY($1::text[]);`
+let makeDeleteByIdsQuery = (~pgSchema, ~tableName, ~idPgType) => {
+  `DELETE FROM "${pgSchema}"."${tableName}" WHERE id = ANY($1::${idPgType}[]);`
 }
 
 let makeLoadAllQuery = (~pgSchema, ~tableName) => {
@@ -744,18 +747,26 @@ let getConnectedPsqlExec = {
   }
 }
 
-let deleteByIdsOrThrow = async (sql, ~pgSchema, ~ids, ~table: Table.table) => {
+let deleteByIdsOrThrow = async (sql, ~pgSchema, ~ids: array<EntityId.t>, ~table: Table.table) => {
+  // A JSON array of the serialized ids. For a single id the query binds it as
+  // `$1` directly (the array is the positional-params array); for many it binds
+  // the whole array to `$1` behind an `ANY(...)`.
+  let idsJson = table->Table.encodeIdsToJson(ids)
   switch await (
     switch ids {
     | [_] =>
       sql->Postgres.preparedUnsafe(
         makeDeleteByIdQuery(~pgSchema, ~tableName=table.tableName),
-        ids->Obj.magic,
+        idsJson->Obj.magic,
       )
     | _ =>
       sql->Postgres.preparedUnsafe(
-        makeDeleteByIdsQuery(~pgSchema, ~tableName=table.tableName),
-        [ids]->Obj.magic,
+        makeDeleteByIdsQuery(
+          ~pgSchema,
+          ~tableName=table.tableName,
+          ~idPgType=table->Table.getIdPgFieldType(~pgSchema),
+        ),
+        [idsJson]->Obj.magic,
       )
     }
   ) {
@@ -811,9 +822,11 @@ let makeInsertDeleteUpdatesQuery = (~entityConfig: Internal.entityConfig, ~pgSch
     ~isNullable=false,
   )
 
+  let idPgType = entityConfig.table->Table.getIdPgFieldType(~pgSchema)
+
   `INSERT INTO "${pgSchema}"."${historyTableName}" (${allHistoryFieldNamesStr})
 SELECT ${selectPartsStr}
-FROM UNNEST($1::text[], $2::${checkpointIdPgType}[]) AS u(${Table.idFieldName}, ${EntityHistory.checkpointIdFieldName})`
+FROM UNNEST($1::${idPgType}[], $2::${checkpointIdPgType}[]) AS u(${Table.idFieldName}, ${EntityHistory.checkpointIdFieldName})`
 }
 
 let executeSet = (
@@ -912,17 +925,21 @@ let rec writeBatch = async (
       // Single pass over the change log: track each id's latest change (the last
       // one seen) and, when saving history, fan every non-diff change out to the
       // history-table batches.
+      // Keyed/deduped in memory by the id's string key (toKey), while the
+      // batches sent to SQL keep the real id values so they serialize with the
+      // id column's type.
       let latestChangeById = Dict.make()
       let orderedIds = []
       changes->Array.forEach(change => {
         let entityId = change->Change.getEntityId
-        if latestChangeById->Utils.Dict.dangerouslyGetNonOption(entityId)->Option.isNone {
+        let entityKey = entityId->EntityId.toKey
+        if latestChangeById->Utils.Dict.dangerouslyGetNonOption(entityKey)->Option.isNone {
           orderedIds->Array.push(entityId)
         }
-        latestChangeById->Dict.set(entityId, change)
+        latestChangeById->Dict.set(entityKey, change)
         if shouldSaveHistory {
           if Some(change->Change.getCheckpointId) === diffCheckpointId {
-            idsWithDiff->Utils.Set.add(entityId)->ignore
+            idsWithDiff->Utils.Set.add(entityKey)->ignore
           } else {
             switch change {
             | Delete({entityId, checkpointId}) =>
@@ -936,13 +953,14 @@ let rec writeBatch = async (
 
       let backfillHistoryIds = Utils.Set.make()
       orderedIds->Array.forEach(entityId => {
-        switch latestChangeById->Dict.getUnsafe(entityId) {
+        let entityKey = entityId->EntityId.toKey
+        switch latestChangeById->Dict.getUnsafe(entityKey) {
         | Set({entity}) => entitiesToSet->Array.push(entity)
         | Delete({entityId}) => idsToDelete->Array.push(entityId)
         }
 
         // An id needs a history backfill iff none of its changes is the diff.
-        if shouldSaveHistory && !(idsWithDiff->Utils.Set.has(entityId)) {
+        if shouldSaveHistory && !(idsWithDiff->Utils.Set.has(entityKey)) {
           backfillHistoryIds->Utils.Set.add(entityId)->ignore
         }
       })
@@ -962,7 +980,7 @@ let rec writeBatch = async (
               await EntityHistory.backfillHistory(
                 sql,
                 ~pgSchema,
-                ~entityName=entityConfig.name,
+                ~table=entityConfig.table,
                 ~entityIndex=entityConfig.index,
                 ~ids=backfillHistoryIds->Utils.Set.toArray,
               )
@@ -974,7 +992,7 @@ let rec writeBatch = async (
                 ->Postgres.preparedUnsafe(
                   makeInsertDeleteUpdatesQuery(~entityConfig, ~pgSchema),
                   (
-                    batchDeleteEntityIds,
+                    entityConfig.table->Table.encodeIdsToJson(batchDeleteEntityIds),
                     batchDeleteCheckpointIds->Utils.BigInt.arrayToStringArray,
                   )->Obj.magic,
                 )
@@ -1230,10 +1248,25 @@ let makeGetRollbackRemovedIdsQuery = (~entityConfig: Internal.entityConfig, ~pgS
     )`
 }
 
-let rollbackRowStateSchema = S.object(s => (
-  s.field(Table.idFieldName, S.string),
-  s.field(EntityHistory.changeFieldName, EntityHistory.RowAction.schema),
-))
+// Memoized per table so the id is parsed with that entity's id schema (a
+// numeric id comes back from Postgres as a number, not a string) and the
+// schema's operations compile once rather than per rollback row.
+let rollbackRowStateSchema: Table.table => S.t<(
+  EntityId.t,
+  EntityHistory.RowAction.t,
+)> = Utils.WeakMap.memoize(table =>
+  S.object(s => (
+    s.field(Table.idFieldName, table->Table.getIdSchema),
+    s.field(EntityHistory.changeFieldName, EntityHistory.RowAction.schema),
+  ))
+)
+
+// Same reason as above for the id-only rows: both rollback queries must yield
+// ids in the entity's own representation, or the two halves of the diff would
+// disagree (Postgres hands back a NUMERIC id as a string, not a bigint).
+let rollbackRemovedIdsSchema: Table.table => S.t<array<EntityId.t>> = Utils.WeakMap.memoize(table =>
+  S.array(S.object(s => s.field(Table.idFieldName, table->Table.getIdSchema)))
+)
 
 let make = (
   ~sql: Postgres.sql,
@@ -1757,7 +1790,7 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
         makeGetRollbackRemovedIdsQuery(~entityConfig, ~pgSchema),
         [rollbackTargetCheckpointId->BigInt.toString]->(Utils.magic: array<string> => unknown),
       )
-      ->(Utils.magic: promise<unknown> => promise<array<{"id": string}>>),
+      ->(Utils.magic: promise<unknown> => promise<array<unknown>>),
       // Get the latest pre-target row, including its SET or DELETE action.
       sql
       ->Postgres.preparedUnsafe(
@@ -1767,10 +1800,10 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
       ->(Utils.magic: promise<unknown> => promise<array<unknown>>),
     ))
 
-    let removedIds = removedIdRows->Array.map(row => row["id"])
+    let removedIds = removedIdRows->S.parseOrThrow(rollbackRemovedIdsSchema(entityConfig.table))
     let restoredEntitiesResult = []
     rollbackRows->Array.forEach(row => {
-      let (entityId, action) = row->S.parseOrThrow(rollbackRowStateSchema)
+      let (entityId, action) = row->S.parseOrThrow(rollbackRowStateSchema(entityConfig.table))
       switch action {
       | SET => restoredEntitiesResult->Array.push(row)->ignore
       | DELETE => removedIds->Array.push(entityId)->ignore

package/src/PgStorage.res.mjs

@@ -10,6 +10,7 @@ import * as Config from "./Config.res.mjs";
 import * as Hasura from "./Hasura.res.mjs";
 import * as Schema from "./db/Schema.res.mjs";
 import * as Logging from "./Logging.res.mjs";
+import * as EntityId from "./EntityId.res.mjs";
 import * as Internal from "./Internal.res.mjs";
 import Postgres from "postgres";
 import * as ChainState from "./ChainState.res.mjs";
@@ -157,7 +158,7 @@ function getEntityHistory(entityConfig) {
     checkpointIdField,
     actionField
   ]), undefined);
-  let setChangeSchema = EntityHistory.makeSetUpdateSchema(entityConfig.schema);
+  let setChangeSchema = EntityHistory.makeSetUpdateSchema(Table.getIdSchema(entityConfig.table), entityConfig.schema);
   let cache_setChangeSchemaRows = S$RescriptSchema.array(setChangeSchema);
   let cache$1 = {
     table: table,
@@ -292,8 +293,8 @@ function makeDeleteByIdQuery(pgSchema, tableName) {
   return `DELETE FROM "` + pgSchema + `"."` + tableName + `" WHERE id = $1;`;
 }
 
-function makeDeleteByIdsQuery(pgSchema, tableName) {
-  return `DELETE FROM "` + pgSchema + `"."` + tableName + `" WHERE id = ANY($1::text[]);`;
+function makeDeleteByIdsQuery(pgSchema, tableName, idPgType) {
+  return `DELETE FROM "` + pgSchema + `"."` + tableName + `" WHERE id = ANY($1::` + idPgType + `[]);`;
 }
 
 function makeLoadAllQuery(pgSchema, tableName) {
@@ -547,9 +548,10 @@ async function getConnectedPsqlExec(pgUser, pgHost, pgDatabase, pgPort, containe
 }
 
 async function deleteByIdsOrThrow(sql, pgSchema, ids, table) {
+  let idsJson = Table.encodeIdsToJson(table, ids);
   try {
     await (
-      ids.length !== 1 ? sql.unsafe(makeDeleteByIdsQuery(pgSchema, table.tableName), [ids], {prepare: true}) : sql.unsafe(makeDeleteByIdQuery(pgSchema, table.tableName), ids, {prepare: true})
+      ids.length !== 1 ? sql.unsafe(makeDeleteByIdsQuery(pgSchema, table.tableName, Table.getIdPgFieldType(table, pgSchema)), [idsJson], {prepare: true}) : sql.unsafe(makeDeleteByIdQuery(pgSchema, table.tableName), idsJson, {prepare: true})
     );
     return;
   } catch (raw_exn) {
@@ -586,9 +588,10 @@ function makeInsertDeleteUpdatesQuery(entityConfig, pgSchema) {
   });
   let selectPartsStr = selectParts.join(", ");
   let checkpointIdPgType = Table.getPgFieldType(EntityHistory.checkpointIdFieldType, pgSchema, false, false, false);
+  let idPgType = Table.getIdPgFieldType(entityConfig.table, pgSchema);
   return `INSERT INTO "` + pgSchema + `"."` + historyTableName + `" (` + allHistoryFieldNamesStr + `)
 SELECT ` + selectPartsStr + `
-FROM UNNEST($1::text[], $2::` + checkpointIdPgType + `[]) AS u(` + Table.idFieldName + `, ` + EntityHistory.checkpointIdFieldName + `)`;
+FROM UNNEST($1::` + idPgType + `[], $2::` + checkpointIdPgType + `[]) AS u(` + Table.idFieldName + `, ` + EntityHistory.checkpointIdFieldName + `)`;
 }
 
 function executeSet(sql, items, dbFunction) {
@@ -648,15 +651,16 @@ async function writeBatch(sql, batch, pgSchema, rollback, isInReorgThreshold, co
       let orderedIds = [];
       param.changes.forEach(change => {
         let entityId = change.entityId;
-        if (Stdlib_Option.isNone(latestChangeById[entityId])) {
+        let entityKey = EntityId.toKey(entityId);
+        if (Stdlib_Option.isNone(latestChangeById[entityKey])) {
           orderedIds.push(entityId);
         }
-        latestChangeById[entityId] = change;
+        latestChangeById[entityKey] = change;
         if (!shouldSaveHistory) {
           return;
         }
         if (change.checkpointId === diffCheckpointId) {
-          idsWithDiff.add(entityId);
+          idsWithDiff.add(entityKey);
           return;
         }
         if (change.type === "SET") {
@@ -668,13 +672,14 @@ async function writeBatch(sql, batch, pgSchema, rollback, isInReorgThreshold, co
       });
       let backfillHistoryIds = new Set();
       orderedIds.forEach(entityId => {
-        let match = latestChangeById[entityId];
+        let entityKey = EntityId.toKey(entityId);
+        let match = latestChangeById[entityKey];
         if (match.type === "SET") {
           entitiesToSet.push(match.entity);
         } else {
           idsToDelete.push(match.entityId);
         }
-        if (shouldSaveHistory && !idsWithDiff.has(entityId)) {
+        if (shouldSaveHistory && !idsWithDiff.has(entityKey)) {
           backfillHistoryIds.add(entityId);
           return;
         }
@@ -685,11 +690,11 @@ async function writeBatch(sql, batch, pgSchema, rollback, isInReorgThreshold, co
           let promises = [];
           if (shouldSaveHistory) {
             if (backfillHistoryIds.size !== 0) {
-              await EntityHistory.backfillHistory(sql, pgSchema, entityConfig.name, entityConfig.index, Array.from(backfillHistoryIds));
+              await EntityHistory.backfillHistory(sql, pgSchema, entityConfig.table, entityConfig.index, Array.from(backfillHistoryIds));
             }
             if (Utils.$$Array.notEmpty(batchDeleteCheckpointIds)) {
               promises.push(sql.unsafe(makeInsertDeleteUpdatesQuery(entityConfig, pgSchema), [
-                batchDeleteEntityIds,
+                Table.encodeIdsToJson(entityConfig.table, batchDeleteEntityIds),
                 Utils.$$BigInt.arrayToStringArray(batchDeleteCheckpointIds)
               ], {prepare: true}));
             }
@@ -822,10 +827,12 @@ function makeGetRollbackRemovedIdsQuery(entityConfig, pgSchema) {
     )`;
 }
 
-let rollbackRowStateSchema = S$RescriptSchema.object(s => [
-  s.f(Table.idFieldName, S$RescriptSchema.string),
+let rollbackRowStateSchema = Utils.$$WeakMap.memoize(table => S$RescriptSchema.object(s => [
+  s.f(Table.idFieldName, Table.getIdSchema(table)),
   s.f(EntityHistory.changeFieldName, EntityHistory.RowAction.schema)
-]);
+]));
+
+let rollbackRemovedIdsSchema = Utils.$$WeakMap.memoize(table => S$RescriptSchema.array(S$RescriptSchema.object(s => s.f(Table.idFieldName, Table.getIdSchema(table)))));
 
 function make(sql, pgHost, pgSchema, pgPort, pgUser, pgDatabase, pgPassword, isHasuraEnabled, sink, onInitialize, onNewTables) {
   let containerName = "envio-postgres";
@@ -1147,10 +1154,10 @@ SELECT id, chain_id, -1, -1, contract_name FROM unnest($1::text[],$2::int[],$3::
       sql.unsafe(makeGetRollbackRemovedIdsQuery(entityConfig, pgSchema), [rollbackTargetCheckpointId.toString()], {prepare: true}),
       sql.unsafe(makeGetRollbackPreTargetRowsQuery(entityConfig, pgSchema), [rollbackTargetCheckpointId.toString()], {prepare: true})
     ]);
-    let removedIds = match[0].map(row => row.id);
+    let removedIds = S$RescriptSchema.parseOrThrow(match[0], rollbackRemovedIdsSchema(entityConfig.table));
     let restoredEntitiesResult = [];
     match[1].forEach(row => {
-      let match = S$RescriptSchema.parseOrThrow(row, rollbackRowStateSchema);
+      let match = S$RescriptSchema.parseOrThrow(row, rollbackRowStateSchema(entityConfig.table));
       if (match[1] === "SET") {
         restoredEntitiesResult.push(row);
         return;
@@ -1297,6 +1304,7 @@ export {
   makeGetRollbackPreTargetRowsQuery,
   makeGetRollbackRemovedIdsQuery,
   rollbackRowStateSchema,
+  rollbackRemovedIdsSchema,
   make,
   makeStorageFromEnv,
   makePersistenceFromConfig,

package/src/SimulateItems.res

@@ -343,8 +343,8 @@ let parse = (
       // run here the way real routing does (one item per registration).
       // Registrations are built the same way `HandlerRegister.finishRegistration`
       // does at startup (not stubs), so the address filter and `where` behave
-      // identically to real indexing — the dead-input tracker relies on
-      // `clientAddressFilter` actually gating unrouted items. Drop registrations
+      // identically to real indexing — the dead-input tracker relies on the
+      // source's address gate actually dropping unrouted items. Drop registrations
       // whose `where` excludes this chain (they wouldn't be fetched live), and
       // ignore the bare handler-less fallback so a missing handler surfaces below
       // instead of silently running nothing.

package/src/TestIndexer.res

@@ -22,7 +22,7 @@ type t<'processConfig> = {process: 'processConfig => promise<processResult>}
 
 type entityChange = {
   sets: array<unknown>,
-  deleted: array<string>,
+  deleted: array<EntityId.t>,
 }
 
 type testIndexerState = {
@@ -136,11 +136,12 @@ let handleWriteBatch = (
       switch change {
       | Set({entityId, entity, checkpointId}) =>
         // The store keeps decoded entities so load comparisons (bigint /
-        // BigDecimal) work on real values.
-        entityDict->Dict.set(entityId, entity)
+        // BigDecimal) work on real values. Ids are keyed by their string form
+        // since they may be string/int/bigint.
+        entityDict->Dict.set(entityId->EntityId.toKey, entity)
         entityChangeFor(checkpointId).sets->Array.push(entity->Utils.magic)->ignore
       | Delete({entityId, checkpointId}) =>
-        Dict.delete(entityDict->Obj.magic, entityId)
+        Dict.delete(entityDict->Obj.magic, entityId->EntityId.toKey)
         entityChangeFor(checkpointId).deleted->Array.push(entityId)->ignore
       }
     }
@@ -197,7 +198,7 @@ let handleWriteBatch = (
             entityObj->Dict.set("sets", sets->(Utils.magic: array<unknown> => unknown))
           }
           if deleted->Array.length > 0 {
-            entityObj->Dict.set("deleted", deleted->(Utils.magic: array<string> => unknown))
+            entityObj->Dict.set("deleted", deleted->(Utils.magic: array<EntityId.t> => unknown))
           }
           // Match the capitalized entity accessor the generated change types expose.
           change->Dict.set(

package/src/TestIndexer.res.mjs

@@ -5,6 +5,7 @@ import * as Utils from "./Utils.res.mjs";
 import * as Config from "./Config.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
+import * as EntityId from "./EntityId.res.mjs";
 import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
 import * as IndexerLoop from "./IndexerLoop.res.mjs";
 import * as Persistence from "./Persistence.res.mjs";
@@ -102,12 +103,12 @@ function handleWriteBatch(state, updatedEntities, checkpointIds, checkpointChain
     let processChange = change => {
       if (change.type === "SET") {
         let entity = change.entity;
-        entityDict[change.entityId] = entity;
+        entityDict[EntityId.toKey(change.entityId)] = entity;
         entityChangeFor(change.checkpointId).sets.push(entity);
         return;
       }
       let entityId = change.entityId;
-      Stdlib_Dict.$$delete(entityDict, entityId);
+      Stdlib_Dict.$$delete(entityDict, EntityId.toKey(entityId));
       entityChangeFor(change.checkpointId).deleted.push(entityId);
     };
     param.changes.forEach(processChange);

package/src/UserContext.res

@@ -144,7 +144,7 @@ let getWhereHandler = (params: entityContextParams, filter: dict<dict<unknown>>)
 }
 
 let noopSet = (_entity: Internal.entity) => ()
-let noopDeleteUnsafe = (_entityId: string) => ()
+let noopDeleteUnsafe = (_entityId: EntityId.t) => ()
 
 // Reads against ClickHouse-only entities have no Postgres table to hit;
 // surface a friendly error instead of letting the SQL layer fail with
@@ -168,7 +168,7 @@ let entityTraps: Utils.Proxy.traps<entityContextParams> = {
           ->InMemoryTable.Entity.set(
             ~committedCheckpointId=params.indexerState->IndexerState.committedCheckpointId,
             Set({
-              entityId: entity.id,
+              entityId: entity.id->EntityId.unsafeOfString,
               checkpointId: params.checkpointId,
               entity,
             }),
@@ -282,7 +282,7 @@ let entityTraps: Utils.Proxy.traps<entityContextParams> = {
             }),
           )
         }
-      }->(Utils.magic: (string => unit) => unknown)
+      }->(Utils.magic: (EntityId.t => unit) => unknown)
     | _ =>
       JsError.throwWithMessage(`Invalid context.${params.entityConfig.name}.${prop} operation.`)
     }

package/src/Writing.res

@@ -237,7 +237,7 @@ let dropCommitted = (state: IndexerState.t, ~keepLoadedFromDb) => {
 
 // Blocks until the store holds fewer than keepLatestChangesLimit changes,
 // freeing committed changes first and awaiting commits as a last resort.
-let rec awaitCapacity = async (state: IndexerState.t) => {
+let rec awaitCapacityLoop = async (state: IndexerState.t) => {
   // After a failed write nothing will free capacity, so bail instead of waiting
   // on a commit that won't come (the error already went to onError).
   if !(state->IndexerState.hasFailedWrite) && state->getChangesCount >= keepLatestChangesLimit {
@@ -259,11 +259,21 @@ let rec awaitCapacity = async (state: IndexerState.t) => {
     ) {
       state->schedule
       await state->waitForCommit
-      await state->awaitCapacity
+      await state->awaitCapacityLoop
     }
   }
 }
 
+// Only the over-limit path is a real stall. Timing every call would charge each
+// batch the microtask hop of awaiting an already-resolved promise, which reads
+// as storage backpressure that isn't there.
+let awaitCapacity = async (state: IndexerState.t) =>
+  if state->getChangesCount >= keepLatestChangesLimit {
+    let timeRef = Performance.now()
+    await state->awaitCapacityLoop
+    state->IndexerState.recordStalledOnStorageWrite(~seconds=timeRef->Performance.secondsSince)
+  }
+
 // Awaits until everything processed is persisted. On a failed write we stop
 // draining (onError already surfaced it) rather than throw.
 let rec flush = async (state: IndexerState.t) => {

package/src/Writing.res.mjs

@@ -4,6 +4,7 @@ import * as Env from "./Env.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Throttler from "./Throttler.res.mjs";
 import * as EffectState from "./EffectState.res.mjs";
+import * as Performance from "./bindings/Performance.res.mjs";
 import * as IndexerState from "./IndexerState.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as InMemoryStore from "./InMemoryStore.res.mjs";
@@ -182,7 +183,7 @@ function dropCommitted(state, keepLoadedFromDb) {
   EffectState.forEach(IndexerState.effectState(state), inMemTable => InMemoryStore.dropCommittedEffects(inMemTable, committedCheckpointId, keepLoadedFromDb));
 }
 
-async function awaitCapacity(state) {
+async function awaitCapacityLoop(state) {
   if (!IndexerState.hasFailedWrite(state) && getChangesCount(state) >= Env.inMemoryObjectsTarget) {
     dropCommitted(state, true);
     if (getChangesCount(state) >= Env.inMemoryObjectsTarget) {
@@ -191,13 +192,22 @@ async function awaitCapacity(state) {
     if (getChangesCount(state) >= Env.inMemoryObjectsTarget && Utils.$$Array.notEmpty(IndexerState.processedBatches(state))) {
       schedule(state);
       await new Promise((resolve, param) => IndexerState.addCommitWaiter(state, resolve));
-      return await awaitCapacity(state);
+      return await awaitCapacityLoop(state);
     } else {
       return;
     }
   }
 }
 
+async function awaitCapacity(state) {
+  if (getChangesCount(state) < Env.inMemoryObjectsTarget) {
+    return;
+  }
+  let timeRef = Performance.now();
+  await awaitCapacityLoop(state);
+  return IndexerState.recordStalledOnStorageWrite(state, Performance.secondsSince(timeRef));
+}
+
 async function flush(state) {
   if (IndexerState.hasFailedWrite(state)) {
     return;
@@ -224,6 +234,7 @@ export {
   setChainMeta,
   commitBatch,
   dropCommitted,
+  awaitCapacityLoop,
   awaitCapacity,
   flush,
 }

package/src/bindings/ClickHouse.res

@@ -91,7 +91,6 @@ let getClickHouseFieldType = (
         ->Array.joinUnsafe(", ")
       `${enumType}(${enumValues})`
     }
-  | Entity(_) => "String"
   }
 
   let baseType = if isArray {
@@ -261,11 +260,14 @@ let setUpdatesOrThrow = async (
         convertOrThrow: S.compile(
           S.array(
             S.union([
-              EntityHistory.makeSetUpdateSchema(makeClickHouseEntitySchema(entityConfig.table)),
+              EntityHistory.makeSetUpdateSchema(
+                ~idSchema=entityConfig.table->Table.getIdSchema,
+                makeClickHouseEntitySchema(entityConfig.table),
+              ),
               S.object(s => {
                 s.tag(EntityHistory.changeFieldName, EntityHistory.RowAction.DELETE)
                 Change.Delete({
-                  entityId: s.field(Table.idFieldName, S.string),
+                  entityId: s.field(Table.idFieldName, entityConfig.table->Table.getIdSchema),
                   checkpointId: s.field(
                     EntityHistory.checkpointIdFieldName,
                     EntityHistory.unsafeCheckpointIdSchema,

package/src/bindings/ClickHouse.res.mjs

@@ -68,9 +68,6 @@ function getClickHouseFieldType(fieldType, isNullable, isArray) {
         let enumValues = config$1.variants.map(variant => `'` + variant + `'`).join(", ");
         baseType = enumType + `(` + enumValues + `)`;
         break;
-      case "Entity" :
-        baseType = "String";
-        break;
     }
   }
   let baseType$1 = isArray ? `Array(` + baseType + `)` : baseType;
@@ -203,12 +200,12 @@ async function setUpdatesOrThrow(client, cache, changes, entityConfig, database)
   } else {
     let cached_tableName = database + `.\`` + EntityHistory.historyTableName(entityConfig.name, entityConfig.index) + `\``;
     let cached_convertOrThrow = S$RescriptSchema.compile(S$RescriptSchema.array(S$RescriptSchema.union([
-      EntityHistory.makeSetUpdateSchema(makeClickHouseEntitySchema(entityConfig.table)),
+      EntityHistory.makeSetUpdateSchema(Table.getIdSchema(entityConfig.table), makeClickHouseEntitySchema(entityConfig.table)),
       S$RescriptSchema.object(s => {
         s.tag(EntityHistory.changeFieldName, "DELETE");
         return {
           type: "DELETE",
-          entityId: s.f(Table.idFieldName, S$RescriptSchema.string),
+          entityId: s.f(Table.idFieldName, Table.getIdSchema(entityConfig.table)),
           checkpointId: s.f(EntityHistory.checkpointIdFieldName, EntityHistory.unsafeCheckpointIdSchema)
         };
       })