@secondlayer/subgraphs 3.25.1 → 3.26.0

package/dist/src/runtime/reindex.d.ts

@@ -345,6 +345,29 @@ interface SubgraphDefinition {
 	/** Handler functions — keys must match source names (or "*" for catch-all) */
 	handlers: Record<string, SubgraphHandler>;
 }
+import { Block, Event, Transaction } from "@secondlayer/shared/db";
+interface BlockData {
+	block: Block;
+	txs: Transaction[];
+	events: Event[];
+}
+/**
+* Where the subgraph runtime reads canonical chain data. Today it taps the
+* indexer Postgres directly (`PostgresBlockSource`); the re-point adds a
+* `PublicApiBlockSource` that consumes the Streams clock + Index data over
+* HTTP. `matchSources` / handlers / flush / outbox are unchanged — only the
+* loader + tip swap behind this seam.
+*/
+interface BlockSource {
+	/** Highest canonical block height available to process. */
+	getTip(): Promise<number>;
+	/** Canonical block data for [fromHeight, toHeight], keyed by height. */
+	loadBlockRange(fromHeight: number, toHeight: number): Promise<Map<number, BlockData>>;
+	/** Sparse-scan probe: lowest height in (afterHeight, untilHeight] holding
+	*  an event this source's subgraph could match, or null when the rest of
+	*  the range is empty. Optional — only event-scoped sources support it. */
+	nextDataHeight?(afterHeight: number, untilHeight: number): Promise<number | null>;
+}
 type ReindexBatchConfig = {
 	defaultBatchSize: number
 	minBatchSize: number
@@ -364,16 +387,49 @@ declare function initialReindexProgressBlock(fromBlock: number): number;
 declare function resolveReindexResumeBlock(row: ReindexResumeRow): number | null;
 declare function resolveReindexBatchConfig(env?: ReindexBatchEnv): ReindexBatchConfig;
 interface ReindexOptions {
-	fromBlock?: number;
-	toBlock?: number;
+	/**
+	* Policy floor on the walk's first block — NOT a caller-supplied range.
+	* Free-tier accounts may not reindex below their registered `start_block`
+	* (see `resolveGenesisPolicy` on the API side); this 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;
 }
 /**
+* Resolve the reindex walk range. Always the whole subgraph:
+* `[def.startBlock, chain tip]`. Chain tip reads from `index_progress` —
+* lives in the source DB.
+*
+* Reindex drops the schema unconditionally, so the walk range is also the
+* ONLY data that survives. A narrower walk therefore does not "reindex a
+* range" — it silently destroys every row outside it while leaving the
+* subgraph reporting `active` at chain tip (f079: a single-block
+* `--from-block N --to-block N` emptied sbtc-flows, and the first recovery
+* attempt rebuilt only 21% of its history). Ranged, additive work is
+* `backfillSubgraph`'s job.
+*
+* `startBlockFloor` is a plan-policy floor, not a range: it can only raise
+* the start block, never lower it, and never bounds the end.
+*/
+declare function resolveBlockRange(source: BlockSource, def: SubgraphDefinition, opts?: ReindexOptions): Promise<{
+	fromBlock: number
+	toBlock: number
+}>;
+/**
 * 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".
 */
@@ -405,4 +461,4 @@ declare function backfillSubgraph(def: SubgraphDefinition, opts: {
 }): Promise<{
 	processed: number
 }>;
-export { resumeReindex, resolveReindexResumeBlock, resolveReindexBatchConfig, reindexSubgraph, initialReindexProgressBlock, backfillSubgraph, ReindexOptions };
+export { resumeReindex, resolveReindexResumeBlock, resolveReindexBatchConfig, resolveBlockRange, reindexSubgraph, initialReindexProgressBlock, backfillSubgraph, ReindexOptions };

package/dist/src/runtime/reindex.js

@@ -3353,9 +3353,9 @@ async function processBlockRange(def, opts) {
   return { blocksProcessed, totalEventsProcessed, totalErrors, aborted };
 }
 async function resolveBlockRange(source, def, opts) {
-  const fromBlock = opts?.fromBlock ?? def.startBlock ?? 1;
-  const toBlock = opts?.toBlock != null ? opts.toBlock : await source.getTip();
-  return { fromBlock, toBlock };
+  const definitionStart = def.startBlock ?? 1;
+  const fromBlock = opts?.startBlockFloor != null ? Math.max(definitionStart, opts.startBlockFloor) : definitionStart;
+  return { fromBlock, toBlock: await source.getTip() };
 }
 async function clearReindexMetadata(db, subgraphName) {
   await db.updateTable("subgraphs").set({ reindex_from_block: null, reindex_to_block: null }).where("name", "=", subgraphName).execute();
@@ -3576,10 +3576,11 @@ export {
   resumeReindex,
   resolveReindexResumeBlock,
   resolveReindexBatchConfig,
+  resolveBlockRange,
   reindexSubgraph,
   initialReindexProgressBlock,
   backfillSubgraph
 };
 
-//# debugId=9F4CFC4A2A15675F64756E2164756E21
+//# debugId=BBDD389FC2EBC25364756E2164756E21
 //# sourceMappingURL=reindex.js.map