envio 3.15.0 → 3.16.0-subgraph

package/src/subgraph/runtime.ts

@@ -0,0 +1,2059 @@
+/**
+ * Turns a translated manifest into envio registrations.
+ *
+ * Each manifest handler becomes an `onEvent` / `onBlock` / `contractRegister`
+ * wrapper that runs the mapping synchronously inside `runSync`: reads try the
+ * in-memory state first, a miss schedules the async op and suspends, and the
+ * replay loop reruns the mapping once what it asked for has landed.
+ */
+
+import { instancesAt, rememberInstance } from "./template-instances.ts";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import { indexer } from "../Api.res.mjs";
+import { Db, Hasura, serverPort } from "../Env.res.mjs";
+import { info, setLogger, warn } from "./log.ts";
+import { cached as storedEffectOutput, resetStartupTables } from "../EffectCacheLookup.res.mjs";
+import {
+  subgraphFileToJavascript,
+  subgraphRegisterHandlers,
+  subgraphSureCreates,
+  subgraphWorkspacePackages,
+  subgraphWorkspaceRoot,
+  subgraphScriptsWriting,
+} from "../Core.res.mjs";
+import { install as installCallSource } from "../sources/CallSource.res.mjs";
+import { fetchCalls, resetCallBackends } from "./calls-source.ts";
+import {
+  currentScope,
+  runInScope,
+  runInScopeUntilSettled,
+  type FileCreate,
+  type RegisterPass,
+  type Scope,
+  type SubgraphSchema,
+} from "./scope.ts";
+import {
+  contextOf,
+  assemblyScriptPrimitives,
+  changetype,
+  retagChangetype,
+  retagEach,
+  installCallHook,
+  installLegacySignatureHook,
+  installHosts,
+  installHandlerCreateHook,
+  setLegacyNullOperands,
+  installRegisterHook,
+  installRegisterMissHook,
+  installFileTemplates,
+  fileCreateId,
+  decodeBase64,
+  ethereum,
+  type EventInput,
+  type EventKind,
+  json as jsonNamespace,
+  makeBlockHandlerBlock,
+  makeEvent as makeGraphEvent,
+  makeCall as makeGraphCall,
+  makeCallBlock,
+  callInputDecodes,
+  type CallKind,
+  commitRegisterWrites,
+  resetRegisterStore,
+  setRegisterFrontier,
+  POSITION_BLOCK,
+  ROUND_SPAN,
+  ethereumValueToJs,
+} from "./graph-ts.ts";
+import { encodeArg, decodeArg, makeCallEffect } from "./calls.ts";
+import { functionSignature } from "./abi-types.ts";
+import { resetRpcClients } from "./rpc.ts";
+import {
+  AS_MAP,
+  AS_SET,
+  AsMap,
+  AsSet,
+  Pointer,
+  builtinMax,
+  builtinMin,
+  memory as assemblyScriptMemory,
+  EVENT_CLASSES_EXPORT,
+  MODULE_INIT,
+  OPERATORS_HELPER,
+  RETAG_EACH_HELPER,
+  RETAG_HELPER,
+  operators,
+  resetNullObjects,
+  stringEncodings,
+} from "./assemblyscript.ts";
+import { makeHostEffects, normalizeIpfsPath, type HostEffects } from "./hosts.ts";
+import { createHash } from "node:crypto";
+import { advanceRollup } from "./rollup.ts";
+import { graftBaseNotice } from "./graft.ts";
+import { fetchMappingPackages, missingMappingPackages } from "./toolchain.ts";
+import { ensureGeneratedCode, generatedDir, missingGeneratedCode, typeCheckMappings } from "./graph-cli.ts";
+import { unknown, unsupported } from "./errors.ts";
+import { runSyncCounted } from "./stats.ts";
+import { resolveAssemblyScriptPackage, resolveWorkspacePackage, unwrittenWorkspaceEntry } from "./as-package.ts";
+import { registerSlots } from "./register-slots.ts";
+
+const SHIM_URL = new URL("./graph-ts.ts", import.meta.url).href;
+const REGEX_SHIM_URL = new URL("./assemblyscript-regex.ts", import.meta.url).href;
+const ENVIO_PACKAGE_URL = new URL("../../", import.meta.url).href;
+
+const jsonFromString = (line: string) => (jsonNamespace as any).fromString(line);
+
+/**
+ * Skips the preload pass, so every read a mapping makes misses and the handler
+ * replays as often as it possibly can. The replay-stress suite runs the whole
+ * subgraph suite this way: a mapping must produce the same store whether its
+ * reads were preloaded or not.
+ */
+const skipPreload = process.env.ENVIO_SUBGRAPH_SKIP_PRELOAD === "1";
+
+/** Escape hatch from the create analysis: every handler gets a register pass. */
+const registerEveryHandler = process.env.ENVIO_SUBGRAPH_REGISTER_ALL_HANDLERS === "1";
+
+type EventHandler = {
+  event: string;
+  name: string;
+  handler: string;
+  receipt: boolean;
+  inputs?: EventInput[];
+  /** `topic1`–`topic3`, keyed by position among the indexed parameters. */
+  /** The ABI declares the event anonymous: topic N is its Nth indexed param, from 0. */
+  anonymous?: boolean;
+  topics?: Record<string, string[]>;
+};
+type CallHandler = {
+  function: string;
+  handler: string;
+  /** The call trigger the translator minted for it. */
+  name: string;
+  inputs?: { name: string; type: string }[];
+  outputs?: { name: string; type: string }[];
+};
+/** As the translator serialises its `BlockFilter`. */
+type BlockHandler = {
+  handler: string;
+  filter: { every: number } | "once" | "call";
+  /** The call trigger a `filter: call` handler runs on. */
+  callEvent?: string;
+  /** The block fields the mapping reads, by envio's names. */
+  blockFields?: string[];
+};
+type DataSource = {
+  kind: string;
+  name: string;
+  network?: string;
+  chainId?: number;
+  address?: string;
+  startBlock?: number;
+  endBlock?: number;
+  mappingFile: string;
+  apiVersion?: string;
+  /** ABI name to file, relative to `root`. */
+  abis?: Record<string, string>;
+  entities?: string[];
+  eventHandlers: EventHandler[];
+  callHandlers?: CallHandler[];
+  blockHandlers: BlockHandler[];
+  context?: Record<string, { type: string; data: string }>;
+  isTemplate: boolean;
+};
+type SubgraphConfig = {
+  specVersion: string;
+  dataSources: DataSource[];
+  templates: DataSource[];
+  declaresEthCalls: boolean;
+  /** Set when the manifest has a `graft:` block; the indexer ignores it. */
+  graft?: { base: string; block: number };
+  graftNotice?: string;
+  /** What the translation left out of the config and why, logged at startup. */
+  notices?: string[];
+  timeseriesEntities?: string[];
+  skipDuplicateEntities?: string[];
+  aggregations?: SubgraphSchema["aggregations"];
+  /** The config's contract name for each data source and template. */
+  contractAccessors: Record<string, string>;
+  root: string;
+  /** The manifest's name within `root`: `--config` may name another than subgraph.yaml. */
+  manifestFile?: string;
+  rpcUrls: string[];
+  /** Per chain id, the reorg depth a block handler's header reads are held back by. */
+  blockHeaderLag?: Record<number, number>;
+  /** Chains HyperSync doesn't serve: their headers and receipts come from RPC alone. */
+  rpcOnlyChains?: number[];
+  /** Set when envio wrote the manifest from the repo's template, or ran the codegen steps that write it. */
+  renderedManifest?: {
+    script: string;
+    inlined?: string[];
+    network: string;
+    template: string;
+    view: string;
+    steps?: string[];
+    commands?: string[];
+  };
+  /** Files the manifest names, as written and where they are read from (another case, or a fetched package). */
+  pathFixes?: [string, string][];
+  /** The network networks.json was applied for when none was picked: the repo build's `--network`. */
+  buildNetwork?: string;
+  isDev: boolean;
+} & SubgraphSchema;
+
+const AS_DATE = Symbol.for("envio.subgraph.date");
+
+/** `file` as the filesystem spells it, each missing component matched to the one entry differing only in case. */
+function onDiskPath(file: string): string | null {
+  if (existsSync(file)) return file;
+  const parent = path.dirname(file);
+  if (parent === file) return null;
+  const dir = onDiskPath(parent);
+  if (dir === null) return null;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const name = path.basename(file).toLowerCase();
+  const matches = entries.filter((entry) => entry.toLowerCase() === name);
+  return matches.length === 1 ? path.join(dir, matches[0]!) : null;
+}
+
+const caseWarned = new Set<string>();
+
+/**
+ * A project file's relative import that exists only in another case
+ * (`../generated/staking/staking` for codegen's `generated/Staking/Staking.ts`):
+ * asc resolves it on the macOS or Windows filesystem the subgraph builds on.
+ */
+function caseMatchedImport(specifier: string, parentURL: string | undefined): string | null {
+  if (!projectRoot || !parentURL?.startsWith(projectRoot) || parentURL.includes("/node_modules/")) return null;
+  const parent = fileURLToPath(parentURL);
+  const base = path.resolve(path.dirname(parent), specifier);
+  for (const candidate of [base, `${base}.ts`, path.join(base, "index.ts")]) {
+    const found = onDiskPath(candidate);
+    if (found === null || found === candidate || !statSync(found).isFile()) continue;
+    if (!pathToFileURL(found).href.startsWith(projectRoot)) continue;
+    const key = `${parent}\0${specifier}`;
+    if (!caseWarned.has(key)) {
+      caseWarned.add(key);
+      warn(
+        `Envio Subgraph: ${path.relative(fileURLToPath(projectRoot), parent)} imports "${specifier}", and the repo has ` +
+          `${path.relative(path.dirname(parent), found)}. They match only on a filesystem that ignores case ` +
+          "(macOS's and Windows' by default), where the subgraph builds; envio loads the file the repo has.",
+      );
+    }
+    return found;
+  }
+  return null;
+}
+
+/**
+ * Where a call sits in its chain for the register pass's store: after every log
+ * of its block, then by transaction and position in the transaction. graph-node
+ * orders a call by its transaction among the logs (after that transaction's own
+ * events); the handler pass follows that order exactly, so this only steers
+ * what a register pass may read — a create decided on state written by a log of
+ * a later transaction of the same block reads it one transaction early.
+ */
+function callPosition(event: any): number {
+  const transaction = Math.min(Number(event.transaction?.transactionIndex ?? 0), 499);
+  return event.block.number * POSITION_BLOCK + 500_000 + transaction * 1000 + Math.min(event.logIndex, 999);
+}
+
+/**
+ * A mapping may import AssemblyScript from outside the manifest's directory:
+ * graph codegen writes `generated/` beside the package.json while the manifest,
+ * schema and mappings sit in `src/` (StakeWise). Any TypeScript that is neither
+ * a dependency nor envio's own is the project's.
+ */
+function isOutsideSource(url: string): boolean {
+  return (
+    url.startsWith("file:") &&
+    url.endsWith(".ts") &&
+    !url.endsWith(".d.ts") &&
+    !url.includes("/node_modules/") &&
+    !url.startsWith(ENVIO_PACKAGE_URL)
+  );
+}
+
+/** A bare import Node resolved to a dependency's JavaScript, which has no AssemblyScript entry at all. */
+function isJavaScriptPackage(specifier: string, url: string | undefined, parentUrl: string): boolean {
+  const bare = !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.includes(":");
+  return (
+    bare &&
+    url !== undefined &&
+    url.includes("/node_modules/") &&
+    /\.[cm]?js$/.test(url) &&
+    resolveAssemblyScriptPackage(specifier, parentUrl) === null
+  );
+}
+
+let hooksInstalled = false;
+/**
+ * Some mapping is below apiVersion 0.0.5, where graph-node reads through a null
+ * pointer instead of trapping. Files are compiled once for the whole project,
+ * so one old mapping makes every file tolerant.
+ */
+let legacyNulls = false;
+let projectRoot: string | null = null;
+/**
+ * `node_modules` envio fetched for packages the mappings import and the
+ * project can't resolve (its own install failed or never ran). A parent URL
+ * inside it is where those specifiers are resolved from, and so are the
+ * packages' own dependencies.
+ */
+let fetchedModulesParent: string | null = null;
+/** The packages of the workspace the project sits in, by name, which an install would link. */
+let workspacePackages = new Map<string, string>();
+let workspaceRoot: string | null = null;
+/** Every project file the load hook has compiled, so their exports can be read back. */
+const projectModules = new Set<string>();
+
+/**
+ * Mappings resolve `@graphprotocol/graph-ts` to the shim. The project's own
+ * files — its mappings and `generated/` — are AssemblyScript, and load through
+ * the addon, which turns each into the JavaScript that computes what `asc`
+ * would (`subgraph/assemblyscript.rs`).
+ */
+function installResolveHook(root: string) {
+  projectRoot = pathToFileURL(path.resolve(root) + path.sep).href;
+  workspacePackages = new Map(Object.entries(subgraphWorkspacePackages(root)));
+  workspaceRoot = subgraphWorkspaceRoot(root);
+  if (hooksInstalled) return;
+  hooksInstalled = true;
+  // The addon's output carries an inline source map back to the mapping, so a
+  // stack trace names the line the developer wrote.
+  process.setSourceMapsEnabled(true);
+
+  registerHooks({
+    resolve(specifier: string, context: any, nextResolve: any) {
+      if (
+        specifier === "@graphprotocol/graph-ts" ||
+        specifier.startsWith("@graphprotocol/graph-ts/") ||
+        // Matchstick re-exports graph-ts' `log`, and some mappings import it
+        // from there; its test helpers have no meaning outside a test.
+        specifier === "matchstick-as" ||
+        specifier.startsWith("matchstick-as/")
+      ) {
+        return { url: SHIM_URL, shortCircuit: true };
+      }
+      // A library of AssemblyScript's own memory-level matching, which the
+      // JavaScript transform of a mapping library can't run.
+      if (specifier === "assemblyscript-regex") return { url: REGEX_SHIM_URL, shortCircuit: true };
+      let resolved;
+      try {
+        resolved = nextResolve(specifier, context);
+      } catch (error: any) {
+        const caseMatched =
+          error?.code === "ERR_MODULE_NOT_FOUND" && specifier.startsWith(".")
+            ? caseMatchedImport(specifier, context?.parentURL)
+            : null;
+        if (caseMatched) return nextResolve(pathToFileURL(caseMatched).href, context);
+        const bare = !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.includes(":");
+        // The workspace's own package before any copy fetched from npm, which
+        // may not be it.
+        const workspaceFile = bare ? resolveWorkspacePackage(specifier, workspacePackages) : null;
+        if (workspaceFile) {
+          return workspaceFile.endsWith(".ts")
+            ? { url: workspaceFile, format: "module", shortCircuit: true }
+            : { url: workspaceFile, shortCircuit: true };
+        }
+        const unwritten =
+          bare && error?.code === "ERR_MODULE_NOT_FOUND"
+            ? unwrittenWorkspaceEntry(specifier, workspacePackages, workspaceRoot)
+            : null;
+        if (unwritten) throw unwritten;
+        let fetched;
+        if (fetchedModulesParent && bare && error?.code === "ERR_MODULE_NOT_FOUND") {
+          try {
+            fetched = nextResolve(specifier, { ...context, parentURL: fetchedModulesParent });
+          } catch {}
+        }
+        if (fetched) {
+          resolved = fetched;
+        } else {
+          // A library written in AssemblyScript has no JavaScript entry for Node
+          // to find (as-base64's package.json names no `main`); asc reads its
+          // assembly/index.ts.
+          const asFile =
+            resolveAssemblyScriptPackage(specifier, context?.parentURL) ??
+            resolveAssemblyScriptPackage(specifier, fetchedModulesParent ?? undefined);
+          if (!asFile) throw error;
+          return { url: asFile, shortCircuit: true };
+        }
+      }
+      const parentUrl: string | undefined = context?.parentURL;
+      const fromProject =
+        projectRoot !== null &&
+        typeof parentUrl === "string" &&
+        (parentUrl.startsWith(projectRoot) || isOutsideSource(parentUrl)) &&
+        !parentUrl.includes("/node_modules/");
+      // Packages envio fetched for the mappings resolve from a parent of their own.
+      const forProject = fromProject || (parentUrl !== undefined && parentUrl === fetchedModulesParent);
+      if (forProject && isJavaScriptPackage(specifier, resolved?.url, parentUrl!)) {
+        const importer = fromProject ? path.relative(fileURLToPath(projectRoot!), fileURLToPath(parentUrl!)) : "A mapping";
+        throw new Error(
+          `${importer} imports the JavaScript package "${specifier}", which AssemblyScript can't compile: ` +
+            "asc reads a package's `ascMain`, assembly/index.ts or a .ts entry, and this one has none, so " +
+            "`graph build` fails on this mapping too.",
+        );
+      }
+      // A subgraph project's package.json has no `type`, so its mappings and
+      // its `generated/` would load as CommonJS and reach the shim — a real ES
+      // module — through `require()`, which Node refuses inside a cycle. They
+      // are ES modules; saying so is what lets them import it.
+      if (projectRoot && resolved?.url && (resolved.url.startsWith(projectRoot) || isOutsideSource(resolved.url))) {
+        return { ...resolved, format: "module" };
+      }
+      return resolved;
+    },
+    // Taken over before any other loader sees the file: a TypeScript
+    // transpiler would refuse AssemblyScript it has no reason to accept, and
+    // would strip `changetype`'s type argument before it could be read.
+    load(url: string, context: any, nextLoad: any) {
+      const isProjectFile =
+        projectRoot !== null && (url.startsWith(projectRoot) || isOutsideSource(url)) && !url.includes("/node_modules/");
+      // A mapping library is AssemblyScript too — OpenZeppelin's
+      // @amxx/graphprotocol-utils, @protofire/subgraph-toolkit — and Node
+      // won't even strip types under node_modules. envio's own sources are
+      // TypeScript, not AssemblyScript, and stay out of it.
+      const isMappingLibrary =
+        url.includes("/node_modules/") && !url.endsWith(".d.ts") && !url.startsWith(ENVIO_PACKAGE_URL);
+      if (!projectRoot || !url.endsWith(".ts") || !(isProjectFile || isMappingLibrary)) {
+        return nextLoad(url, context);
+      }
+      const file = fileURLToPath(url);
+      projectModules.add(url);
+      return {
+        format: "module",
+        source: subgraphFileToJavascript(readFileSync(file, "utf8"), file, legacyNulls),
+        shortCircuit: true,
+      };
+    },
+  });
+
+  // AssemblyScript builtins the generated code uses as globals.
+  const globals = globalThis as any;
+  globals.changetype ??= changetype;
+  globals[OPERATORS_HELPER] ??= operators;
+  globals[RETAG_HELPER] ??= retagChangetype;
+  globals[RETAG_EACH_HELPER] ??= retagEach;
+  globals[AS_MAP] ??= AsMap;
+  globals[AS_SET] ??= AsSet;
+  // AssemblyScript's memory builtins, over the buffers a typed array's
+  // `dataStart` points into.
+  globals.memory ??= assemblyScriptMemory;
+  globals.min ??= builtinMin;
+  globals.max ??= builtinMax;
+  globals.unchecked ??= (value: unknown) => value;
+  globals.String.UTF8 ??= stringEncodings.UTF8;
+  globals.String.UTF16 ??= stringEncodings.UTF16;
+  const typedArray = Object.getPrototypeOf(Uint8Array.prototype);
+  if (!Object.getOwnPropertyDescriptor(typedArray, "dataStart")) {
+    Object.defineProperty(typedArray, "dataStart", {
+      get(this: Uint8Array) {
+        return new Pointer(this.buffer, this.byteOffset);
+      },
+      configurable: true,
+    });
+  }
+  globals.assert ??= (value: unknown, message?: string) => {
+    if (!value) throw new Error(message ?? "assertion failed");
+    return value;
+  };
+  for (const [name, namespace] of Object.entries(assemblyScriptPrimitives)) {
+    globals[name] ??= namespace;
+  }
+
+  // AssemblyScript's Date takes and sets its time as an i64, which the shim
+  // holds as a bigint; JavaScript's refuses one.
+  if (!(globals.Date as any)[AS_DATE]) {
+    const JsDate: DateConstructor = globals.Date;
+    const toNumber = (value: unknown) => (typeof value === "bigint" ? Number(value) : value);
+    class AsDate extends JsDate {
+      constructor(...args: unknown[]) {
+        super(...(args.map(toNumber) as []));
+      }
+      setTime(time: number | bigint): number {
+        return super.setTime(Number(time));
+      }
+      static fromString(text: string): Date {
+        return new AsDate(JsDate.parse(text));
+      }
+    }
+    Object.defineProperty(AsDate, AS_DATE, { value: true });
+    globals.Date = AsDate;
+  }
+
+  // AssemblyScript's typed arrays are made over an existing buffer with
+  // `Uint8Array.wrap(buffer)`; JavaScript has the constructor for it.
+  for (const Array of [Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array]) {
+    (Array as any).wrap ??= (buffer: ArrayBuffer, byteOffset?: number, length?: number) =>
+      new Array(buffer, byteOffset, length);
+  }
+
+  // AssemblyScript's DataView reads and writes a 64-bit integer as `u64`/`i64`
+  // under these names; JavaScript's only as a bigint, under `*Big*` ones.
+  const view = DataView.prototype as any;
+  view.getUint64 ??= function (this: DataView, offset: number, littleEndian?: boolean) {
+    return this.getBigUint64(offset, littleEndian);
+  };
+  view.getInt64 ??= function (this: DataView, offset: number, littleEndian?: boolean) {
+    return this.getBigInt64(offset, littleEndian);
+  };
+  view.setUint64 ??= function (this: DataView, offset: number, value: bigint | number, littleEndian?: boolean) {
+    this.setBigUint64(offset, BigInt.asUintN(64, BigInt(value)), littleEndian);
+  };
+  view.setInt64 ??= function (this: DataView, offset: number, value: bigint | number, littleEndian?: boolean) {
+    this.setBigInt64(offset, BigInt.asIntN(64, BigInt(value)), littleEndian);
+  };
+}
+
+/**
+ * `topicN` narrows the indexed parameter in that topic to the logs whose topic
+ * is one of the listed words; as a `where`, it narrows to that parameter's
+ * decoded values. An anonymous event has no signature topic, so topic0 is its
+ * first indexed parameter, which the translator always narrows. It has refused
+ * a parameter hashed into its topic, and a word no value encodes to.
+ */
+function topicFilter(handler: EventHandler): { params: Record<string, unknown[]> } | undefined {
+  const topics = Object.entries(handler.topics ?? {});
+  if (topics.length === 0) return undefined;
+  const indexed = (handler.inputs ?? []).filter((input) => input.indexed);
+  const params: Record<string, unknown[]> = {};
+  for (const [position, words] of topics) {
+    const input = indexed[handler.anonymous ? Number(position) : Number(position) - 1];
+    params[input.key] = words.map((word) => fromTopic(input.type, word));
+  }
+  return { params };
+}
+
+function fromTopic(type: string, topic: string): unknown {
+  const word = topic.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+  if (type === "address") return `0x${word.slice(24)}`;
+  if (type === "bool") return BigInt(`0x${word}`) !== 0n;
+  // A fixed-size byte string is left-aligned in its word.
+  if (type.startsWith("bytes")) return `0x${word.slice(0, Number(type.slice(5)) * 2)}`;
+  const bits = Number(type.replace(/^u?int/, "") || 256);
+  const value = BigInt(`0x${word}`);
+  return type.startsWith("uint") ? BigInt.asUintN(bits, value) : BigInt.asIntN(bits, value);
+}
+
+/**
+ * Why `graph codegen` never wrote a generated file a mapping imports: it writes
+ * `schema.ts`, `templates.ts`, `<data source>/<ABI>.ts` and
+ * `templates/<template>/<ABI>.ts` for the manifest it runs on, no `index.ts`.
+ * `graph build` then fails on the import too (asc TS6054), so a project that
+ * builds has a tree left from an earlier manifest.
+ */
+function notGenerated(root: string, generated: string, message: string, sources: DataSource[]): string | undefined {
+  const missing = /Cannot find module '([^']+)'/.exec(message)?.[1] ?? /Directory import '([^']+)'/.exec(message)?.[1];
+  if (!missing) return undefined;
+  const relative = path.relative(generated, missing);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return undefined;
+  const dir = path.relative(root, generated) || ".";
+  const stale = "A tree generated for an earlier manifest may still have the file.";
+  if (message.includes("Directory import")) {
+    return `graph codegen writes no index.ts in ${dir}/, so \`graph build\` fails on this directory import as well. ${stale}`;
+  }
+  const parts = relative.split(path.sep);
+  const [kind, name, abi] =
+    parts[0] === "templates" && parts.length === 3
+      ? ["template", parts[1], parts[2]]
+      : parts.length === 2
+        ? ["data source", parts[0], parts[1]]
+        : [undefined, undefined, undefined];
+  if (!kind || !name || !abi) return undefined;
+  const candidates = sources.filter((source) => source.isTemplate === (kind === "template"));
+  const where = `${dir}/${kind === "template" ? "templates/" : ""}<${kind}>/<ABI>.ts`;
+  const source = candidates.find((candidate) => candidate.name === name);
+  const declared = source
+    ? `its ${kind} "${name}" has no ABI named "${abi.replace(/\.ts$/, "")}" (it has ${Object.keys(source.abis ?? {}).join(", ")})`
+    : `the manifest declares no ${kind} named "${name}" (it has ${candidates.map((candidate) => candidate.name).join(", ") || "none"})`;
+  return (
+    `graph codegen writes ${where} for each ${kind} of the manifest, and ${declared}, so \`graph build\` fails on ` +
+    `this import as well. ${stale}`
+  );
+}
+
+/**
+ * Why a generated file lacks a name a mapping imports from it: graph codegen
+ * writes a class per entity, event and ABI type it knows, and `graph build`
+ * fails on any other name too.
+ */
+function notExported(root: string, generated: string, mappingFile: string, message: string): string | undefined {
+  const found = /The requested module '([^']+)' does not provide an export named '([^']+)'/.exec(message);
+  if (!found) return undefined;
+  const [, specifier, name] = found;
+  if (!specifier.startsWith(".")) return undefined;
+  const target = path.resolve(path.dirname(path.resolve(root, mappingFile)), specifier);
+  const file = [target, `${target}.ts`].find((candidate) => existsSync(candidate) && candidate.endsWith(".ts"));
+  if (!file || !file.startsWith(path.resolve(generated) + path.sep)) return undefined;
+  const exported = [...readFileSync(file, "utf8").matchAll(/^export class (\w+)/gm)].map(([, klass]) => klass);
+  const lower = name.toLowerCase();
+  const similar = exported.filter((klass) => klass.toLowerCase().includes(lower) || lower.includes(klass.toLowerCase()));
+  const listed = (similar.length > 0 ? similar : exported.slice(0, 8)).sort();
+  return (
+    `${path.relative(root, file)} is graph codegen's output for this project and has no ${name}` +
+    `${listed.length > 0 ? ` (it exports ${listed.join(", ")})` : ""}, so \`graph build\` fails on this import as well.`
+  );
+}
+
+/**
+ * Why a project file a mapping imports isn't there: a package.json script
+ * writes it before `graph build` (Goldfinch's `"prebuild": "ts-node
+ * ./scripts/update-address-manifest.ts"` writes src/address-manifest.ts).
+ */
+function unwrittenImport(root: string, generated: string, message: string): string | undefined {
+  const found = /Cannot find module '([^']+)' imported from /.exec(message);
+  if (!found) return undefined;
+  const target = found[1]!;
+  const inside = (dir: string) => target.startsWith(path.resolve(dir) + path.sep);
+  if (!path.isAbsolute(target) || !inside(root) || inside(generated)) return undefined;
+  const stem = path.basename(target).replace(/\.[cm]?[jt]s$/, "");
+  const writers = subgraphScriptsWriting(root, stem) as string[][];
+  if (writers.length === 0) return undefined;
+  const file = path.relative(root, target) + (path.extname(target) ? "" : ".ts");
+  const names = writers.map(([name]) => `"${name}"`).join(", ");
+  return writers.length === 1
+    ? `${file}, which the mapping imports, isn't in the repo: the package.json script ${names} writes it ` +
+        `(${writers[0]![1]}), and \`graph build\` fails on this import too until it has run. Run it, then start ` +
+        "envio again."
+    : `${file}, which the mapping imports, isn't in the repo: the package.json scripts ${names} write it, and ` +
+        "`graph build` fails on this import too until one has run. Run the one for your network, then start " +
+        "envio again.";
+}
+
+async function loadMapping(
+  root: string,
+  generated: string,
+  mappingFile: string,
+  scope: Scope,
+  sources: DataSource[] = [],
+): Promise<Record<string, any>> {
+  const url = pathToFileURL(path.resolve(root, mappingFile)).href;
+  try {
+    // graph-node instantiates the module once per data source, with a host
+    // context already in place, so a mapping may read `dataSource.network()`
+    // at module top level — Balancer's constants do. The import runs inside a
+    // scope carrying that data source for the same reason.
+    return await runInScopeUntilSettled(scope, () => import(url));
+  } catch (exn) {
+    const message = exn instanceof Error ? exn.message : String(exn);
+    if (!existsSync(path.resolve(root, mappingFile))) {
+      throw new Error(
+        `Envio Subgraph failed to load the mapping ${mappingFile}: the manifest names it as a data source's ` +
+          `mapping file, and there is no such file under ${path.resolve(root)}. graph-cli refuses the manifest the ` +
+          'same way ("File does not exist").',
+      );
+    }
+    // Only reachable when codegen couldn't run up front, so this reports why
+    // rather than retrying: Node caches a failed resolution for the process.
+    if (message.includes(generated) && !existsSync(generated)) {
+      throw missingGeneratedCode(root, generated);
+    }
+    // An unknown named import fails at Node's ESM link step, before any Proxy
+    // in the shim can see it — rewrap it with the mapping that caused it.
+    const template = undeclaredTemplate(message);
+    if (template) throw new Error(`Envio Subgraph failed to load the mapping ${mappingFile}.\n  ${template}`);
+    const why =
+      notGenerated(root, generated, message, sources) ??
+      notExported(root, generated, mappingFile, message) ??
+      unwrittenImport(root, generated, message);
+    throw new Error(`Envio Subgraph failed to load the mapping ${mappingFile}.\n  ${message}${why ? `\n${why}` : ""}`);
+  }
+}
+
+let declaredTemplates: string[] = [];
+let manifestName = "subgraph.yaml";
+
+/**
+ * daohaus' per-network manifests leave out templates a listed mapping still
+ * imports; graph codegen writes a class only for a declared template, so
+ * `graph build` fails on the import as well.
+ */
+function undeclaredTemplate(message: string): string | null {
+  const missing = message.match(/requested module '([^']*)' does not provide an export named '([^']+)'/);
+  if (!missing || !/(^|\/)templates(\.ts)?$/.test(missing[1]!) || declaredTemplates.includes(missing[2]!)) return null;
+  const name = missing[2]!;
+  const declared = declaredTemplates.length > 0 ? `it declares ${declaredTemplates.join(", ")}` : "it declares none";
+  return (
+    `It imports ${name} from generated/templates, and ${manifestName} declares no template ${name} (${declared}). ` +
+    "graph codegen writes a class only for a template the manifest declares, so `graph build` fails on this " +
+    "import too: the manifest was likely written for another network or deployment than the mappings."
+  );
+}
+
+/**
+ * The generated event class each handler declares, keyed by the handler
+ * function itself. A manifest's mapping file may re-export handlers written in
+ * other files (SSV's does), and the class is exported only by the module the
+ * handler is written in.
+ */
+const eventClasses = new Map<Function, Function>();
+const indexedModules = new Set<string>();
+
+async function indexEventClasses(): Promise<void> {
+  for (const url of projectModules) {
+    if (indexedModules.has(url)) continue;
+    indexedModules.add(url);
+    let module: Record<string, any>;
+    try {
+      // Already evaluated: this only reads its namespace back.
+      module = await import(url);
+    } catch {
+      continue;
+    }
+    const classes = module[EVENT_CLASSES_EXPORT];
+    if (!classes) continue;
+    for (const [name, Class] of Object.entries(classes)) {
+      const handler = module[name];
+      if (typeof handler === "function" && typeof Class === "function") eventClasses.set(handler, Class);
+    }
+  }
+}
+
+type Effect = {
+  name: string;
+  handler: (args: { input: unknown; context: unknown; cacheKey: string; checkpointId: bigint }) => Promise<unknown>;
+};
+
+const REGISTER_SUSPEND = Symbol("envio.subgraph.register.suspend");
+
+/** envio's `Suspend` (a ReScript exception) and the register pass's own: control flow, not errors. */
+function isBridgeSignal(error: unknown): boolean {
+  return error === REGISTER_SUSPEND || (typeof error === "object" && error !== null && "RE_EXN_ID" in error);
+}
+
+/**
+ * Results the register pass has already fetched, across events and blocks.
+ *
+ * A host op's input carries the block it is evaluated at, so an entry can never
+ * go stale — and a factory calling `symbol()` on the same token for every pair
+ * it creates asks the same question hundreds of times. envio's own effect cache
+ * is out of reach here: it hangs off the processing context, and this runs at
+ * fetch time.
+ */
+const registerCache = new Map<string, { value?: unknown; error?: unknown }>();
+const REGISTER_CACHE_LIMIT = 20_000;
+/**
+ * The register passes of a response's items run concurrently, so the same op
+ * at the same block — every pair a factory creates in one block reading the
+ * factory — is usually still in flight when the next pass asks for it.
+ */
+const registerInFlight = new Map<string, Promise<unknown>>();
+
+/**
+ * What the finished register passes cost in host ops (contract calls, balances,
+ * block lookups) each. `ChainFetching` reads it to decide how many register
+ * passes one fetched response may hold: a pass that makes no call needs no
+ * limit, a pass that makes a dozen is what keeps a response from committing.
+ * Unknown (undefined) until enough passes have finished to say.
+ */
+const registerCost = { hostOps: 0, passes: 0 };
+const REGISTER_COST_MIN_PASSES = 20;
+// ChainFetching reports each chain's lowest partition frontier after every
+// response it applies; the register store keeps the versions above it.
+(globalThis as any).__envioSubgraphRegisterFrontier = setRegisterFrontier;
+(globalThis as any).__envioSubgraphRegisterCostPerItem = () =>
+  registerCost.passes < REGISTER_COST_MIN_PASSES ? undefined : registerCost.hostOps / registerCost.passes;
+
+async function runRegisterHost(effect: Effect, input: unknown, chainId: number): Promise<unknown> {
+  // A resync after `envio start -r` keeps the stored call answers; the handler
+  // pass reads them through the effect machinery, this pass reads them here.
+  const stored = await storedEffectOutput(effect as any, chainId, input as any);
+  if (stored !== undefined) return stored;
+  return effect.handler({
+    input,
+    // Only `blockTimestamp` reads the context, and only for the chain id, which
+    // the input already carries for every other host op.
+    context: { chain: { id: chainId } },
+    cacheKey: "",
+    checkpointId: 0n,
+  });
+}
+
+/**
+ * The register pass's half of the sync bridge (§5).
+ *
+ * `contractRegister` runs at fetch time with a context that can only register
+ * addresses — no in-memory store, so no effects. But a factory mapping routinely
+ * reads a contract *before* deciding what to create, so the answer has to arrive
+ * somehow: the op is started, the mapping is suspended, and the round is
+ * replayed once it lands. Same shape as the handler pass, with the results
+ * memoised here instead of in envio's effect tables.
+ */
+/**
+ * A host op that failed, not a mapping that threw. The two are told apart
+ * because the register pass forgives a mapping error — see `runRegisterRounds`
+ * — and forgiving this one would silently drop the `dataSource.create()` calls
+ * the pass exists to collect.
+ */
+class RegisterHostFailure extends Error {
+  constructor(op: string, readonly reason: unknown) {
+    super(`Envio Subgraph could not resolve ${op} while registering contracts: ${String(reason)}`);
+    this.cause = reason;
+  }
+}
+
+function registerHostSync(scope: Scope, effect: Effect, input: unknown) {
+  const key = `${effect.name}\u0000${typeof input === "string" ? input : JSON.stringify(input)}`;
+  const resolved = scope.resolved ?? new Map();
+  scope.resolved = resolved;
+
+  const hit = resolved.get(key) ?? registerCache.get(key);
+  if (hit) {
+    if ("error" in hit) throw new RegisterHostFailure(effect.name, hit.error);
+    return hit.value;
+  }
+
+  const awaiting = scope.awaiting ?? [];
+  scope.awaiting = awaiting;
+  let flight = registerInFlight.get(key);
+  if (!flight) {
+    registerCost.hostOps++;
+    const started = runRegisterHost(effect, input, scope.dataSource.chainId);
+    flight = started;
+    registerInFlight.set(key, started);
+    const settle = () => {
+      if (registerInFlight.get(key) === started) registerInFlight.delete(key);
+    };
+    started.then(settle, settle);
+  }
+  awaiting.push(
+    flight.then(
+      (value) => {
+        resolved.set(key, { value });
+        if (registerCache.size >= REGISTER_CACHE_LIMIT) registerCache.clear();
+        registerCache.set(key, { value });
+      },
+      // A failure is remembered for this event only: a transport error that
+      // fails the batch must not poison every later block too.
+      (error) => resolved.set(key, { error }),
+    ),
+  );
+  throw REGISTER_SUSPEND;
+}
+
+/**
+ * A batch's register passes run concurrently, and a pass's writes reach the
+ * register store only when it completes. Every Comptroller event in Venus's
+ * first batch missed the Market an earlier event was still creating, and
+ * repeated its ~20 creation calls at its own block. So a pass that misses an
+ * entity an earlier pass of its chain also missed, and is still running,
+ * waits for the earliest such pass once and reads again — the per-key order
+ * graph-node's sequential processing gives. Independent events stay
+ * concurrent; a key nobody ends up writing costs one wait.
+ *
+ * An earlier pass that hasn't read the key yet — Dolomite's admin handler
+ * saves each Token after a contract call — isn't among its missers, so a miss
+ * while any earlier pass of the chain still runs is only provisional: once the
+ * pass ends, it waits for those passes and runs again before its writes count.
+ */
+const missers = new Map<string, RegisterPass[]>();
+
+/** Each chain's running passes and the passes waiting on them, by position. */
+type ChainPasses = {
+  running: RegisterPass[];
+  waiters: { position: number; release: () => void }[];
+};
+const chainPasses = new Map<number, ChainPasses>();
+
+/** Passes start in about the order of their events, so this mostly appends. */
+function insertByPosition<T extends { position: number }>(list: T[], item: T) {
+  let at = list.length;
+  while (at > 0 && list[at - 1].position > item.position) at--;
+  list.splice(at, 0, item);
+}
+
+function startRegisterPass(chainId: number, position: number): { pass: RegisterPass; settle: () => void } {
+  let resolve!: () => void;
+  const pass: RegisterPass = {
+    chainId,
+    position,
+    done: new Promise<void>((done) => (resolve = done)),
+    settled: false,
+    missed: [],
+    provisional: false,
+  };
+  const passes = chainPasses.get(chainId) ?? { running: [], waiters: [] };
+  chainPasses.set(chainId, passes);
+  insertByPosition(passes.running, pass);
+  const settle = () => {
+    pass.settled = true;
+    passes.running.splice(passes.running.indexOf(pass), 1);
+    const first = passes.running[0]?.position ?? Infinity;
+    while (passes.waiters.length > 0 && passes.waiters[0].position <= first) passes.waiters.shift()!.release();
+    if (passes.running.length === 0 && passes.waiters.length === 0) chainPasses.delete(chainId);
+    for (const key of pass.missed) {
+      const remaining = (missers.get(key) ?? []).filter((other) => other !== pass);
+      if (remaining.length === 0) missers.delete(key);
+      else missers.set(key, remaining);
+    }
+    registerCost.passes++;
+    resolve();
+  };
+  return { pass, settle };
+}
+
+function earlierPassRunning(pass: RegisterPass): boolean {
+  const first = chainPasses.get(pass.chainId)?.running[0];
+  return first !== undefined && first.position < pass.position;
+}
+
+function earlierPassesSettled(pass: RegisterPass): Promise<void> {
+  const passes = chainPasses.get(pass.chainId);
+  if (!passes || !earlierPassRunning(pass)) return Promise.resolve();
+  return new Promise((release) => insertByPosition(passes.waiters, { position: pass.position, release }));
+}
+
+function onRegisterMiss(scope: Scope, key: string) {
+  const pass = scope.pass;
+  if (!pass) return;
+  const list = missers.get(key) ?? [];
+  if (!scope.waitedKeys?.has(key)) {
+    const earlier = list.find((other) => other.position < pass.position && !other.settled);
+    if (earlier) {
+      (scope.waitedKeys ??= new Set()).add(key);
+      (scope.awaiting ??= []).push(earlier.done);
+      scope.waitsOnPass = true;
+      throw REGISTER_SUSPEND;
+    }
+  }
+  if (!list.includes(pass)) {
+    list.push(pass);
+    list.sort((a, b) => a.position - b.position);
+    missers.set(key, list);
+    pass.missed.push(key);
+  }
+  if (!pass.provisional && earlierPassRunning(pass)) pass.provisional = true;
+}
+
+/**
+ * True when the pass's round must run again: a read missed while an earlier
+ * pass was running, which may have written it since. Its writes are dropped;
+ * a create it made stands, and the rerun registers nothing twice.
+ */
+async function rerunProvisional(scope: Scope): Promise<boolean> {
+  const pass = scope.pass;
+  if (!pass?.provisional) return false;
+  pass.provisional = false;
+  scope.writes = undefined;
+  const settled = earlierPassesSettled(pass);
+  await (scope.slot ? scope.slot.pause(settled) : settled);
+  return true;
+}
+
+/**
+ * graph-node runs every trigger in a fresh instance of the mapping's module
+ * (runtime/wasm/src/mapping.rs instantiates it before each `handle_trigger`):
+ * the files' top-level code runs again in that trigger's context, and no
+ * global keeps what an earlier trigger left in it. Each project module's
+ * `__envio_init` reruns its top-level code after that of the modules it
+ * imports, once per generation.
+ */
+let moduleGeneration = 0;
+function freshModuleState(scope: Scope): void {
+  resetNullObjects();
+  scope.mappingExports[MODULE_INIT]?.(++moduleGeneration);
+}
+
+// A round answers the one call the mapping stopped at, so a handler making N
+// calls before its create() takes N rounds; graph-node has no limit at all.
+// The handler pass's own bound (UserContext.maxSyncRounds).
+const maxRegisterRounds = 10_000;
+
+async function runRegisterRounds(scope: Scope, fn: () => void): Promise<void> {
+  for (let round = 1; round <= maxRegisterRounds; round++) {
+    scope.awaiting = undefined;
+    // A suspended round is replayed from the top, so its writes are dropped.
+    scope.writes = undefined;
+    let suspended = false;
+    try {
+      runInScope(scope, () => {
+        freshModuleState(scope);
+        fn();
+      });
+    } catch (error) {
+      if (error !== REGISTER_SUSPEND) {
+        // A host op that failed is never forgiven: the mapping was about to
+        // decide what to create from its answer, and the handler pass cannot
+        // repair a missed registration — addresses are registered at fetch
+        // time. `untilAnswered` has already outlasted anything transient.
+        if (error instanceof RegisterHostFailure) throw error;
+        // This pass exists to collect `dataSource.create()` calls, and it runs
+        // against a store that only holds what earlier register passes wrote —
+        // so a handler that assumes its entities exist can throw here even
+        // though it is perfectly correct, before or after a create. What it
+        // registered until then stands; the same mapping runs again with the
+        // real store, and any error that is genuinely the mapping's surfaces
+        // there.
+        if (await rerunProvisional(scope)) continue;
+        commitRegisterWrites(scope);
+        return;
+      }
+      suspended = true;
+    }
+    const awaiting = scope.awaiting;
+    if (!suspended) {
+      if (await rerunProvisional(scope)) continue;
+      commitRegisterWrites(scope);
+      return;
+    }
+    if (!awaiting || awaiting.length === 0) {
+      throw new Error(
+        "Envio Subgraph suspended the register pass with nothing to wait for. " +
+          "Please open an issue: https://github.com/enviodev/hyperindex/issues",
+      );
+    }
+    const everything = Promise.all(awaiting);
+    const pausing = scope.waitsOnPass === true;
+    scope.waitsOnPass = false;
+    await (pausing && scope.slot ? scope.slot.pause(everything) : everything);
+  }
+  throw new Error(
+    `Envio Subgraph replayed a mapping's dataSource.create() pass ${maxRegisterRounds} times ` +
+      "without it settling. This usually means the mapping isn't deterministic across reruns.",
+  );
+}
+
+/**
+ * A subgraph team's first move is to POST a query to the indexer's port, the
+ * way graph-node serves one — which answers /metrics only.
+ */
+function announceWhereToQuery() {
+  info(
+    `Envio Subgraph writes the subgraph's entities to Postgres (database "${Db.database}", ` +
+      `schema "${Db.publicSchema}"). This process serves no GraphQL: port ${serverPort} answers ` +
+      "/metrics and /healthz only. " +
+      (Hasura.enabled
+        ? `Hasura (${Hasura.url}) serves envio's own GraphQL over those tables, not The Graph's query API. `
+        : "") +
+      "The Graph's query API (/subgraphs/name/<name>) is served from the same database by " +
+      "envio-serve's subgraph API.",
+  );
+}
+
+/**
+ * The template addresses register passes registered, by chain. A handler pass
+ * runs soon after its event's register pass, so the latest ones are enough.
+ */
+const registeredTemplates = new Set<string>();
+/** Templates with a block handler: their instances' creation blocks are kept. */
+const blockTemplates = new Set<string>();
+const REGISTERED_TEMPLATES_LIMIT = 100_000;
+const unregisteredCreates = new Set<string>();
+
+/**
+ * A `call` block handler is a call handler, and a data source's other block
+ * handlers get a register pass of their own for each of their blocks. A
+ * template's `once` one gets a pass right after the one that creates each
+ * instance; its unfiltered and polling ones run per instance as a handler
+ * only: its instances are known only as register passes register them, so no
+ * pass of one block can list them.
+ */
+function hasRegisterPass(source: DataSource, handler: BlockHandler): boolean {
+  return handler.filter === "call" || handler.filter === "once" || !source.isTemplate;
+}
+
+const BLOCK_HANDLER_CREATE =
+  "envio registers a template's instances in a register pass ahead of the handlers, and a template's " +
+  "unfiltered and polling block handlers get none, nor does a data source's that runs on many blocks " +
+  "unless its code surely reaches a template's generated class, so the instances one creates would " +
+  "never have their events indexed";
+
+/** A data source's block handler that runs on at most this many blocks may get a pass on suspicion. */
+const FEW_BLOCK_HANDLER_BLOCKS = 1_000;
+
+/**
+ * Where a block handler sits in its block for the register pass's store: a
+ * `once` handler ahead of the block's logs (graph-node's
+ * `EthereumBlockTriggerType::Start`), any other after its logs and calls, ahead
+ * of the data sources the block creates.
+ */
+function blockHandlerPosition(blockNumber: number, once: boolean): number {
+  return once ? blockNumber * POSITION_BLOCK - 1 : blockNumber * POSITION_BLOCK + ROUND_SPAN - 0.5;
+}
+
+/**
+ * The block and round each registered address was created in, by the same key.
+ * graph-node runs a data source's events of its creation block in a later round
+ * than the handler that created it, so a register pass for them must read what
+ * that handler's pass saved, whatever the log order. A round past the position
+ * span is clamped.
+ */
+const registrationRounds = new Map<string, { block: number; round: number }>();
+
+function roundOf(chainId: number, name: string, address: string, block: number): number {
+  const entry = registrationRounds.get(`${chainId}:${name}:${address.toLowerCase()}`);
+  return entry !== undefined && entry.block === block ? entry.round : 0;
+}
+
+type FileTemplate = {
+  name: string;
+  kind: "ipfs" | "arweave";
+  /** The mapping function the manifest names. */
+  handler: string;
+  /** The `entities` the manifest lists: all a file data source may touch. */
+  entities: Set<string>;
+  mapping: Record<string, any>;
+};
+
+/** The table that records which file data sources have run (`FILE_DATA_SOURCE_ENTITY`, Rust). */
+const FILE_DATA_SOURCE_ENTITY = "EnvioFileDataSource";
+/** A mapping that makes its file data sources create more, forever, is stopped here. */
+const MAX_FILES_PER_TRIGGER = 10_000;
+
+/**
+ * Runs the file data sources a handler created, right after it, in the block
+ * that created them (graph-node runs them when their file arrives, which is
+ * some later block; running at the creating block is deterministic, and
+ * entities a file handler writes are in the store the moment the creating block
+ * is). Each runs in isolation, as graph-node's do:
+ *
+ * - only once per template, file and context (a record in its own table, so a
+ *   reorg or a restart doesn't run it twice, and a second create is ignored);
+ * - it may touch only the entities its manifest entry lists, and sees only what
+ *   it wrote itself — never a chain entity (`graph-ts.ts` store);
+ * - a file that isn't there after `ENVIO_SUBGRAPH_FILE_ATTEMPTS` attempts
+ *   skips the handler, with a warning (graph-node polls on, with backoff);
+ * - a CID that doesn't parse is ignored, as graph-node ignores it.
+ *
+ * A file handler may itself create file data sources; those run after it.
+ * During preload only the files are fetched, so a batch's files download
+ * concurrently and the execute pass finds them cached.
+ */
+function makeFileRunner(
+  fileTemplates: Map<string, FileTemplate>,
+  hosts: HostEffects,
+  schema: SubgraphSchema,
+) {
+  return async (parent: Scope | undefined, context: any): Promise<void> => {
+    if (!parent?.fileCreates || parent.fileCreates.size === 0) return;
+    const queue: FileCreate[] = [...parent.fileCreates.values()];
+    for (let index = 0; index < queue.length; index++) {
+      if (index >= MAX_FILES_PER_TRIGGER) {
+        throw new Error(
+          `A handler created more than ${MAX_FILES_PER_TRIGGER} file data sources from one trigger; ` +
+            "a file data source that keeps creating more is not going to stop.",
+        );
+      }
+      const create = queue[index];
+      const template = fileTemplates.get(create.template);
+      if (!template) continue;
+      const path =
+        template.kind === "ipfs" ? normalizeIpfsPath(create.source) : create.source.trim().replace(/^\//, "") || null;
+      if (path === null) {
+        context.log.warn(
+          `${template.name}.create() was given "${create.source}", which isn't a content id; ignoring the file data source.`,
+        );
+        continue;
+      }
+      const input = `${template.kind}:${path}`;
+      if (context.isPreload) {
+        await context.effect(hosts.fileData, input);
+        continue;
+      }
+      const handler = template.mapping[template.handler];
+      if (typeof handler !== "function") continue;
+
+      const doneId = createHash("sha1").update(fileCreateId(create)).digest("hex");
+      const done = context[schema.entityAccessors[FILE_DATA_SOURCE_ENTITY]];
+      if (await done.get(doneId)) continue;
+
+      const content: string | null = await context.effect(hosts.fileData, input);
+      if (content === null) {
+        context.log.warn(`${template.name}: ${input} isn't available; its handler is skipped.`);
+        continue;
+      }
+      done.set({ id: doneId });
+
+      const ran: { scope?: Scope } = {};
+      await context.runSync(() =>
+        runInScope(
+          (ran.scope = {
+            context,
+            event: parent.event,
+            mode: "handler",
+            schema,
+            dataSource: { ...parent.dataSource, name: template.name, address: path, context: {} },
+            registered: new Set(),
+            blockNumber: parent.blockNumber,
+            position: parent.position,
+            mappingExports: template.mapping,
+            file: {
+              kind: template.kind,
+              entities: template.entities,
+              written: new Set(),
+              context: create.context,
+            },
+          }),
+          () => {
+            freshModuleState(ran.scope!);
+            return handler(decodeBase64(content));
+          },
+        ),
+      );
+      if (ran.scope?.fileCreates) queue.push(...ran.scope.fileCreates.values());
+    }
+  };
+}
+
+export async function registerSubgraph(config: SubgraphConfig, logger: unknown): Promise<void> {
+  setLogger(logger);
+  legacyNulls = [...config.dataSources, ...config.templates].some((source) => {
+    const [major, minor, patch] = (source.apiVersion ?? "").split(".").map(Number);
+    return major === 0 && minor === 0 && patch < 5;
+  });
+  setLegacyNullOperands(legacyNulls);
+  installResolveHook(config.root);
+  resetRpcClients();
+  resetStartupTables();
+  resetCallBackends();
+  // The chain's sources read calls only when a handler wants them.
+  installCallSource(fetchCalls, config.rpcUrls ?? []);
+  resetRegisterStore();
+  registeredTemplates.clear();
+  blockTemplates.clear();
+  for (const template of config.templates) {
+    if (template.blockHandlers.length > 0) blockTemplates.add(template.name);
+  }
+  registrationRounds.clear();
+  unregisteredCreates.clear();
+  announceWhereToQuery();
+  if (config.graftNotice) warn(config.graftNotice);
+  for (const notice of config.notices ?? []) warn(notice);
+  if (config.graft && process.env.ENVIO_SUBGRAPH_GRAFT_CHECK !== "off") {
+    const ownStarts = config.dataSources.flatMap((source) =>
+      source.startBlock === undefined ? [] : [source.startBlock],
+    );
+    // Best effort and not waited on: an offline box or an unpinned base says nothing.
+    void graftBaseNotice(config.graft, ownStarts).then(
+      (notice) => notice && warn(notice),
+      () => undefined,
+    );
+  }
+
+  // One effect for every contract call: envio already batches and dedupes
+  // effect calls in preload, and the block number in the input is what keeps
+  // a cached result tied to the state the mapping saw.
+  const rpcUrls = config.rpcUrls ?? [];
+  const callEffect = makeCallEffect(rpcUrls, (encoded) => {
+    const hit = registerCache.get(`envio_subgraph_eth_call\u0000${encoded}`);
+    return hit && "value" in hit ? (hit.value as string) : undefined;
+  });
+  const hosts = makeHostEffects(rpcUrls, config.blockHeaderLag ?? {}, config.rpcOnlyChains ?? []);
+  const callSync = (effect: unknown, input: unknown) => {
+    const scope = currentScope();
+    if (scope.mode === "register") {
+      return registerHostSync(scope, effect as Effect, input);
+    }
+    return scope.context.effectSync(effect, input);
+  };
+
+  installHosts({
+    // graph-node's `ipfs.cat` answers null for a path its ContentPath refuses.
+    ipfsCat: (hash) => {
+      const path = normalizeIpfsPath(hash);
+      return path === null ? null : callSync(hosts.ipfsCat, path);
+    },
+    ipfsMap: (hash, callback, userData, flags) => {
+      const scope = currentScope();
+      // graph-node: `ensure!(flags.contains("json"), "Flags must contain 'json'")`.
+      if (!flags.includes("json")) throw new Error("ipfs.map(): Flags must contain 'json'");
+      const fn = scope.mappingExports[callback];
+      if (typeof fn !== "function") {
+        throw new Error(
+          `ipfs.map() names the callback "${callback}", which the mapping doesn't export.`,
+        );
+      }
+      const path = normalizeIpfsPath(hash);
+      if (path === null) throw new Error(`ipfs.map(): "${hash}" is not an IPFS content path`);
+      const encoded: string | null = callSync(hosts.ipfsMapFile, path);
+      if (encoded === null) return;
+      const body = Buffer.from(encoded, "base64").toString("utf8");
+      // One JSON value per line, each handed to the callback in turn; a line
+      // that isn't JSON, or a callback that throws, fails the call, as
+      // graph-node's `ipfs_map: callback '<name>' failed when processing file`.
+      const lines = body.split("\n");
+      for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (line.trim() === "") continue;
+        try {
+          fn(jsonFromString(line), userData);
+        } catch (error) {
+          // A suspend is the sync bridge asking for a replay, not a failure.
+          if (isBridgeSignal(error) || !(error instanceof Error)) throw error;
+          error.message = `ipfs_map: callback '${callback}' failed when processing file '${hash}' (line ${index + 1}): ${error.message}`;
+          throw error;
+        }
+      }
+    },
+    arweaveData: (txId) => callSync(hosts.arweaveData, txId),
+    ensName: (hash) => callSync(hosts.ensName, hash),
+    getBalance: (address) =>
+      callSync(
+        hosts.getBalance,
+        JSON.stringify({ address, blockNumber: currentScope().blockNumber }),
+      ),
+    hasCode: (address) =>
+      callSync(
+        hosts.hasCode,
+        JSON.stringify({ address, blockNumber: currentScope().blockNumber }),
+      ),
+    blockTimestamp: (blockNumber) =>
+      callSync(hosts.blockTimestamp, blockNumber),
+    blockHeader: (blockNumber) => callSync(hosts.blockHeader, blockNumber),
+    receiptLogs: (transaction) => callSync(hosts.receiptLogs, transaction),
+  });
+
+  // Reads the scope rather than closing over one context: register passes for
+  // the items in a batch run concurrently, and this hook is process-wide.
+  installRegisterMissHook(onRegisterMiss);
+
+  // A template's `once` handler runs for an instance at the block that created
+  // it, in the round after its creator (graph-node's reprocessing of that
+  // block for the new data source starts with its `Start` trigger). Its
+  // register pass runs right after the pass that created the instance, with
+  // that pass's register context, so what it creates is registered at the
+  // same block.
+  const templateOnces = new Map<string, (parent: Scope, address: string) => Promise<Scope>>();
+  const runTemplateOnces = async (parent: Scope): Promise<void> => {
+    const queue = [...(parent.templateOnces ?? [])];
+    parent.templateOnces = undefined;
+    for (let index = 0; index < queue.length; index++) {
+      if (index >= MAX_FILES_PER_TRIGGER) {
+        throw new Error(
+          `A handler created more than ${MAX_FILES_PER_TRIGGER} template instances with a once handler from ` +
+            "one trigger; a once handler that keeps creating more is not going to stop.",
+        );
+      }
+      const { template, address } = queue[index]!;
+      const nested = await templateOnces.get(template)!(parent, address);
+      queue.push(...(nested.templateOnces ?? []));
+    }
+  };
+
+  installRegisterHook((templateName, address) => {
+    const accessor = config.contractAccessors[templateName];
+    if (accessor === undefined) throw unknown(`the template ${templateName}`, "a mapping handler");
+    const scope = currentScope();
+    scope.context.chain[accessor].add(address);
+    if (templateOnces.has(templateName)) {
+      (scope.templateOnces ??= []).push({ template: templateName, address });
+    }
+    if (blockTemplates.has(templateName)) {
+      rememberInstance(scope.dataSource.chainId, templateName, address, scope.blockNumber);
+    }
+    const key = `${scope.dataSource.chainId}:${templateName}:${address.toLowerCase()}`;
+    registeredTemplates.delete(key);
+    registeredTemplates.add(key);
+    if (!registrationRounds.has(key)) {
+      const { dataSource, blockNumber } = scope;
+      const round = roundOf(dataSource.chainId, dataSource.name, dataSource.address, blockNumber) + 1;
+      registrationRounds.set(key, { block: blockNumber, round });
+    }
+    if (registeredTemplates.size > REGISTERED_TEMPLATES_LIMIT) {
+      const oldest = registeredTemplates.values().next().value!;
+      registeredTemplates.delete(oldest);
+      registrationRounds.delete(oldest);
+    }
+  });
+
+  // Only the register pass registers an address, at fetch time. A create it
+  // didn't make (it threw on an entity no register pass saved) loses that
+  // template's events; one from a template's block handler, which has no
+  // register pass, is refused.
+  installHandlerCreateHook((templateName, address) => {
+    const scope = currentScope();
+    if (scope.context.isPreload) return;
+    const key = `${scope.dataSource.chainId}:${templateName}:${address.toLowerCase()}`;
+    if (registeredTemplates.has(key) || unregisteredCreates.has(key)) return;
+    if (scope.blockHandler) {
+      throw unsupported(
+        "creating contract templates from a block handler without a register pass",
+        `data source "${scope.dataSource.name}" → blockHandlers → "${scope.blockHandler}", which created ` +
+          `${templateName} ${address.toLowerCase()} at block ${scope.blockNumber}`,
+        BLOCK_HANDLER_CREATE,
+      );
+    }
+    unregisteredCreates.add(key);
+    warn(
+      `Envio Subgraph: data source "${scope.dataSource.name}" created the template "${templateName}" for ` +
+        `${address.toLowerCase()} at block ${scope.blockNumber} in its handler, but no register pass did, so the ` +
+        `events of that ${templateName} are not indexed. A register pass reads only what earlier register passes ` +
+        "saved. Please open an issue: https://github.com/enviodev/hyperindex/issues",
+    );
+  });
+
+  const abiFiles = new Map<string, string>();
+  for (const source of [...config.dataSources, ...config.templates]) {
+    for (const [name, file] of Object.entries(source.abis ?? {})) {
+      if (!abiFiles.has(name)) abiFiles.set(name, path.resolve(config.root, file));
+    }
+  }
+  const legacySignatures = new Map<string, string>();
+  installLegacySignatureHook((abiName, functionName) => {
+    const key = `${abiName}.${functionName}`;
+    const known = legacySignatures.get(key);
+    if (known) return known;
+    const file = abiFiles.get(abiName);
+    const signature = file ? functionSignature(JSON.parse(readFileSync(file, "utf8")), functionName) : null;
+    if (!signature) {
+      throw new Error(
+        `Envio Subgraph: the mapping calls ${key} by name, and the manifest's ABI "${abiName}" has no function ` +
+          `${functionName}. graph-node fails the call the same way.`,
+      );
+    }
+    legacySignatures.set(key, signature);
+    return signature;
+  });
+
+  installCallHook((call) => {
+    const scope = currentScope();
+    const encoded = JSON.stringify({
+      chainId: scope.dataSource.chainId,
+      address: call.contractAddress.toHexString(),
+      signature: call.functionSignature,
+      args: call.functionParams.map((param: any) => encodeArg(ethereumValueToJs(param))),
+      blockNumber: scope.blockNumber,
+    });
+    const raw = callSync(callEffect, encoded);
+    if (raw === null) {
+      return { reverted: true, value: null };
+    }
+    const output = JSON.parse(raw);
+    return {
+      reverted: output.reverted,
+      value: output.values === null ? null : output.values.map(decodeArg),
+    };
+  });
+
+  const schema: SubgraphSchema = {
+    timestampFields: config.timestampFields ?? {},
+    entityListFields: config.entityListFields ?? {},
+    entityFields: config.entityFields ?? {},
+    entityRefFields: config.entityRefFields ?? {},
+    entityFieldTypes: config.entityFieldTypes ?? {},
+    entityAccessors: config.entityAccessors,
+    timeseriesEntities: config.timeseriesEntities ?? [],
+    skipDuplicateEntities: config.skipDuplicateEntities ?? [],
+    aggregations: config.aggregations ?? [],
+  };
+  const secondsOf = (blockNumber: number, given: unknown) => () =>
+    given !== undefined && given !== null
+      ? Number(given)
+      : Number(callSync(hosts.blockTimestamp, blockNumber));
+  // Aggregations roll up when a block's time passes a bucket's end, so every
+  // handler checks first; the timeseries it saves carry the block's time.
+  // graph-node's `SeqGenerator`: one id sequence per block, which its handlers
+  // draw from in the order they run, so a timeseries row gets graph-node's id.
+  // The execute pass runs a chain's handlers one at a time; a run starts where
+  // the block's previous run stopped, and a replayed run starts over there.
+  const idSequences = new Map<number, { block: number; next: number }>();
+  const idSequence = (scope: Scope) => {
+    const chainId = scope.dataSource.chainId;
+    let sequence = idSequences.get(chainId);
+    if (!sequence || sequence.block !== scope.blockNumber) {
+      sequence = { block: scope.blockNumber, next: 0 };
+      idSequences.set(chainId, sequence);
+    }
+    return sequence;
+  };
+  const endRun = (scope: Scope) => {
+    if (scope.timeseriesBase === undefined) return;
+    idSequence(scope).next = scope.timeseriesBase + (scope.timeseriesSequence ?? 0);
+  };
+  const startRun = (scope: Scope) => {
+    freshModuleState(scope);
+    scope.timeseriesSequence = 0;
+    if (!scope.context.isPreload) scope.timeseriesBase ??= idSequence(scope).next;
+    // A replayed round creates its file data sources again.
+    scope.fileCreates = undefined;
+    if (schema.aggregations.length > 0) {
+      advanceRollup(scope, BigInt(scope.blockSeconds!()) * 1_000_000n);
+    }
+  };
+
+  // Before any mapping is imported: Node caches a failed module resolution for
+  // the life of the process, so generating after the import has already failed
+  // wouldn't help.
+  const sources = [...config.dataSources, ...config.templates];
+  const handlersOf = (source: (typeof sources)[number]): string[] =>
+    [...source.eventHandlers, ...(source.callHandlers ?? []), ...source.blockHandlers].map(
+      (handler) => handler.handler,
+    );
+  let registerPassHandlers: Map<(typeof sources)[number], Set<string>> | undefined;
+  const generated = generatedDir(
+    config.root,
+    sources.map((source) => source.mappingFile),
+  );
+  const fetchedModules = await fetchMappingPackages(
+    config.root,
+    missingMappingPackages(
+      config.root,
+      sources.map((source) => source.mappingFile),
+    ).filter((name) => !workspacePackages.has(name)),
+  );
+  fetchedModulesParent = fetchedModules
+    ? pathToFileURL(path.join(path.dirname(fetchedModules), "resolve-from.mjs")).href
+    : null;
+  const rendered = config.renderedManifest;
+  manifestName = config.manifestFile ?? "subgraph.yaml";
+  declaredTemplates = config.templates.map((template) => template.name);
+  if (rendered?.commands?.length) {
+    info(
+      `Envio Subgraph ran ${rendered.commands.map((command) => `\`${command}\``).join(", ")} from the package.json ` +
+        `script "${rendered.script}" first: it is the one that writes ${manifestName}` +
+        (rendered.network ? ` (network "${rendered.network}").` : "."),
+    );
+  } else if (rendered?.steps?.length) {
+    info(
+      `Envio Subgraph ran ${rendered.steps.map((step) => `\`${step}\``).join(", ")} from the codegen script ` +
+        `first: it writes ${manifestName}` +
+        (rendered.network ? ` (network "${rendered.network}"; ENVIO_SUBGRAPH_NETWORK picks another).` : "."),
+    );
+  } else if (rendered) {
+    const how =
+      rendered.template === rendered.view
+        ? `copied ${rendered.template} to ${manifestName}`
+        : `rendered ${manifestName} from ${rendered.template} with ${rendered.view}`;
+    info(
+      `Envio Subgraph ${how} for the network "${rendered.network}", as the package.json script ` +
+        `"${rendered.script}" does. ENVIO_SUBGRAPH_NETWORK picks another.`,
+    );
+  }
+  if (config.buildNetwork) {
+    info(
+      `Envio Subgraph built ${manifestName} for the network "${config.buildNetwork}" from networks.json, ` +
+        `as the project's own build does (\`graph build --network ${config.buildNetwork}\`). ` +
+        "ENVIO_SUBGRAPH_NETWORK picks another.",
+    );
+  }
+  for (const [written, found] of config.pathFixes ?? []) {
+    warn(
+      path.isAbsolute(found)
+        ? `Envio Subgraph: ${manifestName} names ${written}, in a package the project's install didn't ` +
+            `provide; envio reads it from the package fetched into ${found}.`
+        : `Envio Subgraph: ${manifestName} names ${written}, and the repo has ${found}. They match only on a ` +
+            "filesystem that ignores case (macOS's and Windows' by default), where the subgraph builds; " +
+            `envio reads ${found}.`,
+    );
+  }
+  await ensureGeneratedCode(
+    config.root,
+    generated,
+    config.manifestFile,
+    sources.map((source) => source.mappingFile),
+    {
+      renderScripts: rendered && !rendered.steps?.length ? [rendered.script, ...(rendered.inlined ?? [])] : [],
+      ranSteps: rendered?.steps,
+      pathFixes: config.pathFixes,
+    },
+  );
+
+  if (config.isDev) {
+    await typeCheckMappings(config.root, config.manifestFile, config.pathFixes);
+  }
+
+  // A file template has no contract: nothing is registered for it, so it takes
+  // no part in the create analysis or the folding below.
+  const isFile = (source: DataSource) => source.kind === "fileIpfs" || source.kind === "fileArweave";
+  const templateNames = new Set(
+    config.templates.filter((template) => !isFile(template)).map((template) => template.name),
+  );
+  const sureCreatingBySource = new Map<DataSource, Set<string>>();
+  const sureCreating = (source: DataSource): Set<string> => {
+    let found = sureCreatingBySource.get(source);
+    if (!found) {
+      const handlers = source.blockHandlers.map((handler) => handler.handler);
+      const created = subgraphSureCreates(path.resolve(config.root, source.mappingFile), handlers, [
+        ...templateNames,
+      ]);
+      found = new Set(handlers.filter((_, index) => created[index]!.length > 0));
+      sureCreatingBySource.set(source, found);
+    }
+    return found;
+  };
+  // A template's block handler's create is refused when it runs (the create
+  // hook above). Whether one will run depends on data — moonwell's Feed
+  // handler creates only at the blocks its network's config lists, none on
+  // base — so the creates the analysis is sure the code reaches are named up
+  // front, as a warning.
+  if (templateNames.size > 0) {
+    for (const source of sources) {
+      const handlers = source.blockHandlers
+        .filter((handler) => !hasRegisterPass(source, handler))
+        .map((handler) => handler.handler);
+      if (source.kind !== "contract" || handlers.length === 0) continue;
+      const created = subgraphSureCreates(path.resolve(config.root, source.mappingFile), handlers, [...templateNames]);
+      handlers.forEach((handler, index) => {
+        if (created[index]!.length === 0) return;
+        warn(
+          `Envio Subgraph: data source "${source.name}" → blockHandlers → "${handler}" can create ` +
+            `${created[index]!.join(", ")}, and envio stops with an error if it does: ${BLOCK_HANDLER_CREATE}.`,
+        );
+      });
+    }
+  }
+  const fileTemplates = new Map<string, FileTemplate>();
+  for (const source of config.templates) {
+    if (!isFile(source)) continue;
+    const mapping = await loadMapping(config.root, generated, source.mappingFile, {
+      context: null,
+      event: null,
+      mode: "handler",
+      schema,
+      dataSource: { name: source.name, address: "", chainId: 0, network: "", context: {} },
+      registered: new Set(),
+      blockNumber: 0,
+      mappingExports: {},
+    }, sources);
+    await indexEventClasses();
+    fileTemplates.set(source.name, {
+      name: source.name,
+      kind: source.kind === "fileArweave" ? "arweave" : "ipfs",
+      handler: source.eventHandlers[0]?.handler ?? "",
+      entities: new Set(source.entities ?? []),
+      mapping,
+    });
+  }
+  installFileTemplates(new Map([...fileTemplates].map(([name, template]) => [name, template.kind])));
+  const runFileDataSources = makeFileRunner(fileTemplates, hosts, schema);
+
+  // A template sharing a data source's name is folded into its envio contract,
+  // so both sets of handlers fire for every address of it. graph-node runs the
+  // data source's for its own address and the template's for the ones it
+  // created, so each is gated to its side.
+  const staticAddresses = new Map<string, Set<string>>();
+  for (const source of config.dataSources) {
+    if (!source.address || !templateNames.has(source.name)) continue;
+    const addresses = staticAddresses.get(source.name) ?? new Set();
+    addresses.add(`${source.chainId}:${source.address.toLowerCase()}`);
+    staticAddresses.set(source.name, addresses);
+  }
+  const ownerOf = (source: DataSource) => {
+    const addresses = staticAddresses.get(source.name);
+    if (!addresses) return () => true;
+    return (event: any) =>
+      addresses.has(`${event.chainId}:${String(event.srcAddress).toLowerCase()}`) !== source.isTemplate;
+  };
+
+  for (const source of sources) {
+    if (source.kind !== "contract") continue;
+    const mapping = await loadMapping(config.root, generated, source.mappingFile, {
+      context: null,
+      event: null,
+      mode: "handler",
+      schema,
+      dataSource: {
+        name: source.name,
+        address: source.address ?? "",
+        chainId: source.chainId ?? 0,
+        network: source.network ?? "",
+        context: source.context ?? {},
+      },
+      registered: new Set(),
+      blockNumber: source.startBlock ?? 0,
+      mappingExports: {},
+    }, sources);
+
+    await indexEventClasses();
+    const owns = ownerOf(source);
+    // graph-node runs none of a data source's handlers past its endBlock
+    // (`has_expired`), while its chain and every template instance go on.
+    const live = (event: any) =>
+      source.isTemplate || source.endBlock === undefined || event.block.number <= source.endBlock;
+    // After codegen, so the analysis can follow the mapping into
+    // `generated/templates.ts`; for every source at once, as a create in one
+    // can hang on what another one's handlers save.
+    registerPassHandlers ??=
+      templateNames.size === 0
+        ? new Map()
+        : new Map(
+            (registerEveryHandler
+              ? sources.map((each) => handlersOf(each))
+              : subgraphRegisterHandlers(
+                  sources.map((each) => path.resolve(config.root, each.mappingFile)),
+                  sources.map((each) => handlersOf(each)),
+                )
+            ).map((names: string[], index: number) => [sources[index], new Set(names)]),
+          );
+    const creating = registerPassHandlers.get(source) ?? new Set<string>();
+    // graph-node matches a data source without `source.address` against every
+    // contract's logs — ENS's Resolver is one data source for every resolver
+    // anyone deploys. Nothing would ever register an address for it here.
+    const wildcard = !source.isTemplate && !source.address;
+
+    for (const handler of source.eventHandlers) {
+      const fn = mapping[handler.handler];
+      // `graph build` doesn't check that a named handler is exported — Aave's
+      // mainnet manifest names one its mappings renamed years ago — so a
+      // subgraph that deploys today would be refused here for a stale line the
+      // event it names never reaches.
+      if (typeof fn !== "function") continue;
+
+      const kind: EventKind = {
+        location: `data source "${source.name}" → "${handler.name}"`,
+        inputs: handler.inputs ?? [],
+        hasReceipt: handler.receipt ?? false,
+      };
+      // Built as the generated class the handler declares, when it declares
+      // one: its `params` getters are graph codegen's own.
+      const EventClass = mapping[EVENT_CLASSES_EXPORT]?.[handler.handler] ?? eventClasses.get(fn) ?? ethereum.Event;
+      const makeEvent = (event: unknown) => makeGraphEvent(event, kind, EventClass);
+
+      const makeScope = (event: any, context: any, mode: Scope["mode"]): Scope => ({
+        context,
+        event,
+        mode,
+        schema,
+        dataSource: {
+          name: source.name,
+          address: event.srcAddress,
+          chainId: event.chainId,
+          network: source.network ?? "",
+          context: contextOf(event.chainId, source.name, event.srcAddress) ?? source.context ?? {},
+          wildcard,
+        },
+        registered: new Set(),
+        blockNumber: event.block.number,
+        blockSeconds: secondsOf(event.block.number, event.block.timestamp),
+        position:
+          event.block.number * POSITION_BLOCK +
+          Math.min(roundOf(event.chainId, source.name, event.srcAddress, event.block.number), 15) * ROUND_SPAN +
+          event.logIndex,
+        mappingExports: mapping,
+      });
+
+      const where = topicFilter(handler);
+
+      indexer.onEvent(
+        { contract: config.contractAccessors[source.name], event: handler.name, where, wildcard },
+        async ({ event, context }: any) => {
+          if ((skipPreload && context.isPreload) || !owns(event) || !live(event)) return;
+          const scope = makeScope(event, context, "handler");
+          await runSyncCounted(context, () =>
+            runInScope(scope, () => {
+              startRun(scope);
+              // A fresh event per run: the handler is replayed while it waits on
+              // calls, and one that edits its event (Seamless rewrites
+              // `event.parameters[2]` into the newer shape) must not meet its own
+              // edit on the next round.
+              return fn(makeEvent(event));
+            }),
+          );
+          endRun(scope);
+          await runFileDataSources(scope, context);
+        },
+      );
+
+      // `dataSource.create` has to reach envio's contractRegister, which runs
+      // at fetch time — before any entity exists. The same mapping reruns in
+      // register mode, where writes and logs are no-ops and reads are null —
+      // only when its code can reach a create (`subgraph/creates.rs`): the
+      // rerun costs every contract call the handler makes on the way.
+      if (creating.has(handler.handler)) {
+        indexer.contractRegister(
+          { contract: config.contractAccessors[source.name], event: handler.name, where, wildcard },
+          async ({ event, context }: any) => {
+            if (!owns(event) || !live(event)) return;
+            const scope = makeScope(event, context, "register");
+            scope.slot = await registerSlots.acquire(scope.position ?? 0);
+            const { pass, settle } = startRegisterPass(event.chainId, scope.position ?? 0);
+            scope.pass = pass;
+            try {
+              await runRegisterRounds(scope, () => fn(makeEvent(event)));
+            } finally {
+              settle();
+              scope.slot?.release();
+            }
+            await runTemplateOnces(scope);
+          },
+        );
+      }
+    }
+
+    // A call is an envio item like a log: the source that reads traces produces
+    // it, and everything between the fetch and here — partitioning, order, the
+    // register pass, rollback — treats it as one. Its params carry the raw
+    // calldata and return data, decoded against the function's ABI on demand.
+    const callScope = (event: any, context: any, mode: Scope["mode"]): Scope => ({
+      context,
+      event,
+      mode,
+      schema,
+      dataSource: {
+        name: source.name,
+        address: event.srcAddress,
+        chainId: event.chainId,
+        network: source.network ?? "",
+        context: source.context ?? {},
+      },
+      registered: new Set(),
+      blockNumber: event.block.number,
+      blockSeconds: secondsOf(event.block.number, event.block?.timestamp),
+      position: callPosition(event),
+      mappingExports: mapping,
+    });
+
+    const registerCallHandler = (
+      trigger: string,
+      handlerName: string,
+      kind: CallKind | null,
+      run: (event: any, call: unknown) => unknown,
+    ) => {
+      const fn = mapping[handlerName];
+      if (typeof fn !== "function") return;
+      const CallClass = mapping[EVENT_CLASSES_EXPORT]?.[handlerName] ?? eventClasses.get(fn) ?? ethereum.Call;
+      const make = (event: any) =>
+        kind === null ? makeCallBlock(event.block) : makeGraphCall(event, kind, CallClass);
+      const target = { contract: config.contractAccessors[source.name], event: trigger };
+
+      indexer.onEvent(target, async ({ event, context }: any) => {
+        if ((skipPreload && context.isPreload) || !owns(event) || !live(event)) return;
+        // graph-node skips a call whose calldata doesn't decode against the
+        // function, with a warning — a proxy's fallback shares selectors.
+        if (kind !== null && !callInputDecodes(kind, event.params.callInput)) {
+          if (!context.isPreload) {
+            context.log.warn(
+              `Skipping a call to ${event.srcAddress} in transaction ${event.transaction.hash}: its input does not decode as ${kind.location}`,
+            );
+          }
+          return;
+        }
+        const scope = callScope(event, context, "handler");
+        // A fresh call per run, as for events: a replayed handler must not meet
+        // its own edits.
+        await runSyncCounted(context, () =>
+          runInScope(scope, () => {
+            startRun(scope);
+            return run(event, make(event));
+          }),
+        );
+        endRun(scope);
+        await runFileDataSources(scope, context);
+      });
+
+      if (creating.has(handlerName)) {
+        indexer.contractRegister(target, async ({ event, context }: any) => {
+          if (!owns(event) || !live(event)) return;
+          if (kind !== null && !callInputDecodes(kind, event.params.callInput)) return;
+          const scope = callScope(event, context, "register");
+          scope.slot = await registerSlots.acquire(scope.position ?? 0);
+          const { pass, settle } = startRegisterPass(event.chainId, scope.position ?? 0);
+          scope.pass = pass;
+          try {
+            await runRegisterRounds(scope, () => run(event, make(event)));
+          } finally {
+            settle();
+            scope.slot?.release();
+          }
+          await runTemplateOnces(scope);
+        });
+      }
+    };
+
+    for (const handler of source.callHandlers ?? []) {
+      registerCallHandler(
+        handler.name,
+        handler.handler,
+        {
+          location: `data source "${source.name}" → callHandlers → "${handler.function}"`,
+          inputs: handler.inputs ?? [],
+          outputs: handler.outputs ?? [],
+        },
+        (_, call) => mapping[handler.handler](call),
+      );
+    }
+
+    for (const handler of source.blockHandlers) {
+      // Once per call to the data source's address in the block, after the
+      // block's logs and calls — graph-node's `WithCallTo` block trigger.
+      if (handler.filter === "call" && handler.callEvent) {
+        registerCallHandler(handler.callEvent, handler.handler, null, (_, block) =>
+          mapping[handler.handler](block),
+        );
+      }
+    }
+
+    for (const handler of source.blockHandlers) {
+      if (handler.filter === "call") continue;
+      const fn = mapping[handler.handler];
+      if (typeof fn !== "function") continue;
+      const start = source.startBlock ?? 0;
+      const once = handler.filter === "once";
+      const every = typeof handler.filter === "object" ? handler.filter.every : 1;
+      // graph-node creates a data source from any handler, a block handler's
+      // included, and runs it from that block on. A data source's block handler
+      // that can reach a create runs in register mode at each of its blocks,
+      // ahead of them, as an event's does; so does every `once` one when there
+      // are templates at all: Venus's saves the Comptroller that
+      // getOrCreateMarket's register pass reads before it creates a VToken.
+      // One that runs on every block, or every few, gets a pass only when the
+      // code surely reaches a template's class: anything the analysis can't
+      // follow counts as a create, and kiln's vsuite handleBlock, which checks
+      // BLS signatures in a module it can't follow, would redo them at every
+      // block. A create from one without a pass is refused where it runs.
+      const blocksRun = once
+        ? 1
+        : source.endBlock === undefined
+          ? Number.POSITIVE_INFINITY
+          : Math.floor((source.endBlock - start) / every) + 1;
+      const registers =
+        !source.isTemplate &&
+        templateNames.size > 0 &&
+        (once ||
+          (blocksRun <= FEW_BLOCK_HANDLER_BLOCKS
+            ? creating.has(handler.handler)
+            : sureCreating(source).has(handler.handler)));
+      const contractRegister =
+        registers
+          ? async ({ block, context }: any) => {
+              const blockNumber: number = block.number;
+              const position = blockHandlerPosition(blockNumber, once);
+              const scope: Scope = {
+                context,
+                event: block,
+                mode: "register",
+                schema,
+                dataSource: {
+                  name: source.name,
+                  address: source.address ?? "",
+                  chainId: source.chainId ?? 0,
+                  network: source.network ?? "",
+                  context: source.context ?? {},
+                },
+                registered: new Set(),
+                blockNumber,
+                position,
+                mappingExports: mapping,
+              };
+              scope.slot = await registerSlots.acquire(position);
+              const { pass, settle } = startRegisterPass(source.chainId ?? 0, position);
+              scope.pass = pass;
+              try {
+                await runRegisterRounds(scope, () => fn(makeBlockHandlerBlock(blockNumber)));
+              } finally {
+                settle();
+                scope.slot?.release();
+              }
+              await runTemplateOnces(scope);
+            }
+          : undefined;
+      if (source.isTemplate && once && templateNames.size > 0) {
+        templateOnces.set(source.name, async (parent, address) => {
+          const { chainId } = parent.dataSource;
+          const { blockNumber } = parent;
+          const round = roundOf(chainId, source.name, address, blockNumber);
+          const position = blockNumber * POSITION_BLOCK + Math.min(round, 15) * ROUND_SPAN - 0.5;
+          const scope: Scope = {
+            context: parent.context,
+            event: { number: blockNumber },
+            mode: "register",
+            schema,
+            dataSource: {
+              name: source.name,
+              address,
+              chainId,
+              network: source.network ?? "",
+              context: contextOf(chainId, source.name, address) ?? source.context ?? {},
+            },
+            registered: new Set(),
+            blockNumber,
+            position,
+            mappingExports: mapping,
+          };
+          scope.slot = await registerSlots.acquire(position);
+          const { pass, settle } = startRegisterPass(chainId, position);
+          scope.pass = pass;
+          try {
+            await runRegisterRounds(scope, () => fn(makeBlockHandlerBlock(blockNumber)));
+          } finally {
+            settle();
+            scope.slot?.release();
+          }
+          return scope;
+        });
+      }
+      // A template's instances all exist from the first static source on its
+      // chain, and the handler runs once per instance from its creation block.
+      const chainStarts = config.dataSources
+        .filter((other) => other.chainId === source.chainId)
+        .map((other) => other.startBlock ?? 0);
+      const first = source.isTemplate ? (chainStarts.length > 0 ? Math.min(...chainStarts) : 0) : start;
+      // An instance's creation block is its start block (graph-node), so a
+      // template's `once` and `polling` schedules differ by instance: every
+      // block is visited and each instance checked.
+      const blocks = source.isTemplate
+        ? { _gte: first, _every: 1 }
+        : handler.filter === "once"
+          ? { _gte: start, _lte: start }
+          : source.endBlock === undefined
+            ? { _gte: first, _every: handler.filter.every }
+            : { _gte: start, _lte: source.endBlock, _every: handler.filter.every };
+      const scheduled = (created: number, blockNumber: number) =>
+        once ? blockNumber === created : (blockNumber - created) % every === 0;
+      indexer.onBlock(
+        {
+          name: `${source.name}_${handler.handler}`,
+          where: ({ chain }: { chain: { id: number } }) =>
+            chain.id === source.chainId && { block: { number: blocks } },
+          runsFirst: once && !source.isTemplate,
+          contractRegister,
+          // A template's handler visits every block for instances it may not
+          // have, and a register pass runs on blocks generated locally: both
+          // read their fields afterwards, only where they run.
+          fields:
+            !source.isTemplate && !contractRegister && (handler.blockFields?.length ?? 0) > 0
+              ? { block: handler.blockFields }
+              : undefined,
+        } as any,
+        async ({ block, context }: any) => {
+          if (skipPreload && context.isPreload) return;
+          const graphBlock = makeBlockHandlerBlock(block.number, block);
+          const addresses = source.isTemplate
+            ? instancesAt(block.chainId ?? source.chainId, source.name, block.number)
+                .filter((instance) => scheduled(instance.block, block.number))
+                .map((instance) => instance.address)
+            : [source.address ?? ""];
+          for (const address of addresses) {
+            const scope: Scope = {
+              context,
+              event: block,
+              mode: "handler",
+              schema,
+              dataSource: {
+                name: source.name,
+                address,
+                chainId: source.chainId ?? 0,
+                network: source.network ?? "",
+                context: (source.isTemplate ? contextOf(source.chainId ?? 0, source.name, address) : undefined) ?? source.context ?? {},
+              },
+              registered: new Set(),
+              blockNumber: block.number,
+              blockSeconds: secondsOf(block.number, block.timestamp),
+              mappingExports: mapping,
+              blockHandler:
+                (source.isTemplate ? hasRegisterPass(source, handler) : registers) ? undefined : handler.handler,
+            };
+            await runSyncCounted(context, () =>
+              runInScope(scope, () => {
+                startRun(scope);
+                return fn(graphBlock);
+              }),
+            );
+            endRun(scope);
+            await runFileDataSources(scope, context);
+          }
+        },
+      );
+    }
+  }
+}