@secondlayer/subgraphs 4.4.1 → 5.0.0

package/README.md

@@ -12,16 +12,11 @@ bun add @secondlayer/subgraphs
 
 ## Quick Start
 
-For the full hosted beta loop, including project setup, fast deploys with
-`--start-block`, querying, and webhooks, start with
-[QUICKSTART.md](QUICKSTART.md).
-
 ```typescript
 import { defineSubgraph } from "@secondlayer/subgraphs";
 
 export default defineSubgraph({
   name: "token-transfers",
-  version: "1.0.0",
   sources: {
     // Named event sources — the key becomes the handler name.
     transfer: {
@@ -51,28 +46,25 @@ export default defineSubgraph({
 });
 ```
 
-Deploy via CLI (`secondlayer subgraphs deploy path/to/definition.ts`), SDK (`sl.subgraphs.deploy({...})`), or MCP (`subgraphs_deploy`). The CLI can also scaffold from a deployed contract with `secondlayer subgraphs scaffold <contract> -o subgraphs/name.ts`; scaffold writes or amends `package.json` and runs `bun install` unless `--no-install` is passed. The dashboard is read-only — creation always happens through an API surface.
+Deploy via CLI (`secondlayer subgraphs deploy path/to/definition.ts`), SDK (`sl.subgraphs.deploy({...})`), or MCP (`subgraphs_deploy`). The CLI can also scaffold from a deployed contract with `secondlayer subgraphs scaffold <contract> -o subgraphs/name.ts`; scaffold writes or amends `package.json` and runs `bun install` unless `--no-install` is passed. `secondlayer subgraphs create <name> --from-contract <id>` writes a definition with one `ctx.insert` handler per print topic.
+
+Every source needs a handler of the same name. Handlers write with `ctx.insert`, `update`, `upsert`, `delete` and `increment`, and read with `ctx.findOne` / `findMany`. A `contract_call` source with `functionName` gets its `abi` fetched at deploy by the CLI; pass it yourself for wildcard, multi-contract or trait sources, or a local deploy.
 
 ## Exports
 
 | Subpath | Description |
 | --- | --- |
-| `.` | `defineSubgraph`, `validateSubgraphDefinition`, `deploySchema`, `diffSchema`, `reindexSubgraph`, `backfillSubgraph`, `generateSubgraphSQL`, `pgSchemaName` |
+| `.` | `defineSubgraph`, `defineSchema`, `InferContext` / `TypedSubgraphContext`, `readContractAt`, `validateSubgraphDefinition`, ORM generators (`generatePrismaSchema`, `generateDrizzleSchema`, `generateKyselySchema`), `deploySchema`, `diffSchema`, `generateSubgraphSQL`, `pgSchemaName` |
 | `./types` | All schema + filter + handler types (`SubgraphDefinition`, `SubgraphFilter`, `StxTransferFilter`, etc.) |
 | `./schema` | Generator + deployer internals |
 | `./validate` | Shape + filter validation for deploys |
-| `./triggers` | Typed `on.*` helpers for all `SubgraphFilter` variants |
-| `./runtime/source-matcher` | Pure fn: match txs+events against a `SubgraphFilter` — used by the processor hot path |
-| `./runtime/replay` | `replayWebhook({ accountId, webhookId, fromBlock, toBlock })` — re-enqueue historical rows as outbox entries |
-
-## Runtime components
+| `./testing` | `runSubgraphTest`, `createTestContext`, `buildEvent`: run handlers against real or built events before deploying |
+| `./runtime/replay` | `replayWebhook({ accountId, webhookId, fromBlock, toBlock })`: re-enqueue historical rows as outbox entries |
+| `./runtime/emitter` | Webhook egress checks used by the API (`checkEgressAllowed`) |
 
-The runtime ships behind these entrypoints (import from the package root):
+## Runtime
 
-- `startSubgraphProcessor(opts?)` — boots the block processor. LISTENs on `indexer:new_block`, matches sources, runs handlers, flushes writes inside a transaction, and emits outbox rows for matching webhooks. Also boots the emitter worker.
-- `processBlock(subgraph, name, height, opts?)` — single-block entry point used by catch-up, reindex, and tests.
-- `catchUpSubgraph(def, name)` — drains pending blocks up to chain tip.
-- `reindexSubgraph(def, opts)` — drop + rebuild schema tables from a start block. Breaking schema changes trigger this automatically on deploy.
+The processor runs as a service, not a library import: `bun run packages/subgraphs/src/service.ts` (the `subgraph-processor` container in `docker/`). It LISTENs on `indexer:new_block`, matches sources, runs handlers, flushes writes inside a transaction, and emits outbox rows for matching webhooks. Breaking schema changes trigger a reindex on deploy.
 
 ## Webhook emitter
 
@@ -80,7 +72,7 @@ Every row written through `ctx.insert()` / `ctx.upsert()` is atomically enqueued
 
 The emitter drains the outbox via `LISTEN webhooks:new_outbox` and `FOR UPDATE SKIP LOCKED` batch claims. Live deliveries win a 90/10 split over replays. Each row dispatches through the format builder matching the webhook's `format` column (`standard-webhooks`, `inngest`, `trigger`, `cloudflare`, `cloudevents`, `raw`). Retries follow `30s → 2m → 10m → 1h → 6h → 24h → 72h`. Twenty consecutive failures trips the per-sub circuit breaker and pauses the webhook.
 
-Delivery bodies and response previews land in `webhook_deliveries`. Rows whose retries exhaust mark `status = 'dead'` in the outbox and surface in the dashboard's dead-letter queue for one-click requeue.
+Delivery bodies and response previews land in `webhook_deliveries`. Rows whose retries exhaust mark `status = 'dead'` in the outbox; list them with `secondlayer webhooks dead <id>` and send one again with `secondlayer webhooks requeue`.
 
 ## Environment
 
@@ -100,13 +92,13 @@ Delivery bodies and response previews land in `webhook_deliveries`. Rows whose r
 Once rows land in your DB, generate a typed schema for your ORM:
 
 ```bash
+secondlayer codegen subgraph subgraphs/my.ts                      # Kysely (default)
 secondlayer codegen subgraph subgraphs/my.ts --target prisma  -o prisma/schema.prisma
 secondlayer codegen subgraph subgraphs/my.ts --target drizzle -o db/schema.ts
 ```
 
-Prisma and Drizzle have first-class generators (`generatePrismaSchema` /
-`generateDrizzleSchema` are exported); both emit relations/`@relation` from the
-schema's `relations` metadata. For Kysely, run `kysely-codegen` against the DB.
+The generators are exported too (`generateKyselySchema`, `generatePrismaSchema`,
+`generateDrizzleSchema`). No foreign keys or relation fields are generated.
 Output mirrors the deployed DDL — `prisma db pull` should be a no-op; treat the
 tables as read-only (the processor owns them) and never `migrate`/`push`.
 `uint`→`Decimal`/`numeric` and the `BigInt` id need `.toString()` for JSON.

package/dist/{src/index.d.ts → index.d.ts}

@@ -110,22 +110,6 @@ interface SubgraphColumn {
 	default?: string | number | boolean;
 }
 /**
-* A foreign-key relation to another table in the same subgraph. Drives DDL FK
-* constraints and ORM codegen (`@relation` in Prisma, `relations()` in Drizzle)
-* so generated clients get typed joins. The referenced columns must form a
-* `uniqueKeys` entry on the target table.
-*/
-interface SubgraphRelation {
-	/** Relation field name on this table's generated model (e.g. "pool"). */
-	name: string;
-	/** Target table name in this subgraph. */
-	references: string;
-	/** Local column(s) holding the foreign key. */
-	fields: string[];
-	/** Target column(s) the fields point at (a uniqueKeys entry on the target). */
-	referencedColumns: string[];
-}
-/**
 * Table definition within a subgraph schema.
 *
 * The array fields are `readonly` so a schema literal can be hoisted out of
@@ -141,8 +125,6 @@ interface SubgraphTable {
 	indexes?: readonly (readonly string[])[];
 	/** Unique key constraints (each entry is an array of column names). Required for upsert. */
 	uniqueKeys?: readonly (readonly string[])[];
-	/** Foreign-key relations to other tables (for typed ORM joins). */
-	relations?: readonly SubgraphRelation[];
 }
 /** Subgraph schema — maps table names to table definitions */
 type SubgraphSchema = Record<string, SubgraphTable>;
@@ -305,9 +287,8 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	/**
 	* One contract id, or a SET of them (max 20) — the standard DeFi shape is
 	* a router plus N pools, which used to cost N near-identical sources and
-	* handlers, or the `"*"` catch-all that erases per-source typing. Payload
-	* types are identical per `type`, so one handler serves the set and
-	* `event.contractId` disambiguates.
+	* handlers. Payload types are identical per `type`, so one handler serves
+	* the set and `event.contractId` disambiguates.
 	*
 	* Supports `*` wildcards (e.g. `"SP1ABC….pool-*"`). Mutually exclusive
 	* with `trait`, which resolves its own set per block.
@@ -321,8 +302,11 @@ interface ContractCallFilter extends TraitScope, FactoryScope {
 	* definition and used at runtime to decode args by name. Omit to keep
 	* `event.args` as a positional `unknown[]`.
 	*
-	* Deploy validation requires `abi` whenever `functionName` is set
-	* (`normalizeAbi()` from `@secondlayer/stacks/clarity`).
+	* Required whenever `functionName` is set. `secondlayer subgraphs deploy`
+	* fills it in from the deployed contract for a single concrete
+	* `contractId`; pass it yourself for wildcard, multi-contract or trait
+	* sources, or a local deploy (`normalizeAbi()` from
+	* `@secondlayer/stacks/clarity`).
 	*/
 	abi?: AbiContract2;
 }
@@ -379,29 +363,9 @@ type PrintField = ColumnType | {
 * is skipped and logged rather than written as nulls.
 */
 type PrintEventPrints = Record<string, Record<string, PrintField>>;
-/**
-* One column in a static identity map. Literals only — the bundler never
-* executes user code, so `{ from: "tokenX" }` is valid and `from("tokenX")`
-* is not.
-*/
-type MaterializeColumn = {
-	from: string
-} | {
-	fromTx: "sender" | "txId"
-} | {
-	fromBlock: "height" | "hash" | "timestamp"
-};
-/** Static insert from a source event — replaces a 1:1 handler. */
-interface MaterializeSpec {
-	table: string;
-	/** Keys = schema column names (snake). */
-	columns: Record<string, MaterializeColumn>;
-}
 type PrintEventFields = FactoryScope & {
 	type: "print_event"
 	topic?: string
-	/** Identity map: insert without a handler function. XOR with handlers[name]. */
-	materialize?: MaterializeSpec
 };
 /**
 * Pinned to one or more contract ids with no trait — `prints` is required so
@@ -447,8 +411,6 @@ interface TxMeta {
 }
 /** Scalar types that can appear as row values */
 type RowValue = string | number | bigint | boolean | null | undefined | Record<string, unknown> | unknown[];
-/** Value or computed function that receives existing row */
-type ComputedValue = RowValue | ((existing: Record<string, unknown> | null) => unknown);
 /** Context passed to subgraph handlers during event processing */
 interface SubgraphContext {
 	block: {
@@ -479,27 +441,11 @@ interface SubgraphContext {
 	* Atomic counter update — the blessed accumulator primitive. Applies
 	* `col = COALESCE(col, 0) + delta` per column (insert-or-add); deltas may
 	* be negative. Requires a uniqueKeys constraint matching `key`. Prefer
-	* this over patchOrInsert with functional updaters for running totals.
+	* this over read-modify-write handlers for running totals.
 	*/
 	increment(table: string, key: Record<string, unknown>, deltas: Record<string, bigint | number>): void;
-	/** Partial update — sets only specified fields, preserves others */
-	patch(table: string, where: Record<string, unknown>, set: Record<string, unknown>): void;
-	/** Find-then-merge-or-insert. Values can be functions: (existing) => newValue */
-	patchOrInsert(table: string, key: Record<string, unknown>, row: Record<string, ComputedValue>): Promise<void>;
 	findOne(table: string, where: Record<string, unknown>): Promise<Record<string, unknown> | null>;
 	findMany(table: string, where: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-	/** Format a bigint amount with decimal places */
-	formatUnits(value: bigint, decimals: number): string;
-	/** Count rows matching filter */
-	count(table: string, where?: Record<string, unknown>): Promise<number>;
-	/** Sum a numeric column */
-	sum(table: string, column: string, where?: Record<string, unknown>): Promise<bigint>;
-	/** Min of a numeric column */
-	min(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	/** Max of a numeric column */
-	max(table: string, column: string, where?: Record<string, unknown>): Promise<bigint | null>;
-	/** Count distinct values in a column */
-	countDistinct(table: string, column: string, where?: Record<string, unknown>): Promise<number>;
 }
 /** Handler function that processes events and writes to the subgraph */
 type SubgraphHandler = (event: Record<string, unknown>, ctx: SubgraphContext) => Promise<void> | void;
@@ -507,8 +453,6 @@ type SubgraphHandler = (event: Record<string, unknown>, ctx: SubgraphContext) =>
 interface SubgraphDefinition {
 	/** Unique subgraph name (lowercase, alphanumeric + hyphens) */
 	name: string;
-	/** Semantic version */
-	version?: string;
 	/** Human description */
 	description?: string;
 	/** Block height to start indexing from (default: 1) */
@@ -520,90 +464,9 @@ interface SubgraphDefinition {
 	sources: Record<string, SubgraphFilter>;
 	/** Tables in this subgraph */
 	schema: SubgraphSchema;
-	/** Handler functions — keys must match source names (or "*" for catch-all) */
+	/** Handler functions, one per source, keyed by source name */
 	handlers: Record<string, SubgraphHandler>;
 }
-/**
-* Validates a subgraph definition, returning the parsed result or throwing on failure.
-*/
-declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
-/**
-* Per-source-type field vocabulary, DERIVED from
-* {@link SubgraphFilterSchema}. Agent-facing surfaces (the MCP filters
-* reference) used to hand-maintain a parallel copy of this list; deriving it
-* means adding a field to a filter can never leave the documentation behind.
-*/
-declare function filterFieldsByType(): Array<{
-	type: string
-	fields: string[]
-}>;
-/** A (decoded event type, optional contract scope) pair the sparse probe
-*  checks. Contract scoping is what makes token-subgraph reindexes leap over
-*  everything that isn't their token. */
-type SparseProbeTarget = {
-	eventType: string
-	contractId?: string
-};
-/** Sparse scanning is sound only when EVERY source is an event-type filter —
-*  a contract_call/contract_deploy source matches transactions, which the
-*  event probe can't see. */
-declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
-/** Probe targets for a subgraph's filters: decoded type + contract scope when\\n*  the filter pins one (assetIdentifier "SP….contract::asset" or contractId). */
-declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
-interface ReindexOptions {
-	/**
-	* Floor on the walk's first block — NOT a caller-supplied range. When set
-	* (e.g. an op row carrying a `from_block`), it raises the walk start and
-	* can never lower it. There is deliberately no `toBlock` counterpart:
-	* a reindex always runs to chain tip. See {@link resolveBlockRange}.
-	*/
-	startBlockFloor?: number;
-	schemaName?: string;
-	/** Op row to receive processed_events on each progress flush. */
-	operationId?: string;
-	signal?: AbortSignal;
-}
-/**
-* Reindex a subgraph by dropping its tables, recreating them, and reprocessing
-* all historical blocks through the handler pipeline.
-*
-* Always whole-subgraph: `[start_block, chain tip]`. There is no ranged
-* reindex — the drop cannot be scoped to a range without re-running delta
-* handlers (`ctx.increment` / `ctx.update` / `ctx.patchOrInsert`) over rows
-* that were never removed, which is the exact double-count hazard `backfill`
-* already refuses. Use `backfillSubgraph` for ranged, additive work.
-*
-* Supports cancellation via AbortSignal — on shutdown abort, status stays
-* "reindexing" for auto-resume; on user cancel, status resets to "active".
-*/
-declare function reindexSubgraph(def: SubgraphDefinition, opts?: ReindexOptions): Promise<{
-	processed: number
-}>;
-/**
-* Resume a previously interrupted reindex. Skips schema drop (already done)
-* and continues from last_processed_block + 1.
-*/
-declare function resumeReindex(def: SubgraphDefinition, opts: {
-	schemaName: string
-	operationId?: string
-	signal?: AbortSignal
-}): Promise<{
-	processed: number
-}>;
-/**
-* Backfill a subgraph by re-processing a block range WITHOUT dropping the schema.
-* Uses upserts so existing data is updated, not duplicated. Safe to run while
-* the subgraph is actively syncing.
-*/
-declare function backfillSubgraph(def: SubgraphDefinition, opts: {
-	fromBlock: number
-	toBlock: number
-	schemaName?: string
-	operationId?: string
-	signal?: AbortSignal
-}): Promise<{
-	processed: number
-}>;
 import { AbiContract as AbiContract3, ExtractFunctionArgs as ExtractFunctionArgs2, ExtractFunctionNames } from "@secondlayer/stacks/clarity";
 /** Maps a ColumnType string literal to its TypeScript equivalent */
 type ColumnToTS<T extends string> = T extends "uint" | "int" ? bigint : T extends "text" | "principal" | "timestamp" ? string : T extends "boolean" ? boolean : T extends "jsonb" ? Record<string, unknown> : unknown;
@@ -758,8 +621,6 @@ type WriteColumnType<C extends SubgraphColumn> = C["type"] extends "uint" | "int
 * defaulted columns are optional; all others required.
 */
 type WriteRow<T extends SubgraphTable> = { [K in keyof T["columns"] as IsOptionalColumn<T["columns"][K]> extends true ? never : K] : WriteColumnType<T["columns"][K]> } & { [K in keyof T["columns"] as IsOptionalColumn<T["columns"][K]> extends true ? K : never]? : WriteColumnType<T["columns"][K]> };
-/** Computed-or-value row for `patchOrInsert` — each field may be a function of the existing row. */
-type PatchRow<T extends SubgraphTable> = { [K in keyof WriteRow<T>]? : WriteRow<T>[K] | ((existing: InferTableRow<T> | null) => unknown) };
 type TableName<S extends SubgraphSchema> = keyof S & string;
 type ColumnName<
 	S extends SubgraphSchema,
@@ -799,8 +660,6 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 		K extends Partial<WriteRow<S[T]>>
 	>(table: T, key: K, row: Omit<WriteRow<S[T]>, keyof K> & Partial<WriteRow<S[T]>>): void;
 	delete<T extends TableName<S>>(table: T, where: RowWhere<S, T>): void;
-	patch<T extends TableName<S>>(table: T, where: RowWhere<S, T>, set: Partial<WriteRow<S[T]>>): void;
-	patchOrInsert<T extends TableName<S>>(table: T, key: Partial<WriteRow<S[T]>>, row: PatchRow<S[T]> & Record<string, ComputedValue>): Promise<void>;
 	/**
 	* Atomic accumulator — `INSERT … ON CONFLICT (key) DO UPDATE SET col =
 	* COALESCE(col,0) + delta`. Deltas commute, so it's the reorg-safe primitive
@@ -810,12 +669,6 @@ interface TypedSubgraphContext<S extends SubgraphSchema> {
 	increment<T extends TableName<S>>(table: T, key: Partial<WriteRow<S[T]>>, deltas: Partial<Record<ColumnName<S, T>, bigint | number>>): void;
 	findOne<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]> | null>;
 	findMany<T extends TableName<S>>(table: T, where: RowWhere<S, T>): Promise<InferTableRow<S[T]>[]>;
-	formatUnits(value: bigint, decimals: number): string;
-	count<T extends TableName<S>>(table: T, where?: RowWhere<S, T>): Promise<number>;
-	sum<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint>;
-	min<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint | null>;
-	max<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<bigint | null>;
-	countDistinct<T extends TableName<S>>(table: T, column: ColumnName<S, T>, where?: RowWhere<S, T>): Promise<number>;
 }
 /** Infer a typed client object from a subgraph definition shape */
 type InferSubgraphClient<T> = T extends {
@@ -1015,29 +868,22 @@ type EventForFilter<F extends SubgraphFilter> = F extends {
 } ? VarSetPayload : F extends {
 	type: infer T extends "map_set" | "map_insert" | "map_delete"
 } ? T extends "map_delete" ? MapDeletePayload : MapWritePayload : never;
-/** Union of every event payload — the `"*"` catch-all handler receives this. */
+/** Union of every event payload. */
 type AnyEvent = FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | PrintEventPayload | ContractCallEvent | ContractDeployPayload | NestedContractCallPayload | VarSetPayload | MapWritePayload | MapDeletePayload;
 type HandlerFn<
 	F extends SubgraphFilter,
 	S extends SubgraphSchema
 > = (event: EventForFilter<F>, ctx: TypedSubgraphContext<S>) => void | Promise<void>;
-type SourceHasMaterialize<F> = F extends {
-	materialize: MaterializeSpec
-} ? true : false;
 /**
-* Handlers keyed by source name. Each handler's `event` is typed from the
-* matching source's filter `type` (e.g. a `print_event` source → `event.topic`
-* is a `string`), and `ctx` is typed against the subgraph `schema` (table
-* names + row columns checked). Sources with `materialize` may omit a
-* handler; every other source key is required. Optional `"*"` catch-all
-* receives any event (validate also accepts `*` alone).
+* Handlers keyed by source name, one per source. Each handler's `event` is
+* typed from the matching source's filter `type` (e.g. a `print_event` source
+* gives `event.topic: string`), and `ctx` is typed against the subgraph
+* `schema` (table names + row columns checked).
 */
 type TypedHandlers<
 	Sources extends Record<string, SubgraphFilter>,
 	S extends SubgraphSchema
-> = { [K in keyof Sources as SourceHasMaterialize<Sources[K]> extends true ? never : K]-? : HandlerFn<Sources[K], S> } & { [K in keyof Sources as SourceHasMaterialize<Sources[K]> extends true ? K : never]? : HandlerFn<Sources[K], S> } & {
-	"*"?: (event: AnyEvent, ctx: TypedSubgraphContext<S>) => void | Promise<void>
-};
+> = { [K in keyof Sources]-? : HandlerFn<Sources[K], S> };
 /** Subgraph definition with `sources`/`schema` literals preserved for typed
 * handlers and downstream query-client inference (`getSubgraph`). */
 type TypedSubgraphDefinition<
@@ -1113,6 +959,20 @@ declare function defineSchema<const S extends SubgraphSchema>(schema: S): S;
 type InferContext<D> = D extends {
 	schema: infer S extends SubgraphSchema
 } ? TypedSubgraphContext<S> : never;
+/**
+* Validates a subgraph definition, returning the parsed result or throwing on failure.
+*/
+declare function validateSubgraphDefinition(def: unknown): SubgraphDefinition;
+/**
+* Per-source-type field vocabulary, DERIVED from
+* {@link SubgraphFilterSchema}. Agent-facing surfaces (the MCP filters
+* reference) used to hand-maintain a parallel copy of this list; deriving it
+* means adding a field to a filter can never leave the documentation behind.
+*/
+declare function filterFieldsByType(): Array<{
+	type: string
+	fields: string[]
+}>;
 type PrintValidationResult = {
 	ok: true
 } | {
@@ -1120,12 +980,6 @@ type PrintValidationResult = {
 	reason: string
 };
 /**
-* Validate one decoded print event against a source's `prints` declaration.
-* Returns `{ ok: true }` when no declaration covers this topic (undeclared
-* topics are not the developer's stated contract, so they pass through).
-*/
-declare function validatePrintPayload(prints: Record<string, Record<string, PrintField>> | undefined, topic: string, data: Record<string, unknown>): PrintValidationResult;
-/**
 * Empirical print-payload schema inference. Callers (the index print-schema
 * endpoint) extract topic + raw Clarity hex per row; this module deserializes
 * a bounded sample per topic, unifies the observed value shapes into a single
@@ -1159,13 +1013,6 @@ interface InferredTopicSchema {
 	non_tuple: boolean;
 	fields: InferredPrintField[];
 }
-/**
-* Kebab-case → camelCase for print tuple keys. Canonical: the runner uses
-* this on `event.data`, and `camel_name` in inferred print schema is the
-* same function. Distinct from ABI `toCamelCase` (`transfer-STX` stays
-* `transfer-STX` here, becomes `transferSTX` there).
-*/
-declare function camelizeDataKey(str: string): string;
 /** Recursively camelize object keys with the print-payload helper (not ABI
 *  `toCamelCase` — that one strips `-STX` and prefixes leading digits). */
 declare function camelizeKeys(obj: unknown): unknown;
@@ -1229,12 +1076,10 @@ interface IndexCodegenOptions {
 	datasourceEnv?: string;
 }
 declare function generateIndexSchema(target: IndexCodegenTarget, opts?: IndexCodegenOptions): string;
-/** Index tables available to codegen, for help text and validation. */
-declare const INDEX_CODEGEN_TABLES: readonly string[];
 import { pgSchemaName } from "@secondlayer/shared/db/queries/subgraphs";
-import { Database as Database3 } from "@secondlayer/shared/db";
-import { Kysely as Kysely3 } from "kysely";
-type AnyDb = Kysely3<Database3>;
+import { Database as Database2 } from "@secondlayer/shared/db";
+import { Kysely as Kysely2 } from "kysely";
+type AnyDb = Kysely2<Database2>;
 interface TableDiff {
 	/** Tables added to the schema */
 	addedTables: string[];
@@ -1316,7 +1161,6 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	apiKeyId?: string
 	accountId?: string
 	schemaName?: string
-	version?: string
 	handlerCode?: string
 	sourceCode?: string
 }): Promise<{
@@ -1327,4 +1171,30 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
 	warnings?: string[]
 }>;
-export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, readContractAt, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, filterFieldsByType, diffSchema, deploySchema, defineSubgraph, defineSchema, canSparseScan, camelizeKeys, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, VarSetPayload, UnpinnedPrintEventFilter, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TraitPrintEventFilter, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPrints, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, PinnedPrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, NestedContractCallPayload, MaterializeSpec, MaterializeColumn, MapWritePayload, MapDeletePayload, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferContext, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, FactoryScope, EventForFilter, ErasedChainReadClient, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ChainReadOptions, ChainReadMethods, ChainReadError, ChainReadClient, ChainReadCacheMode, AnyEvent, AggregateSpec, AggregateResult };
+/** A (decoded event type, optional contract scope) pair the sparse probe
+*  checks. Contract scoping is what makes token-subgraph reindexes leap over
+*  everything that isn't their token. */
+type SparseProbeTarget = {
+	eventType: string
+	contractId?: string
+};
+/** Sparse scanning is sound only when EVERY source is an event-type filter —
+*  a contract_call/contract_deploy source matches transactions, which the
+*  event probe can't see. */
+declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
+/** Probe targets for a subgraph's filters: decoded type + contract scope when\\n*  the filter pins one (assetIdentifier "SP….contract::asset" or contractId). */
+declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
+interface ReindexOptions {
+	/**
+	* Floor on the walk's first block — NOT a caller-supplied range. When set
+	* (e.g. an op row carrying a `from_block`), it raises the walk start and
+	* can never lower it. There is deliberately no `toBlock` counterpart:
+	* a reindex always runs to chain tip. See {@link resolveBlockRange}.
+	*/
+	startBlockFloor?: number;
+	schemaName?: string;
+	/** Op row to receive processed_events on each progress flush. */
+	operationId?: string;
+	signal?: AbortSignal;
+}
+export { AggregateResult, AggregateSpec, AnyEvent, ChainReadCacheMode, ChainReadClient, ChainReadError, ChainReadMethods, ChainReadOptions, ColumnDiff, ColumnToTS, ColumnType, ComparisonFilter, ContractCallEvent, ContractCallFilter, ContractCallPayload, ContractDeployFilter, ContractDeployPayload, DeployDiff, DeployPlan, DrizzleGenOptions, ErasedChainReadClient, EventForFilter, FactoryScope, FindManyOptions, FtBurnFilter, FtBurnPayload, FtMintFilter, FtMintPayload, FtTransferFilter, FtTransferPayload, GeneratedSQL, IndexCodegenOptions, IndexCodegenTarget, InferColumnType, InferContext, InferSubgraphClient, InferTableRow, InferredPrintField, InferredTopicSchema, KyselyGenOptions, MapDeletePayload, MapWritePayload, NestedContractCallPayload, NftBurnFilter, NftBurnPayload, NftMintFilter, NftMintPayload, NftTransferFilter, NftTransferPayload, PinnedPrintEventFilter, PrintDataOf, PrintEventFilter, PrintEventFor, PrintEventPayload, PrintEventPrints, PrintField, PrintFieldToTS, PrintSample, PrintValidationResult, PrismaGenOptions, ReindexOptions, RowValue, SparseProbeTarget, StxBurnFilter, StxBurnPayload, StxLockFilter, StxLockPayload, StxMintFilter, StxMintPayload, StxTransferFilter, StxTransferPayload, SubgraphColumn, SubgraphContext, SubgraphDefinition, SubgraphFilter, SubgraphHandler, SubgraphSchema, SubgraphTable, SubgraphTableClient, SubscribeOptions, SystemRow, TableDiff, TraitPrintEventFilter, TxMeta, TypedHandlers, TypedSubgraphContext, TypedSubgraphDefinition, UnpinnedPrintEventFilter, VarSetPayload, WhereInput, WriteRow, camelizeKeys, canSparseScan, defineSchema, defineSubgraph, deploySchema, diffSchema, filterFieldsByType, generateDrizzleSchema, generateIndexSchema, generateKyselySchema, generatePrismaSchema, generateSubgraphSQL, hasBreakingChanges, inferPrintTopics, pgSchemaName, readContractAt, renderDeployPlan, sparseProbeTargets, validateSubgraphDefinition };