envio 3.13.0 → 3.14.0-subgraph

package/src/Core.res

@@ -12,6 +12,7 @@ type transactionStoreCtor
 type blockStoreCtor
 type clickHouseSinkCtor
 type addressStoreCtor
+type tuiCtor
 // Test-only: a local HyperSync server, bound by MockHyperSyncServer in envio-tests.
 type mockHyperSyncServerCtor
 type fromUserApiOptions = {
@@ -27,12 +28,25 @@ type fromUserApiResult = {
   indexerCode: Null.t<string>,
 }
 
+type fromSubgraphOptions = {
+  name?: string,
+  env?: dict<string>,
+  files?: dict<string>,
+  root?: string,
+}
+
 type addon = {
   getConfigJson: (~configPath: Null.t<string>, ~directory: Null.t<string>) => string,
+  fromSubgraph: (string, string, fromSubgraphOptions) => fromUserApiResult,
+  subgraphFileToJavascript: (string, string) => string,
   encodeIndexedTopic: (~abiType: string, ~value: unknown) => EvmTypes.Hex.t,
   isSvmPubkey: (~value: string) => bool,
   fromUserApi: (string, fromUserApiOptions) => fromUserApiResult,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
+  loadTs: string => string,
+  tsCheckHandlerFormat: string => unit,
+  tsResolveCandidates: (string, Null.t<string>) => array<string>,
+  tsNotFoundCandidates: (string, Null.t<string>, string) => array<string>,
   @as("EvmHyperSyncClient")
   evmHyperSyncClient: evmHyperSyncClientCtor,
   @as("EvmRpcClient")
@@ -49,6 +63,8 @@ type addon = {
   addressStore: addressStoreCtor,
   @as("ClickHouseSink")
   clickHouseSink: clickHouseSinkCtor,
+  @as("Tui")
+  tui: tuiCtor,
   @as("MockHyperSyncServer")
   mockHyperSyncServer: mockHyperSyncServerCtor,
   encodeAddresses: (~ecosystem: string, ~addresses: array<Address.t>) => array<NodeJs.Buffer.t>,
@@ -99,7 +115,7 @@ let callRequire: ({..}, string) => addon = %raw(`(req, id) => req(id)`)
 let envioPackageDir = pathDirname(pathDirname(fileURLToPath(importMetaUrl)))
 
 // Runs `cargo build` on every invocation (like `cargo run`).
-let loadDevAddon: ({..}, string) => addon = %raw(`function(req, envioDir) {
+let loadDevAddon: ({..}, string) => Null.t<addon> = %raw(`function(req, envioDir) {
   var cp = Nodechild_process;
   var path = Nodepath;
   var fs = Nodefs;
@@ -177,6 +193,22 @@ let loadDevAddon: ({..}, string) => addon = %raw(`function(req, envioDir) {
 // `code`, and any other fields a diagnostic might rely on.
 let rethrow: JsExn.t => 'a = %raw(`function(e) { throw e }`)
 
+type packageJson = {version: string}
+let requirePackageJson: ({..}, string) => packageJson = %raw(`(req, p) => req(p)`)
+let devVersion = "0.0.1-dev"
+
+let isGlibc: unit => bool = %raw(`() => Boolean(process.report?.getReport().header.glibcVersionRuntime)`)
+
+@val external npmUserAgent: option<string> = "process.env.npm_config_user_agent"
+
+let addCommand = () =>
+  switch npmUserAgent {
+  | Some(ua) if ua->String.startsWith("pnpm/") => "pnpm add"
+  | Some(ua) if ua->String.startsWith("yarn/") => "yarn add"
+  | Some(ua) if ua->String.startsWith("bun/") => "bun add"
+  | _ => "npm install"
+  }
+
 let loadAddon = () => {
   let req = createRequire(importMetaUrl)
 
@@ -212,15 +244,32 @@ let loadAddon = () => {
   switch tryRequire(0) {
   | Some(addon) => addon
   | None =>
-    // Dev build fallback (cargo build on every run)
-    switch loadDevAddon(req, envioPackageDir)->(Utils.magic: addon => option<addon>) {
+    let version = requirePackageJson(req, "../package.json").version
+    // Publishing stamps the real version, so only a monorepo checkout (or a
+    // `file:` link to one) can have a dev build to fall back to. Skipping it
+    // spares published installs a `pnpm list` spawn before the error below.
+    let devAddon = if version === devVersion {
+      loadDevAddon(req, envioPackageDir)->Null.toOption
+    } else {
+      None
+    }
+    switch devAddon {
     | Some(addon) => addon
     | None =>
       let host = `${processPlatform}-${processArch}`
-      let msg = if candidates->Array.length === 0 {
+      let msg = switch candidates {
+      | []
+        if processPlatform === "win32" => `envio doesn't run natively on Windows. Use WSL 2 instead: https://learn.microsoft.com/windows/wsl/install`
+      | [] =>
         `envio doesn't support ${host}. Supported: linux-x64 (glibc/musl), linux-arm64, darwin-x64, darwin-arm64.`
-      } else {
-        `Couldn't load the envio native addon for ${host}. Reinstall envio (ensure optional dependencies aren't skipped).`
+      | _ =>
+        let pkg = if processPlatform === "linux" && processArch === "x64" && !isGlibc() {
+          `envio-linux-x64-musl`
+        } else {
+          candidates->Array.getUnsafe(0)
+        }
+        `envio's native binary for ${host} isn't installed (package "${pkg}"). This happens when optional dependencies are skipped (--omit=optional, --no-optional) or the lockfile was generated on another platform.
+Reinstall dependencies, or add the package explicitly: ${addCommand()} ${pkg}@${version}`
       }
       JsError.throwWithMessage(msg)
     }
@@ -265,6 +314,18 @@ let fromUserApi = (~schema=?, ~env=?, ~files=?, ~withIndexerTypes=false, yaml) =
   )
 }
 
+/// Parses a subgraph project without touching the filesystem: subgraph.yaml and
+/// its schema inline, ABI bodies through `files`.
+let fromSubgraph = (~name=?, ~env=?, ~files=?, ~root=?, ~manifest, ~schema) => {
+  let addon = getAddon()
+  addon.fromSubgraph(manifest, schema, {?name, ?env, ?files, ?root})
+}
+
+let subgraphFileToJavascript = (~source, ~path) => {
+  let addon = getAddon()
+  addon.subgraphFileToJavascript(source, path)
+}
+
 let runCli = args => {
   let addon = getAddon()
   addon.runCli(~args, ~envioPackageDir=Null.make(envioPackageDir))

package/src/Core.res.mjs

@@ -6,6 +6,7 @@ import * as Nodepath from "node:path";
 import * as Stdlib_Null from "@rescript/runtime/lib/es6/Stdlib_Null.js";
 import * as Nodemodule from "node:module";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Nodechild_process from "node:child_process";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 
@@ -97,6 +98,29 @@ let loadDevAddon = (function(req, envioDir) {
 
 let rethrow = (function(e) { throw e });
 
+let requirePackageJson = ((req, p) => req(p));
+
+let devVersion = "0.0.1-dev";
+
+let isGlibc = (() => Boolean(process.report?.getReport().header.glibcVersionRuntime));
+
+function addCommand() {
+  let ua = process.env.npm_config_user_agent;
+  if (ua !== undefined) {
+    if (ua.startsWith("pnpm/")) {
+      return "pnpm add";
+    } else if (ua.startsWith("yarn/")) {
+      return "yarn add";
+    } else if (ua.startsWith("bun/")) {
+      return "bun add";
+    } else {
+      return "npm install";
+    }
+  } else {
+    return "npm install";
+  }
+}
+
 function loadAddon() {
   let req = Nodemodule.createRequire(import.meta.url);
   let match = process.platform;
@@ -161,12 +185,21 @@ function loadAddon() {
   if (addon !== undefined) {
     return addon;
   }
-  let addon$1 = loadDevAddon(req, envioPackageDir);
-  if (addon$1 !== undefined) {
-    return addon$1;
+  let version = requirePackageJson(req, "../package.json").version;
+  let devAddon = version === devVersion ? Primitive_option.fromNull(loadDevAddon(req, envioPackageDir)) : undefined;
+  if (devAddon !== undefined) {
+    return devAddon;
   }
   let host = process.platform + `-` + process.arch;
-  return Stdlib_JsError.throwWithMessage(candidates.length === 0 ? `envio doesn't support ` + host + `. Supported: linux-x64 (glibc/musl), linux-arm64, darwin-x64, darwin-arm64.` : `Couldn't load the envio native addon for ` + host + `. Reinstall envio (ensure optional dependencies aren't skipped).`);
+  let tmp;
+  if (candidates.length !== 0) {
+    let pkg = process.platform === "linux" && process.arch === "x64" && !isGlibc() ? `envio-linux-x64-musl` : candidates[0];
+    tmp = `envio's native binary for ` + host + ` isn't installed (package "` + pkg + `"). This happens when optional dependencies are skipped (--omit=optional, --no-optional) or the lockfile was generated on another platform.
+Reinstall dependencies, or add the package explicitly: ` + addCommand() + ` ` + pkg + `@` + version;
+  } else {
+    tmp = process.platform === "win32" ? `envio doesn't run natively on Windows. Use WSL 2 instead: https://learn.microsoft.com/windows/wsl/install` : `envio doesn't support ` + host + `. Supported: linux-x64 (glibc/musl), linux-arm64, darwin-x64, darwin-arm64.`;
+  }
+  return Stdlib_JsError.throwWithMessage(tmp);
 }
 
 let addonRef = {
@@ -199,6 +232,21 @@ function fromUserApi(schema, env, files, withIndexerTypesOpt, yaml) {
   });
 }
 
+function fromSubgraph(name, env, files, root, manifest, schema) {
+  let addon = getAddon();
+  return addon.fromSubgraph(manifest, schema, {
+    name: name,
+    env: env,
+    files: files,
+    root: root
+  });
+}
+
+function subgraphFileToJavascript(source, path) {
+  let addon = getAddon();
+  return addon.subgraphFileToJavascript(source, path);
+}
+
 function runCli(args) {
   let addon = getAddon();
   return addon.runCli(args, envioPackageDir);
@@ -211,11 +259,17 @@ export {
   envioPackageDir,
   loadDevAddon,
   rethrow,
+  requirePackageJson,
+  devVersion,
+  isGlibc,
+  addCommand,
   loadAddon,
   addonRef,
   getAddon,
   getConfigJson,
   fromUserApi,
+  fromSubgraph,
+  subgraphFileToJavascript,
   runCli,
 }
 /* envioPackageDir Not a pure module */

package/src/EventConfigBuilder.res

@@ -343,7 +343,7 @@ let validateFieldsShapeOrThrow = (
 }
 
 let selectionList = (fields: unknown, key: string): option<array<string>> =>
-  switch (fields->(Utils.magic: unknown => dict<unknown>))->Dict.get(key) {
+  switch fields->(Utils.magic: unknown => dict<unknown>)->Dict.get(key) {
   | None => None
   | Some(value) => Some(value->(Utils.magic: unknown => array<string>))
   }
@@ -371,8 +371,8 @@ let parseFieldsOrThrow = (
     if !(valid->Utils.Set.has(name)) {
       JsError.throwWithMessage(
         `Invalid "${name}" field in the fields.${kind} option of ${registration}. Valid ${kind} fields: ${Utils.Array.quotedJoin(
-          valid->Utils.Set.toArray,
-        )}.`,
+            valid->Utils.Set.toArray,
+          )}.`,
       )
     }
     if seen->Utils.Set.has(name) {
@@ -858,13 +858,7 @@ let buildFuelEventConfig = (
   ~rawAbi: JSON.t,
 ): Internal.fuelEventConfig => {
   let fuelKind = switch kind {
-  | "logData" =>
-    // Transpile raw Fuel ABI to the format expected by the vendored ABI coder
-    let abi = FuelSDK.transpileAbi(rawAbi)
-    Internal.LogData({
-      logId: sighash,
-      decode: FuelSDK.Receipt.getLogDataDecoder(~abi, ~logId=sighash),
-    })
+  | "logData" => Internal.LogData({logId: sighash, abi: rawAbi})
   | "mint" => Mint
   | "burn" => Burn
   | "transfer" => Transfer

package/src/EventConfigBuilder.res.mjs

@@ -6,7 +6,6 @@ import * as Core from "./Core.res.mjs";
 import * as Fuel from "./sources/Fuel.res.mjs";
 import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
-import * as FuelSDK from "./sources/FuelSDK.res.mjs";
 import * as Internal from "./Internal.res.mjs";
 import * as LogSelection from "./LogSelection.res.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
@@ -590,11 +589,10 @@ function buildFuelEventConfig(contractName, eventName, kind, sighash, rawAbi) {
       fuelKind = "Call";
       break;
     case "logData" :
-      let abi = FuelSDK.transpileAbi(rawAbi);
       fuelKind = {
         TAG: "LogData",
         logId: sighash,
-        decode: FuelSDK.Receipt.getLogDataDecoder(abi, sighash)
+        abi: rawAbi
       };
       break;
     case "mint" :

package/src/EventProcessing.res

@@ -51,7 +51,7 @@ let runEventHandlerOrThrow = async (
       isPreload: false,
       chains,
       config,
-      isResolved: false,
+      sync: UserContext.makeSyncState(),
     }
     await handler(
       (
@@ -61,7 +61,7 @@ let runEventHandlerOrThrow = async (
         }: Internal.handlerArgs
       ),
     )
-    contextParams.isResolved = true
+    contextParams.sync.status = Resolved
   } catch {
   | exn =>
     throw(
@@ -102,7 +102,7 @@ let runHandlerOrThrow = async (
         isPreload: false,
         chains,
         config,
-        isResolved: false,
+        sync: UserContext.makeSyncState(),
       }
       await handler(
         Ecosystem.makeOnBlockArgs(
@@ -111,7 +111,7 @@ let runHandlerOrThrow = async (
           ~context=UserContext.getHandlerContext(contextParams),
         ),
       )
-      contextParams.isResolved = true
+      contextParams.sync.status = Resolved
     } catch {
     | exn =>
       throw(
@@ -186,7 +186,7 @@ let preloadBatchOrThrow = async (
                   checkpointId,
                   isPreload: true,
                   chains,
-                  isResolved: false,
+                  sync: UserContext.makeSyncState(),
                   config,
                 }),
               })
@@ -221,7 +221,7 @@ let preloadBatchOrThrow = async (
                   checkpointId,
                   isPreload: true,
                   chains,
-                  isResolved: false,
+                  sync: UserContext.makeSyncState(),
                   config,
                 }),
               )

package/src/EventProcessing.res.mjs

@@ -38,6 +38,7 @@ let ProcessingError = /* @__PURE__ */Primitive_exceptions.create("EventProcessin
 async function runEventHandlerOrThrow(item, checkpointId, handler, indexerState, loadManager, persistence, chains, config) {
   let timeBeforeHandler = Performance.now();
   try {
+    let contextParams_sync = UserContext.makeSyncState();
     let contextParams = {
       item: item,
       checkpointId: checkpointId,
@@ -47,13 +48,13 @@ async function runEventHandlerOrThrow(item, checkpointId, handler, indexerState,
       isPreload: false,
       chains: chains,
       config: config,
-      isResolved: false
+      sync: contextParams_sync
     };
     await handler({
       event: Ecosystem.getItemEvent(item, config.ecosystem),
       context: UserContext.getHandlerContext(contextParams)
     });
-    contextParams.isResolved = true;
+    contextParams_sync.status = "Resolved";
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
     throw {
@@ -79,6 +80,7 @@ async function runHandlerOrThrow(item, checkpointId, indexerState, loadManager,
     }
   }
   try {
+    let contextParams_sync = UserContext.makeSyncState();
     let contextParams = {
       item: item,
       checkpointId: checkpointId,
@@ -88,10 +90,10 @@ async function runHandlerOrThrow(item, checkpointId, indexerState, loadManager,
       isPreload: false,
       chains: chains,
       config: config,
-      isResolved: false
+      sync: contextParams_sync
     };
     await item.onBlockRegistration.handler(Ecosystem.makeOnBlockArgs(item.blockNumber, config.ecosystem, UserContext.getHandlerContext(contextParams)));
-    contextParams.isResolved = true;
+    contextParams_sync.status = "Resolved";
     return;
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
@@ -133,7 +135,7 @@ async function preloadBatchOrThrow(batch, loadManager, persistence, config, inde
                 isPreload: true,
                 chains: chains,
                 config: config,
-                isResolved: false
+                sync: UserContext.makeSyncState()
               })
             }).then(() => IndexerState.endPreloadHandler(indexerState, timerRef, contractName, eventName))));
           } catch (exn) {
@@ -151,7 +153,7 @@ async function preloadBatchOrThrow(batch, loadManager, persistence, config, inde
             isPreload: true,
             chains: chains,
             config: config,
-            isResolved: false
+            sync: UserContext.makeSyncState()
           })))));
         } catch (exn$1) {
           

package/src/ExitOnCaughtUp.res

@@ -14,7 +14,11 @@ let run = async (state: IndexerState.t) => {
       | Some(onExit) => onExit()
       | None =>
         Logging.info("Exiting with success")
-        NodeJs.process->NodeJs.exitWithCode(Success)
+        if Worker.isEnabled {
+          Worker.exitAfterReporting(~metrics=state->IndexerState.toMetrics)
+        } else {
+          NodeJs.process->NodeJs.exitWithCode(Success)
+        }
       }
     | Some(message) => state->IndexerState.errorExit(ErrorHandling.make(Utils.Error.make(message)))
     }

package/src/ExitOnCaughtUp.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Worker from "./Worker.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Writing from "./Writing.res.mjs";
 import * as Process from "process";
@@ -24,12 +25,16 @@ async function run(state) {
     return onExit();
   } else {
     Logging.info("Exiting with success");
-    Process.exit(0);
-    return;
+    if (Worker.isEnabled) {
+      return Worker.exitAfterReporting(IndexerState.toMetrics(state));
+    } else {
+      Process.exit(0);
+      return;
+    }
   }
 }
 
 export {
   run,
 }
-/* Logging Not a pure module */
+/* Worker Not a pure module */

package/src/HandlerLoader.res

@@ -1,20 +1,37 @@
 @module("node:fs/promises")
 external globIterator: string => Utils.asyncIterator<string> = "glob"
 
-// Register tsx for TypeScript handler support
-// Wrapped in try-catch because if tsx is already loaded via --import (e.g., in tests),
-// calling module.register again will throw an error
-try {
-  NodeJs.Module.register("tsx/esm", NodeJs.ImportMeta.url)
-} catch {
-| _ => () // tsx already loaded, ignore
+type tsHooksAddon = {
+  loadTs: string => string,
+  tsResolveCandidates: (string, Null.t<string>) => array<string>,
+  tsNotFoundCandidates: (string, Null.t<string>, string) => array<string>,
 }
 
-// Convert a relative path to a file:// URL for dynamic import
-// Paths are resolved relative to process.cwd() (project root)
-let toImportUrl = (relativePath: string) => {
-  let absolutePath = NodeJs.Path.resolve([NodeJs.Process.cwd(), relativePath])->NodeJs.Path.toString
-  NodeJs.Url.pathToFileURL(absolutePath)->NodeJs.Url.toString
+@module("./TsModuleHooks.mjs")
+external registerTsHooksWith: tsHooksAddon => unit = "register"
+
+// The resolve hook calls into the addon, and loading the addon goes through
+// the resolve hook, so the addon has to be loaded before the hooks exist.
+let registerTsHooks = () => {
+  let addon = Core.getAddon()
+  registerTsHooksWith({
+    loadTs: addon.loadTs,
+    tsResolveCandidates: addon.tsResolveCandidates,
+    tsNotFoundCandidates: addon.tsNotFoundCandidates,
+  })
+}
+
+let isTypeScript = file => /\.m?tsx?$/->RegExp.test(file)
+
+// Paths are relative to the project root, which is the working directory.
+let toAbsolutePath = (file: string) =>
+  NodeJs.Path.resolve([NodeJs.Process.cwd(), file])->NodeJs.Path.toString
+
+let importHandler = async file => {
+  if isTypeScript(file) {
+    Core.getAddon().tsCheckHandlerFormat(toAbsolutePath(file))
+  }
+  await Utils.importPath(toAbsolutePath(file)->NodeJs.Url.pathToFileURL->NodeJs.Url.toString)
 }
 
 let registerContractHandlers = async (~contractName, ~handler: option<string>) => {
@@ -22,7 +39,7 @@ let registerContractHandlers = async (~contractName, ~handler: option<string>) =
   | None => ()
   | Some(handlerPath) =>
     try {
-      let _ = await Utils.importPath(toImportUrl(handlerPath))
+      let _ = await importHandler(handlerPath)
     } catch {
     | exn =>
       let cause = exn->Utils.prettifyExn->Obj.magic
@@ -37,10 +54,9 @@ let registerContractHandlers = async (~contractName, ~handler: option<string>) =
   }
 }
 
-let autoLoadFromSrcHandlers = async (~handlers: string) => {
-  // Relative to cwd (project root)
+let globAutoLoadFiles = async (~handlers) => {
   let srcPattern = `./${handlers}/**/*.{js,mjs,ts}`
-  let handlerFiles = try {
+  try {
     let iterator = globIterator(srcPattern)
     let files = await iterator->Utils.Array.fromAsyncIterator
     // Filter out test and spec files
@@ -54,22 +70,46 @@ let autoLoadFromSrcHandlers = async (~handlers: string) => {
   } catch {
   | exn =>
     JsError.throwWithMessage(
-      `Failed to glob src/handlers directory for auto-loading handlers. Pattern: ${srcPattern}. Before continuing, check that you're using Node.js >=22 version. Error: ${exn
+      `Failed to glob src/handlers directory for auto-loading handlers. Pattern: ${srcPattern}. Error: ${exn
         ->Utils.prettifyExn
         ->Obj.magic}`,
     )
   }
+}
 
-  // Import handler files using absolute file:// URLs resolved from cwd
-  let _ = await handlerFiles
-  ->Array.map(file => {
-    Utils.importPath(toImportUrl(file))->Promise.catch(exn => {
-      let cause = exn->Utils.prettifyExn->Obj.magic
-      Logging.errorWithExn(exn, `Failed to auto-load handler file: ${file}`)
-      JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
-    })
-  })
-  ->Promise.all
+let getAutoLoadFiles = async (~config: Config.t) =>
+  switch config.subgraph {
+  // A subgraph project's `src/` holds AssemblyScript mappings, not envio
+  // handlers: auto-loading or type-checking them as TypeScript would fail.
+  | Some(_) => []
+  | None => await globAutoLoadFiles(~handlers=config.handlers)
+  }
+
+type typeCheckResult = {
+  skipped?: string,
+  errors?: string,
+}
+
+@module("./HandlerTypeCheck.mjs")
+external checkTypesInWorker: (~cwd: string, ~files: array<string>) => promise<typeCheckResult> =
+  "check"
+
+let typeCheck = async (~config: Config.t, ~autoLoadFiles) => {
+  // A contract's `handler:` may also be an auto-loaded file.
+  let files =
+    autoLoadFiles
+    ->Array.concat(config.contractHandlers->Array.filterMap(({handler}) => handler))
+    ->Array.filter(isTypeScript)
+    ->Array.map(toAbsolutePath)
+    ->Utils.Set.fromArray
+    ->Utils.Set.toArray
+  if files->Array.length > 0 {
+    switch await checkTypesInWorker(~cwd=NodeJs.Process.cwd(), ~files) {
+    | {errors} => JsError.throwWithMessage(`Handler files have type errors:\n\n${errors}`)
+    | {skipped} => Logging.warn(skipped)
+    | _ => ()
+    }
+  }
 }
 
 // `Config` holds only event definitions; handler + per-chain `where`
@@ -77,18 +117,40 @@ let autoLoadFromSrcHandlers = async (~handlers: string) => {
 // `HandlerRegister.finishRegistration`. This loads the user handler files
 // (populating the global `HandlerRegister` registry as a side effect) and
 // returns the resulting per-chain registrations.
-let registerAllHandlers = async (~config: Config.t): HandlerRegister.registrationsByChainId => {
+// The subgraph runtime lives in this package but is never exported: it's
+// reached only from here, when the resolved config carries a translated
+// manifest.
+let registerSubgraph: (JSON.t, ~isDev: bool) => promise<unit> = %raw(`(subgraph, isDev) =>
+  import("./subgraph/runtime.ts").then((m) => m.registerSubgraph({ ...subgraph, isDev }))`)
+
+let registerAllHandlers = async (
+  ~config: Config.t,
+  ~autoLoadFiles,
+): HandlerRegister.registrationsByChainId => {
   HandlerRegister.startRegistration(~config)
+  registerTsHooks()
 
-  // Auto-load all .js files from src/handlers directory
-  await autoLoadFromSrcHandlers(~handlers=config.handlers)
+  switch config.subgraph {
+  // Registered after the TypeScript hooks, so the subgraph runtime's own hooks
+  // see a mapping first.
+  | Some(subgraph) => await registerSubgraph(subgraph, ~isDev=config.isDev)
+  | None =>
+    let _ = await autoLoadFiles
+    ->Array.map(file => {
+      importHandler(file)->Promise.catch(exn => {
+        let cause = exn->Utils.prettifyExn->Obj.magic
+        Logging.errorWithExn(exn, `Failed to auto-load handler file: ${file}`)
+        JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
+      })
+    })
+    ->Promise.all
 
-  // Load contract-specific handlers
-  let _ = await config.contractHandlers
-  ->Array.map(({name, handler}) => {
-    registerContractHandlers(~contractName=name, ~handler)
-  })
-  ->Promise.all
+    let _ = await config.contractHandlers
+    ->Array.map(({name, handler}) => {
+      registerContractHandlers(~contractName=name, ~handler)
+    })
+    ->Promise.all
+  }
 
   HandlerRegister.finishRegistration(~config)
 }