@secondlayer/sdk 6.47.0 → 6.48.1

package/dist/sinks/kysely.js

@@ -1,6 +1,3 @@
-// src/sinks/kysely.ts
-import { sql } from "kysely";
-
 // src/errors.ts
 var DOCS_BASE = "https://www.secondlayer.tools";
 
@@ -158,79 +155,119 @@ function isByoBreakingDetails(x) {
   return Array.isArray(d.reasons) && !!plan && typeof plan === "object" && typeof plan.dropStatement === "string";
 }
 
-// src/sinks/kysely.ts
-function kyselySink(db, options) {
-  const checkpointTable = options.checkpointTable ?? "sl_consumer_checkpoints";
+// src/sinks/core.ts
+var DEFAULT_CHECKPOINT_TABLE = "sl_consumer_checkpoints";
+function assertSqlIdentifier(name, label) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new ValidationError(`${label}: invalid identifier "${name}" (letters, digits, underscores only).`, 400);
+  }
+}
+function quoteIdent(name) {
+  return `"${name}"`;
+}
+function createSink(driver, options) {
+  const { label } = options;
+  const checkpointTable = options.checkpointTable ?? DEFAULT_CHECKPOINT_TABLE;
   if (options.tables.length === 0) {
-    throw new ValidationError("kyselySink: `tables` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.", 400);
+    throw new ValidationError(`${label}: \`tables\` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.`, 400);
   }
-  const ident = (name) => {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-      throw new ValidationError(`kyselySink: invalid identifier "${name}" (letters, digits, underscores only).`, 400);
-    }
-    return `"${name}"`;
-  };
-  const cp = ident(checkpointTable);
-  const heightCol = ident(options.height);
+  assertSqlIdentifier(checkpointTable, label);
+  assertSqlIdentifier(options.height, label);
   for (const table of options.tables)
-    ident(table);
-  async function acquireLock(tx) {
-    const locked = await sql`
-			SELECT pg_try_advisory_xact_lock(hashtext(${options.id})) AS "ok"
-		`.execute(tx);
-    if (!locked.rows[0]?.ok) {
-      throw new ValidationError(`kyselySink: another consumer holds the "${options.id}" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`, 409);
-    }
-  }
-  async function upsertCursor(tx, cursor) {
-    await sql`
-			INSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})
-			ON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor
-		`.execute(tx);
-  }
+    assertSqlIdentifier(table, label);
   return {
+    capabilities: options.capabilities,
     async loadCursor() {
-      await sql.raw(`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`).execute(db);
+      await driver.ensureCheckpointStore();
       for (const table of options.tables) {
-        const col = await sql`
-					SELECT EXISTS (
-						SELECT 1 FROM information_schema.columns
-						WHERE table_name = ${table} AND column_name = ${options.height}
-					) AS "ok"
-				`.execute(db);
-        if (!col.rows[0]?.ok) {
-          throw new ValidationError(`kyselySink: table "${table}" has no "${String(options.height)}" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \`height\`).`, 400);
+        if (!await driver.hasColumn(table, options.height)) {
+          throw new ValidationError(`${label}: table "${table}" has no "${options.height}" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \`height\`).`, 400);
         }
       }
-      const row = await sql`
-				SELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}
-			`.execute(db);
-      return row.rows[0]?.cursor ?? null;
+      return driver.readCursor();
     },
     async commitBatch(cursor, write) {
-      await db.transaction().execute(async (tx) => {
-        await acquireLock(tx);
+      await driver.transact(async (tx) => {
+        await driver.acquireLock?.(tx);
         await write(tx);
-        await upsertCursor(tx, cursor);
+        await driver.writeCursor(tx, cursor);
       });
     },
     async rollback(forkPointHeight, rewindCursor) {
-      await db.transaction().execute(async (tx) => {
-        await acquireLock(tx);
+      await driver.transact(async (tx) => {
+        await driver.acquireLock?.(tx);
         for (const table of options.tables) {
-          await sql`
-						DELETE FROM ${sql.raw(ident(table))}
-						WHERE ${sql.raw(heightCol)} >= ${forkPointHeight}
-					`.execute(tx);
+          await driver.deleteAtOrAbove(tx, table, forkPointHeight);
         }
-        await upsertCursor(tx, rewindCursor);
+        await driver.writeCursor(tx, rewindCursor);
       });
     }
   };
 }
+
+// src/sinks/kysely.ts
+import { sql } from "kysely";
+function kyselySink(db, options) {
+  const checkpointTable = options.checkpointTable ?? DEFAULT_CHECKPOINT_TABLE;
+  const cp = quoteIdent(checkpointTable);
+  const driver = {
+    transact: (fn) => db.transaction().execute(fn),
+    async ensureCheckpointStore() {
+      try {
+        await sql.raw(`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`).execute(db);
+      } catch (err) {
+        const code = err?.code;
+        if (code !== "42P07" && code !== "23505")
+          throw err;
+      }
+    },
+    async readCursor() {
+      const row = await sql`
+				SELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}
+			`.execute(db);
+      return row.rows[0]?.cursor ?? null;
+    },
+    async writeCursor(tx, cursor) {
+      await sql`
+				INSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})
+				ON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor
+			`.execute(tx);
+    },
+    async deleteAtOrAbove(tx, table, height) {
+      await sql`
+				DELETE FROM ${sql.raw(quoteIdent(table))}
+				WHERE ${sql.raw(quoteIdent(options.height))} >= ${height}
+			`.execute(tx);
+    },
+    async hasColumn(table, column) {
+      const col = await sql`
+				SELECT EXISTS (
+					SELECT 1 FROM information_schema.columns
+					WHERE table_name = ${table} AND column_name = ${column}
+				) AS "ok"
+			`.execute(db);
+      return col.rows[0]?.ok ?? false;
+    },
+    async acquireLock(tx) {
+      const locked = await sql`
+				SELECT pg_try_advisory_xact_lock(hashtextextended(${options.id}, 0)) AS "ok"
+			`.execute(tx);
+      if (!locked.rows[0]?.ok) {
+        throw new ValidationError(`kyselySink: another consumer holds the "${options.id}" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`, 409);
+      }
+    }
+  };
+  return createSink(driver, {
+    label: "kyselySink",
+    id: options.id,
+    tables: options.tables,
+    height: options.height,
+    checkpointTable
+  });
+}
 export {
   kyselySink
 };
 
-//# debugId=667BFBBF3BF09CCB64756E2164756E21
+//# debugId=475014242F550C1264756E2164756E21
 //# sourceMappingURL=kysely.js.map

package/dist/sinks/kysely.js.map

@@ -1,11 +1,12 @@
 {
   "version": 3,
-  "sources": ["../src/sinks/kysely.ts", "../src/errors.ts"],
+  "sources": ["src/errors.ts", "src/sinks/core.ts", "src/sinks/kysely.ts"],
   "sourcesContent": [
-    "import { type Kysely, type Transaction, sql } from \"kysely\";\nimport { ValidationError } from \"../errors.ts\";\nimport type { ConsumerSink } from \"./types.ts\";\n\n/**\n * Column present on EVERY declared table — `keyof` a union of row types is\n * the intersection of their keys, so a column missing from any one table is\n * a compile error at the `height:` option.\n */\ntype CommonColumn<DB, T extends keyof DB> = keyof DB[T] & string;\n\nexport interface KyselySinkOptions<DB, T extends keyof DB & string> {\n\t/** Checkpoint identity AND concurrency key: the cursor row's primary key,\n\t *  and the input to `pg_try_advisory_xact_lock(hashtext(id))` — a second\n\t *  consumer with the same id fails loudly instead of double-writing. */\n\tid: string;\n\t/** Rollback scope. On a reorg, rows AT OR ABOVE the fork point are deleted\n\t *  from exactly these tables (inclusive `>=` — the new chain re-supplies\n\t *  the fork block). A table you write but don't declare keeps orphaned\n\t *  rows forever, so declare everything the handler touches. */\n\ttables: readonly T[];\n\t/** The block-height stamp column, present on every declared table (compile\n\t *  and first-use checked). Height-stamp rollback is correct for\n\t *  APPEND-ONLY projections (one row per event/call); aggregates that\n\t *  mutate rows (balances, counters) can't be rolled back this way — use a\n\t *  subgraph for those. */\n\theight: CommonColumn<DB, T>;\n\t/** Checkpoint table name. Default `sl_consumer_checkpoints` (created on\n\t *  first use). */\n\tcheckpointTable?: string;\n}\n\n/**\n * A {@link ConsumerSink} over a Kysely Postgres database — keyed on the\n * QUERY BUILDER (not the driver) so the `DB` schema generic flows through:\n * `tables` is `(keyof DB)[]`, `height` must exist on every declared table,\n * and `ctx.tx` inside `onBatch` is a fully typed `Transaction<DB>`.\n *\n * What it owns (so your indexer doesn't):\n * - the checkpoint table + cursor load on start;\n * - rows AND cursor committed in ONE transaction per batch — a handler\n *   throw aborts both, so a crashed batch is re-read on restart with no\n *   gaps and no double-writes;\n * - reorg rollback: delete `>= fork_point_height` from every declared table\n *   and commit the rewound cursor atomically (the crash-between-the-two-\n *   writes gap is unrepresentable);\n * - a per-id advisory lock, so two replicas of the same consumer can't\n *   interleave commits.\n *\n * ```ts\n * const sink = kyselySink(db, { id: \"sales\", tables: [\"sales\"], height: \"block_height\" });\n * await index.contractCalls.consume({\n *   contractId: MARKETPLACE, functionName: \"purchase-asset\", fromHeight: 0,\n *   sink,\n *   onBatch: (calls, _env, ctx) =>\n *     ctx.tx.insertInto(\"sales\").values(calls.map(toSale)).execute(),\n * });\n * ```\n */\nexport function kyselySink<DB, T extends keyof DB & string>(\n\tdb: Kysely<DB>,\n\toptions: KyselySinkOptions<DB, T>,\n): ConsumerSink<Transaction<DB>> {\n\tconst checkpointTable = options.checkpointTable ?? \"sl_consumer_checkpoints\";\n\tif (options.tables.length === 0) {\n\t\tthrow new ValidationError(\n\t\t\t\"kyselySink: `tables` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.\",\n\t\t\t400,\n\t\t);\n\t}\n\n\t/** `sql.raw`-safe identifier (we interpolate table/column names). */\n\tconst ident = (name: string): string => {\n\t\tif (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t`kyselySink: invalid identifier \"${name}\" (letters, digits, underscores only).`,\n\t\t\t\t400,\n\t\t\t);\n\t\t}\n\t\treturn `\"${name}\"`;\n\t};\n\tconst cp = ident(checkpointTable);\n\tconst heightCol = ident(options.height as string);\n\tfor (const table of options.tables) ident(table);\n\n\tasync function acquireLock(tx: Transaction<DB>): Promise<void> {\n\t\tconst locked = await sql<{ ok: boolean }>`\n\t\t\tSELECT pg_try_advisory_xact_lock(hashtext(${options.id})) AS \"ok\"\n\t\t`.execute(tx);\n\t\tif (!locked.rows[0]?.ok) {\n\t\t\tthrow new ValidationError(\n\t\t\t\t`kyselySink: another consumer holds the \"${options.id}\" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`,\n\t\t\t\t409,\n\t\t\t);\n\t\t}\n\t}\n\n\tasync function upsertCursor(\n\t\ttx: Transaction<DB>,\n\t\tcursor: string,\n\t): Promise<void> {\n\t\t// Identifiers via validated sql.raw; VALUES via bound parameters.\n\t\tawait sql`\n\t\t\tINSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})\n\t\t\tON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor\n\t\t`.execute(tx);\n\t}\n\n\treturn {\n\t\tasync loadCursor() {\n\t\t\tawait sql\n\t\t\t\t.raw(\n\t\t\t\t\t`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`,\n\t\t\t\t)\n\t\t\t\t.execute(db);\n\t\t\t// First-use validation of the rollback precondition: every declared\n\t\t\t// table must exist and carry the height column. Failing here beats a\n\t\t\t// rollback that silently deletes nothing during a reorg.\n\t\t\tfor (const table of options.tables) {\n\t\t\t\tconst col = await sql<{ ok: boolean }>`\n\t\t\t\t\tSELECT EXISTS (\n\t\t\t\t\t\tSELECT 1 FROM information_schema.columns\n\t\t\t\t\t\tWHERE table_name = ${table} AND column_name = ${options.height as string}\n\t\t\t\t\t) AS \"ok\"\n\t\t\t\t`.execute(db);\n\t\t\t\tif (!col.rows[0]?.ok) {\n\t\t\t\t\tthrow new ValidationError(\n\t\t\t\t\t\t`kyselySink: table \"${table}\" has no \"${String(options.height)}\" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \\`height\\`).`,\n\t\t\t\t\t\t400,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst row = await sql<{ cursor: string }>`\n\t\t\t\tSELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}\n\t\t\t`.execute(db);\n\t\t\treturn row.rows[0]?.cursor ?? null;\n\t\t},\n\n\t\tasync commitBatch(cursor, write) {\n\t\t\tawait db.transaction().execute(async (tx) => {\n\t\t\t\tawait acquireLock(tx);\n\t\t\t\tawait write(tx);\n\t\t\t\tawait upsertCursor(tx, cursor);\n\t\t\t});\n\t\t},\n\n\t\tasync rollback(forkPointHeight, rewindCursor) {\n\t\t\tawait db.transaction().execute(async (tx) => {\n\t\t\t\tawait acquireLock(tx);\n\t\t\t\t// INCLUSIVE of the fork block: the new canonical chain re-supplies\n\t\t\t\t// it, and the consumer rewinds to re-read from `fork:0`.\n\t\t\t\tfor (const table of options.tables) {\n\t\t\t\t\t// Identifiers via validated sql.raw; the height bound as a parameter.\n\t\t\t\t\tawait sql`\n\t\t\t\t\t\tDELETE FROM ${sql.raw(ident(table))}\n\t\t\t\t\t\tWHERE ${sql.raw(heightCol)} >= ${forkPointHeight}\n\t\t\t\t\t`.execute(tx);\n\t\t\t\t}\n\t\t\t\tawait upsertCursor(tx, rewindCursor);\n\t\t\t});\n\t\t},\n\t};\n}\n",
-    "import type { ByoBreakingChangeDetails } from \"@secondlayer/shared/errors\";\n\nexport type { ByoBreakingChangeDetails };\n\nconst DOCS_BASE = \"https://www.secondlayer.tools\";\n\n/** Options accepted by every error in the family. */\nexport interface SecondLayerErrorOptions {\n\tcause?: Error;\n\tdetails?: string;\n\t/** Stable machine-readable code (e.g. `UPGRADE_REQUIRED`, `BYO_BREAKING_CHANGE`). */\n\tcode?: string;\n\t/** Docs page that explains this failure and its fix. */\n\tdocsUrl?: string;\n\t/** Extra context lines appended to the message (DDL to run, next steps). */\n\tmetaMessages?: string[];\n\t/** Whether retrying the SAME request can succeed (429/5xx/network). */\n\tretryable?: boolean;\n\t/** Parsed `Retry-After`, in seconds — set on rate limits that carry it. */\n\tretryAfterSeconds?: number;\n}\n\n/**\n * Root of the SDK error family. Implements the same protocol as `BaseError`\n * in `@secondlayer/stacks` (`shortMessage`, `cause`, `toJSON`) so a failed\n * chain read and a failed platform read serialize and introspect identically.\n * It intentionally does NOT extend that class: `BaseError.details` is a\n * `string`, while {@link ByoBreakingChangeError.details} is the documented\n * structured migration plan — and cross-package `instanceof` is unreliable\n * under per-package bundling anyway (match on `code`/`name` across packages).\n *\n * `retryable` is the signal the consume loops act on: 429/5xx/network are\n * retryable, 4xx and body-serialization failures are not.\n */\nexport class SecondLayerError extends Error {\n\toverride name = \"SecondLayerError\";\n\t/** The one-line failure, without the appended context blocks. */\n\tshortMessage: string;\n\tcode?: string;\n\tdocsUrl?: string;\n\tmetaMessages?: string[];\n\tretryable: boolean;\n\tretryAfterSeconds?: number;\n\n\tconstructor(shortMessage: string, options: SecondLayerErrorOptions = {}) {\n\t\tconst detailBlocks = [\n\t\t\t...(options.metaMessages ?? []),\n\t\t\t...(options.details ? [options.details] : []),\n\t\t\t...(options.docsUrl ? [`Docs: ${options.docsUrl}`] : []),\n\t\t];\n\t\tconst message = [\n\t\t\tshortMessage,\n\t\t\tdetailBlocks.length > 0 ? `\\n${detailBlocks.join(\"\\n\")}` : \"\",\n\t\t].join(\"\");\n\t\tsuper(message, options.cause ? { cause: options.cause } : undefined);\n\t\tthis.shortMessage = shortMessage;\n\t\tthis.code = options.code;\n\t\tthis.docsUrl = options.docsUrl;\n\t\tthis.metaMessages = options.metaMessages;\n\t\tthis.retryable = options.retryable ?? false;\n\t\tthis.retryAfterSeconds = options.retryAfterSeconds;\n\t}\n\n\t/**\n\t * Walk the cause chain. With a predicate, returns the first error matching\n\t * it (or `null`); without one, returns the deepest cause. Mirrors viem's\n\t * `error.walk()` so cross-library error handling reads the same.\n\t */\n\twalk(fn?: (err: unknown) => boolean): unknown {\n\t\t// biome-ignore lint/suspicious/noExplicitAny: cause chains are untyped by nature\n\t\tlet err: any = this;\n\t\tlet last: unknown = this;\n\t\twhile (err != null) {\n\t\t\tif (fn?.(err)) return err;\n\t\t\tlast = err;\n\t\t\terr = err.cause;\n\t\t}\n\t\treturn fn ? null : last;\n\t}\n\n\ttoJSON(): {\n\t\tname: string;\n\t\tmessage: string;\n\t\tshortMessage: string;\n\t\tcause: string | undefined;\n\t\tcode: string | undefined;\n\t\tdocsUrl: string | undefined;\n\t\tretryable: boolean;\n\t\tretryAfterSeconds: number | undefined;\n\t} {\n\t\treturn {\n\t\t\tname: this.name,\n\t\t\tmessage: this.message,\n\t\t\tshortMessage: this.shortMessage,\n\t\t\tcause: this.cause instanceof Error ? this.cause.message : undefined,\n\t\t\tcode: this.code,\n\t\t\tdocsUrl: this.docsUrl,\n\t\t\tretryable: this.retryable,\n\t\t\tretryAfterSeconds: this.retryAfterSeconds,\n\t\t};\n\t}\n}\n\n/** Retryability of an HTTP status: 429 and 5xx are transient. */\nfunction statusRetryable(status: number): boolean {\n\treturn status === 429 || status >= 500;\n}\n\n/** Docs page for a status/code pair, when one exists. */\nfunction docsFor(status: number, code?: string): string | undefined {\n\tif (code === \"UPGRADE_REQUIRED\" || code === \"PLAN_REQUIRED\" || status === 402)\n\t\treturn `${DOCS_BASE}/docs/authentication#pay-as-you-go-credits`;\n\tif (status === 429 || status === 401)\n\t\treturn `${DOCS_BASE}/docs/authentication`;\n\treturn undefined;\n}\n\n/**\n * Error thrown by {@link SecondLayer} when an API request fails.\n * Includes the HTTP status code for programmatic error handling.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.get(\"my-subgraph\");\n * } catch (err) {\n *   if (err instanceof ApiError && err.status === 404) {\n *     console.log(\"Subgraph not found\");\n *   }\n * }\n * ```\n */\nexport class ApiError extends SecondLayerError {\n\tconstructor(\n\t\t/** HTTP status code (0 for network errors). */\n\t\tpublic status: number,\n\t\tmessage: string,\n\t\t/** Raw response body (parsed JSON if possible) — preserved for callers that need error details. */\n\t\tpublic body?: unknown,\n\t\t/** Stable machine-readable code from the API's `{error, code}` error envelope. */\n\t\tcode?: string,\n\t\toptions: SecondLayerErrorOptions = {},\n\t) {\n\t\tsuper(message, {\n\t\t\tcode,\n\t\t\tretryable: options.retryable ?? statusRetryable(status),\n\t\t\tdocsUrl: options.docsUrl ?? docsFor(status, code),\n\t\t\t...(options.cause ? { cause: options.cause } : {}),\n\t\t\t...(options.details ? { details: options.details } : {}),\n\t\t\t...(options.metaMessages ? { metaMessages: options.metaMessages } : {}),\n\t\t\t...(options.retryAfterSeconds !== undefined\n\t\t\t\t? { retryAfterSeconds: options.retryAfterSeconds }\n\t\t\t\t: {}),\n\t\t});\n\t\tthis.name = \"ApiError\";\n\t}\n}\n\n/** Thrown on a 401 — by both the platform clients and Streams. */\nexport class AuthError extends ApiError {\n\toverride readonly status = 401 as const;\n\n\tconstructor(message = \"API key invalid or expired.\") {\n\t\tsuper(401, message);\n\t\tthis.name = \"AuthError\";\n\t}\n}\n\n/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,\n *  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */\nexport class RateLimitError extends ApiError {\n\toverride readonly status = 429 as const;\n\n\tconstructor(\n\t\tmessage = \"Rate limited. Try again later.\",\n\t\t/** Raw `Retry-After` header value (seconds or HTTP-date). */\n\t\treadonly retryAfter?: string,\n\t) {\n\t\tsuper(429, message, undefined, undefined, {\n\t\t\tretryable: true,\n\t\t\tretryAfterSeconds: parseRetryAfter(retryAfter),\n\t\t});\n\t\tthis.name = \"RateLimitError\";\n\t}\n}\n\n/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */\nexport class ValidationError extends ApiError {\n\tconstructor(message: string, status: number, body?: unknown) {\n\t\tsuper(status, message, body, undefined, { retryable: false });\n\t\tthis.name = \"ValidationError\";\n\t}\n}\n\n/** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */\nexport function parseRetryAfter(value?: string | null): number | undefined {\n\tif (!value) return undefined;\n\tconst seconds = Number(value);\n\tif (Number.isFinite(seconds) && seconds >= 0) return seconds;\n\tconst date = Date.parse(value);\n\tif (!Number.isNaN(date)) return Math.max(0, (date - Date.now()) / 1000);\n\treturn undefined;\n}\n\n/**\n * Thrown on optimistic-concurrency conflict when a deploy supplies an\n * `expectedVersion` that no longer matches the server's stored version.\n */\nexport class VersionConflictError extends ApiError {\n\tconstructor(\n\t\tpublic currentVersion: string,\n\t\tpublic expectedVersion: string,\n\t\tmessage = `Version conflict: expected ${expectedVersion}, current ${currentVersion}`,\n\t) {\n\t\tsuper(409, message, { currentVersion, expectedVersion });\n\t\tthis.name = \"VersionConflictError\";\n\t}\n}\n\n/**\n * Thrown when a BYO subgraph deploy is refused for a breaking schema change.\n * The deploy did NOT run — `details.plan` carries the DROP + rebuild DDL to run\n * manually on your own database, plus the breaking `reasons` and the `diff`.\n * The same DDL is surfaced on `metaMessages`, so a bare `console.error(err)`\n * already shows the operator what to run.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.deploy(bundle);\n * } catch (err) {\n *   if (err instanceof ByoBreakingChangeError) {\n *     console.log(err.details.plan.dropStatement);\n *     console.log(err.details.plan.statements.join(\";\\n\"));\n *   }\n * }\n * ```\n */\nexport class ByoBreakingChangeError extends ApiError {\n\treadonly details: ByoBreakingChangeDetails;\n\tconstructor(message: string, details: ByoBreakingChangeDetails) {\n\t\tsuper(422, message, details, \"BYO_BREAKING_CHANGE\", {\n\t\t\tmetaMessages: [\n\t\t\t\t\"Review and run manually on your database:\",\n\t\t\t\tdetails.plan.dropStatement,\n\t\t\t\t...details.plan.statements,\n\t\t\t],\n\t\t});\n\t\tthis.name = \"ByoBreakingChangeError\";\n\t\tthis.details = details;\n\t}\n}\n\n/** Narrow an unknown error body's `details` to {@link ByoBreakingChangeDetails}. */\nexport function isByoBreakingDetails(\n\tx: unknown,\n): x is ByoBreakingChangeDetails {\n\tif (!x || typeof x !== \"object\") return false;\n\tconst d = x as Record<string, unknown>;\n\tconst plan = d.plan as Record<string, unknown> | undefined;\n\treturn (\n\t\tArray.isArray(d.reasons) &&\n\t\t!!plan &&\n\t\ttypeof plan === \"object\" &&\n\t\ttypeof plan.dropStatement === \"string\"\n\t);\n}\n"
+    "import type { ByoBreakingChangeDetails } from \"@secondlayer/shared/errors\";\n\nexport type { ByoBreakingChangeDetails };\n\nconst DOCS_BASE = \"https://www.secondlayer.tools\";\n\n/** Options accepted by every error in the family. */\nexport interface SecondLayerErrorOptions {\n\tcause?: Error;\n\tdetails?: string;\n\t/** Stable machine-readable code (e.g. `UPGRADE_REQUIRED`, `BYO_BREAKING_CHANGE`). */\n\tcode?: string;\n\t/** Docs page that explains this failure and its fix. */\n\tdocsUrl?: string;\n\t/** Extra context lines appended to the message (DDL to run, next steps). */\n\tmetaMessages?: string[];\n\t/** Whether retrying the SAME request can succeed (429/5xx/network). */\n\tretryable?: boolean;\n\t/** Parsed `Retry-After`, in seconds — set on rate limits that carry it. */\n\tretryAfterSeconds?: number;\n}\n\n/**\n * Root of the SDK error family. Implements the same protocol as `BaseError`\n * in `@secondlayer/stacks` (`shortMessage`, `cause`, `toJSON`) so a failed\n * chain read and a failed platform read serialize and introspect identically.\n * It intentionally does NOT extend that class: `BaseError.details` is a\n * `string`, while {@link ByoBreakingChangeError.details} is the documented\n * structured migration plan — and cross-package `instanceof` is unreliable\n * under per-package bundling anyway (match on `code`/`name` across packages).\n *\n * `retryable` is the signal the consume loops act on: 429/5xx/network are\n * retryable, 4xx and body-serialization failures are not.\n */\nexport class SecondLayerError extends Error {\n\toverride name = \"SecondLayerError\";\n\t/** The one-line failure, without the appended context blocks. */\n\tshortMessage: string;\n\tcode?: string;\n\tdocsUrl?: string;\n\tmetaMessages?: string[];\n\tretryable: boolean;\n\tretryAfterSeconds?: number;\n\n\tconstructor(shortMessage: string, options: SecondLayerErrorOptions = {}) {\n\t\tconst detailBlocks = [\n\t\t\t...(options.metaMessages ?? []),\n\t\t\t...(options.details ? [options.details] : []),\n\t\t\t...(options.docsUrl ? [`Docs: ${options.docsUrl}`] : []),\n\t\t];\n\t\tconst message = [\n\t\t\tshortMessage,\n\t\t\tdetailBlocks.length > 0 ? `\\n${detailBlocks.join(\"\\n\")}` : \"\",\n\t\t].join(\"\");\n\t\tsuper(message, options.cause ? { cause: options.cause } : undefined);\n\t\tthis.shortMessage = shortMessage;\n\t\tthis.code = options.code;\n\t\tthis.docsUrl = options.docsUrl;\n\t\tthis.metaMessages = options.metaMessages;\n\t\tthis.retryable = options.retryable ?? false;\n\t\tthis.retryAfterSeconds = options.retryAfterSeconds;\n\t}\n\n\t/**\n\t * Walk the cause chain. With a predicate, returns the first error matching\n\t * it (or `null`); without one, returns the deepest cause. Mirrors viem's\n\t * `error.walk()` so cross-library error handling reads the same.\n\t */\n\twalk(fn?: (err: unknown) => boolean): unknown {\n\t\t// biome-ignore lint/suspicious/noExplicitAny: cause chains are untyped by nature\n\t\tlet err: any = this;\n\t\tlet last: unknown = this;\n\t\twhile (err != null) {\n\t\t\tif (fn?.(err)) return err;\n\t\t\tlast = err;\n\t\t\terr = err.cause;\n\t\t}\n\t\treturn fn ? null : last;\n\t}\n\n\ttoJSON(): {\n\t\tname: string;\n\t\tmessage: string;\n\t\tshortMessage: string;\n\t\tcause: string | undefined;\n\t\tcode: string | undefined;\n\t\tdocsUrl: string | undefined;\n\t\tretryable: boolean;\n\t\tretryAfterSeconds: number | undefined;\n\t} {\n\t\treturn {\n\t\t\tname: this.name,\n\t\t\tmessage: this.message,\n\t\t\tshortMessage: this.shortMessage,\n\t\t\tcause: this.cause instanceof Error ? this.cause.message : undefined,\n\t\t\tcode: this.code,\n\t\t\tdocsUrl: this.docsUrl,\n\t\t\tretryable: this.retryable,\n\t\t\tretryAfterSeconds: this.retryAfterSeconds,\n\t\t};\n\t}\n}\n\n/** Retryability of an HTTP status: 429 and 5xx are transient. */\nfunction statusRetryable(status: number): boolean {\n\treturn status === 429 || status >= 500;\n}\n\n/** Docs page for a status/code pair, when one exists. */\nfunction docsFor(status: number, code?: string): string | undefined {\n\tif (code === \"UPGRADE_REQUIRED\" || code === \"PLAN_REQUIRED\" || status === 402)\n\t\treturn `${DOCS_BASE}/docs/authentication#pay-as-you-go-credits`;\n\tif (status === 429 || status === 401)\n\t\treturn `${DOCS_BASE}/docs/authentication`;\n\treturn undefined;\n}\n\n/**\n * Error thrown by {@link SecondLayer} when an API request fails.\n * Includes the HTTP status code for programmatic error handling.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.get(\"my-subgraph\");\n * } catch (err) {\n *   if (err instanceof ApiError && err.status === 404) {\n *     console.log(\"Subgraph not found\");\n *   }\n * }\n * ```\n */\nexport class ApiError extends SecondLayerError {\n\tconstructor(\n\t\t/** HTTP status code (0 for network errors). */\n\t\tpublic status: number,\n\t\tmessage: string,\n\t\t/** Raw response body (parsed JSON if possible) — preserved for callers that need error details. */\n\t\tpublic body?: unknown,\n\t\t/** Stable machine-readable code from the API's `{error, code}` error envelope. */\n\t\tcode?: string,\n\t\toptions: SecondLayerErrorOptions = {},\n\t) {\n\t\tsuper(message, {\n\t\t\tcode,\n\t\t\tretryable: options.retryable ?? statusRetryable(status),\n\t\t\tdocsUrl: options.docsUrl ?? docsFor(status, code),\n\t\t\t...(options.cause ? { cause: options.cause } : {}),\n\t\t\t...(options.details ? { details: options.details } : {}),\n\t\t\t...(options.metaMessages ? { metaMessages: options.metaMessages } : {}),\n\t\t\t...(options.retryAfterSeconds !== undefined\n\t\t\t\t? { retryAfterSeconds: options.retryAfterSeconds }\n\t\t\t\t: {}),\n\t\t});\n\t\tthis.name = \"ApiError\";\n\t}\n}\n\n/** Thrown on a 401 — by both the platform clients and Streams. */\nexport class AuthError extends ApiError {\n\toverride readonly status = 401 as const;\n\n\tconstructor(message = \"API key invalid or expired.\") {\n\t\tsuper(401, message);\n\t\tthis.name = \"AuthError\";\n\t}\n}\n\n/** Thrown on a 429 — by both the platform clients and Streams. `retryable`,\n *  with `retryAfterSeconds` parsed from the `Retry-After` header when sent. */\nexport class RateLimitError extends ApiError {\n\toverride readonly status = 429 as const;\n\n\tconstructor(\n\t\tmessage = \"Rate limited. Try again later.\",\n\t\t/** Raw `Retry-After` header value (seconds or HTTP-date). */\n\t\treadonly retryAfter?: string,\n\t) {\n\t\tsuper(429, message, undefined, undefined, {\n\t\t\tretryable: true,\n\t\t\tretryAfterSeconds: parseRetryAfter(retryAfter),\n\t\t});\n\t\tthis.name = \"RateLimitError\";\n\t}\n}\n\n/** Thrown on a 4xx the caller can fix (bad cursor, bad params). Never retried. */\nexport class ValidationError extends ApiError {\n\tconstructor(message: string, status: number, body?: unknown) {\n\t\tsuper(status, message, body, undefined, { retryable: false });\n\t\tthis.name = \"ValidationError\";\n\t}\n}\n\n/** Parse a `Retry-After` header: delta-seconds or an HTTP-date. */\nexport function parseRetryAfter(value?: string | null): number | undefined {\n\tif (!value) return undefined;\n\tconst seconds = Number(value);\n\tif (Number.isFinite(seconds) && seconds >= 0) return seconds;\n\tconst date = Date.parse(value);\n\tif (!Number.isNaN(date)) return Math.max(0, (date - Date.now()) / 1000);\n\treturn undefined;\n}\n\n/**\n * Thrown on optimistic-concurrency conflict when a deploy supplies an\n * `expectedVersion` that no longer matches the server's stored version.\n */\nexport class VersionConflictError extends ApiError {\n\tconstructor(\n\t\tpublic currentVersion: string,\n\t\tpublic expectedVersion: string,\n\t\tmessage = `Version conflict: expected ${expectedVersion}, current ${currentVersion}`,\n\t) {\n\t\tsuper(409, message, { currentVersion, expectedVersion });\n\t\tthis.name = \"VersionConflictError\";\n\t}\n}\n\n/**\n * Thrown when a BYO subgraph deploy is refused for a breaking schema change.\n * The deploy did NOT run — `details.plan` carries the DROP + rebuild DDL to run\n * manually on your own database, plus the breaking `reasons` and the `diff`.\n * The same DDL is surfaced on `metaMessages`, so a bare `console.error(err)`\n * already shows the operator what to run.\n *\n * @example\n * ```ts\n * try {\n *   await client.subgraphs.deploy(bundle);\n * } catch (err) {\n *   if (err instanceof ByoBreakingChangeError) {\n *     console.log(err.details.plan.dropStatement);\n *     console.log(err.details.plan.statements.join(\";\\n\"));\n *   }\n * }\n * ```\n */\nexport class ByoBreakingChangeError extends ApiError {\n\treadonly details: ByoBreakingChangeDetails;\n\tconstructor(message: string, details: ByoBreakingChangeDetails) {\n\t\tsuper(422, message, details, \"BYO_BREAKING_CHANGE\", {\n\t\t\tmetaMessages: [\n\t\t\t\t\"Review and run manually on your database:\",\n\t\t\t\tdetails.plan.dropStatement,\n\t\t\t\t...details.plan.statements,\n\t\t\t],\n\t\t});\n\t\tthis.name = \"ByoBreakingChangeError\";\n\t\tthis.details = details;\n\t}\n}\n\n/** Narrow an unknown error body's `details` to {@link ByoBreakingChangeDetails}. */\nexport function isByoBreakingDetails(\n\tx: unknown,\n): x is ByoBreakingChangeDetails {\n\tif (!x || typeof x !== \"object\") return false;\n\tconst d = x as Record<string, unknown>;\n\tconst plan = d.plan as Record<string, unknown> | undefined;\n\treturn (\n\t\tArray.isArray(d.reasons) &&\n\t\t!!plan &&\n\t\ttypeof plan === \"object\" &&\n\t\ttypeof plan.dropStatement === \"string\"\n\t);\n}\n",
+    "import { ValidationError } from \"../errors.ts\";\nimport type { ConsumerSink } from \"./types.ts\";\n\n/** Default checkpoint table name, shared by every SQL-backed sink so two\n *  sinks on the same database land in one table keyed by `id`. */\nexport const DEFAULT_CHECKPOINT_TABLE = \"sl_consumer_checkpoints\";\n\n/**\n * The driver surface a database adapter implements — the ~7 methods that\n * actually differ between SQL stores. Everything above them (the\n * commit/rollback call sequences, the guards, identifier validation, the\n * checkpoint schema) is policy owned by {@link createSink}, so a driver\n * cannot get the ordering wrong: it never sees a cursor write outside the\n * transaction that carries the rows, and never sees a delete without the\n * rewound cursor riding along.\n *\n * Identifier args (`table`, `column`) arrive pre-validated against\n * `[A-Za-z_][A-Za-z0-9_]*` — safe to interpolate after quoting (see\n * {@link quoteIdent}). Values (cursor, height, id) must still be bound as\n * parameters.\n */\nexport interface SinkDriver<Tx> {\n\t/** Run `fn` inside ONE transaction: begin, run, commit — a throw from\n\t *  `fn` must roll the whole transaction back and re-throw. */\n\ttransact<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;\n\t/** Create the checkpoint store if missing: `(id primary key, cursor)`.\n\t *  Must be safe under concurrent first start (two consumers racing the\n\t *  same CREATE). */\n\tensureCheckpointStore(): Promise<void>;\n\t/** The committed cursor for this sink's `id`, or `null` if none. */\n\treadCursor(): Promise<string | null>;\n\t/** Upsert this sink's cursor row inside `tx`. */\n\twriteCursor(tx: Tx, cursor: string): Promise<void>;\n\t/** Delete rows with `height column >= height` from `table`, inside `tx`. */\n\tdeleteAtOrAbove(tx: Tx, table: string, height: number): Promise<void>;\n\t/** Whether `table` exists AND carries `column` — the first-use check that\n\t *  keeps reorg rollback from being a silent no-op. */\n\thasColumn(table: string, column: string): Promise<boolean>;\n\t/** Optional: assert this consumer is the only live writer for its `id`,\n\t *  inside `tx`. Must FAIL LOUDLY (throw) when another writer holds it —\n\t *  never block or interleave (contract invariant #13). */\n\tacquireLock?(tx: Tx): Promise<void>;\n}\n\n/** Options for {@link createSink} — the policy inputs, driver-agnostic.\n *  Concrete sinks re-expose these with schema-typed `tables`/`height`. */\nexport interface CreateSinkOptions {\n\t/** Error-message prefix naming the concrete sink (e.g. `\"kyselySink\"`),\n\t *  so a thrown guard points at the thing the user actually constructed. */\n\tlabel: string;\n\t/** Checkpoint identity AND concurrency key. */\n\tid: string;\n\t/** Rollback scope: on a reorg, rows at/above the fork point are deleted\n\t *  from exactly these tables. */\n\ttables: readonly string[];\n\t/** The block-height stamp column, present on every declared table. */\n\theight: string;\n\t/** Checkpoint table name. Default {@link DEFAULT_CHECKPOINT_TABLE}. */\n\tcheckpointTable?: string;\n\t/** Forwarded to {@link ConsumerSink.capabilities}. */\n\tcapabilities?: ConsumerSink[\"capabilities\"];\n}\n\n/** Throw unless `name` is a bare SQL identifier (letters, digits,\n *  underscores; no leading digit) — the guard that makes interpolating\n *  table/column names into DDL and DELETE statements safe. */\nexport function assertSqlIdentifier(name: string, label: string): void {\n\tif (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {\n\t\tthrow new ValidationError(\n\t\t\t`${label}: invalid identifier \"${name}\" (letters, digits, underscores only).`,\n\t\t\t400,\n\t\t);\n\t}\n}\n\n/** Double-quote a (pre-validated) identifier for interpolation. */\nexport function quoteIdent(name: string): string {\n\treturn `\"${name}\"`;\n}\n\n/**\n * Build a {@link ConsumerSink} from a {@link SinkDriver}: the portable ~90\n * lines every SQL sink otherwise re-implements — and re-risks. Owns the two\n * transaction sequences (begin → lock → write rows → write cursor;\n * begin → lock → delete `>=` fork → write rewound cursor), the empty-`tables`\n * guard, identifier validation, and the first-use height-column check.\n *\n * A driver implemented against this base cannot violate contract invariants\n * #4, #5, #8, #9, or #11 (see {@link ConsumerSink}) without breaking\n * `transact` itself — which is exactly what the conformance kit probes.\n */\nexport function createSink<Tx>(\n\tdriver: SinkDriver<Tx>,\n\toptions: CreateSinkOptions,\n): ConsumerSink<Tx> {\n\tconst { label } = options;\n\tconst checkpointTable = options.checkpointTable ?? DEFAULT_CHECKPOINT_TABLE;\n\tif (options.tables.length === 0) {\n\t\tthrow new ValidationError(\n\t\t\t`${label}: \\`tables\\` is empty — declare every table the handler writes, or reorg rollback is a no-op and orphaned rows persist forever.`,\n\t\t\t400,\n\t\t);\n\t}\n\tassertSqlIdentifier(checkpointTable, label);\n\tassertSqlIdentifier(options.height, label);\n\tfor (const table of options.tables) assertSqlIdentifier(table, label);\n\n\treturn {\n\t\tcapabilities: options.capabilities,\n\n\t\tasync loadCursor() {\n\t\t\tawait driver.ensureCheckpointStore();\n\t\t\t// First-use validation of the rollback precondition: every declared\n\t\t\t// table must exist and carry the height column. Failing here beats a\n\t\t\t// rollback that silently deletes nothing during a reorg.\n\t\t\tfor (const table of options.tables) {\n\t\t\t\tif (!(await driver.hasColumn(table, options.height))) {\n\t\t\t\t\tthrow new ValidationError(\n\t\t\t\t\t\t`${label}: table \"${table}\" has no \"${options.height}\" column — the height stamp is what makes reorg rollback possible. Add the column (or fix \\`height\\`).`,\n\t\t\t\t\t\t400,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn driver.readCursor();\n\t\t},\n\n\t\tasync commitBatch(cursor, write) {\n\t\t\tawait driver.transact(async (tx) => {\n\t\t\t\tawait driver.acquireLock?.(tx);\n\t\t\t\tawait write(tx);\n\t\t\t\tawait driver.writeCursor(tx, cursor);\n\t\t\t});\n\t\t},\n\n\t\tasync rollback(forkPointHeight, rewindCursor) {\n\t\t\tawait driver.transact(async (tx) => {\n\t\t\t\tawait driver.acquireLock?.(tx);\n\t\t\t\t// INCLUSIVE of the fork block: the new canonical chain re-supplies\n\t\t\t\t// it, and the consumer rewinds to re-read from `fork:0`.\n\t\t\t\tfor (const table of options.tables) {\n\t\t\t\t\tawait driver.deleteAtOrAbove(tx, table, forkPointHeight);\n\t\t\t\t}\n\t\t\t\tawait driver.writeCursor(tx, rewindCursor);\n\t\t\t});\n\t\t},\n\t};\n}\n",
+    "import { type Kysely, type Transaction, sql } from \"kysely\";\nimport { ValidationError } from \"../errors.ts\";\nimport {\n\tDEFAULT_CHECKPOINT_TABLE,\n\ttype SinkDriver,\n\tcreateSink,\n\tquoteIdent,\n} from \"./core.ts\";\nimport type { ConsumerSink } from \"./types.ts\";\n\n/**\n * Column present on EVERY declared table — `keyof` a union of row types is\n * the intersection of their keys, so a column missing from any one table is\n * a compile error at the `height:` option.\n */\ntype CommonColumn<DB, T extends keyof DB> = keyof DB[T] & string;\n\nexport interface KyselySinkOptions<DB, T extends keyof DB & string> {\n\t/** Checkpoint identity AND concurrency key: the cursor row's primary key,\n\t *  and the input to `pg_try_advisory_xact_lock(hashtextextended(id, 0))`.\n\t *  The lock is transaction-scoped: it stops two replicas from\n\t *  INTERLEAVING inside a commit, but is released at each commit boundary\n\t *  — it is NOT a fence, so two replicas alternating batches both pass.\n\t *  Run exactly one consumer per id; the lock turns the racy overlap loud,\n\t *  it does not make a second replica safe. */\n\tid: string;\n\t/** Rollback scope. On a reorg, rows AT OR ABOVE the fork point are deleted\n\t *  from exactly these tables (inclusive `>=` — the new chain re-supplies\n\t *  the fork block). A table you write but don't declare keeps orphaned\n\t *  rows forever, so declare everything the handler touches. */\n\ttables: readonly T[];\n\t/** The block-height stamp column, present on every declared table (compile\n\t *  and first-use checked). Height-stamp rollback is correct for\n\t *  APPEND-ONLY projections (one row per event/call); aggregates that\n\t *  mutate rows (balances, counters) can't be rolled back this way — use a\n\t *  subgraph for those. */\n\theight: CommonColumn<DB, T>;\n\t/** Checkpoint table name. Default `sl_consumer_checkpoints` (created on\n\t *  first use). */\n\tcheckpointTable?: string;\n}\n\n/**\n * A {@link ConsumerSink} over a Kysely Postgres database — keyed on the\n * QUERY BUILDER (not the driver) so the `DB` schema generic flows through:\n * `tables` is `(keyof DB)[]`, `height` must exist on every declared table,\n * and `ctx.tx` inside `onBatch` is a fully typed `Transaction<DB>`.\n *\n * What it owns (so your indexer doesn't):\n * - the checkpoint table + cursor load on start;\n * - rows AND cursor committed in ONE transaction per batch — a handler\n *   throw aborts both, so a crashed batch is re-read on restart with no\n *   gaps and no double-writes;\n * - reorg rollback: delete `>= fork_point_height` from every declared table\n *   and commit the rewound cursor atomically (the crash-between-the-two-\n *   writes gap is unrepresentable);\n * - a per-id advisory lock, so two replicas of the same consumer can't\n *   interleave commits.\n *\n * Structurally it is a 7-method {@link SinkDriver} on the shared\n * `createSink` base (`@secondlayer/sdk/sinks/core`), which owns the\n * transaction sequences and guards — this file only knows how to speak\n * Postgres-flavored Kysely.\n *\n * ```ts\n * const sink = kyselySink(db, { id: \"sales\", tables: [\"sales\"], height: \"block_height\" });\n * await index.contractCalls.consume({\n *   contractId: MARKETPLACE, functionName: \"purchase-asset\", fromHeight: 0,\n *   sink,\n *   onBatch: (calls, _env, ctx) =>\n *     ctx.tx.insertInto(\"sales\").values(calls.map(toSale)).execute(),\n * });\n * ```\n */\nexport function kyselySink<DB, T extends keyof DB & string>(\n\tdb: Kysely<DB>,\n\toptions: KyselySinkOptions<DB, T>,\n): ConsumerSink<Transaction<DB>> {\n\tconst checkpointTable = options.checkpointTable ?? DEFAULT_CHECKPOINT_TABLE;\n\tconst cp = quoteIdent(checkpointTable);\n\n\tconst driver: SinkDriver<Transaction<DB>> = {\n\t\ttransact: (fn) => db.transaction().execute(fn),\n\n\t\tasync ensureCheckpointStore() {\n\t\t\ttry {\n\t\t\t\tawait sql\n\t\t\t\t\t.raw(\n\t\t\t\t\t\t`CREATE TABLE IF NOT EXISTS ${cp} (id text PRIMARY KEY, cursor text NOT NULL)`,\n\t\t\t\t\t)\n\t\t\t\t\t.execute(db);\n\t\t\t} catch (err) {\n\t\t\t\t// Two consumers racing the same first start: IF NOT EXISTS still\n\t\t\t\t// throws under concurrency (42P07 duplicate_table, or 23505 on the\n\t\t\t\t// pg_type catalog). Either way the table exists — the outcome we\n\t\t\t\t// were creating.\n\t\t\t\tconst code = (err as { code?: string } | null)?.code;\n\t\t\t\tif (code !== \"42P07\" && code !== \"23505\") throw err;\n\t\t\t}\n\t\t},\n\n\t\tasync readCursor() {\n\t\t\tconst row = await sql<{ cursor: string }>`\n\t\t\t\tSELECT cursor FROM ${sql.raw(cp)} WHERE id = ${options.id}\n\t\t\t`.execute(db);\n\t\t\treturn row.rows[0]?.cursor ?? null;\n\t\t},\n\n\t\tasync writeCursor(tx, cursor) {\n\t\t\t// Identifiers via validated sql.raw; VALUES via bound parameters.\n\t\t\tawait sql`\n\t\t\t\tINSERT INTO ${sql.raw(cp)} (id, cursor) VALUES (${options.id}, ${cursor})\n\t\t\t\tON CONFLICT (id) DO UPDATE SET cursor = EXCLUDED.cursor\n\t\t\t`.execute(tx);\n\t\t},\n\n\t\tasync deleteAtOrAbove(tx, table, height) {\n\t\t\t// Identifiers via validated sql.raw; the height bound as a parameter.\n\t\t\tawait sql`\n\t\t\t\tDELETE FROM ${sql.raw(quoteIdent(table))}\n\t\t\t\tWHERE ${sql.raw(quoteIdent(options.height as string))} >= ${height}\n\t\t\t`.execute(tx);\n\t\t},\n\n\t\tasync hasColumn(table, column) {\n\t\t\tconst col = await sql<{ ok: boolean }>`\n\t\t\t\tSELECT EXISTS (\n\t\t\t\t\tSELECT 1 FROM information_schema.columns\n\t\t\t\t\tWHERE table_name = ${table} AND column_name = ${column}\n\t\t\t\t) AS \"ok\"\n\t\t\t`.execute(db);\n\t\t\treturn col.rows[0]?.ok ?? false;\n\t\t},\n\n\t\tasync acquireLock(tx) {\n\t\t\t// hashtextextended (int8), not hashtext (int4): the 32-bit space\n\t\t\t// collides across distinct ids at real scale, and a collision reads\n\t\t\t// as a false \"another consumer\" 409 between unrelated sinks.\n\t\t\tconst locked = await sql<{ ok: boolean }>`\n\t\t\t\tSELECT pg_try_advisory_xact_lock(hashtextextended(${options.id}, 0)) AS \"ok\"\n\t\t\t`.execute(tx);\n\t\t\tif (!locked.rows[0]?.ok) {\n\t\t\t\tthrow new ValidationError(\n\t\t\t\t\t`kyselySink: another consumer holds the \"${options.id}\" lock — two replicas of the same consumer would interleave commits. Stop the other instance or use a distinct id.`,\n\t\t\t\t\t409,\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn createSink(driver, {\n\t\tlabel: \"kyselySink\",\n\t\tid: options.id,\n\t\ttables: options.tables,\n\t\theight: options.height as string,\n\t\tcheckpointTable,\n\t});\n}\n"
   ],
-  "mappings": ";AAAA;;;ACIA,IAAM,YAAY;AAAA;AA8BX,MAAM,yBAAyB,MAAM;AAAA,EAClC,OAAO;AAAA,EAEhB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA,WAAW,CAAC,cAAsB,UAAmC,CAAC,GAAG;AAAA,IACxE,MAAM,eAAe;AAAA,MACpB,GAAI,QAAQ,gBAAgB,CAAC;AAAA,MAC7B,GAAI,QAAQ,UAAU,CAAC,QAAQ,OAAO,IAAI,CAAC;AAAA,MAC3C,GAAI,QAAQ,UAAU,CAAC,SAAS,QAAQ,SAAS,IAAI,CAAC;AAAA,IACvD;AAAA,IACA,MAAM,UAAU;AAAA,MACf;AAAA,MACA,aAAa,SAAS,IAAI;AAAA,EAAK,aAAa,KAAK;AAAA,CAAI,MAAM;AAAA,IAC5D,EAAE,KAAK,EAAE;AAAA,IACT,MAAM,SAAS,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,SAAS;AAAA,IACnE,KAAK,eAAe;AAAA,IACpB,KAAK,OAAO,QAAQ;AAAA,IACpB,KAAK,UAAU,QAAQ;AAAA,IACvB,KAAK,eAAe,QAAQ;AAAA,IAC5B,KAAK,YAAY,QAAQ,aAAa;AAAA,IACtC,KAAK,oBAAoB,QAAQ;AAAA;AAAA,EAQlC,IAAI,CAAC,IAAyC;AAAA,IAE7C,IAAI,MAAW;AAAA,IACf,IAAI,OAAgB;AAAA,IACpB,OAAO,OAAO,MAAM;AAAA,MACnB,IAAI,KAAK,GAAG;AAAA,QAAG,OAAO;AAAA,MACtB,OAAO;AAAA,MACP,MAAM,IAAI;AAAA,IACX;AAAA,IACA,OAAO,KAAK,OAAO;AAAA;AAAA,EAGpB,MAAM,GASJ;AAAA,IACD,OAAO;AAAA,MACN,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,cAAc,KAAK;AAAA,MACnB,OAAO,KAAK,iBAAiB,QAAQ,KAAK,MAAM,UAAU;AAAA,MAC1D,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,WAAW,KAAK;AAAA,MAChB,mBAAmB,KAAK;AAAA,IACzB;AAAA;AAEF;AAGA,SAAS,eAAe,CAAC,QAAyB;AAAA,EACjD,OAAO,WAAW,OAAO,UAAU;AAAA;AAIpC,SAAS,OAAO,CAAC,QAAgB,MAAmC;AAAA,EACnE,IAAI,SAAS,sBAAsB,SAAS,mBAAmB,WAAW;AAAA,IACzE,OAAO,GAAG;AAAA,EACX,IAAI,WAAW,OAAO,WAAW;AAAA,IAChC,OAAO,GAAG;AAAA,EACX;AAAA;AAAA;AAkBM,MAAM,iBAAiB,iBAAiB;AAAA,EAGtC;AAAA,EAGA;AAAA,EALR,WAAW,CAEH,QACP,SAEO,MAEP,MACA,UAAmC,CAAC,GACnC;AAAA,IACD,MAAM,SAAS;AAAA,MACd;AAAA,MACA,WAAW,QAAQ,aAAa,gBAAgB,MAAM;AAAA,MACtD,SAAS,QAAQ,WAAW,QAAQ,QAAQ,IAAI;AAAA,SAC5C,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA,SAC5C,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;AAAA,SAClD,QAAQ,eAAe,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;AAAA,SACjE,QAAQ,sBAAsB,YAC/B,EAAE,mBAAmB,QAAQ,kBAAkB,IAC/C,CAAC;AAAA,IACL,CAAC;AAAA,IAlBM;AAAA,IAGA;AAAA,IAgBP,KAAK,OAAO;AAAA;AAEd;AAAA;AAGO,MAAM,kBAAkB,SAAS;AAAA,EACrB,SAAS;AAAA,EAE3B,WAAW,CAAC,UAAU,+BAA+B;AAAA,IACpD,MAAM,KAAK,OAAO;AAAA,IAClB,KAAK,OAAO;AAAA;AAEd;AAAA;AAIO,MAAM,uBAAuB,SAAS;AAAA,EAMlC;AAAA,EALQ,SAAS;AAAA,EAE3B,WAAW,CACV,UAAU,kCAED,YACR;AAAA,IACD,MAAM,KAAK,SAAS,WAAW,WAAW;AAAA,MACzC,WAAW;AAAA,MACX,mBAAmB,gBAAgB,UAAU;AAAA,IAC9C,CAAC;AAAA,IALQ;AAAA,IAMT,KAAK,OAAO;AAAA;AAEd;AAAA;AAGO,MAAM,wBAAwB,SAAS;AAAA,EAC7C,WAAW,CAAC,SAAiB,QAAgB,MAAgB;AAAA,IAC5D,MAAM,QAAQ,SAAS,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;AAAA,IAC5D,KAAK,OAAO;AAAA;AAEd;AAGO,SAAS,eAAe,CAAC,OAA2C;AAAA,EAC1E,IAAI,CAAC;AAAA,IAAO;AAAA,EACZ,MAAM,UAAU,OAAO,KAAK;AAAA,EAC5B,IAAI,OAAO,SAAS,OAAO,KAAK,WAAW;AAAA,IAAG,OAAO;AAAA,EACrD,MAAM,OAAO,KAAK,MAAM,KAAK;AAAA,EAC7B,IAAI,CAAC,OAAO,MAAM,IAAI;AAAA,IAAG,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,KAAK,IAAI;AAAA,EACtE;AAAA;AAAA;AAOM,MAAM,6BAA6B,SAAS;AAAA,EAE1C;AAAA,EACA;AAAA,EAFR,WAAW,CACH,gBACA,iBACP,UAAU,8BAA8B,4BAA4B,kBACnE;AAAA,IACD,MAAM,KAAK,SAAS,EAAE,gBAAgB,gBAAgB,CAAC;AAAA,IAJhD;AAAA,IACA;AAAA,IAIP,KAAK,OAAO;AAAA;AAEd;AAAA;AAqBO,MAAM,+BAA+B,SAAS;AAAA,EAC3C;AAAA,EACT,WAAW,CAAC,SAAiB,SAAmC;AAAA,IAC/D,MAAM,KAAK,SAAS,SAAS,uBAAuB;AAAA,MACnD,cAAc;AAAA,QACb;AAAA,QACA,QAAQ,KAAK;AAAA,QACb,GAAG,QAAQ,KAAK;AAAA,MACjB;AAAA,IACD,CAAC;AAAA,IACD,KAAK,OAAO;AAAA,IACZ,KAAK,UAAU;AAAA;AAEjB;AAGO,SAAS,oBAAoB,CACnC,GACgC;AAAA,EAChC,IAAI,CAAC,KAAK,OAAO,MAAM;AAAA,IAAU,OAAO;AAAA,EACxC,MAAM,IAAI;AAAA,EACV,MAAM,OAAO,EAAE;AAAA,EACf,OACC,MAAM,QAAQ,EAAE,OAAO,KACvB,CAAC,CAAC,QACF,OAAO,SAAS,YAChB,OAAO,KAAK,kBAAkB;AAAA;;;AD7MzB,SAAS,UAA2C,CAC1D,IACA,SACgC;AAAA,EAChC,MAAM,kBAAkB,QAAQ,mBAAmB;AAAA,EACnD,IAAI,QAAQ,OAAO,WAAW,GAAG;AAAA,IAChC,MAAM,IAAI,gBACT,2IACA,GACD;AAAA,EACD;AAAA,EAGA,MAAM,QAAQ,CAAC,SAAyB;AAAA,IACvC,IAAI,CAAC,2BAA2B,KAAK,IAAI,GAAG;AAAA,MAC3C,MAAM,IAAI,gBACT,mCAAmC,8CACnC,GACD;AAAA,IACD;AAAA,IACA,OAAO,IAAI;AAAA;AAAA,EAEZ,MAAM,KAAK,MAAM,eAAe;AAAA,EAChC,MAAM,YAAY,MAAM,QAAQ,MAAgB;AAAA,EAChD,WAAW,SAAS,QAAQ;AAAA,IAAQ,MAAM,KAAK;AAAA,EAE/C,eAAe,WAAW,CAAC,IAAoC;AAAA,IAC9D,MAAM,SAAS,MAAM;AAAA,+CACwB,QAAQ;AAAA,IACnD,QAAQ,EAAE;AAAA,IACZ,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI;AAAA,MACxB,MAAM,IAAI,gBACT,2CAA2C,QAAQ,wHACnD,GACD;AAAA,IACD;AAAA;AAAA,EAGD,eAAe,YAAY,CAC1B,IACA,QACgB;AAAA,IAEhB,MAAM;AAAA,iBACS,IAAI,IAAI,EAAE,0BAA0B,QAAQ,OAAO;AAAA;AAAA,IAEhE,QAAQ,EAAE;AAAA;AAAA,EAGb,OAAO;AAAA,SACA,WAAU,GAAG;AAAA,MAClB,MAAM,IACJ,IACA,8BAA8B,gDAC/B,EACC,QAAQ,EAAE;AAAA,MAIZ,WAAW,SAAS,QAAQ,QAAQ;AAAA,QACnC,MAAM,MAAM,MAAM;AAAA;AAAA;AAAA,2BAGK,2BAA2B,QAAQ;AAAA;AAAA,MAExD,QAAQ,EAAE;AAAA,QACZ,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI;AAAA,UACrB,MAAM,IAAI,gBACT,sBAAsB,kBAAkB,OAAO,QAAQ,MAAM,2GAC7D,GACD;AAAA,QACD;AAAA,MACD;AAAA,MACA,MAAM,MAAM,MAAM;AAAA,yBACI,IAAI,IAAI,EAAE,gBAAgB,QAAQ;AAAA,KACtD,QAAQ,EAAE;AAAA,MACZ,OAAO,IAAI,KAAK,IAAI,UAAU;AAAA;AAAA,SAGzB,YAAW,CAAC,QAAQ,OAAO;AAAA,MAChC,MAAM,GAAG,YAAY,EAAE,QAAQ,OAAO,OAAO;AAAA,QAC5C,MAAM,YAAY,EAAE;AAAA,QACpB,MAAM,MAAM,EAAE;AAAA,QACd,MAAM,aAAa,IAAI,MAAM;AAAA,OAC7B;AAAA;AAAA,SAGI,SAAQ,CAAC,iBAAiB,cAAc;AAAA,MAC7C,MAAM,GAAG,YAAY,EAAE,QAAQ,OAAO,OAAO;AAAA,QAC5C,MAAM,YAAY,EAAE;AAAA,QAGpB,WAAW,SAAS,QAAQ,QAAQ;AAAA,UAEnC,MAAM;AAAA,oBACS,IAAI,IAAI,MAAM,KAAK,CAAC;AAAA,cAC1B,IAAI,IAAI,SAAS,QAAQ;AAAA,OAChC,QAAQ,EAAE;AAAA,QACb;AAAA,QACA,MAAM,aAAa,IAAI,YAAY;AAAA,OACnC;AAAA;AAAA,EAEH;AAAA;",
-  "debugId": "667BFBBF3BF09CCB64756E2164756E21",
+  "mappings": "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",
+  "debugId": "475014242F550C1264756E2164756E21",
   "names": []
 }

package/dist/sinks/testing.d.ts

@@ -0,0 +1,183 @@
+/**
+* A consumer sink: the destination adapter a consume loop writes through.
+*
+* Without a sink, the user owns the three hard parts of a durable indexer —
+* checkpoint persistence, rows+cursor atomicity, and reorg rollback — and
+* the reasoning that makes them safe lives in doc comments. A sink owns all
+* three: the loop loads its committed cursor, hands the handler a
+* transaction, commits rows AND cursor atomically, and rolls back reorgs
+* without any user code. Crucially, a sink also closes the silent-skip
+* hazard where omitting `onReorg` meant reorgs were ignored forever: with a
+* sink attached, rollback is unconditional.
+*
+* The interface is dependency-free on purpose: implementations with real
+* database drivers live behind subpath exports (`@secondlayer/sdk/sinks/*`)
+* so the root entry ships no DB dependency.
+*
+* ## The contract
+*
+* Binding on every implementation; the conformance kit
+* (`@secondlayer/sdk/sinks/testing`) probes each one. Violations are SILENT
+* in production — they surface as gaps or duplicates weeks later, never as
+* errors at the violation site — which is why they are spelled out here and
+* mechanically tested.
+*
+* What the loop guarantees the sink:
+*
+* 1. **Init-before-first-page.** `loadCursor` is called exactly once, before
+*    the first fetch — even when the caller passed an explicit `fromCursor`.
+*    It is the sink's init hook: create checkpoint storage, validate
+*    rollback preconditions.
+* 2. **Deterministic replay.** Re-reading from the same cursor yields the
+*    same rows in the same order. `cursor` is therefore a valid idempotency
+*    key: an append-only sink can dedup on it with no contract change.
+* 3. **At-least-once delivery.** A batch whose commit outcome was lost (crash
+*    after commit, before the loop observed it) is re-committed on restart
+*    with the SAME cursor and the same rows.
+*
+* What the sink must guarantee — `commitBatch`:
+*
+* 4. **Rows+cursor atomicity.** The handler's writes and `cursor` commit in
+*    ONE transaction. Committing them separately is the classic torn-batch
+*    bug: a crash between the two either re-delivers (duplicates) or skips
+*    (gap) depending on the order.
+* 5. **Abort on throw.** A throw from `write` aborts the WHOLE transaction —
+*    neither rows nor cursor land — so a crashed batch is simply re-read.
+* 6. **The lent transaction is the real one.** `write(tx)` receives the same
+*    live transaction the cursor commits in; every handler write must go
+*    through it. Writes outside `tx` escape atomicity AND rollback.
+* 7. **Replay safety.** Committing the same cursor twice must not corrupt
+*    state (per #3 the rows are identical; upsert/dedup make it exact).
+*
+* What the sink must guarantee — `rollback`:
+*
+* 8. **Delete+rewind atomicity.** Undoing rows at/above the fork and
+*    committing `rewindCursor` happen in ONE transaction. A crash between
+*    them resumes above the fork and the deleted range is never re-read —
+*    the silent-gap bug.
+* 9. **Inclusive fork point.** Undo AT OR ABOVE `forkPointHeight` (`>=`) —
+*    the new canonical chain re-supplies the fork block itself.
+* 10. **Idempotent.** The loop may re-apply the same rollback after a crash
+*     (reorgs are deduped in memory only); a second application must be a
+*     harmless no-op.
+* 11. **Scope by height, not cursor.** On a page reporting several forks the
+*     loop calls `rollback` once per fork: each call carries its own
+*     `forkPointHeight` but ALL carry the same `rewindCursor` (the lowest
+*     fork point). Derive the undo range from `forkPointHeight` only; a
+*     sink that derives it from `rewindCursor` under-deletes silently.
+*
+* Error semantics and concurrency:
+*
+* 12. **Throw, don't swallow; no internal retry.** The loop owns retry
+*     policy. A swallowed commit error advances the loop past unwritten
+*     data; an internal retry can double-apply around a partial failure.
+* 13. **Single writer per checkpoint id.** The loop assumes one live
+*     consumer per checkpoint identity. A sink that can detect a second
+*     writer (e.g. a lock) must fail loudly — never block or interleave.
+*/
+interface ConsumerSink<Tx = unknown> {
+	/** Phantom marker carrying `Tx` in a directly-inferable position, so the
+	*  consume loops' `TTx` type parameter resolves from the `sink` option
+	*  (never set at runtime). */
+	readonly _tx?: Tx;
+	/** Static capabilities, read by the loop before the first fetch to fail
+	*  fast on impossible pairings. */
+	readonly capabilities?: {
+		/** This sink cannot undo committed rows (append-only store, ClickHouse,
+		*  parquet, …), so `rollback` is unimplementable and following the
+		*  unfinalized tip would corrupt it on the first fork. The loop throws
+		*  loudly unless consuming with `finalizedOnly: true` — in that mode
+		*  reorgs never reach the sink and `rollback` may simply throw. */
+		finalizedOnly?: boolean;
+	};
+	/** The committed checkpoint, or `null` on first run. Called once, before
+	*  the first page. Implementations may create their checkpoint storage
+	*  here and SHOULD validate their rollback preconditions (e.g. that every
+	*  declared table carries the height column). */
+	loadCursor(): Promise<string | null>;
+	/**
+	* Apply one batch atomically: open a transaction, run `write(tx)` (the
+	* user's inserts), and commit the rows AND `cursor` together. A throw
+	* from `write` must abort the whole transaction — leaving neither rows
+	* nor cursor, so a crashed batch is simply re-read on restart.
+	*/
+	commitBatch(cursor: string, write: (tx: Tx) => Promise<void> | void): Promise<void>;
+	/**
+	* Roll the projection back to the fork: delete everything AT OR ABOVE
+	* `forkPointHeight` (inclusive `>=` — the new chain re-supplies the fork
+	* block) and commit `rewindCursor` in the SAME transaction. Deleting
+	* without the rewound cursor is the classic silent-gap bug: a crash
+	* between the two writes resumes above the fork and the deleted range is
+	* never re-read.
+	*
+	* On a multi-fork page this is called once PER fork, every call with the
+	* same `rewindCursor` (the lowest fork point) but its own
+	* `forkPointHeight` — scope the undo by `forkPointHeight` only (contract
+	* invariant #11), and expect re-application after a crash (#10).
+	*/
+	rollback(forkPointHeight: number, rewindCursor: string): Promise<void>;
+}
+/**
+* The sink conformance kit: executable probes for the {@link ConsumerSink}
+* contract invariants — the ones that are SILENT when violated in
+* production (torn batches, silent gaps, under-deleted forks) and only
+* surface weeks later as missing or duplicated rows.
+*
+* Run every sink you author through it, in CI, against the real store:
+*
+* ```ts
+* import { test } from "bun:test";
+* import { attachSinkConformance } from "@secondlayer/sdk/sinks/testing";
+*
+* attachSinkConformance(test, {
+*   makeSink: () => mySink(db, { id: "conformance", tables: ["rows"], height: "height" }),
+*   reset: () => db.deleteFrom(...)...,
+*   insertRow: (tx, height, key) => ..., // MUST be replay-safe (upsert on key)
+*   readRows: () => ...,
+*   readCursor: () => ...,
+* });
+* ```
+*
+* Framework-agnostic: probes throw plain `Error`s, so they run under
+* bun:test, vitest, jest, or a bare loop.
+*/
+interface SinkConformanceHarness<Tx = unknown> {
+	/** A fresh sink instance bound to the SAME store and the SAME checkpoint
+	*  id each call — "new instance" is how the kit simulates a restart. */
+	makeSink(): ConsumerSink<Tx> | Promise<ConsumerSink<Tx>>;
+	/** Wipe the store back to empty: projection rows AND this id's
+	*  checkpoint. Called before every probe. */
+	reset(): Promise<void> | void;
+	/** Insert one projection row through the lent transaction, exactly as a
+	*  real `onBatch` handler would. MUST be replay-safe (upsert / insert-
+	*  on-conflict-do-nothing keyed on `key`) — the same requirement the
+	*  contract's at-least-once delivery puts on real handlers. */
+	insertRow(tx: Tx, height: number, key: string): Promise<void> | void;
+	/** Every committed projection row, read OUTSIDE any transaction. */
+	readRows(): Promise<Array<{
+		height: number;
+		key: string;
+	}>>;
+	/** The committed checkpoint cursor as visible to a restarted process, or
+	*  `null` when none was ever committed. */
+	readCursor(): Promise<string | null>;
+	/** Optional (sinks with a writer lock): hold the lock for this sink's id
+	*  — as a second live consumer would — while `during` runs. Enables the
+	*  lock-contention probe (invariant #13: fail loudly, never interleave). */
+	withLockHeld?(during: () => Promise<void>): Promise<void>;
+}
+/** One executable contract probe; `run` throws on violation. */
+interface ConformanceProbe {
+	name: string;
+	run(): Promise<void>;
+}
+/** Build the probe list for a harness. Prefer {@link attachSinkConformance}
+*  inside a test framework; use this directly for a bare runner. */
+declare function sinkConformanceProbes<Tx>(harness: SinkConformanceHarness<Tx>): ConformanceProbe[];
+/**
+* Register every conformance probe with a test framework: pass your
+* framework's `test` function (bun:test, vitest, jest — anything with a
+* `(name, fn)` signature). One probe becomes one test case.
+*/
+declare function attachSinkConformance<Tx>(test: (name: string, fn: () => Promise<void>) => void, harness: SinkConformanceHarness<Tx>): void;
+export { sinkConformanceProbes, attachSinkConformance, SinkConformanceHarness, ConformanceProbe };