@secondlayer/shared 7.3.1 → 7.5.0

package/dist/src/db/queries/integrity.d.ts

@@ -682,6 +682,21 @@ interface ChainReadCacheTable {
 	result_hex: string;
 	created_at: Generated<Date>;
 }
+/**
+* A block that arrived for a height we already hold, staged until a later
+* block's `parent_hash` says which of the two the chain kept. See migration
+* 0112 — adopting on first sight picked the losing fork twice.
+*/
+interface PendingForkBlocksTable {
+	height: number;
+	block_hash: string;
+	parent_hash: string;
+	/** The canonical hash we held at this height when the contender arrived. */
+	incumbent_hash: string;
+	/** The raw observer payload, replayed verbatim if this fork wins. */
+	payload: ColumnType<unknown, unknown, unknown>;
+	received_at: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -744,6 +759,7 @@ interface Database {
 	x402_payments: X402PaymentsTable;
 	x402_balances: X402BalancesTable;
 	chain_read_cache: ChainReadCacheTable;
+	pending_fork_blocks: PendingForkBlocksTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {
@@ -986,4 +1002,29 @@ declare function checkChainDataIntegrity(db: Kysely<Database>, opts?: {
 	lookback?: number
 }): Promise<ChainDataIntegrity>;
 declare function computeContiguousTip(db: Kysely<Database>, fromHeight: number): Promise<number>;
-export { findGaps, countMissingBlocks, computeContiguousTip, checkChainDataIntegrity, Gap, ChainDataIntegrity };
+type BrokenLink = {
+	height: number
+	hash: string
+	expectedParent: string
+	storedParent: string
+};
+/**
+* Canonical heights whose block does not descend from the canonical block
+* below it.
+*
+* `findGaps` asks "is every height present?", which a chain sitting on a losing
+* fork answers yes to. On 2026-07-30 a reorg at 8,663,166 was resolved the
+* wrong way: we adopted a block that mainnet orphaned, its true successors were
+* swept non-canonical, and later blocks were inserted canonical on top. Every
+* height existed. Nothing was "missing". The chain simply did not join up, and
+* no check asked that question — so we served a broken chain for seventeen
+* hours and only noticed because subgraphs stopped moving.
+*
+* Scoped to a recent window by default: an unlinked height is an active-repair
+* concern, and scanning eight million rows every cycle is not.
+*/
+declare function findBrokenLinks(db: Kysely<Database>, opts?: {
+	window?: number
+	limit?: number
+}): Promise<BrokenLink[]>;
+export { findGaps, findBrokenLinks, countMissingBlocks, computeContiguousTip, checkChainDataIntegrity, Gap, ChainDataIntegrity, BrokenLink };

package/dist/src/db/queries/integrity.js

@@ -92,12 +92,37 @@ async function computeContiguousTip(db, fromHeight) {
   `.execute(db);
   return Number(rows[0]?.tip ?? fromHeight);
 }
+async function findBrokenLinks(db, opts = {}) {
+  const windowSize = opts.window ?? 1e4;
+  const limitClause = opts.limit ? sql`LIMIT ${opts.limit}` : sql``;
+  const { rows } = await sql`
+		WITH recent AS (
+			SELECT height, hash, parent_hash
+			FROM blocks
+			WHERE canonical = true
+				AND height > (SELECT MAX(height) - ${windowSize} FROM blocks WHERE canonical = true)
+		)
+		SELECT b.height, b.hash, p.hash AS expected_parent, b.parent_hash AS stored_parent
+		FROM recent b
+		JOIN recent p ON p.height = b.height - 1
+		WHERE b.parent_hash <> p.hash
+		ORDER BY b.height
+		${limitClause}
+	`.execute(db);
+  return rows.map((r) => ({
+    height: Number(r.height),
+    hash: r.hash,
+    expectedParent: r.expected_parent,
+    storedParent: r.stored_parent
+  }));
+}
 export {
   findGaps,
+  findBrokenLinks,
   countMissingBlocks,
   computeContiguousTip,
   checkChainDataIntegrity
 };
 
-//# debugId=EADA898ADC77C59264756E2164756E21
+//# debugId=FFA2BEF866239EA364756E2164756E21
 //# sourceMappingURL=integrity.js.map

package/dist/src/db/queries/integrity.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/db/queries/integrity.ts"],
   "sourcesContent": [
-    "import { type Kysely, sql } from \"kysely\";\nimport type { Database } from \"../types.ts\";\n\nexport interface Gap {\n\tgapStart: number;\n\tgapEnd: number;\n\tsize: number;\n}\n\nexport async function findGaps(\n\tdb: Kysely<Database>,\n\tlimit?: number,\n): Promise<Gap[]> {\n\tconst limitClause = limit ? sql`LIMIT ${limit}` : sql``;\n\tconst { rows } = await sql<{\n\t\tgap_start: string;\n\t\tgap_end: string;\n\t\tsize: string;\n\t}>`\n    SELECT gap_start, gap_end, gap_end - gap_start + 1 AS size\n    FROM (\n      SELECT height + 1 AS gap_start, next_height - 1 AS gap_end\n      FROM (\n        SELECT height, LEAD(height) OVER (ORDER BY height) AS next_height\n        FROM blocks WHERE canonical = true\n      ) sub\n      WHERE next_height - height > 1\n    ) gaps\n    ORDER BY gap_start\n    ${limitClause}\n  `.execute(db);\n\n\treturn rows.map((r) => ({\n\t\tgapStart: Number(r.gap_start),\n\t\tgapEnd: Number(r.gap_end),\n\t\tsize: Number(r.size),\n\t}));\n}\n\nexport async function countMissingBlocks(\n\tdb: Kysely<Database>,\n): Promise<number> {\n\tconst { rows } = await sql<{ total: string }>`\n    SELECT COALESCE(SUM(next_height - height - 1), 0) AS total\n    FROM (\n      SELECT height, LEAD(height) OVER (ORDER BY height) AS next_height\n      FROM blocks WHERE canonical = true\n    ) sub\n    WHERE next_height - height > 1\n  `.execute(db);\n\n\treturn Number(rows[0]?.total ?? 0);\n}\n\nexport interface ChainDataIntegrity {\n\tok: boolean;\n\tmaxHeight: number;\n\tsampleHeight: number | null;\n\tsampleBlocks: number;\n\treason: string | null;\n}\n\n/**\n * Cheap sanity check that the `blocks` table actually holds the history its tip\n * implies. Catches a wrong/empty Postgres volume — e.g. a container recreated\n * against a fresh volume — being silently served: if the tip is high but a\n * window of blocks well below it is missing, the data isn't what the tip claims.\n *\n * Below `checkFloor` we can't distinguish a fresh install from an empty volume,\n * so we report ok — a genuinely new DB legitimately has little history. Two\n * indexed lookups, safe to run on every startup / health poll.\n */\nexport async function checkChainDataIntegrity(\n\tdb: Kysely<Database>,\n\topts?: { checkFloor?: number; lookback?: number },\n): Promise<ChainDataIntegrity> {\n\tconst checkFloor = opts?.checkFloor ?? 1_000_000;\n\tconst lookback = opts?.lookback ?? 500_000;\n\n\tconst { rows: tipRows } = await sql<{ max: string | null }>`\n\t\tSELECT MAX(height) AS max FROM blocks WHERE canonical = true\n\t`.execute(db);\n\tconst maxHeight = Number(tipRows[0]?.max ?? 0);\n\n\tif (maxHeight < checkFloor) {\n\t\treturn {\n\t\t\tok: true,\n\t\t\tmaxHeight,\n\t\t\tsampleHeight: null,\n\t\t\tsampleBlocks: 0,\n\t\t\treason: null,\n\t\t};\n\t}\n\n\tconst sampleHeight = maxHeight - lookback;\n\tconst { rows: sampleRows } = await sql<{ n: string }>`\n\t\tSELECT count(*) AS n FROM blocks\n\t\tWHERE canonical = true AND height >= ${sampleHeight} AND height < ${sampleHeight + 1000}\n\t`.execute(db);\n\tconst sampleBlocks = Number(sampleRows[0]?.n ?? 0);\n\n\treturn {\n\t\tok: sampleBlocks > 0,\n\t\tmaxHeight,\n\t\tsampleHeight,\n\t\tsampleBlocks,\n\t\treason:\n\t\t\tsampleBlocks > 0\n\t\t\t\t? null\n\t\t\t\t: `tip is ${maxHeight} but no canonical blocks near ${sampleHeight} — wrong or empty volume?`,\n\t};\n}\n\nexport async function computeContiguousTip(\n\tdb: Kysely<Database>,\n\tfromHeight: number,\n): Promise<number> {\n\tconst { rows } = await sql<{ tip: string }>`\n    SELECT COALESCE(MAX(height), ${fromHeight}) AS tip\n    FROM (\n      SELECT height, height - ROW_NUMBER() OVER (ORDER BY height) AS grp\n      FROM blocks WHERE canonical = true AND height >= ${fromHeight}\n    ) sub\n    WHERE grp = (\n      SELECT height - ROW_NUMBER() OVER (ORDER BY height)\n      FROM blocks WHERE canonical = true AND height = ${fromHeight}\n    )\n  `.execute(db);\n\n\treturn Number(rows[0]?.tip ?? fromHeight);\n}\n"
+    "import { type Kysely, sql } from \"kysely\";\nimport type { Database } from \"../types.ts\";\n\nexport interface Gap {\n\tgapStart: number;\n\tgapEnd: number;\n\tsize: number;\n}\n\nexport async function findGaps(\n\tdb: Kysely<Database>,\n\tlimit?: number,\n): Promise<Gap[]> {\n\tconst limitClause = limit ? sql`LIMIT ${limit}` : sql``;\n\tconst { rows } = await sql<{\n\t\tgap_start: string;\n\t\tgap_end: string;\n\t\tsize: string;\n\t}>`\n    SELECT gap_start, gap_end, gap_end - gap_start + 1 AS size\n    FROM (\n      SELECT height + 1 AS gap_start, next_height - 1 AS gap_end\n      FROM (\n        SELECT height, LEAD(height) OVER (ORDER BY height) AS next_height\n        FROM blocks WHERE canonical = true\n      ) sub\n      WHERE next_height - height > 1\n    ) gaps\n    ORDER BY gap_start\n    ${limitClause}\n  `.execute(db);\n\n\treturn rows.map((r) => ({\n\t\tgapStart: Number(r.gap_start),\n\t\tgapEnd: Number(r.gap_end),\n\t\tsize: Number(r.size),\n\t}));\n}\n\nexport async function countMissingBlocks(\n\tdb: Kysely<Database>,\n): Promise<number> {\n\tconst { rows } = await sql<{ total: string }>`\n    SELECT COALESCE(SUM(next_height - height - 1), 0) AS total\n    FROM (\n      SELECT height, LEAD(height) OVER (ORDER BY height) AS next_height\n      FROM blocks WHERE canonical = true\n    ) sub\n    WHERE next_height - height > 1\n  `.execute(db);\n\n\treturn Number(rows[0]?.total ?? 0);\n}\n\nexport interface ChainDataIntegrity {\n\tok: boolean;\n\tmaxHeight: number;\n\tsampleHeight: number | null;\n\tsampleBlocks: number;\n\treason: string | null;\n}\n\n/**\n * Cheap sanity check that the `blocks` table actually holds the history its tip\n * implies. Catches a wrong/empty Postgres volume — e.g. a container recreated\n * against a fresh volume — being silently served: if the tip is high but a\n * window of blocks well below it is missing, the data isn't what the tip claims.\n *\n * Below `checkFloor` we can't distinguish a fresh install from an empty volume,\n * so we report ok — a genuinely new DB legitimately has little history. Two\n * indexed lookups, safe to run on every startup / health poll.\n */\nexport async function checkChainDataIntegrity(\n\tdb: Kysely<Database>,\n\topts?: { checkFloor?: number; lookback?: number },\n): Promise<ChainDataIntegrity> {\n\tconst checkFloor = opts?.checkFloor ?? 1_000_000;\n\tconst lookback = opts?.lookback ?? 500_000;\n\n\tconst { rows: tipRows } = await sql<{ max: string | null }>`\n\t\tSELECT MAX(height) AS max FROM blocks WHERE canonical = true\n\t`.execute(db);\n\tconst maxHeight = Number(tipRows[0]?.max ?? 0);\n\n\tif (maxHeight < checkFloor) {\n\t\treturn {\n\t\t\tok: true,\n\t\t\tmaxHeight,\n\t\t\tsampleHeight: null,\n\t\t\tsampleBlocks: 0,\n\t\t\treason: null,\n\t\t};\n\t}\n\n\tconst sampleHeight = maxHeight - lookback;\n\tconst { rows: sampleRows } = await sql<{ n: string }>`\n\t\tSELECT count(*) AS n FROM blocks\n\t\tWHERE canonical = true AND height >= ${sampleHeight} AND height < ${sampleHeight + 1000}\n\t`.execute(db);\n\tconst sampleBlocks = Number(sampleRows[0]?.n ?? 0);\n\n\treturn {\n\t\tok: sampleBlocks > 0,\n\t\tmaxHeight,\n\t\tsampleHeight,\n\t\tsampleBlocks,\n\t\treason:\n\t\t\tsampleBlocks > 0\n\t\t\t\t? null\n\t\t\t\t: `tip is ${maxHeight} but no canonical blocks near ${sampleHeight} — wrong or empty volume?`,\n\t};\n}\n\nexport async function computeContiguousTip(\n\tdb: Kysely<Database>,\n\tfromHeight: number,\n): Promise<number> {\n\tconst { rows } = await sql<{ tip: string }>`\n    SELECT COALESCE(MAX(height), ${fromHeight}) AS tip\n    FROM (\n      SELECT height, height - ROW_NUMBER() OVER (ORDER BY height) AS grp\n      FROM blocks WHERE canonical = true AND height >= ${fromHeight}\n    ) sub\n    WHERE grp = (\n      SELECT height - ROW_NUMBER() OVER (ORDER BY height)\n      FROM blocks WHERE canonical = true AND height = ${fromHeight}\n    )\n  `.execute(db);\n\n\treturn Number(rows[0]?.tip ?? fromHeight);\n}\n\nexport type BrokenLink = {\n\theight: number;\n\thash: string;\n\texpectedParent: string;\n\tstoredParent: string;\n};\n\n/**\n * Canonical heights whose block does not descend from the canonical block\n * below it.\n *\n * `findGaps` asks \"is every height present?\", which a chain sitting on a losing\n * fork answers yes to. On 2026-07-30 a reorg at 8,663,166 was resolved the\n * wrong way: we adopted a block that mainnet orphaned, its true successors were\n * swept non-canonical, and later blocks were inserted canonical on top. Every\n * height existed. Nothing was \"missing\". The chain simply did not join up, and\n * no check asked that question — so we served a broken chain for seventeen\n * hours and only noticed because subgraphs stopped moving.\n *\n * Scoped to a recent window by default: an unlinked height is an active-repair\n * concern, and scanning eight million rows every cycle is not.\n */\nexport async function findBrokenLinks(\n\tdb: Kysely<Database>,\n\topts: { window?: number; limit?: number } = {},\n): Promise<BrokenLink[]> {\n\tconst windowSize = opts.window ?? 10_000;\n\tconst limitClause = opts.limit ? sql`LIMIT ${opts.limit}` : sql``;\n\tconst { rows } = await sql<{\n\t\theight: string | number;\n\t\thash: string;\n\t\texpected_parent: string;\n\t\tstored_parent: string;\n\t}>`\n\t\tWITH recent AS (\n\t\t\tSELECT height, hash, parent_hash\n\t\t\tFROM blocks\n\t\t\tWHERE canonical = true\n\t\t\t\tAND height > (SELECT MAX(height) - ${windowSize} FROM blocks WHERE canonical = true)\n\t\t)\n\t\tSELECT b.height, b.hash, p.hash AS expected_parent, b.parent_hash AS stored_parent\n\t\tFROM recent b\n\t\tJOIN recent p ON p.height = b.height - 1\n\t\tWHERE b.parent_hash <> p.hash\n\t\tORDER BY b.height\n\t\t${limitClause}\n\t`.execute(db);\n\treturn rows.map((r) => ({\n\t\theight: Number(r.height),\n\t\thash: r.hash,\n\t\texpectedParent: r.expected_parent,\n\t\tstoredParent: r.stored_parent,\n\t}));\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AASA,eAAsB,QAAQ,CAC7B,IACA,OACiB;AAAA,EACjB,MAAM,cAAc,QAAQ,YAAY,UAAU;AAAA,EAClD,QAAQ,SAAS,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAelB;AAAA,IACF,QAAQ,EAAE;AAAA,EAEb,OAAO,KAAK,IAAI,CAAC,OAAO;AAAA,IACvB,UAAU,OAAO,EAAE,SAAS;AAAA,IAC5B,QAAQ,OAAO,EAAE,OAAO;AAAA,IACxB,MAAM,OAAO,EAAE,IAAI;AAAA,EACpB,EAAE;AAAA;AAGH,eAAsB,kBAAkB,CACvC,IACkB;AAAA,EAClB,QAAQ,SAAS,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOpB,QAAQ,EAAE;AAAA,EAEb,OAAO,OAAO,KAAK,IAAI,SAAS,CAAC;AAAA;AAqBlC,eAAsB,uBAAuB,CAC5C,IACA,MAC8B;AAAA,EAC9B,MAAM,aAAa,MAAM,cAAc;AAAA,EACvC,MAAM,WAAW,MAAM,YAAY;AAAA,EAEnC,QAAQ,MAAM,YAAY,MAAM;AAAA;AAAA,GAE9B,QAAQ,EAAE;AAAA,EACZ,MAAM,YAAY,OAAO,QAAQ,IAAI,OAAO,CAAC;AAAA,EAE7C,IAAI,YAAY,YAAY;AAAA,IAC3B,OAAO;AAAA,MACN,IAAI;AAAA,MACJ;AAAA,MACA,cAAc;AAAA,MACd,cAAc;AAAA,MACd,QAAQ;AAAA,IACT;AAAA,EACD;AAAA,EAEA,MAAM,eAAe,YAAY;AAAA,EACjC,QAAQ,MAAM,eAAe,MAAM;AAAA;AAAA,yCAEK,6BAA6B,eAAe;AAAA,GAClF,QAAQ,EAAE;AAAA,EACZ,MAAM,eAAe,OAAO,WAAW,IAAI,KAAK,CAAC;AAAA,EAEjD,OAAO;AAAA,IACN,IAAI,eAAe;AAAA,IACnB;AAAA,IACA;AAAA,IACA;AAAA,IACA,QACC,eAAe,IACZ,OACA,UAAU,0CAA0C;AAAA,EACzD;AAAA;AAGD,eAAsB,oBAAoB,CACzC,IACA,YACkB;AAAA,EAClB,QAAQ,SAAS,MAAM;AAAA,mCACW;AAAA;AAAA;AAAA,yDAGsB;AAAA;AAAA;AAAA;AAAA,wDAID;AAAA;AAAA,IAEpD,QAAQ,EAAE;AAAA,EAEb,OAAO,OAAO,KAAK,IAAI,OAAO,UAAU;AAAA;",
-  "debugId": "EADA898ADC77C59264756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;AAAA;AASA,eAAsB,QAAQ,CAC7B,IACA,OACiB;AAAA,EACjB,MAAM,cAAc,QAAQ,YAAY,UAAU;AAAA,EAClD,QAAQ,SAAS,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAelB;AAAA,IACF,QAAQ,EAAE;AAAA,EAEb,OAAO,KAAK,IAAI,CAAC,OAAO;AAAA,IACvB,UAAU,OAAO,EAAE,SAAS;AAAA,IAC5B,QAAQ,OAAO,EAAE,OAAO;AAAA,IACxB,MAAM,OAAO,EAAE,IAAI;AAAA,EACpB,EAAE;AAAA;AAGH,eAAsB,kBAAkB,CACvC,IACkB;AAAA,EAClB,QAAQ,SAAS,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOpB,QAAQ,EAAE;AAAA,EAEb,OAAO,OAAO,KAAK,IAAI,SAAS,CAAC;AAAA;AAqBlC,eAAsB,uBAAuB,CAC5C,IACA,MAC8B;AAAA,EAC9B,MAAM,aAAa,MAAM,cAAc;AAAA,EACvC,MAAM,WAAW,MAAM,YAAY;AAAA,EAEnC,QAAQ,MAAM,YAAY,MAAM;AAAA;AAAA,GAE9B,QAAQ,EAAE;AAAA,EACZ,MAAM,YAAY,OAAO,QAAQ,IAAI,OAAO,CAAC;AAAA,EAE7C,IAAI,YAAY,YAAY;AAAA,IAC3B,OAAO;AAAA,MACN,IAAI;AAAA,MACJ;AAAA,MACA,cAAc;AAAA,MACd,cAAc;AAAA,MACd,QAAQ;AAAA,IACT;AAAA,EACD;AAAA,EAEA,MAAM,eAAe,YAAY;AAAA,EACjC,QAAQ,MAAM,eAAe,MAAM;AAAA;AAAA,yCAEK,6BAA6B,eAAe;AAAA,GAClF,QAAQ,EAAE;AAAA,EACZ,MAAM,eAAe,OAAO,WAAW,IAAI,KAAK,CAAC;AAAA,EAEjD,OAAO;AAAA,IACN,IAAI,eAAe;AAAA,IACnB;AAAA,IACA;AAAA,IACA;AAAA,IACA,QACC,eAAe,IACZ,OACA,UAAU,0CAA0C;AAAA,EACzD;AAAA;AAGD,eAAsB,oBAAoB,CACzC,IACA,YACkB;AAAA,EAClB,QAAQ,SAAS,MAAM;AAAA,mCACW;AAAA;AAAA;AAAA,yDAGsB;AAAA;AAAA;AAAA;AAAA,wDAID;AAAA;AAAA,IAEpD,QAAQ,EAAE;AAAA,EAEb,OAAO,OAAO,KAAK,IAAI,OAAO,UAAU;AAAA;AAyBzC,eAAsB,eAAe,CACpC,IACA,OAA4C,CAAC,GACrB;AAAA,EACxB,MAAM,aAAa,KAAK,UAAU;AAAA,EAClC,MAAM,cAAc,KAAK,QAAQ,YAAY,KAAK,UAAU;AAAA,EAC5D,QAAQ,SAAS,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA,yCAUiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOrC;AAAA,GACD,QAAQ,EAAE;AAAA,EACZ,OAAO,KAAK,IAAI,CAAC,OAAO;AAAA,IACvB,QAAQ,OAAO,EAAE,MAAM;AAAA,IACvB,MAAM,EAAE;AAAA,IACR,gBAAgB,EAAE;AAAA,IAClB,cAAc,EAAE;AAAA,EACjB,EAAE;AAAA;",
+  "debugId": "FFA2BEF866239EA364756E2164756E21",
   "names": []
 }

package/dist/src/db/queries/subgraph-gaps.d.ts

@@ -682,6 +682,21 @@ interface ChainReadCacheTable {
 	result_hex: string;
 	created_at: Generated<Date>;
 }
+/**
+* A block that arrived for a height we already hold, staged until a later
+* block's `parent_hash` says which of the two the chain kept. See migration
+* 0112 — adopting on first sight picked the losing fork twice.
+*/
+interface PendingForkBlocksTable {
+	height: number;
+	block_hash: string;
+	parent_hash: string;
+	/** The canonical hash we held at this height when the contender arrived. */
+	incumbent_hash: string;
+	/** The raw observer payload, replayed verbatim if this fork wins. */
+	payload: ColumnType<unknown, unknown, unknown>;
+	received_at: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -744,6 +759,7 @@ interface Database {
 	x402_payments: X402PaymentsTable;
 	x402_balances: X402BalancesTable;
 	chain_read_cache: ChainReadCacheTable;
+	pending_fork_blocks: PendingForkBlocksTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {

package/dist/src/db/queries/subgraph-operations.d.ts

@@ -682,6 +682,21 @@ interface ChainReadCacheTable {
 	result_hex: string;
 	created_at: Generated<Date>;
 }
+/**
+* A block that arrived for a height we already hold, staged until a later
+* block's `parent_hash` says which of the two the chain kept. See migration
+* 0112 — adopting on first sight picked the losing fork twice.
+*/
+interface PendingForkBlocksTable {
+	height: number;
+	block_hash: string;
+	parent_hash: string;
+	/** The canonical hash we held at this height when the contender arrived. */
+	incumbent_hash: string;
+	/** The raw observer payload, replayed verbatim if this fork wins. */
+	payload: ColumnType<unknown, unknown, unknown>;
+	received_at: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -744,6 +759,7 @@ interface Database {
 	x402_payments: X402PaymentsTable;
 	x402_balances: X402BalancesTable;
 	chain_read_cache: ChainReadCacheTable;
+	pending_fork_blocks: PendingForkBlocksTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {

package/dist/src/db/queries/subgraphs.d.ts

@@ -683,6 +683,21 @@ interface ChainReadCacheTable {
 	result_hex: string;
 	created_at: Generated<Date>;
 }
+/**
+* A block that arrived for a height we already hold, staged until a later
+* block's `parent_hash` says which of the two the chain kept. See migration
+* 0112 — adopting on first sight picked the losing fork twice.
+*/
+interface PendingForkBlocksTable {
+	height: number;
+	block_hash: string;
+	parent_hash: string;
+	/** The canonical hash we held at this height when the contender arrived. */
+	incumbent_hash: string;
+	/** The raw observer payload, replayed verbatim if this fork wins. */
+	payload: ColumnType<unknown, unknown, unknown>;
+	received_at: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -745,6 +760,7 @@ interface Database {
 	x402_payments: X402PaymentsTable;
 	x402_balances: X402BalancesTable;
 	chain_read_cache: ChainReadCacheTable;
+	pending_fork_blocks: PendingForkBlocksTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {
@@ -1015,6 +1031,22 @@ declare function listSubgraphs(db: Kysely<Database>, accountId?: string): Promis
 declare function findPublicSubgraphByName(db: Kysely<Database>, name: string): Promise<Subgraph | null>;
 declare function updateSubgraphVisibility(db: Kysely<Database>, name: string, accountId: string, visibility: "public" | "private"): Promise<void>;
 declare function updateSubgraphStatus(db: Kysely<Database>, name: string, status: string, lastProcessedBlock?: number): Promise<void>;
+/** Live-walk ERROR write (f069): a block whose handlers ALL failed
+*  (`processed === 0 && errors > 0`, `block-processor.ts`'s `applyProgress`)
+*  is stamped 'error' and its height is recorded as processed, same as
+*  `updateSubgraphStatus(db, name, "error", blockHeight)` — except the
+*  cursor half of that write now goes through the same conditional `<`
+*  guard as {@link recordLiveProgress}. Marking a subgraph 'error' is not
+*  itself replay-sensitive, but it shares the `last_processed_block` column
+*  with the replay guard: an unconditional write here could regress the
+*  cursor a racing (successful) writer already advanced past, which is
+*  exactly the regress-then-re-walk loop this guard exists to close. In
+*  practice `ctx.rollbackTo` (`runner.ts`) means an all-failed block never
+*  flushes writes, so a lost race here is always a silent no-op, never a
+*  case that needs `CursorRaceLostError`-style tx abort. Returns whether
+*  the write applied. Live path only — reindex/backfill's error stamping
+*  goes through {@link updateSubgraphStatus} unconditionally, as before. */
+declare function recordLiveError(db: Kysely<Database>, name: string, blockHeight: number): Promise<boolean>;
 declare function recordSubgraphProcessed(db: Kysely<Database>, name: string, processed: number, errors: number, lastError?: string): Promise<void>;
 declare function updateSubgraphHandlerPath(db: Kysely<Database>, name: string, handlerPath: string, opts?: {
 	handlerCode?: string
@@ -1029,16 +1061,49 @@ declare function updateSubgraphExpiry(db: Kysely<Database>, name: string, accoun
 *  status stamping let catch-up flap a parked subgraph back into its own path
 *  per block, fighting the queued reindex op.
 *
-*  `last_processed_block` itself is written UNCONDITIONALLY — no monotonic
-*  guard — on purpose: a reorg rewind must be able to move it *backward* to
-*  the fork height, and a naive GREATEST(old, new) would block that. This
-*  only stays correct because the two writers that can advance/rewind a
-*  given subgraph's cursor concurrently (the catch-up walk and the reorg
-*  handler, both in `@secondlayer/subgraphs/runtime`) serialize on an
-*  in-process per-subgraph lock + reorg epoch guard
-*  (`packages/subgraphs/src/runtime/catchup.ts`, `subgraphBlockLockHeld` /
-*  `reorgEpoch` — see the comment there for the full invariant; f057). Don't
-*  add a monotonic guard here without re-deriving that it can't also block
-*  the rewind. */
-declare function recordLiveProgress(db: Kysely<Database>, name: string, lastProcessedBlock: number): Promise<void>;
-export { updateSubgraphVisibility, updateSubgraphStatus, updateSubgraphHandlerPath, updateSubgraphExpiry, subgraphDatabaseUrl, resolveSubgraphRawClient, resolveSubgraphDb, registerSubgraph, recordSubgraphProcessed, recordLiveProgress, pgSchemaNameFor, pgSchemaName, listSubgraphs, isByoSubgraph, getSubgraph, findPublicSubgraphByName, encryptDatabaseUrl, deleteSubgraph };
+*  `last_processed_block` is now written CONDITIONALLY — `WHERE
+*  last_processed_block < lastProcessedBlock`, mirroring
+*  `advanceOperationCursor`'s (`subgraph-operations.ts`) comparison shape —
+*  and returns whether THIS call actually advanced it. This used to be
+*  unconditional by design, on the premise that the only two writers able to
+*  advance/rewind a given subgraph's cursor concurrently (the catch-up walk
+*  and the reorg handler) serialize on an in-process per-subgraph lock +
+*  reorg epoch guard (`packages/subgraphs/src/runtime/catchup.ts`,
+*  `subgraphBlockLockHeld` / `reorgEpoch`; f057). That guard is in-process
+*  only. The f068 investigation
+*  (`docs/internal/audits/asset-holdings-unreproducible-balances-f068.md`)
+*  found a cross-process sequence it does not cover: a catch-up leader that
+*  loses its advisory-lock connection mid-walk keeps writing (leadership is
+*  checked only at walk entry, not per-iteration) while a new leader takes
+*  over and walks the same range — both commit increments for overlapping
+*  heights, and every regressed cursor write from the laggard re-triggers a
+*  full re-walk, growing per-height application without bound. The
+*  conditional advance here (paired with the fast-path replay guard armed on
+*  the live path in `block-processor.ts`) is now the cross-process
+*  guarantee: a block at/below the current cursor can never re-advance it,
+*  so a laggard's commits can no longer regress-then-retrigger.
+*
+*  This conditionality is why the reorg rewind can no longer go through this
+*  function — a rewind's whole point is to move the cursor *backward*, which
+*  the `<` guard would silently refuse. Reorg mode calls
+*  {@link rewindLiveProgress} instead, which keeps the old unconditional
+*  semantics and is safe specifically because the reorg path takes a
+*  transaction-scoped advisory lock (`reorg.ts`) other writers can't cross. */
+declare function recordLiveProgress(db: Kysely<Database>, name: string, lastProcessedBlock: number): Promise<boolean>;
+/** Reorg-rewind progress write: the OLD unconditional `recordLiveProgress`
+*  semantics, verbatim — moves `last_processed_block` to the fork height
+*  regardless of its current value, because that is by definition a
+*  backward move the conditional `<` guard in `recordLiveProgress` would
+*  refuse. Same status-promotion CASE (never unparks an explicit
+*  'reindexing').
+*
+*  Callers: exclusively the subgraph-reorg path
+*  (`packages/subgraphs/src/runtime/reorg.ts`, via `block-processor.ts`'s
+*  `reorgRewind` mode), which is safe from the cross-process race this
+*  function reintroduces because it holds a transaction-scoped Postgres
+*  advisory lock (`pg_advisory_xact_lock`) for the whole
+*  delete+reprocess+rewind sequence — no other writer can interleave a
+*  forward write between the rewind and the fork block's reprocess. Do not
+*  call this from the live catch-up path. */
+declare function rewindLiveProgress(db: Kysely<Database>, name: string, lastProcessedBlock: number): Promise<void>;
+export { updateSubgraphVisibility, updateSubgraphStatus, updateSubgraphHandlerPath, updateSubgraphExpiry, subgraphDatabaseUrl, rewindLiveProgress, resolveSubgraphRawClient, resolveSubgraphDb, registerSubgraph, recordSubgraphProcessed, recordLiveProgress, recordLiveError, pgSchemaNameFor, pgSchemaName, listSubgraphs, isByoSubgraph, getSubgraph, findPublicSubgraphByName, encryptDatabaseUrl, deleteSubgraph };

package/dist/src/db/queries/subgraphs.js

@@ -657,6 +657,7 @@ var TABLE_TO_DB = {
   contracts: "source",
   chain_reorgs: "source",
   chain_read_cache: "source",
+  pending_fork_blocks: "source",
   decoded_events: "source",
   decoder_checkpoints: "source",
   pox4_calls: "source",
@@ -1092,6 +1093,14 @@ async function updateSubgraphStatus(db, name, status, lastProcessedBlock) {
     updated_at: new Date
   }).where("name", "=", name).execute();
 }
+async function recordLiveError(db, name, blockHeight) {
+  const result = await db.updateTable("subgraphs").set({
+    status: "error",
+    last_processed_block: blockHeight,
+    updated_at: new Date
+  }).where("name", "=", name).where("last_processed_block", "<", blockHeight).executeTakeFirst();
+  return Number(result.numUpdatedRows ?? 0n) > 0;
+}
 async function recordSubgraphProcessed(db, name, processed, errors, lastError) {
   await db.updateTable("subgraphs").set({
     total_processed: sql3`total_processed + ${processed}`,
@@ -1129,6 +1138,14 @@ async function updateSubgraphExpiry(db, name, accountId, expiresAt) {
   await db.updateTable("subgraphs").set({ expires_at: expiresAt }).where("name", "=", name).where("account_id", "=", accountId).execute();
 }
 async function recordLiveProgress(db, name, lastProcessedBlock) {
+  const result = await db.updateTable("subgraphs").set({
+    last_processed_block: lastProcessedBlock,
+    status: sql3`CASE WHEN status = 'reindexing' THEN status ELSE 'active' END`,
+    updated_at: new Date
+  }).where("name", "=", name).where("last_processed_block", "<", lastProcessedBlock).executeTakeFirst();
+  return Number(result.numUpdatedRows ?? 0n) > 0;
+}
+async function rewindLiveProgress(db, name, lastProcessedBlock) {
   await db.updateTable("subgraphs").set({
     last_processed_block: lastProcessedBlock,
     status: sql3`CASE WHEN status = 'reindexing' THEN status ELSE 'active' END`,
@@ -1141,11 +1158,13 @@ export {
   updateSubgraphHandlerPath,
   updateSubgraphExpiry,
   subgraphDatabaseUrl,
+  rewindLiveProgress,
   resolveSubgraphRawClient,
   resolveSubgraphDb,
   registerSubgraph,
   recordSubgraphProcessed,
   recordLiveProgress,
+  recordLiveError,
   pgSchemaNameFor,
   pgSchemaName,
   listSubgraphs,
@@ -1156,5 +1175,5 @@ export {
   deleteSubgraph
 };
 
-//# debugId=2EF0B7E8B91D856C64756E2164756E21
+//# debugId=3C4CE031C9F5B5D364756E2164756E21
 //# sourceMappingURL=subgraphs.js.map