envio 3.8.0 → 3.9.0-resolvers.0

package/index.d.ts

@@ -1169,37 +1169,34 @@ export type SvmLogKind =
   | "data"
   | (string & {});
 
-export type SvmLog = {
+export type SvmAllLogFields = {
   readonly kind: SvmLogKind;
   readonly message: string;
 };
 
-export type SvmAccountActivity = {
+export type SvmAllAccountLamportsFields = {
+  readonly pre: bigint;
+  readonly post: bigint;
+};
+
+export type SvmAllAccountTokenActivityFields = {
+  readonly mint: string;
+  readonly owner: string;
+  readonly decimals: number;
+  readonly preAmount: bigint | undefined;
+  readonly postAmount: bigint | undefined;
+};
+
+export type SvmAllAccountActivityFields = {
   readonly address: string;
   readonly transactionAccountIndex: number;
   readonly isSigner: boolean;
   readonly isWritable: boolean;
-  readonly lamports: { readonly pre: bigint; readonly post: bigint } | undefined;
-  readonly token: {
-    readonly mint: string;
-    readonly owner: string;
-    readonly decimals: number;
-    readonly preAmount: bigint | undefined;
-    readonly postAmount: bigint | undefined;
-  } | undefined;
+  readonly lamports: SvmAllAccountLamportsFields | undefined;
+  readonly token: SvmAllAccountTokenActivityFields | undefined;
 };
 
-export type SvmInstructionAccount<
-  Activity = SvmAccountActivity,
-  Name extends string = string,
-> = {
-  readonly address: string;
-  readonly accountName: Name;
-  readonly instructionAccountIndex: number;
-  readonly activity: Activity | undefined;
-};
-
-export type SvmBlock = {
+export type SvmAllBlockFields = {
   readonly slot: number;
   readonly time: number;
   readonly hash: string;
@@ -1208,10 +1205,10 @@ export type SvmBlock = {
   readonly parentHash: string;
 };
 
-/** All SVM parent-transaction fields when selected. Handler
- *  `fields.transaction` narrows this; `accountActivities` is implied by
+/** All SVM parent-transaction fields. Handler `fields.transaction` narrows
+ *  this via {@link SvmTransaction}; `accountActivities` is implied by
  *  `fields.accountActivity`. */
-export type SvmTransaction = {
+export type SvmAllTransactionFields = {
   readonly transactionIndex: number;
   readonly signature: string;
   readonly feePayer: string;
@@ -1250,10 +1247,8 @@ export type SvmAccountActivityFieldName =
   | "transactionAccountIndex"
   | "isSigner"
   | "isWritable"
-  | "lamports"
   | "lamports.pre"
   | "lamports.post"
-  | "token"
   | "token.mint"
   | "token.owner"
   | "token.decimals"
@@ -1276,6 +1271,19 @@ export type SvmFieldsSelection = {
   readonly log?: readonly SvmLogFieldName[];
 };
 
+/** A {@link SvmFieldsSelection} with every field selected.
+ *
+ * Type-level only — its knobs are field-name arrays rather than literals, so it
+ * describes a payload (`SvmInstruction<SvmAllFieldsSelection>`) but can't be
+ * passed as a registration's `fields` value. */
+export type SvmAllFieldsSelection = {
+  readonly instruction: readonly SvmInstructionFieldName[];
+  readonly transaction: readonly SvmTransactionFieldName[];
+  readonly accountActivity: readonly SvmAccountActivityFieldName[];
+  readonly block: readonly SvmBlockFieldName[];
+  readonly log: readonly SvmLogFieldName[];
+};
+
 type SvmListedArray<Fields, Knob extends keyof SvmFieldsSelection> = Fields[Knob &
   keyof Fields];
 type SvmListedFields<Fields, Knob extends keyof SvmFieldsSelection> = NonNullable<
@@ -1302,15 +1310,7 @@ type SvmActivityHas<Fields, Name extends string> = [SvmActivityListed<Fields>] e
   ? false
   : Name extends SvmActivityListed<Fields>
     ? true
-    : Name extends `lamports.${string}`
-      ? "lamports" extends SvmActivityListed<Fields>
-        ? true
-        : false
-      : Name extends `token.${string}`
-        ? "token" extends SvmActivityListed<Fields>
-          ? true
-          : false
-        : false;
+    : false;
 
 type SvmActivityField<Fields, Name extends string, T> = SvmActivityHas<
   Fields,
@@ -1319,38 +1319,37 @@ type SvmActivityField<Fields, Name extends string, T> = SvmActivityHas<
   ? T
   : FieldNotSelected<`Field '${Name}' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>;
 
-type SvmSelectedLamports<Fields> =
-  SvmActivityHas<Fields, "lamports.pre"> extends true
-    ? SvmActivityHas<Fields, "lamports.post"> extends true
-      ? { readonly pre: bigint; readonly post: bigint } | undefined
-      : { readonly pre: bigint } | undefined
-    : SvmActivityHas<Fields, "lamports.post"> extends true
-      ? { readonly post: bigint } | undefined
-      : FieldNotSelected<`Field 'lamports' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>;
-
-export type SvmAccountTokenActivity = {
-  readonly mint: string;
-  readonly owner: string;
-  readonly decimals: number;
-  readonly preAmount: bigint | undefined;
-  readonly postAmount: bigint | undefined;
-};
+/** The pre/post lamport balances of a {@link SvmAccountActivity}, narrowed to
+ * the registration's fields selection. */
+export type SvmAccountLamports<Fields extends SvmFieldsSelection> = [
+  SvmActivityListed<Fields> & `lamports.${string}`,
+] extends [never]
+  ? FieldNotSelected<`Field 'lamports' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>
+  : {
+      readonly [K in keyof SvmAllAccountLamportsFields]: SvmActivityHas<Fields, `lamports.${K & string}`> extends true
+        ? SvmAllAccountLamportsFields[K]
+        : FieldNotSelected<`Field 'lamports.${K & string}' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>;
+    } | undefined;
 
-type SvmSelectedToken<Fields> = [SvmActivityListed<Fields> & (`token` | `token.${string}`)] extends [never]
+/** The token activity of a {@link SvmAccountActivity}, narrowed to the
+ * registration's fields selection. */
+export type SvmAccountTokenActivity<Fields extends SvmFieldsSelection> = [SvmActivityListed<Fields> & `token.${string}`] extends [never]
   ? FieldNotSelected<`Field 'token' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>
   : {
-      readonly [K in keyof SvmAccountTokenActivity as SvmActivityHas<Fields, `token.${K & string}`> extends true
-        ? K
-        : never]: SvmAccountTokenActivity[K];
+      readonly [K in keyof SvmAllAccountTokenActivityFields]: SvmActivityHas<Fields, `token.${K & string}`> extends true
+        ? SvmAllAccountTokenActivityFields[K]
+        : FieldNotSelected<`Field 'token.${K & string}' is not selected for this handler. Add it to fields.accountActivity in the registration options.`>;
     } | undefined;
 
-type SvmSelectedAccountActivity<Fields> = {
+/** An account activity of a {@link SvmTransaction}, narrowed to the
+ * registration's fields selection. */
+export type SvmAccountActivity<Fields extends SvmFieldsSelection> = {
   readonly address: string;
   readonly transactionAccountIndex: SvmActivityField<Fields, "transactionAccountIndex", number>;
   readonly isSigner: SvmActivityField<Fields, "isSigner", boolean>;
   readonly isWritable: SvmActivityField<Fields, "isWritable", boolean>;
-  readonly lamports: SvmSelectedLamports<Fields>;
-  readonly token: SvmSelectedToken<Fields>;
+  readonly lamports: SvmAccountLamports<Fields>;
+  readonly token: SvmAccountTokenActivity<Fields>;
 };
 
 type SvmInstrListed<Fields> = SvmListedFields<Fields, "instruction">;
@@ -1358,37 +1357,54 @@ type SvmInstrField<Fields, Name extends SvmInstructionFieldName, T> = Name exten
   ? T
   : FieldNotSelected<`Field '${Name}' is not selected for this handler. Add it to fields.instruction in the registration options.`>;
 
+/** A named account of a {@link SvmInstruction}. Its `activity` narrows to the
+ * registration's fields selection. */
+export type SvmInstructionAccount<
+  Fields extends SvmFieldsSelection,
+  Name extends string = string,
+> = {
+  readonly address: string;
+  readonly accountName: Name;
+  readonly instructionAccountIndex: number;
+  readonly activity:
+    | ([SvmActivityListed<Fields>] extends [never]
+        ? FieldNotSelected<`Field 'activity' is not selected for this handler. Add fields.accountActivity in the registration options.`>
+        : SvmAccountActivity<Fields>)
+    | undefined;
+};
+
 type SvmNamedAccounts<
   Acc extends Readonly<Record<string, unknown>>,
-  Fields,
+  Fields extends SvmFieldsSelection,
 > = {
-  readonly [K in keyof Acc & string]: SvmInstructionAccount<
-    [SvmActivityListed<Fields>] extends [never]
-      ? FieldNotSelected<`Field 'activity' is not selected for this handler. Add fields.accountActivity in the registration options.`>
-      : SvmSelectedAccountActivity<Fields> | undefined,
-    K
-  >;
+  readonly [K in keyof Acc & string]: SvmInstructionAccount<Fields, K>;
 };
 
-type SvmSelectedTransaction<Fields> = {
-  readonly [K in keyof SvmTransaction]: K extends SvmListedFields<Fields, "transaction">
-    ? SvmTransaction[K]
+/** The parent transaction of a {@link SvmInstruction}, narrowed to the
+ * registration's fields selection. */
+export type SvmTransaction<Fields extends SvmFieldsSelection> = {
+  readonly [K in keyof SvmAllTransactionFields]: K extends SvmListedFields<Fields, "transaction">
+    ? SvmAllTransactionFields[K]
     : FieldNotSelected<`Field '${K & string}' is not selected for this handler. Add it to fields.transaction in the registration options.`>;
 } & {
   readonly accountActivities: [SvmActivityListed<Fields>] extends [never]
     ? FieldNotSelected<`Field 'accountActivities' is not selected for this handler. Add fields.accountActivity in the registration options.`>
-    : readonly SvmSelectedAccountActivity<Fields>[];
+    : readonly SvmAccountActivity<Fields>[];
 };
 
-type SvmSelectedBlock<Fields> = {
-  readonly [K in keyof SvmBlock]: K extends "slot"
-    ? SvmBlock[K]
+/** The block of a {@link SvmInstruction}, narrowed to the registration's
+ * fields selection. `slot` is always selected. */
+export type SvmBlock<Fields extends SvmFieldsSelection> = {
+  readonly [K in keyof SvmAllBlockFields]: K extends "slot"
+    ? SvmAllBlockFields[K]
     : K extends SvmListedFields<Fields, "block">
-      ? SvmBlock[K]
+      ? SvmAllBlockFields[K]
       : FieldNotSelected<`Field '${K & string}' is not selected for this handler. Add it to fields.block in the registration options.`>;
 };
 
-type SvmSelectedLog<Fields> = {
+/** A log of a {@link SvmInstruction}, narrowed to the registration's fields
+ * selection. */
+export type SvmLog<Fields extends SvmFieldsSelection> = {
   readonly kind: "kind" extends SvmListedFields<Fields, "log">
     ? SvmLogKind
     : FieldNotSelected<`Field 'kind' is not selected for this handler. Add it to fields.log in the registration options.`>;
@@ -1397,10 +1413,12 @@ type SvmSelectedLog<Fields> = {
     : FieldNotSelected<`Field 'message' is not selected for this handler. Add it to fields.log in the registration options.`>;
 };
 
-export type SvmInstruction<
-  ProgInstr = { readonly args: unknown; readonly accounts: Readonly<Record<string, string>> },
-  Fields = {},
-> = {
+type SvmAnyProgramInstruction = {
+  readonly args: unknown;
+  readonly accounts: Readonly<Record<string, string>>;
+};
+
+type SvmSelectedInstruction<Fields extends SvmFieldsSelection, ProgInstr> = {
   readonly programName: string;
   readonly instructionName: string;
   readonly discriminator: string;
@@ -1411,7 +1429,7 @@ export type SvmInstruction<
   readonly args: SvmInstrField<
     Fields,
     "args",
-    ProgInstr extends { readonly args: infer A } ? A | undefined : unknown | undefined
+    ProgInstr extends { readonly args: infer A } ? A : unknown
   >;
   readonly accounts: SvmInstrField<
     Fields,
@@ -1423,25 +1441,85 @@ export type SvmInstruction<
   readonly accountArguments: SvmInstrField<Fields, "accountArguments", readonly string[]>;
   readonly logs: [SvmListedFields<Fields, "log">] extends [never]
     ? FieldNotSelected<`Field 'logs' is not selected for this handler. Add fields.log in the registration options.`>
-    : readonly SvmSelectedLog<Fields>[];
-  readonly transaction: SvmSelectedTransaction<Fields>;
-  readonly block: SvmSelectedBlock<Fields>;
-};
+    : readonly SvmLog<Fields>[];
+  readonly transaction: SvmTransaction<Fields>;
+  readonly block: SvmBlock<Fields>;
+};
+
+type SvmConfiguredInstruction<Program extends string, Instruction extends string> = [
+  Program,
+] extends [never]
+  ? SvmAnyProgramInstruction
+  : Program extends keyof SvmProgramsT
+    ? Instruction extends keyof SvmProgramsT[Program]
+      ? SvmProgramsT[Program][Instruction]
+      : SvmAnyProgramInstruction
+    : SvmAnyProgramInstruction;
+
+/** The `instruction` payload of an `indexer.onInstruction` handler. `Fields`
+ * must be the registration's fields selection (use `typeof fields` on a
+ * `const fields = {...} as const satisfies SvmFieldsSelection`, or
+ * {@link SvmAllFieldsSelection}). Pass the config-declared program and
+ * instruction names to type `args` and `accounts`. */
+export type SvmInstruction<
+  Fields extends SvmFieldsSelection,
+  Program extends keyof SvmProgramsT & string = never,
+  Instruction extends keyof SvmProgramsT[Program] & string = never,
+> = SvmSelectedInstruction<Fields, SvmConfiguredInstruction<Program, Instruction>>;
 
-/** Arguments passed to handlers registered via `indexer.onInstruction`. */
-export type SvmOnInstructionHandlerArgs<
-  Config extends IndexerConfigTypes = GlobalConfig,
-  Instr = SvmInstruction,
-> = {
+type SvmOnInstructionArgsFor<Instr, Config extends IndexerConfigTypes> = {
   readonly instruction: Instr;
   readonly context: SvmOnSlotContext<Config>;
 };
 
+type SvmOnInstructionHandlerFor<Instr, Config extends IndexerConfigTypes> = (
+  args: SvmOnInstructionArgsFor<Instr, Config>,
+) => Promise<void>;
+
+/** Arguments passed to handlers registered via `indexer.onInstruction`.
+ * Takes the same type arguments as {@link SvmInstruction}. */
+export type SvmOnInstructionHandlerArgs<
+  Fields extends SvmFieldsSelection,
+  Program extends keyof SvmProgramsT & string = never,
+  Instruction extends keyof SvmProgramsT[Program] & string = never,
+> = SvmOnInstructionArgsFor<SvmInstruction<Fields, Program, Instruction>, GlobalConfig>;
+
+/** The named accounts of a configured instruction. Falls back to an open
+ * record when the instruction carries no resolved schema, so its filter keys
+ * are unconstrained rather than unusable. */
+type SvmAccountsOf<Program extends string, Instruction extends string> =
+  SvmConfiguredInstruction<Program, Instruction>["accounts"];
+
+/** One AND-group of account narrowings: every named account must match one of
+ * its listed pubkeys. Names are the instruction's own account names. */
+export type SvmAccountsFilter<Accounts> = {
+  readonly [K in keyof Accounts]?: string | readonly string[];
+};
+
+/** The `where` option value of `indexer.onInstruction`.
+ *
+ * `accounts` accepts either a single AND-group of account narrowings, or an
+ * array of them (OR semantics). `block.slot._gte` promotes to the
+ * registration's startBlock and overrides the chain-level `start_block` — use
+ * it to restrict per-instruction processing without touching `config.yaml`.
+ * Only `_gte` is supported here; use `indexer.onSlot` for `_lte` / `_every`. */
+export type SvmOnInstructionWhere<Accounts> = {
+  /** Match only inner (CPI-invoked) or only outer instructions. Absent
+   * matches both. */
+  readonly isInner?: boolean;
+  readonly accounts?: SvmAccountsFilter<Accounts> | readonly SvmAccountsFilter<Accounts>[];
+  readonly block?: {
+    readonly slot?: {
+      readonly _gte?: number;
+    };
+  };
+};
+
 /** Options for an SVM `indexer.onInstruction` registration. */
 export type SvmOnInstructionOptions<
   P extends string = string,
   I extends string = string,
-  Fields extends SvmFieldsSelection | undefined = undefined,
+  Fields extends SvmFieldsSelection = {},
 > = {
   /** Program name as declared under `chains[].programs[].name` in
    * `config.yaml`. */
@@ -1450,12 +1528,24 @@ export type SvmOnInstructionOptions<
    * `chains[].programs[].instructions[].name` in `config.yaml`. */
   readonly instruction: I;
   readonly fields?: Fields & SvmFieldsLiteralCheck<Fields>;
+  readonly where?: SvmOnInstructionWhere<SvmAccountsOf<P, I>>;
 };
 
-/** Handler function for an SVM `indexer.onInstruction` registration. */
+/** Handler function for an SVM `indexer.onInstruction` registration. Takes
+ * the same type arguments as {@link SvmInstruction}, so a standalone handler
+ * needs a single annotation:
+ *
+ *     const handleSwap: SvmOnInstructionHandler<typeof fields, "Swapper", "swap"> =
+ *       async ({ instruction, context }) => { ... };
+ */
 export type SvmOnInstructionHandler<
-  Config extends IndexerConfigTypes = GlobalConfig,
-> = (args: SvmOnInstructionHandlerArgs<Config>) => Promise<void>;
+  Fields extends SvmFieldsSelection,
+  Program extends keyof SvmProgramsT & string = never,
+  Instruction extends keyof SvmProgramsT[Program] & string = never,
+> = SvmOnInstructionHandlerFor<
+  SvmInstruction<Fields, Program, Instruction>,
+  GlobalConfig
+>;
 
 // ============== Indexer Types ==============
 
@@ -1685,18 +1775,13 @@ type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
                 readonly onInstruction: <
                   P extends keyof Programs & string,
                   I extends keyof Programs[P] & string,
-                  const F extends SvmFieldsSelection | undefined,
+                  const F extends SvmFieldsSelection = {},
                 >(
                   options: SvmOnInstructionOptions<P, I, F>,
-                  handler: (
-                    args: SvmOnInstructionHandlerArgs<
-                      Config,
-                      SvmInstruction<
-                        Programs[P][I],
-                        [F] extends [undefined] ? {} : F
-                      >
-                    >,
-                  ) => Promise<void>,
+                  handler: SvmOnInstructionHandlerFor<
+                    SvmSelectedInstruction<F, Programs[P][I]>,
+                    Config
+                  >,
                 ) => void;
               }
             : {
@@ -1867,9 +1952,9 @@ type SvmSimulateItem<Config extends IndexerConfigTypes = GlobalConfig> =
             /** Logs scoped to this instruction. */
             logs?: readonly { readonly kind?: string; readonly message?: string }[];
             /** Override block fields. */
-            block?: Partial<SvmBlock>;
+            block?: Partial<SvmAllBlockFields>;
             /** Override transaction fields. `accountActivities` are joined onto named accounts at process time. */
-            transaction?: Partial<SvmTransaction> & {
+            transaction?: Partial<SvmAllTransactionFields> & {
               readonly accountActivities?: readonly {
                 readonly address: string;
                 readonly transactionAccountIndex?: number;
@@ -1927,10 +2012,10 @@ type ConfigEntities<Config extends IndexerConfigTypes = GlobalConfig> =
 type PerChainEntityNames<Config extends IndexerConfigTypes = GlobalConfig> =
   Config extends { perChainEntities: infer Names extends string } ? Names : never;
 
-/** The row shape the chain-agnostic test-indexer operations exchange. A
- * per-chain entity's row is only identified together with its chain, so the
- * chain id travels alongside the entity fields. */
-type TestIndexerEntityRow<
+/** The row shape chain-agnostic APIs exchange. A per-chain entity's row is
+ * only identified together with its chain, so the chain id travels alongside
+ * the entity fields. */
+type ChainScopedEntityRow<
   Config extends IndexerConfigTypes,
   Name,
   Entity
@@ -2124,7 +2209,7 @@ export type TestIndexerFromConfig<Config extends IndexerConfigTypes = GlobalConf
 } & SingleEcosystemTestChains<Config> & {
   /** Entity operations for direct manipulation outside of handlers. */
   readonly [K in keyof ConfigEntities<Config>]: TestIndexerEntityOperations<
-    TestIndexerEntityRow<Config, K, ConfigEntities<Config>[K]>
+    ChainScopedEntityRow<Config, K, ConfigEntities<Config>[K]>
   >;
 };
 
@@ -2138,6 +2223,7 @@ type EvmContractsT  = GlobalConfig extends { evm:  { contracts: infer X extends
 type FuelChainsT    = GlobalConfig extends { fuel: { chains:    infer X extends Record<string, { id: number }> } } ? X : {};
 type FuelContractsT = GlobalConfig extends { fuel: { contracts: infer X extends Record<string, Record<string, any>> } } ? X : {};
 type SvmChainsT     = GlobalConfig extends { svm:  { chains:    infer X extends Record<string, { id: number }> } } ? X : {};
+type SvmProgramsT   = GlobalConfig extends { svm:  { programs:  infer X extends Record<string, Record<string, any>> } } ? X : {};
 type EntitiesT      = GlobalConfig extends { entities: infer X extends Record<string, object> } ? X : {};
 type EnumsT         = GlobalConfig extends { enums: infer X extends Record<string, any> } ? X : {};
 
@@ -2197,6 +2283,244 @@ export type EnumName = keyof EnumsT & string;
 /** Lookup an enum value type by name (e.g. `Enum<"AccountType">`). */
 export type Enum<TName extends EnumName> = EnumsT[TName];
 
+// ============== Custom Resolver Types ==============
+
+/** Handle for a custom GraphQL resolver created via {@link createResolver}. */
+export declare abstract class Resolver<Args, Output> {
+  protected opaque: Args | Output;
+}
+
+/** The selection the caller asked for: field names and their nesting, with
+ *  aliases and fragments already resolved away. A resolver may use it to skip
+ *  work it wasn't asked for — the response is projected against the declared
+ *  schema either way, so correctness never depends on honouring it. */
+export type ResolverSelection = { readonly [field: string]: ResolverSelection };
+
+/** Request metadata, forwarded by envio-serve. */
+export type ResolverContext = {
+  /** The role the operation was executed under. `admin: true` resolvers are
+   *  only reachable as `"admin"`. */
+  readonly role: "public" | "admin";
+  /** Correlates this field's work with the operation it belongs to. */
+  readonly requestId: string;
+  /** W3C trace context of the incoming request, when the caller sent one. */
+  readonly traceparent?: string;
+};
+
+/** How far a chain has been indexed. Read it to refuse to answer from a stale
+ *  index — `sourceBlock - progressBlock` is how far behind the head the
+ *  indexer is. */
+export type ChainHeight = {
+  readonly chainId: number;
+  /** `"evm"`, `"fuel"` or `"svm"`. Chain ids are only unique within one. */
+  readonly ecosystem: string;
+  readonly startBlock: number;
+  readonly endBlock: number | null;
+  /** The latest block seen on the chain. */
+  readonly sourceBlock: number;
+  /** The latest block fetched from the source. */
+  readonly bufferBlock: number;
+  /** The latest block whose events have been processed and committed. */
+  readonly progressBlock: number;
+  /** When the chain first caught up to the head, or null while it hasn't. */
+  readonly readyAt: Date | null;
+  readonly isReady: boolean;
+};
+
+/** Raw SQL, run under the resolver's `statement_timeout` and against its
+ *  bounded pool. */
+export type ResolverSql = {
+  /** ``db.sql`select 1` `` */
+  <Row = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: readonly unknown[]
+  ): Promise<Row[]>;
+  /** `db.sql.unsafe(text, params)` — the direct lift for a query built as a
+   *  string with positional parameters. */
+  unsafe<Row = Record<string, unknown>>(
+    text: string,
+    params?: readonly unknown[],
+    options?: { readonly prepare?: boolean }
+  ): Promise<Row[]>;
+};
+
+/** Options accepted by `db.find`. */
+export type ResolverFindOptions<Entity> = {
+  /** Filter by field, with the same operators as `context.<Entity>.getWhere`.
+   *  Unlike `getWhere`, any field can be filtered on here — it is a query
+   *  against the table, so an unindexed field is a slow one, not an error. */
+  readonly where?: GetWhereFilter<Entity>;
+  readonly orderBy?: readonly {
+    readonly field: keyof Entity & string;
+    readonly direction: "asc" | "desc";
+  }[];
+  readonly limit?: number;
+  readonly offset?: number;
+};
+
+/** The database a resolver reads through. Every query it runs carries the
+ *  resolver's `timeoutMs` as a `statement_timeout` and takes one of the
+ *  process's bounded connections. */
+export type ResolverDb<Config extends IndexerConfigTypes = GlobalConfig> = {
+  /** Entities matching `where`, decoded exactly as a handler sees them. */
+  readonly find: <Name extends keyof ConfigEntities<Config> & string>(
+    entityName: Name,
+    options?: ResolverFindOptions<
+      ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>
+    >
+  ) => Promise<
+    ChainScopedEntityRow<Config, Name, ConfigEntities<Config>[Name]>[]
+  >;
+  /** One entity by id, or null. Not available for per-chain entities, whose
+   *  key is the id together with a chain — use {@link ResolverDb.find}. */
+  readonly get: <
+    Name extends Exclude<
+      keyof ConfigEntities<Config> & string,
+      PerChainEntityNames<Config>
+    >
+  >(
+    entityName: Name,
+    id: EntityId<ConfigEntities<Config>[Name]>
+  ) => Promise<ConfigEntities<Config>[Name] | null>;
+  /** Raw SQL, for what the loaders don't express. */
+  readonly sql: ResolverSql;
+  /** The Postgres schema the indexer's tables live in. Raw SQL has to qualify
+   *  table names with it — it is not `"public"` on a hosted deployment. */
+  readonly pgSchema: string;
+  /** Several queries on one connection, under one timeout. */
+  readonly transaction: <T>(work: (sql: ResolverSql) => Promise<T>) => Promise<T>;
+  /** How far each chain has been indexed, keyed by chain id. */
+  readonly chainHeights: () => Promise<Record<string, ChainHeight>>;
+};
+
+/** Arguments passed to a {@link Resolver}'s handler. */
+export type ResolverHandlerArgs<
+  Args,
+  Config extends IndexerConfigTypes = GlobalConfig
+> = {
+  /** Coerced and validated against the declared arg schemas before the
+   *  resolver is reached. */
+  readonly args: Args;
+  readonly db: ResolverDb<Config>;
+  readonly selection: ResolverSelection;
+  readonly ctx: ResolverContext;
+};
+
+/**
+ * Declares a custom GraphQL resolver: a root query field served alongside the
+ * generated entity fields, backed by TypeScript in this project.
+ *
+ * Arguments and result are declared with the same `S` schemas effects use, and
+ * the GraphQL types are derived from them. A field is non-null unless its
+ * schema is optional. Object types must be named with {@link defineType} —
+ * GraphQL has no anonymous types.
+ *
+ * ```ts
+ * export const marketsAprByPeriod = createResolver({
+ *   name: "marketsAprByPeriod",
+ *   args: { periodStart: S.int32, periodEnd: S.int32 },
+ *   output: S.array(defineType("MarketApr", { marketAddress: S.string })),
+ *   timeoutMs: 30_000,
+ *   handler: async ({ args, db }) => db.find("MarketInfo"),
+ * });
+ * ```
+ */
+export function createResolver<
+  // Both are schemas at runtime: `createResolver` reads `output.t` and walks
+  // every argument with `toGraphQLType` while the module is being imported, so
+  // anything else fails at indexer startup rather than in the editor.
+  AS extends Record<string, Sury.Schema<unknown>>,
+  OS extends Sury.Schema<unknown>,
+  A = UnknownToOutput<AS>,
+  O = UnknownToOutput<OS>,
+  // A hack to enforce that the inferred return type matches the output schema.
+  R extends O = O
+>(options: {
+  /** The GraphQL field name. Must not collide with a generated one. */
+  readonly name: string;
+  /** Shown in the schema, for the people querying it. */
+  readonly description?: string;
+  /** Argument schemas, keyed by argument name. */
+  readonly args?: AS;
+  /** The result schema. Determines the field's GraphQL type. */
+  readonly output: OS;
+  /** Register the field on the admin schema only: it stays out of public
+   *  introspection and is unexecutable without the admin secret. */
+  readonly admin?: boolean;
+  /** The `statement_timeout` every query this resolver runs is bounded by.
+   *  Required: it is the only thing bounding a runaway query. */
+  readonly timeoutMs: number;
+  readonly handler: (args: ResolverHandlerArgs<A>) => Promise<R>;
+}): Resolver<A, O>;
+
+/**
+ * Thrown by a resolver to put a specific error on the client's response.
+ *
+ * Anything else a handler throws is reported as an internal failure with its
+ * message withheld — a driver error can carry a connection string, and the
+ * caller is the public internet — so this is how a resolver says more than
+ * that. envio-serve carries the extensions through unchanged.
+ *
+ * ```ts
+ * throw new ResolverError("Service is syncing", {
+ *   code: "SERVICE_UNAVAILABLE",
+ *   httpStatus: 503,
+ * });
+ * ```
+ */
+export declare class ResolverError extends Error {
+  constructor(
+    message: string,
+    options?: {
+      /** Becomes `extensions.code`. Defaults to `"INTERNAL_SERVER_ERROR"`. */
+      readonly code?: string;
+      /** Becomes `extensions.http.status`. */
+      readonly httpStatus?: number;
+      /** Merged into `extensions` alongside `code`. */
+      readonly extensions?: Record<string, unknown>;
+    }
+  );
+  readonly code: string;
+  readonly httpStatus?: number;
+  readonly extensions?: Record<string, unknown>;
+}
+
+/** Names a schema so it can appear in the GraphQL schema as an object type. */
+export function defineType<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/**
+ * Names a schema that appears in an argument.
+ *
+ * GraphQL keeps input and output types in a separate namespace from object
+ * types, so a `where` argument is declared with this rather than with
+ * {@link defineType}.
+ */
+export function defineInput<F extends Record<string, unknown>>(
+  name: string,
+  fields: F
+): Sury.Schema<UnknownToOutput<F>>;
+
+/** Every resolver declared so far, in declaration order. */
+export function getRegisteredResolvers(): readonly Resolver<unknown, unknown>[];
+
+/** The manifest and SDL for everything declared so far. */
+export function buildRegisteredManifest(): { manifest: unknown; sdl: string };
+
+/** Names a schema representing a GraphQL enum. */
+export function defineEnum<const V extends readonly string[]>(
+  name: string,
+  values: V
+): Sury.Schema<V[number]>;
+
+/** Names a schema representing a custom GraphQL scalar, such as `BigInt`. */
+export function defineScalar<T>(
+  name: string,
+  schema: Sury.Schema<T>
+): Sury.Schema<T>;
+
 // ============== Runtime values ==============
 
 /** The indexer instance. Register handlers with `indexer.onEvent`,