@secondlayer/shared 7.8.0 → 7.10.0

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

@@ -0,0 +1,92 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/db/queries/instance.ts
+var INSTANCE_NETWORKS = ["mainnet", "testnet", "devnet"];
+
+class InstanceNetworkMismatchError extends Error {
+  existing;
+  requested;
+  name = "InstanceNetworkMismatchError";
+  constructor(existing, requested) {
+    super(`instance network is ${existing}; cannot change to ${requested}`);
+    this.existing = existing;
+    this.requested = requested;
+  }
+}
+
+class InvalidInstanceNetworkError extends Error {
+  value;
+  name = "InvalidInstanceNetworkError";
+  constructor(value) {
+    super(`instance network must be mainnet, testnet, or devnet (got ${value})`);
+    this.value = value;
+  }
+}
+function parseInstanceNetwork(value) {
+  const network = value.trim().toLowerCase();
+  if (INSTANCE_NETWORKS.includes(network)) {
+    return network;
+  }
+  throw new InvalidInstanceNetworkError(value);
+}
+function instanceNetworkFromEnv(env = process.env) {
+  return parseInstanceNetwork(env.STACKS_NETWORK ?? env.NETWORK ?? "mainnet");
+}
+async function getInstance(db) {
+  const row = await db.selectFrom("instances").select(["id", "network", "created_at"]).executeTakeFirst();
+  return row ? toInstance(row) : null;
+}
+async function ensureInstance(db, input) {
+  const existing = await getInstance(db);
+  if (existing) {
+    if (existing.network !== input.network) {
+      throw new InstanceNetworkMismatchError(existing.network, input.network);
+    }
+    return existing;
+  }
+  try {
+    const inserted = await db.insertInto("instances").values({ network: input.network }).returning(["id", "network", "created_at"]).executeTakeFirstOrThrow();
+    return toInstance(inserted);
+  } catch {
+    const raced = await getInstance(db);
+    if (!raced)
+      throw new Error("failed to create instance");
+    if (raced.network !== input.network) {
+      throw new InstanceNetworkMismatchError(raced.network, input.network);
+    }
+    return raced;
+  }
+}
+function toInstance(row) {
+  return {
+    id: row.id,
+    network: parseInstanceNetwork(row.network),
+    created_at: row.created_at
+  };
+}
+export {
+  parseInstanceNetwork,
+  instanceNetworkFromEnv,
+  getInstance,
+  ensureInstance,
+  InvalidInstanceNetworkError,
+  InstanceNetworkMismatchError,
+  INSTANCE_NETWORKS
+};
+
+//# debugId=52C8BB0A1418347D64756E2164756E21
+//# sourceMappingURL=instance.js.map

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

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/db/queries/instance.ts"],
+  "sourcesContent": [
+    "import type { Kysely } from \"kysely\";\nimport type { Database } from \"../types.ts\";\n\nexport const INSTANCE_NETWORKS = [\"mainnet\", \"testnet\", \"devnet\"] as const;\nexport type InstanceNetwork = (typeof INSTANCE_NETWORKS)[number];\n\nexport type InstanceRow = {\n\tid: string;\n\tnetwork: InstanceNetwork;\n\tcreated_at: Date;\n};\n\nexport class InstanceNetworkMismatchError extends Error {\n\treadonly name = \"InstanceNetworkMismatchError\";\n\tconstructor(\n\t\treadonly existing: InstanceNetwork,\n\t\treadonly requested: InstanceNetwork,\n\t) {\n\t\tsuper(`instance network is ${existing}; cannot change to ${requested}`);\n\t}\n}\n\nexport class InvalidInstanceNetworkError extends Error {\n\treadonly name = \"InvalidInstanceNetworkError\";\n\tconstructor(readonly value: string) {\n\t\tsuper(\n\t\t\t`instance network must be mainnet, testnet, or devnet (got ${value})`,\n\t\t);\n\t}\n}\n\nexport function parseInstanceNetwork(value: string): InstanceNetwork {\n\tconst network = value.trim().toLowerCase();\n\tif ((INSTANCE_NETWORKS as readonly string[]).includes(network)) {\n\t\treturn network as InstanceNetwork;\n\t}\n\tthrow new InvalidInstanceNetworkError(value);\n}\n\n/** STACKS_NETWORK, then NETWORK, then mainnet. */\nexport function instanceNetworkFromEnv(\n\tenv: NodeJS.ProcessEnv = process.env,\n): InstanceNetwork {\n\treturn parseInstanceNetwork(env.STACKS_NETWORK ?? env.NETWORK ?? \"mainnet\");\n}\n\nexport async function getInstance(\n\tdb: Kysely<Database>,\n): Promise<InstanceRow | null> {\n\tconst row = await db\n\t\t.selectFrom(\"instances\")\n\t\t.select([\"id\", \"network\", \"created_at\"])\n\t\t.executeTakeFirst();\n\treturn row ? toInstance(row) : null;\n}\n\n/**\n * Return the singleton instance, creating it on first call.\n * A second call with a different network is refused — the network is\n * immutable for the life of the database.\n */\nexport async function ensureInstance(\n\tdb: Kysely<Database>,\n\tinput: { network: InstanceNetwork },\n): Promise<InstanceRow> {\n\tconst existing = await getInstance(db);\n\tif (existing) {\n\t\tif (existing.network !== input.network) {\n\t\t\tthrow new InstanceNetworkMismatchError(existing.network, input.network);\n\t\t}\n\t\treturn existing;\n\t}\n\ttry {\n\t\tconst inserted = await db\n\t\t\t.insertInto(\"instances\")\n\t\t\t.values({ network: input.network })\n\t\t\t.returning([\"id\", \"network\", \"created_at\"])\n\t\t\t.executeTakeFirstOrThrow();\n\t\treturn toInstance(inserted);\n\t} catch {\n\t\t// Lost the singleton race — the other writer won.\n\t\tconst raced = await getInstance(db);\n\t\tif (!raced) throw new Error(\"failed to create instance\");\n\t\tif (raced.network !== input.network) {\n\t\t\tthrow new InstanceNetworkMismatchError(raced.network, input.network);\n\t\t}\n\t\treturn raced;\n\t}\n}\n\nfunction toInstance(row: {\n\tid: string;\n\tnetwork: string;\n\tcreated_at: Date;\n}): InstanceRow {\n\treturn {\n\t\tid: row.id,\n\t\tnetwork: parseInstanceNetwork(row.network),\n\t\tcreated_at: row.created_at,\n\t};\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAGO,IAAM,oBAAoB,CAAC,WAAW,WAAW,QAAQ;AAAA;AASzD,MAAM,qCAAqC,MAAM;AAAA,EAG7C;AAAA,EACA;AAAA,EAHD,OAAO;AAAA,EAChB,WAAW,CACD,UACA,WACR;AAAA,IACD,MAAM,uBAAuB,8BAA8B,WAAW;AAAA,IAH7D;AAAA,IACA;AAAA;AAIX;AAAA;AAEO,MAAM,oCAAoC,MAAM;AAAA,EAEjC;AAAA,EADZ,OAAO;AAAA,EAChB,WAAW,CAAU,OAAe;AAAA,IACnC,MACC,6DAA6D,QAC9D;AAAA,IAHoB;AAAA;AAKtB;AAEO,SAAS,oBAAoB,CAAC,OAAgC;AAAA,EACpE,MAAM,UAAU,MAAM,KAAK,EAAE,YAAY;AAAA,EACzC,IAAK,kBAAwC,SAAS,OAAO,GAAG;AAAA,IAC/D,OAAO;AAAA,EACR;AAAA,EACA,MAAM,IAAI,4BAA4B,KAAK;AAAA;AAIrC,SAAS,sBAAsB,CACrC,MAAyB,QAAQ,KACf;AAAA,EAClB,OAAO,qBAAqB,IAAI,kBAAkB,IAAI,WAAW,SAAS;AAAA;AAG3E,eAAsB,WAAW,CAChC,IAC8B;AAAA,EAC9B,MAAM,MAAM,MAAM,GAChB,WAAW,WAAW,EACtB,OAAO,CAAC,MAAM,WAAW,YAAY,CAAC,EACtC,iBAAiB;AAAA,EACnB,OAAO,MAAM,WAAW,GAAG,IAAI;AAAA;AAQhC,eAAsB,cAAc,CACnC,IACA,OACuB;AAAA,EACvB,MAAM,WAAW,MAAM,YAAY,EAAE;AAAA,EACrC,IAAI,UAAU;AAAA,IACb,IAAI,SAAS,YAAY,MAAM,SAAS;AAAA,MACvC,MAAM,IAAI,6BAA6B,SAAS,SAAS,MAAM,OAAO;AAAA,IACvE;AAAA,IACA,OAAO;AAAA,EACR;AAAA,EACA,IAAI;AAAA,IACH,MAAM,WAAW,MAAM,GACrB,WAAW,WAAW,EACtB,OAAO,EAAE,SAAS,MAAM,QAAQ,CAAC,EACjC,UAAU,CAAC,MAAM,WAAW,YAAY,CAAC,EACzC,wBAAwB;AAAA,IAC1B,OAAO,WAAW,QAAQ;AAAA,IACzB,MAAM;AAAA,IAEP,MAAM,QAAQ,MAAM,YAAY,EAAE;AAAA,IAClC,IAAI,CAAC;AAAA,MAAO,MAAM,IAAI,MAAM,2BAA2B;AAAA,IACvD,IAAI,MAAM,YAAY,MAAM,SAAS;AAAA,MACpC,MAAM,IAAI,6BAA6B,MAAM,SAAS,MAAM,OAAO;AAAA,IACpE;AAAA,IACA,OAAO;AAAA;AAAA;AAIT,SAAS,UAAU,CAAC,KAIJ;AAAA,EACf,OAAO;AAAA,IACN,IAAI,IAAI;AAAA,IACR,SAAS,qBAAqB,IAAI,OAAO;AAAA,IACzC,YAAY,IAAI;AAAA,EACjB;AAAA;",
+  "debugId": "52C8BB0A1418347D64756E2164756E21",
+  "names": []
+}

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

@@ -1,5 +1,23 @@
 import { Kysely } from "kysely";
 import { ColumnType, Generated } from "kysely";
+/**
+* Coverage-kernel constraints. SQL CHECKs in migration 0116 must stay
+* identical — property tests treat this file as the spec.
+*/
+declare const STAGE_KINDS: readonly ["raw", "decode", "subgraph", "queue"];
+type StageKind = (typeof STAGE_KINDS)[number];
+declare const NATIVE_CLOCKS: readonly ["block", "cursor", "queue"];
+type NativeClock = (typeof NATIVE_CLOCKS)[number];
+declare const REPAIR_MODES: readonly ["range_safe", "full_reindex", "archive_replay", "none"];
+type RepairMode = (typeof REPAIR_MODES)[number];
+declare const RUN_STATUSES: readonly ["pending", "running", "complete", "syncing", "lagging", "gap", "stale", "failed", "unverified_import", "unanchored", "source_unavailable", "out_of_scope", "disabled", "halted"];
+type RunStatus = (typeof RUN_STATUSES)[number];
+declare const FAILURE_UNITS: readonly ["block", "range", "cursor", "queue"];
+type FailureUnit = (typeof FAILURE_UNITS)[number];
+declare const FAILURE_CLASSES: readonly ["omission", "version", "digest_mismatch", "crash", "reorg", "source_gap", "handler", "timeout", "unknown"];
+type FailureClass = (typeof FAILURE_CLASSES)[number];
+declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
+type RetryState = (typeof RETRY_STATES)[number];
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -191,6 +209,12 @@ interface ApiKeysTable {
 	revoked_at: Date | null;
 	created_at: Generated<Date>;
 }
+/** Singleton self-host / publisher identity. Network is immutable. */
+interface InstancesTable {
+	id: Generated<string>;
+	network: string;
+	created_at: Generated<Date>;
+}
 interface AccountsTable {
 	id: Generated<string>;
 	/** NULL for unclaimed ghost accounts (anonymous self-serve keys). */
@@ -721,6 +745,72 @@ interface ObserverJournalTable {
 	error: string | null;
 	processed_at: Date | null;
 }
+/** Declared coverage stage. Identity is the `id` string (`raw`, `decode:stx`, …). */
+interface StageRegistryTable {
+	id: string;
+	kind: StageKind;
+	depends_on: string | null;
+	native_clock: NativeClock;
+	producer_version: string;
+	repair_mode: RepairMode;
+	enabled: Generated<boolean>;
+	created_at: Generated<Date>;
+}
+/** One versioned sweep of a stage. */
+interface StageRunsTable {
+	id: Generated<string>;
+	stage_id: string;
+	code_hash: string;
+	config_hash: string;
+	handler_hash: string | null;
+	target_height: number | null;
+	target_cursor: string | null;
+	status: RunStatus;
+	complete_through: number | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
+/** Per-block acknowledgement. Unique on (stage, height, hash). */
+interface StageBlockReceiptsTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	block_height: number;
+	block_hash: string;
+	input_count: number;
+	input_digest: string;
+	effect_digest: string;
+	finalized: Generated<boolean>;
+	compacted_at: Date | null;
+	created_at: Generated<Date>;
+}
+/** Compacted finalized range. Only sealed after receipts in the range finalize. */
+interface CoverageSegmentsTable {
+	id: Generated<string>;
+	stage_id: string;
+	from_height: number;
+	to_height: number;
+	chain_digest: string;
+	input_digest: string;
+	output_digest: string;
+	sealed_at: Generated<Date>;
+}
+/** Exact unit or range that failed, plus retry/retention state. */
+interface StageFailuresTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	unit_kind: FailureUnit;
+	from_height: number | null;
+	to_height: number | null;
+	class: FailureClass;
+	retry_state: RetryState;
+	retry_count: Generated<number>;
+	last_error: string | null;
+	created_at: Generated<Date>;
+	resolved_at: Date | null;
+	retain_until: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -733,6 +823,7 @@ interface Database {
 	contracts: ContractsTable;
 	subgraphs: SubgraphsTable;
 	api_keys: ApiKeysTable;
+	instances: InstancesTable;
 	accounts: AccountsTable;
 	sessions: SessionsTable;
 	magic_links: MagicLinksTable;
@@ -785,6 +876,11 @@ interface Database {
 	chain_read_cache: ChainReadCacheTable;
 	pending_fork_blocks: PendingForkBlocksTable;
 	observer_journal: ObserverJournalTable;
+	stage_registry: StageRegistryTable;
+	stage_runs: StageRunsTable;
+	stage_block_receipts: StageBlockReceiptsTable;
+	coverage_segments: CoverageSegmentsTable;
+	stage_failures: StageFailuresTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {

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

@@ -1,5 +1,23 @@
 import { Kysely } from "kysely";
 import { ColumnType, Generated } from "kysely";
+/**
+* Coverage-kernel constraints. SQL CHECKs in migration 0116 must stay
+* identical — property tests treat this file as the spec.
+*/
+declare const STAGE_KINDS: readonly ["raw", "decode", "subgraph", "queue"];
+type StageKind = (typeof STAGE_KINDS)[number];
+declare const NATIVE_CLOCKS: readonly ["block", "cursor", "queue"];
+type NativeClock = (typeof NATIVE_CLOCKS)[number];
+declare const REPAIR_MODES: readonly ["range_safe", "full_reindex", "archive_replay", "none"];
+type RepairMode = (typeof REPAIR_MODES)[number];
+declare const RUN_STATUSES: readonly ["pending", "running", "complete", "syncing", "lagging", "gap", "stale", "failed", "unverified_import", "unanchored", "source_unavailable", "out_of_scope", "disabled", "halted"];
+type RunStatus = (typeof RUN_STATUSES)[number];
+declare const FAILURE_UNITS: readonly ["block", "range", "cursor", "queue"];
+type FailureUnit = (typeof FAILURE_UNITS)[number];
+declare const FAILURE_CLASSES: readonly ["omission", "version", "digest_mismatch", "crash", "reorg", "source_gap", "handler", "timeout", "unknown"];
+type FailureClass = (typeof FAILURE_CLASSES)[number];
+declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
+type RetryState = (typeof RETRY_STATES)[number];
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -191,6 +209,12 @@ interface ApiKeysTable {
 	revoked_at: Date | null;
 	created_at: Generated<Date>;
 }
+/** Singleton self-host / publisher identity. Network is immutable. */
+interface InstancesTable {
+	id: Generated<string>;
+	network: string;
+	created_at: Generated<Date>;
+}
 interface AccountsTable {
 	id: Generated<string>;
 	/** NULL for unclaimed ghost accounts (anonymous self-serve keys). */
@@ -721,6 +745,72 @@ interface ObserverJournalTable {
 	error: string | null;
 	processed_at: Date | null;
 }
+/** Declared coverage stage. Identity is the `id` string (`raw`, `decode:stx`, …). */
+interface StageRegistryTable {
+	id: string;
+	kind: StageKind;
+	depends_on: string | null;
+	native_clock: NativeClock;
+	producer_version: string;
+	repair_mode: RepairMode;
+	enabled: Generated<boolean>;
+	created_at: Generated<Date>;
+}
+/** One versioned sweep of a stage. */
+interface StageRunsTable {
+	id: Generated<string>;
+	stage_id: string;
+	code_hash: string;
+	config_hash: string;
+	handler_hash: string | null;
+	target_height: number | null;
+	target_cursor: string | null;
+	status: RunStatus;
+	complete_through: number | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
+/** Per-block acknowledgement. Unique on (stage, height, hash). */
+interface StageBlockReceiptsTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	block_height: number;
+	block_hash: string;
+	input_count: number;
+	input_digest: string;
+	effect_digest: string;
+	finalized: Generated<boolean>;
+	compacted_at: Date | null;
+	created_at: Generated<Date>;
+}
+/** Compacted finalized range. Only sealed after receipts in the range finalize. */
+interface CoverageSegmentsTable {
+	id: Generated<string>;
+	stage_id: string;
+	from_height: number;
+	to_height: number;
+	chain_digest: string;
+	input_digest: string;
+	output_digest: string;
+	sealed_at: Generated<Date>;
+}
+/** Exact unit or range that failed, plus retry/retention state. */
+interface StageFailuresTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	unit_kind: FailureUnit;
+	from_height: number | null;
+	to_height: number | null;
+	class: FailureClass;
+	retry_state: RetryState;
+	retry_count: Generated<number>;
+	last_error: string | null;
+	created_at: Generated<Date>;
+	resolved_at: Date | null;
+	retain_until: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -733,6 +823,7 @@ interface Database {
 	contracts: ContractsTable;
 	subgraphs: SubgraphsTable;
 	api_keys: ApiKeysTable;
+	instances: InstancesTable;
 	accounts: AccountsTable;
 	sessions: SessionsTable;
 	magic_links: MagicLinksTable;
@@ -785,6 +876,11 @@ interface Database {
 	chain_read_cache: ChainReadCacheTable;
 	pending_fork_blocks: PendingForkBlocksTable;
 	observer_journal: ObserverJournalTable;
+	stage_registry: StageRegistryTable;
+	stage_runs: StageRunsTable;
+	stage_block_receipts: StageBlockReceiptsTable;
+	coverage_segments: CoverageSegmentsTable;
+	stage_failures: StageFailuresTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {

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

@@ -1,5 +1,23 @@
 import { Kysely } from "kysely";
 import { ColumnType, Generated, Selectable } from "kysely";
+/**
+* Coverage-kernel constraints. SQL CHECKs in migration 0116 must stay
+* identical — property tests treat this file as the spec.
+*/
+declare const STAGE_KINDS: readonly ["raw", "decode", "subgraph", "queue"];
+type StageKind = (typeof STAGE_KINDS)[number];
+declare const NATIVE_CLOCKS: readonly ["block", "cursor", "queue"];
+type NativeClock = (typeof NATIVE_CLOCKS)[number];
+declare const REPAIR_MODES: readonly ["range_safe", "full_reindex", "archive_replay", "none"];
+type RepairMode = (typeof REPAIR_MODES)[number];
+declare const RUN_STATUSES: readonly ["pending", "running", "complete", "syncing", "lagging", "gap", "stale", "failed", "unverified_import", "unanchored", "source_unavailable", "out_of_scope", "disabled", "halted"];
+type RunStatus = (typeof RUN_STATUSES)[number];
+declare const FAILURE_UNITS: readonly ["block", "range", "cursor", "queue"];
+type FailureUnit = (typeof FAILURE_UNITS)[number];
+declare const FAILURE_CLASSES: readonly ["omission", "version", "digest_mismatch", "crash", "reorg", "source_gap", "handler", "timeout", "unknown"];
+type FailureClass = (typeof FAILURE_CLASSES)[number];
+declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
+type RetryState = (typeof RETRY_STATES)[number];
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -191,6 +209,12 @@ interface ApiKeysTable {
 	revoked_at: Date | null;
 	created_at: Generated<Date>;
 }
+/** Singleton self-host / publisher identity. Network is immutable. */
+interface InstancesTable {
+	id: Generated<string>;
+	network: string;
+	created_at: Generated<Date>;
+}
 interface AccountsTable {
 	id: Generated<string>;
 	/** NULL for unclaimed ghost accounts (anonymous self-serve keys). */
@@ -721,6 +745,72 @@ interface ObserverJournalTable {
 	error: string | null;
 	processed_at: Date | null;
 }
+/** Declared coverage stage. Identity is the `id` string (`raw`, `decode:stx`, …). */
+interface StageRegistryTable {
+	id: string;
+	kind: StageKind;
+	depends_on: string | null;
+	native_clock: NativeClock;
+	producer_version: string;
+	repair_mode: RepairMode;
+	enabled: Generated<boolean>;
+	created_at: Generated<Date>;
+}
+/** One versioned sweep of a stage. */
+interface StageRunsTable {
+	id: Generated<string>;
+	stage_id: string;
+	code_hash: string;
+	config_hash: string;
+	handler_hash: string | null;
+	target_height: number | null;
+	target_cursor: string | null;
+	status: RunStatus;
+	complete_through: number | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
+/** Per-block acknowledgement. Unique on (stage, height, hash). */
+interface StageBlockReceiptsTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	block_height: number;
+	block_hash: string;
+	input_count: number;
+	input_digest: string;
+	effect_digest: string;
+	finalized: Generated<boolean>;
+	compacted_at: Date | null;
+	created_at: Generated<Date>;
+}
+/** Compacted finalized range. Only sealed after receipts in the range finalize. */
+interface CoverageSegmentsTable {
+	id: Generated<string>;
+	stage_id: string;
+	from_height: number;
+	to_height: number;
+	chain_digest: string;
+	input_digest: string;
+	output_digest: string;
+	sealed_at: Generated<Date>;
+}
+/** Exact unit or range that failed, plus retry/retention state. */
+interface StageFailuresTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	unit_kind: FailureUnit;
+	from_height: number | null;
+	to_height: number | null;
+	class: FailureClass;
+	retry_state: RetryState;
+	retry_count: Generated<number>;
+	last_error: string | null;
+	created_at: Generated<Date>;
+	resolved_at: Date | null;
+	retain_until: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -733,6 +823,7 @@ interface Database {
 	contracts: ContractsTable;
 	subgraphs: SubgraphsTable;
 	api_keys: ApiKeysTable;
+	instances: InstancesTable;
 	accounts: AccountsTable;
 	sessions: SessionsTable;
 	magic_links: MagicLinksTable;
@@ -785,6 +876,11 @@ interface Database {
 	chain_read_cache: ChainReadCacheTable;
 	pending_fork_blocks: PendingForkBlocksTable;
 	observer_journal: ObserverJournalTable;
+	stage_registry: StageRegistryTable;
+	stage_runs: StageRunsTable;
+	stage_block_receipts: StageBlockReceiptsTable;
+	coverage_segments: CoverageSegmentsTable;
+	stage_failures: StageFailuresTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {

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

@@ -1,6 +1,24 @@
 import { Kysely } from "kysely";
 import postgres from "postgres";
 import { ColumnType, Generated, Selectable } from "kysely";
+/**
+* Coverage-kernel constraints. SQL CHECKs in migration 0116 must stay
+* identical — property tests treat this file as the spec.
+*/
+declare const STAGE_KINDS: readonly ["raw", "decode", "subgraph", "queue"];
+type StageKind = (typeof STAGE_KINDS)[number];
+declare const NATIVE_CLOCKS: readonly ["block", "cursor", "queue"];
+type NativeClock = (typeof NATIVE_CLOCKS)[number];
+declare const REPAIR_MODES: readonly ["range_safe", "full_reindex", "archive_replay", "none"];
+type RepairMode = (typeof REPAIR_MODES)[number];
+declare const RUN_STATUSES: readonly ["pending", "running", "complete", "syncing", "lagging", "gap", "stale", "failed", "unverified_import", "unanchored", "source_unavailable", "out_of_scope", "disabled", "halted"];
+type RunStatus = (typeof RUN_STATUSES)[number];
+declare const FAILURE_UNITS: readonly ["block", "range", "cursor", "queue"];
+type FailureUnit = (typeof FAILURE_UNITS)[number];
+declare const FAILURE_CLASSES: readonly ["omission", "version", "digest_mismatch", "crash", "reorg", "source_gap", "handler", "timeout", "unknown"];
+type FailureClass = (typeof FAILURE_CLASSES)[number];
+declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
+type RetryState = (typeof RETRY_STATES)[number];
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -192,6 +210,12 @@ interface ApiKeysTable {
 	revoked_at: Date | null;
 	created_at: Generated<Date>;
 }
+/** Singleton self-host / publisher identity. Network is immutable. */
+interface InstancesTable {
+	id: Generated<string>;
+	network: string;
+	created_at: Generated<Date>;
+}
 interface AccountsTable {
 	id: Generated<string>;
 	/** NULL for unclaimed ghost accounts (anonymous self-serve keys). */
@@ -722,6 +746,72 @@ interface ObserverJournalTable {
 	error: string | null;
 	processed_at: Date | null;
 }
+/** Declared coverage stage. Identity is the `id` string (`raw`, `decode:stx`, …). */
+interface StageRegistryTable {
+	id: string;
+	kind: StageKind;
+	depends_on: string | null;
+	native_clock: NativeClock;
+	producer_version: string;
+	repair_mode: RepairMode;
+	enabled: Generated<boolean>;
+	created_at: Generated<Date>;
+}
+/** One versioned sweep of a stage. */
+interface StageRunsTable {
+	id: Generated<string>;
+	stage_id: string;
+	code_hash: string;
+	config_hash: string;
+	handler_hash: string | null;
+	target_height: number | null;
+	target_cursor: string | null;
+	status: RunStatus;
+	complete_through: number | null;
+	started_at: Generated<Date>;
+	finished_at: Date | null;
+}
+/** Per-block acknowledgement. Unique on (stage, height, hash). */
+interface StageBlockReceiptsTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	block_height: number;
+	block_hash: string;
+	input_count: number;
+	input_digest: string;
+	effect_digest: string;
+	finalized: Generated<boolean>;
+	compacted_at: Date | null;
+	created_at: Generated<Date>;
+}
+/** Compacted finalized range. Only sealed after receipts in the range finalize. */
+interface CoverageSegmentsTable {
+	id: Generated<string>;
+	stage_id: string;
+	from_height: number;
+	to_height: number;
+	chain_digest: string;
+	input_digest: string;
+	output_digest: string;
+	sealed_at: Generated<Date>;
+}
+/** Exact unit or range that failed, plus retry/retention state. */
+interface StageFailuresTable {
+	id: Generated<string>;
+	stage_id: string;
+	run_id: string | null;
+	unit_kind: FailureUnit;
+	from_height: number | null;
+	to_height: number | null;
+	class: FailureClass;
+	retry_state: RetryState;
+	retry_count: Generated<number>;
+	last_error: string | null;
+	created_at: Generated<Date>;
+	resolved_at: Date | null;
+	retain_until: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -734,6 +824,7 @@ interface Database {
 	contracts: ContractsTable;
 	subgraphs: SubgraphsTable;
 	api_keys: ApiKeysTable;
+	instances: InstancesTable;
 	accounts: AccountsTable;
 	sessions: SessionsTable;
 	magic_links: MagicLinksTable;
@@ -786,6 +877,11 @@ interface Database {
 	chain_read_cache: ChainReadCacheTable;
 	pending_fork_blocks: PendingForkBlocksTable;
 	observer_journal: ObserverJournalTable;
+	stage_registry: StageRegistryTable;
+	stage_runs: StageRunsTable;
+	stage_block_receipts: StageBlockReceiptsTable;
+	coverage_segments: CoverageSegmentsTable;
+	stage_failures: StageFailuresTable;
 }
 /** Prepaid x402 credit — one running USD-micros balance per payer principal. */
 interface X402BalancesTable {
@@ -1025,6 +1121,8 @@ declare function resolveSubgraphRawClient(subgraph: Subgraph): ReturnType<typeof
 * Platform-mode deploys use `pgSchemaNameFor(accountId, name)`.
 */
 declare function pgSchemaName(subgraphName: string): string;
+/** OSS writes empty account_id — name is the local unique key. */
+declare function localSubgraphAccountId(accountId?: string): string;
 /**
 * Account-scoped schema name. Matches migration 0028's rename pattern:
 *   subgraph_{first8charsOfAccountId, dashes-as-underscores}_{name}
@@ -1131,4 +1229,4 @@ declare function recordLiveProgress(db: Kysely<Database>, name: string, lastProc
 *  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 };
+export { updateSubgraphVisibility, updateSubgraphStatus, updateSubgraphHandlerPath, updateSubgraphExpiry, subgraphDatabaseUrl, rewindLiveProgress, resolveSubgraphRawClient, resolveSubgraphDb, registerSubgraph, recordSubgraphProcessed, recordLiveProgress, recordLiveError, pgSchemaNameFor, pgSchemaName, localSubgraphAccountId, listSubgraphs, isByoSubgraph, getSubgraph, findPublicSubgraphByName, encryptDatabaseUrl, deleteSubgraph };