@voltro/sql-mysql 0.43.1 → 0.44.0

package/CHANGELOG.md

@@ -39,6 +39,71 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.44.0] — 2026-08-19
+
+### ⚠ BREAKING
+
+- **@voltro/data-transfer, @voltro/cli** — `runImport` returns an `ImportOutcome` instead of the bundle's `Manifest`, and `--mode replace` runs as ONE transaction by default.
+
+  **Why the return type changed.** The summary line counted the rows the BUNDLE carries, not the rows the run wrote. Those differ most exactly where it matters: a bundle directory carries its own resume ledger, so a copied directory imports nothing — correctly, with a warning naming the file to delete — and the run then printed `import complete … rows: 242950` over a target it had not touched. The warning was one line above, which is one line too far for anyone piping the output through `tail -1`. The outcome carries `rowsWritten`, `rowsSkipped` and `fullyResumed`, the CLI reports written-vs-carried, and a fully-skipped run says so on its LAST line.
+
+  Migration: `runImport(...)` now resolves to `{ manifest, tablesWritten, rowsWritten, tablesSkipped, rowsSkipped, fullyResumed }`. Read `.manifest` where you read the manifest before.
+
+  **Why replace is atomic now.** The all-or-nothing guarantee was written for the emptying step, and read — reasonably — as covering the run. A replace that died partway through the LOAD left the target emptied of its old rows and holding part of the new ones, measured on a live instance over sixteen minutes. There is no useful state for a replace to stop in, so it is a default rather than a flag you have to know about. It also closes the window that produced that failure: with the tables emptied and the load uncommitted, a concurrent writer in the application waits instead of inserting a row the bundle is about to insert too.
+
+  `--no-atomic` (CLI) / `atomic: false` (API) opts out. The trade is stated where it bites: every write to those tables waits for the load, and on postgres the bulk `COPY` loader cannot join a transaction it does not own — an atomic run now says that once rather than being quietly slower.
+
+  Two smaller things from the same report: `--mode replace` against a running instance warns about the empty-target window when it is NOT atomic, and the `--target api` upload reports progress per chunk plus a line explaining that the final request stays open for the whole import — sixteen minutes of silence is indistinguishable from a hang, and one operator killed a run that had finished.
+
+  **`voltro update` carries you across this** — codemod `0.44.0/01_import-outcome`.
+
+### Fixed
+
+- **@voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/data-transfer** — A write and its write-recorders now succeed or fail together on every SQL dialect, and the data importer's retry is idempotent.
+
+  A recorder (a versioning trail, an audit log) runs on the caller's connection and is ALLOWED to fail — a recorder that throws must take the write down with it, that is its contract. Outside a caller transaction the two were not one unit: the row's statement committed on its own, and the recorder's INSERT ran afterwards as a second autocommit statement. So a recorder that threw left a COMMITTED row behind a write that reported failure. Measured directly: `insert` throws, the row is in the table, and a second attempt at the same row is `ER_DUP_ENTRY` on PRIMARY.
+
+  Anything that retries a failed write then meets its own row. The data importer retries by design — it holds a row whose write failed and tries again once the remaining tables have streamed — so a `--mode replace` that had just emptied a table failed on a duplicate key IN that table. From outside, that is the impossible-looking thing: an import that emptied a table and then failed because something was already in it. Reproduced verbatim, including the table name and `[ER_DUP_ENTRY/1062]`, by putting the old retry back.
+
+  Both ends are closed, and they are independent on purpose:
+
+  - **The cause.** A table that HAS recorders writes inside a transaction now, so the row and the trail commit together or not at all — on mysql, mariadb, postgres, sqlite and mssql, verified by one suite that asks all five the same question. A table with no recorders — the default — takes the direct path unchanged; `recordsTable` is a Map-size check first, so it costs one comparison. - **The defence.** The importer's retry upserts instead of inserting in `replace` mode. That covers every OTHER way a write can land while reporting failure: a driver timeout on a write the server applied, a connection lost after the commit, a concurrent writer inserting the same key. It is sound precisely because the table was emptied by this same run — there is nothing in it that is not ours.
+
+  The test that pinned the divergence went red when the fix landed, exactly as its own note said it would, and is inverted with that note kept.
+
+---
+
+## [0.43.2] — 2026-08-18
+
+### Fixed
+
+- **@voltro/sql-mysql, @voltro/database, @voltro/cli** — The mysql-family binlog reader no longer keeps a table excluded after the very migration that fixed it.
+
+  A UNIQUE on an unbounded text column is a MariaDB hash long-unique, whose hidden `DB_ROW_HASH_n` column the reader can never account for — so the table is held out of binlog capture and the exclusion is reported. `voltro dev` builds its store BEFORE it migrates (kv, cross-replica broadcast and the analytics mirror all need one), so on a boot whose own auto-migration bounds the column, that finding was drawn from a schema that stopped existing about a second later. The exclusion then outlived its cause for the life of the process, and the message — correct when written, and typically the only error line in the boot log — went on describing the pre-migration database.
+
+  Three changes:
+
+  - `DataStore.refreshChangeCaptureExclusions()` (optional; implemented by the mysql-family store) re-runs the probe and re-points the LIVE reader, in both directions — schema work that CREATES the condition now excludes the table immediately instead of after three failed writes. `voltro dev` calls it once, after all its schema work. `voltro serve` needs no equivalent: it builds its store after every schema step and never applies DDL itself. - The definitive message now states its own durability — that it is the schema as read at reader attach, and that applying the remedy does not by itself lift the exclusion. - On a boot that will re-check, the finding is reported as a provisional note rather than as a verdict, so a boot that fixes the condition leaves no error line about it. The note escalates to the full verdict on its own if the re-check never runs. - Two reader fixes the re-check depended on: applying a new exclusion set now WAITS for a reconnect already in flight (it is what applies the set, so resolving before it landed meant the caller's next write hit the old filter), and the reconnect loop no longer keeps resuming from an offset it has just jumped away from — that turned one purged offset into a reconnect every watchdog interval, forever, delivering nothing.
+- **@voltro/data-transfer, @voltro/database, @voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/cli** — `voltro data import --mode replace` no longer leaves a target in neither state, and now works against schemas that have foreign keys.
+
+  The delete step ran table by table and stopped at the first refusal, so a run that could not finish left dozens of tables emptied and nothing loaded — and a second attempt destroyed more than the first, because it got further before hitting the same wall. The wall itself was not exotic: MySQL, MariaDB and SQL Server check a foreign key as each ROW is deleted, so a table that references ITSELF cannot be emptied by any ordering of the tables. `createdBy → actors` on the `actors` table is exactly that shape, and it is what an audit mixin on an actor table produces.
+
+  - `DataStore.emptyTables()` (per dialect) empties the whole set as one unit, in one transaction, with referential integrity suspended for the duration — `FOREIGN_KEY_CHECKS` on the mysql family, a multi-table `TRUNCATE` on postgres, `defer_foreign_keys` on sqlite, per-table `NOCHECK`/`WITH CHECK CHECK` on mssql. All-or-nothing on every engine, including under `--atomic`, where it runs on the transaction the import already holds. - A **pre-flight refusal**: if a table OUTSIDE the bundle holds rows referencing one inside it, the import refuses before deleting anything and names the tables, the columns and the row counts. Those rows cannot be restored from the bundle, so forcing it is not an option. An EMPTY outside table blocks nothing. - Table-level failures carry the driver's own reason and code, the way row-level failures already did. `truncate <table> failed: Failed to execute statement` fits every plausible cause equally; the classification that produced `foreign key <name>: … [ER_NO_REFERENCED_ROW_2/1452]` one level down now applies one level up. The word "truncate" is gone from the message too — the step issues DELETE, and naming a statement it does not run sends whoever reads it to reproduce the wrong thing. - A typed refusal reaching the `--target api` transport keeps its text: the admin import endpoint answers `409` with the reason instead of flattening it to `import failed`, on the one transport where the operator has no other way to see it.
+
+  The bulk empty emits no change events, where the per-table loop emitted one per row. An import through `--target api` now asks every live subscription to re-read once it lands — the coarse refresh the framework already uses after a broadcast gap — so neither the missing deletes nor a table the bundle carries EMPTY leaves a subscriber holding rows that are gone. Wired where the route is mounted, which is the one place both boot paths share.
+
+  On postgres the emptying is a `DELETE` per table, not a `TRUNCATE`, and the difference is not performance: postgres refuses `TRUNCATE` on a table with ANY incoming foreign key, rows or not, while the mysql family refuses a DELETE only when rows actually reference the doomed ones. A `TRUNCATE` version made an EMPTY table outside the bundle block a replace on postgres and not on mariadb — one import, refused on one engine and accepted on the other, over a table holding nothing.
+
+  `--target api` also no longer times out on a full bundle. Both api-target calls went through `fetch`, whose undici default gives up after 300 s — a bound on the caller's database size, on a call whose response arrives only when the import does. They wait as long as the instance needs now, stream the body instead of buffering the whole bundle, and take `--timeout <seconds>` when a deadline is wanted. If one is hit, the message says the instance is probably still importing — and gives different advice for `replace` than for the idempotent modes, since re-running the first while it is mid-flight would empty the target under it.
+
+  Two more, found by measuring rather than by reading:
+
+  - **`--atomic` on postgres could not import a bundle that needed the deferred-FK repair at all.** A failed statement aborts the transaction there, and that repair depends on a row whose parent has not loaded yet failing, being held, and being retried — so the first such row poisoned every write after it. Every tolerated write now runs inside a savepoint. Per-row savepoints measured 2.40x the time of none on 5 000 rows, so they are amortised: one savepoint per batch of 200, and a batch that fails rolls back whole and replays row by row. The mysql family and sqlite leave a transaction usable after a failed statement and pay nothing for any of this. - **The replace pre-flight asked the caller's snapshot.** Over `--target api` that is the app's DECLARED schema, which cannot show a table the app stopped declaring but the database still has — and rows in a table nobody declares are exactly the rows nobody is watching. `DataStore.incomingForeignKeys()` reads the live catalog per dialect; the snapshot remains the fallback for stores without one.
+
+  A bundle bigger than one chunk is now uploaded as a series of short requests, so a proxy body cap or an ingress read timeout has nothing large to choke on, and the switch is automatic — the packer's stream is buffered one chunk ahead, so a small bundle is sent exactly as before and nobody has to know in advance which table is the big one. The import still runs ONCE, at the end, over the whole bundle. Resume is byte-exact (`packBundle` is deterministic over a directory, which this package now asserts), guarded by a bundle key so a different bundle under the same upload id is refused rather than spliced into the partial one, and by a contiguity check so a mis-ordered append cannot produce an archive that only fails later during decode. `--chunk-size <mb>` overrides the 16 MiB default.
+
+---
+
 ## [0.43.1] — 2026-08-18
 
 ### Fixed

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { CDC_OFFSETS_TABLE } from '@voltro/database';
 import { CdcConfig } from '@voltro/database';
+import { ChangeCaptureExclusionRefresh } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
 import { ChangeStrategy } from '@voltro/database';
 import { ConfigError } from 'effect';
@@ -31,6 +32,22 @@ export declare interface BinlogCdcHandle {
     readonly stop: () => Promise<void>;
     /** Last position the reader has advanced past (for a final checkpoint). */
     readonly currentPosition: () => BinlogPosition | null;
+    /**
+     * Replace the undecodable-table set on a LIVE reader.
+     *
+     * Exists because the set is a property of the SCHEMA, and the schema can move
+     * after the reader attached — a boot that migrates in the same process is the
+     * ordinary case, not an exotic one. Without this the verdict taken at attach
+     * outlives its own cause: a table whose column got bounded seconds later stays
+     * excluded for the life of the process.
+     *
+     * Re-attaches only when the effective set CHANGED, because a re-attach costs a
+     * dropped replication connection and a resume — pointless when the answer is
+     * the same. Resumes from `currentPosition()`, so no event window is skipped.
+     *
+     * Returns whether it re-attached.
+     */
+    readonly setUndecodableTables: (tables: ReadonlyArray<string>) => Promise<boolean>;
 }
 
 export declare interface BinlogCdcOptions {
@@ -254,7 +271,24 @@ export declare class MysqlStore implements DataStore {
     private inflightTxns;
     private readonly log;
     private cdcHandle;
+    /** The reader's declared filter + the exclusions currently in force, so a
+     *  refresh can diff against the decision that is actually running. */
+    private cdcIncludeTables;
+    private cdcExcluded;
+    /** Owns what gets SAID about those exclusions, and when — including the
+     *  escalation that stands behind `exclusionRefreshFollows`. */
+    private readonly cdcReporter;
     private cdcCheckpointTimer;
+    /**
+     * A one-connection SQL runtime on the CDC credentials.
+     *
+     * The store's OWN pool runs as the app user, who does not have `REPLICATION
+     * CLIENT` — so `SHOW MASTER STATUS` fails there and every position question
+     * degraded to "start at the end". The replication connection has those grants
+     * by definition (it could not read a binlog otherwise), so asking over IT is
+     * the difference between knowing where the primary is and guessing.
+     */
+    private cdcAdminRuntime;
     private cdcPendingPosition;
     private cdcReplicaId;
     private cdcStreamName;
@@ -461,6 +495,30 @@ export declare class MysqlStore implements DataStore {
      * The gap being closed is specific: a plain write's statement commits ITSELF,
      * so the transport fires while this is still awaiting the driver.
      */
+    /**
+     * A write and its write-recorders, as ONE unit.
+     *
+     * Without this they are two: the row's statement commits on its own, and the
+     * recorder's INSERT is a second autocommit statement afterwards. A recorder
+     * that throws — which it is SUPPOSED to be able to do, that is the whole
+     * contract — then leaves a committed row behind a write that reported failure.
+     *
+     * Measured against MariaDB: `insert` throws, the row is in the table, and a
+     * second attempt at the same row is `ER_DUP_ENTRY` on PRIMARY. Any caller that
+     * retries a failed write — the data importer holds and retries by design —
+     * meets its own row and reports a duplicate-key error for a row nobody wrote
+     * twice. That reads like the impossible thing it looks like: "we replaced
+     * everything and then failed because something was already there."
+     *
+     * Only tables that HAVE a recorder pay for the transaction. `recordsTable` is
+     * a Map-size check first, so the default — no recorders — costs one comparison
+     * and takes the direct path exactly as before.
+     *
+     * Events are buffered and emitted after COMMIT, the same order the
+     * transactional view uses: a subscriber must not see a change that then rolls
+     * back.
+     */
+    private writeWithRecorders;
     private localWrite;
     insert(t: string, r: Row): Promise<Readonly<Record<string, unknown>>>;
     insertMany(t: string, rows: ReadonlyArray<Row>): Promise<readonly Readonly<Record<string, unknown>>[]>;
@@ -483,7 +541,27 @@ export declare class MysqlStore implements DataStore {
     /* Excluded from this release type: emitChange */
     /* Excluded from this release type: startCdcConsumer */
     /* Excluded from this release type: assertBinlogConfig */
-    /* Excluded from this release type: resolveBinlogEnd */
+    /**
+     * Resolve the current binlog (file, position). The statement DIVERGES
+     * by engine: MySQL 8.4 REMOVED `SHOW MASTER STATUS` in favour of
+     * `SHOW BINARY LOG STATUS`; MariaDB (and mysql < 8.4) only know
+     * `SHOW MASTER STATUS`. Pick by variant, then fall back to the other
+     * spelling so a mysql < 8.4 or a future rename still resolves. Both
+     * return the same `File`/`Position` columns. @internal
+     */
+    /**
+     * Does the server still have this binlog file?
+     *
+     * `SHOW BINARY LOGS` needs `REPLICATION CLIENT` (or `SUPER`), which is why it
+     * runs on the CDC credentials rather than the store's. A probe that cannot run
+     * answers `true`: refusing to resume on a question we could not ask would
+     * throw away a perfectly good offset, and the reader's existing purge recovery
+     * still covers the case we then get wrong.
+     */
+    private binlogFileExists;
+    private resolveBinlogEnd;
+    /** The primary's current binlog end, asked over the replication credentials. */
+    private resolveBinlogEndOverCdc;
     /* Excluded from this release type: readCdcOffset */
     /* Excluded from this release type: flushCdcOffset */
     /* Excluded from this release type: getInternalExecuteQuery */
@@ -494,6 +572,41 @@ export declare class MysqlStore implements DataStore {
     /* Excluded from this release type: getInternalExecuteDelete */
     /* Excluded from this release type: getInternalExecuteUpsert */
     /* Excluded from this release type: getInternalExecuteInsertIgnore */
+    /**
+     * Empty `tables` as one unit — see `DataStore.emptyTables`.
+     *
+     * The engine-specific half is why this cannot live in the importer: MySQL and
+     * MariaDB check a foreign key as each ROW is deleted, so no ordering of the
+     * TABLES can empty a table that references itself. `actors.createdBy →
+     * actors` is exactly that shape, it is the framework's own actor pattern, and
+     * it made `--mode replace` fail on the first parent table of any real schema.
+     * `FOREIGN_KEY_CHECKS` is the session switch that lets the whole set go at
+     * once; the final state satisfies every constraint because the caller reloads
+     * all of these tables next, and refuses beforehand if anything OUTSIDE the set
+     * points into it.
+     *
+     * Two details are load-bearing:
+     *
+     *   - The switch is SESSION-scoped, so it must be set on the connection the
+     *     deletes actually run on — hence one transaction, and hence `sql`
+     *     directly rather than the transactional VIEW (whose `deleteMany` walks
+     *     row by row, which is both the wrong shape here and unaffordable at
+     *     bundle scale).
+     *   - Restoring it is not optional and not conditional. A connection handed
+     *     back to the pool with checks off would silently accept dangling
+     *     references for every later caller, so the restore is a release step
+     *     that runs on success, on failure and on interrupt alike.
+     */
+    emptyTables(tables: ReadonlyArray<string>): Promise<void>;
+    /** See `DataStore.incomingForeignKeys`. `information_schema` is the catalog on
+     *  both engines of this family, and `REFERENCED_TABLE_NAME` is only set on the
+     *  rows that ARE foreign keys — so no join is needed to exclude the rest. */
+    incomingForeignKeys(tables: ReadonlyArray<string>): Promise<ReadonlyArray<{
+        from: string;
+        column: string;
+        to: string;
+    }>>;
+    /* Excluded from this release type: emptyTablesOn */
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
     /**
      * The DIALECT half of the shared transaction bracket
@@ -517,6 +630,18 @@ export declare class MysqlStore implements DataStore {
     get changeScope(): 'local' | 'fleet';
     injectExternalChange(event: ChangeEvent): void;
     run<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+    /**
+     * Re-run the undecodable probe against the CURRENT schema and hand the answer
+     * to the live reader. See `DataStore.refreshChangeCaptureExclusions`.
+     *
+     * Diffs in both directions on purpose. Re-admission is the direction a boot
+     * that migrates in-process needs; the opposite — schema work that CREATES an
+     * unbounded unique on a captured table — is the same staleness with the signs
+     * flipped, and it is the one that loses events quietly, since the reader keeps
+     * tailing a table it can no longer decode until the reconnect loop diagnoses
+     * it three failures later.
+     */
+    refreshChangeCaptureExclusions(): Promise<ChangeCaptureExclusionRefresh>;
     close(gracePeriodMs?: number): Promise<void>;
     /** Liveness probe — `SELECT 1`. Rejects if the pool can't answer. */
     ping(): Promise<void>;

package/dist/index.js

@@ -1,18 +1,18 @@
 import { MysqlClient as e } from "@effect/sql-mysql2";
 import { Config as t, Effect as n, Layer as r, ManagedRuntime as i, Option as a, Redacted as o, Schedule as s } from "effect";
-import { CDC_OFFSETS_TABLE as c, DEFAULT_ACQUIRE_TIMEOUT_MS as l, EagerCardinalityError as u, _voltroCdcOffsetsTable as d, attachEagerLoads as f, attributionFields as p, attributionKey as m, beginLocalWrite as h, bulkInsertLimitsFor as g, chunkRowsForInsert as _, compileEagerJson as v, compilePredicate as y, compileRawFragment as b, compileSelect as x, decodeRowsFromSchema as S, encodeRowForSchema as C, endLocalWrite as w, externalChangeEvent as T, getTable as E, hasEagerLoads as ee, isTableReactive as D, makeEagerFallbackReporter as te, observeDbOp as O, qualifyTable as ne, raiseChangeListenerCeiling as re, recordsTable as ie, registerPendingAttribution as k, requireTable as A, resolveEchoAttribution as j, runStoreTransaction as ae, runWriteRecorders as oe, stampGeneratedId as M, stampGeneratedIds as se, withCapturedAttribution as N } from "@voltro/database";
-import { EventEmitter as ce } from "node:events";
-import { createLogger as P } from "@voltro/logger";
-import { SqlClient as F, TransactionConnection as I } from "@effect/sql/SqlClient";
+import { CDC_OFFSETS_TABLE as c, DEFAULT_ACQUIRE_TIMEOUT_MS as l, EagerCardinalityError as u, _voltroCdcOffsetsTable as d, attachEagerLoads as f, attributionFields as p, attributionKey as m, beginLocalWrite as h, bulkInsertLimitsFor as g, chunkRowsForInsert as _, compileEagerJson as v, compilePredicate as y, compileRawFragment as b, compileSelect as x, decodeRowsFromSchema as S, encodeRowForSchema as C, endLocalWrite as w, externalChangeEvent as T, getTable as E, hasEagerLoads as D, isTableReactive as O, makeEagerFallbackReporter as k, observeDbOp as A, qualifyTable as j, raiseChangeListenerCeiling as M, recordsTable as N, registerPendingAttribution as ee, requireTable as te, resolveEchoAttribution as ne, runStoreTransaction as re, runWriteRecorders as ie, stampGeneratedId as P, stampGeneratedIds as ae, withCapturedAttribution as F } from "@voltro/database";
+import { EventEmitter as oe } from "node:events";
+import { createLogger as I } from "@voltro/logger";
+import { SqlClient as L, TransactionConnection as R } from "@effect/sql/SqlClient";
 //#region src/sqlLayer.ts
-var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
+var se = (e) => e ? { rejectUnauthorized: !1 } : void 0, ce = (e) => {
 	let t = e.acquireTimeoutMs ?? l;
 	return t > 0 ? t : void 0;
-}, L = (e) => {
+}, le = (e) => {
 	let t = e.acquireQueueLimit;
 	return t !== void 0 && t > 0 ? t : void 0;
-}, R = (e) => {
-	let t = e.ssl === void 0 ? void 0 : le(e.ssl), n = ue(e), r = L(e);
+}, ue = (e) => {
+	let t = e.ssl === void 0 ? void 0 : se(e.ssl), n = ce(e), r = le(e);
 	return {
 		...t === void 0 ? {} : { ssl: t },
 		...n === void 0 ? {} : { connectTimeout: n },
@@ -24,7 +24,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	username: t.succeed(n.username),
 	password: t.succeed(o.make(n.password)),
 	database: t.succeed(n.database),
-	poolConfig: t.succeed(R(n)),
+	poolConfig: t.succeed(ue(n)),
 	...n.maxConnections === void 0 ? {} : { maxConnections: t.succeed(n.maxConnections) }
 }), B = (e) => {
 	let t = e.get("sslmode");
@@ -70,69 +70,103 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 }, H = (e) => z(V(e)), U = (e, t) => e === null ? !1 : t === null ? !0 : e.filename === t.filename ? e.position > t.position : e.filename > t.filename, de = (e) => e.msSinceProgress < e.stallThresholdMs ? "healthy" : e.primary !== null && !U(e.primary, e.reader) ? "idle-caught-up" : "reconnect", fe = (e) => (e instanceof Error ? e.message : String(e ?? "")).includes("schema changed between binlog event and metadata fetch"), pe = (e) => {
 	let t = e instanceof Error ? e.message : String(e ?? "");
 	return /Table\s+[^\s.]+\.(\S+)\s+schema changed between binlog event and metadata fetch/.exec(t)?.[1] ?? null;
-}, me = "\n  SELECT DISTINCT s.TABLE_NAME AS tableName\n  FROM information_schema.STATISTICS s\n  JOIN information_schema.COLUMNS c\n    ON c.TABLE_SCHEMA = s.TABLE_SCHEMA\n   AND c.TABLE_NAME  = s.TABLE_NAME\n   AND c.COLUMN_NAME = s.COLUMN_NAME\n  WHERE s.TABLE_SCHEMA = DATABASE()\n    AND s.NON_UNIQUE = 0\n    AND s.SUB_PART IS NULL\n    AND c.DATA_TYPE IN ('text','tinytext','mediumtext','longtext','blob','tinyblob','mediumblob','longblob')\n", W = (e) => `cdc: table '${e}' is EXCLUDED from binlog capture — its row image carries a hidden column the reader cannot account for. Cause: a UNIQUE constraint on an UNBOUNDED text column, which MariaDB backs with a HASH long-unique index; that index adds a hidden DB_ROW_HASH_n column to the row, present in the binlog and absent from information_schema.COLUMNS. Remedy: bound the column — text().maxLength(n) — so the constraint becomes an ordinary B-tree index with no hidden column. ALTER TABLE FORCE does NOT help: the rebuild recreates the index and the hidden column. Until then, cross-instance change events for this table are lost; own-node reactivity is unaffected (writes still emit inline).`, he = 3e5, ge = 3, _e = (e, t) => {
-	let n = [...e.filter((e) => t - e < he), t];
+}, me = "\n  SELECT DISTINCT s.TABLE_NAME AS tableName\n  FROM information_schema.STATISTICS s\n  JOIN information_schema.COLUMNS c\n    ON c.TABLE_SCHEMA = s.TABLE_SCHEMA\n   AND c.TABLE_NAME  = s.TABLE_NAME\n   AND c.COLUMN_NAME = s.COLUMN_NAME\n  WHERE s.TABLE_SCHEMA = DATABASE()\n    AND s.NON_UNIQUE = 0\n    AND s.SUB_PART IS NULL\n    AND c.DATA_TYPE IN ('text','tinytext','mediumtext','longtext','blob','tinyblob','mediumblob','longblob')\n", he = "This verdict is the schema as read when the reader attached; applying the remedy does not lift it by itself. A boot that migrates in-process re-checks it once its schema work is done and re-admits the table in the same run; otherwise it holds until the process restarts.", W = (e) => `cdc: table '${e}' is EXCLUDED from binlog capture — its row image carries a hidden column the reader cannot account for. Cause: a UNIQUE constraint on an UNBOUNDED text column, which MariaDB backs with a HASH long-unique index; that index adds a hidden DB_ROW_HASH_n column to the row, present in the binlog and absent from information_schema.COLUMNS. Remedy: bound the column — text().maxLength(n) — so the constraint becomes an ordinary B-tree index with no hidden column. ALTER TABLE FORCE does NOT help: the rebuild recreates the index and the hidden column. Until then, cross-instance change events for this table are lost; own-node reactivity is unaffected (writes still emit inline). ${he}`, ge = (e) => `cdc: table '${e}' looks undecodable (a UNIQUE on an UNBOUNDED text column → MariaDB hash long-unique → a hidden DB_ROW_HASH_n column in the row image). Held OUT of binlog capture for now and re-checked after this boot's schema work — a migration that bounds the column re-admits it in the same run. Not a verdict yet; the definitive line follows.`, _e = (e) => `cdc: table '${e}' re-admitted to binlog capture — the hidden-column condition is gone (the schema moved since the reader attached). Cross-instance change events for it flow again.`, ve = 12e4, ye = (e, t = ve) => {
+	let n = null, r = [], i = () => {
+		n &&= (clearTimeout(n), null), r = [];
+	};
 	return {
-		verdict: n.length >= ge ? "persistent" : "backlog",
+		announce: (a, o) => {
+			if (i(), a.length !== 0) {
+				if (!o) {
+					for (let t of a) e("error", W(t));
+					return;
+				}
+				for (let t of a) e("warn", ge(t));
+				r = a, n = setTimeout(() => {
+					let i = r;
+					n = null, r = [];
+					for (let n of i) e("error", `${W(n)} (Held provisionally for ${Math.round(t / 1e3)}s awaiting a post-migration re-check that never ran; standing by the reading taken at attach.)`);
+				}, t), n.unref && n.unref();
+			}
+		},
+		settle: (t) => {
+			i();
+			for (let n of t.stillExcluded) e("error", W(n));
+			for (let n of t.newlyExcluded) e("error", W(n));
+			for (let n of t.readmitted) e("info", _e(n));
+		},
+		dispose: i
+	};
+}, be = (e, t) => {
+	let n = new Set(e), r = new Set(t);
+	return {
+		stillExcluded: t.filter((e) => n.has(e)),
+		readmitted: e.filter((e) => !r.has(e)),
+		newlyExcluded: t.filter((e) => !n.has(e))
+	};
+}, xe = 3e5, Se = 3, Ce = (e, t) => {
+	let n = [...e.filter((e) => t - e < xe), t];
+	return {
+		verdict: n.length >= Se ? "persistent" : "backlog",
 		hits: n
 	};
-}, ve = /* @__PURE__ */ new Set([
+}, we = /* @__PURE__ */ new Set([
 	"writerows",
 	"updaterows",
 	"deleterows"
-]), ye = /\b(alter|rename|drop|create)\s+(table|column)?/i, G = (e) => new Promise((t) => setTimeout(t, e)), K = async (e) => {
-	let t = P({ scope: `voltro:${e.variant}:cdc` }), n;
+]), Te = /\b(alter|rename|drop|create)\s+(table|column)?/i, G = (e) => new Promise((t) => setTimeout(t, e)), K = async (e) => {
+	let t = I({ scope: `voltro:${e.variant}:cdc` }), n;
 	try {
 		n = (await import("@vlasky/zongji")).default;
 	} catch (t) {
 		throw Error(`changeStrategy='cdc' on ${e.variant} requires the '@vlasky/zongji' optional dependency. Install it (it ships as an optionalDependency of @voltro/sql-mysql) to enable binlog CDC.`, { cause: t });
 	}
-	let r = new Set(e.undecodableTables ?? []), i = e.includeTables ? new Set(e.includeTables.filter((e) => !r.has(e))) : null, a = e.connection.database, o = e.startPosition?.filename ?? null, s = e.startPosition ?? null, c = (t, n) => S([n], t, e.variant)[0], l = null, u = !1, d = 0, f = Date.now(), p = !1, m = /* @__PURE__ */ new Map(), h = /* @__PURE__ */ new Set(), g = null, _ = e.stallThresholdMs ?? 25e3, v = e.watchdogIntervalMs ?? 15e3, y = () => {
+	let r = new Set(e.undecodableTables ?? []), i = e.includeTables ? new Set(e.includeTables) : null, a = e.connection.database, o = e.startPosition?.filename ?? null, s = e.startPosition ?? null, c = (t, n) => S([n], t, e.variant)[0], l = null, u = !1, d = 0, f = Date.now(), p = !1, m = null, h = /* @__PURE__ */ new Map(), g = /* @__PURE__ */ new Set(), _ = null, v = e.stallThresholdMs ?? 25e3, y = e.watchdogIntervalMs ?? 15e3, b = () => {
 		f = Date.now();
-	}, b = (n) => {
-		y();
-		let r = n.getEventName();
-		if (r === "rotate" && n.binlogName) {
+	}, x = (n) => {
+		b();
+		let u = n.getEventName();
+		if (u === "rotate" && n.binlogName) {
 			o = n.binlogName;
 			return;
 		}
-		if (r === "query" && n.query && ye.test(n.query)) {
+		if (u === "query" && n.query && Te.test(n.query)) {
 			l && (l.tableMap = {});
 			return;
 		}
 		if (n.nextPosition && o && (s = {
 			filename: o,
 			position: n.nextPosition
-		}, e.onPosition?.(s)), !ve.has(r)) return;
-		let u = n.tableMap[n.tableId];
-		if (!u || u.parentSchema !== a) return;
-		let d = u.tableName;
-		if (!d.startsWith("_voltro_") && !(i && !i.has(d))) try {
-			if (r === "writerows") for (let t of n.rows) e.onChange({
-				table: d,
+		}, e.onPosition?.(s)), !we.has(u)) return;
+		let d = n.tableMap[n.tableId];
+		if (!d || d.parentSchema !== a) return;
+		let f = d.tableName;
+		if (!f.startsWith("_voltro_") && !(i && !i.has(f)) && !r.has(f)) try {
+			if (u === "writerows") for (let t of n.rows) e.onChange({
+				table: f,
 				op: "insert",
 				old: null,
-				new: c(d, t)
+				new: c(f, t)
 			});
-			else if (r === "deleterows") for (let t of n.rows) e.onChange({
-				table: d,
+			else if (u === "deleterows") for (let t of n.rows) e.onChange({
+				table: f,
 				op: "delete",
-				old: c(d, t),
+				old: c(f, t),
 				new: null
 			});
 			else for (let t of n.rows) e.onChange({
-				table: d,
+				table: f,
 				op: "update",
-				old: c(d, t.before),
-				new: c(d, t.after)
+				old: c(f, t.before),
+				new: c(f, t.after)
 			});
 		} catch (n) {
 			t.warn("cdc: failed to map a row event", {
-				table: d,
-				name: r
+				table: f,
+				name: u
 			}, n), e.onError?.(n);
 		}
-	}, x = (t) => {
+	}, C = (t) => {
 		let n = {
 			serverId: e.serverId,
 			includeEvents: [
@@ -146,10 +180,10 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			]
 		};
 		return e.includeTables && e.includeTables.length > 0 && (n.includeSchema = { [a]: e.includeTables.filter((e) => !r.has(e)) }), t ? (n.filename = t.filename, n.position = t.position) : n.startAtEnd = !0, n;
-	}, C = (e) => {
+	}, w = (e) => {
 		let t = e;
 		return t?.errno === 1236 || String(t?.code ?? "").includes("ER_MASTER_FATAL_ERROR_READING_BINLOG");
-	}, w = (r) => new Promise((i, a) => {
+	}, T = (r) => new Promise((i, a) => {
 		let o = new n({
 			host: e.connection.host,
 			port: e.connection.port,
@@ -160,8 +194,8 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		});
 		l = o;
 		let s = !1;
-		o.on("binlog", b), o.on("ready", () => {
-			y(), !s && (s = !0, d = 0, t.info("cdc: binlog reader attached", {
+		o.on("binlog", x), o.on("ready", () => {
+			b(), !s && (s = !0, d = 0, t.info("cdc: binlog reader attached", {
 				serverId: e.serverId,
 				from: r ?? "current-end"
 			}), i());
@@ -170,82 +204,101 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 				s = !0, a(e instanceof Error ? e : Error(String(e)));
 				return;
 			}
-			T("binlog reader error", e);
-		}), o.start(x(r));
-	}), T = async (n, i) => {
-		if (!(u || p)) {
-			p = !0, t.warn(`cdc: reconnecting — ${n}`, {}, i instanceof Error ? i : void 0), e.onError?.(i);
-			try {
-				let n = i;
-				for (; !u;) {
-					try {
-						l?.stop();
-					} catch {}
-					if (d++, await G(Math.min(3e4, 500 * 2 ** Math.min(d, 6))), u) return;
-					let i = s, a = C(n), c = !a && fe(n), f = !1;
-					if (c) {
-						let e = pe(n), i = e ?? "<unknown>", { verdict: a, hits: o } = _e(m.get(i) ?? [], Date.now());
-						m.set(i, o), f = a === "persistent", f && !h.has(i) && (h.add(i), e !== null && r.add(e), t.error(W(i)));
-					}
-					(a || c) && (f || t.warn(c ? "cdc: un-replayable backlog event (schema moved past it) — jumping to current end + self-heal" : "cdc: binlog gap (purged/failover) — jumping to current end + self-heal"), i = e.resolveStartPosition ? await e.resolveStartPosition().catch(() => null) : null, o = i?.filename ?? null, f || e.onResync?.());
-					try {
-						await w(i), d = 0, y();
-						return;
-					} catch (e) {
-						n = e;
-					}
+			D("binlog reader error", e);
+		}), o.start(C(r));
+	}), E = async (n, i) => {
+		p = !0, t.warn(`cdc: reconnecting — ${n}`, {}, i instanceof Error ? i : void 0), e.onError?.(i);
+		try {
+			let n = i;
+			for (; !u;) {
+				try {
+					l?.stop();
+				} catch {}
+				if (d++, await G(Math.min(3e4, 500 * 2 ** Math.min(d, 6))), u) return;
+				let i = s, a = w(n), c = !a && fe(n), f = !1;
+				if (c) {
+					let e = pe(n), i = e ?? "<unknown>", { verdict: a, hits: o } = Ce(h.get(i) ?? [], Date.now());
+					h.set(i, o), f = a === "persistent", f && !g.has(i) && (g.add(i), e !== null && r.add(e), t.error(W(i)));
+				}
+				(a || c) && (f || t.warn(c ? "cdc: un-replayable backlog event (schema moved past it) — jumping to current end + self-heal" : "cdc: binlog gap (purged/failover) — jumping to current end + self-heal"), i = e.resolveStartPosition ? await e.resolveStartPosition().catch(() => null) : null, o = i?.filename ?? null, s = i, f || e.onResync?.());
+				try {
+					await T(i), d = 0, b();
+					return;
+				} catch (e) {
+					n = e;
 				}
-			} finally {
-				p = !1;
 			}
+		} finally {
+			p = !1;
 		}
-	};
+	}, D = (e, t) => u ? Promise.resolve() : p ? m ?? Promise.resolve() : (m = E(e, t).finally(() => {
+		m = null;
+	}), m);
 	try {
-		await w(e.startPosition ?? null);
+		await T(e.startPosition ?? null);
 	} catch (n) {
-		if (C(n) && e.startPosition) {
+		if (w(n) && e.startPosition) {
 			t.warn("cdc: persisted offset purged — starting at current end + self-heal");
 			try {
 				l?.stop();
 			} catch {}
 			let n = e.resolveStartPosition ? await e.resolveStartPosition().catch(() => null) : null;
-			o = n?.filename ?? null, e.onResync?.(), await G(500), await w(n);
+			o = n?.filename ?? null, s = n, e.onResync?.(), await G(500), await T(n);
 		} else throw n;
 	}
-	let E = async () => {
-		if (u || p || Date.now() - f < _) return;
+	let O = async () => {
+		if (u || p || Date.now() - f < v) return;
 		let n = null;
 		if (e.resolveStartPosition && (n = await e.resolveStartPosition().catch(() => null)), u || p) return;
 		let r = de({
 			msSinceProgress: Date.now() - f,
-			stallThresholdMs: _,
+			stallThresholdMs: v,
 			primary: n,
 			reader: s
 		});
 		if (r !== "reconnect") {
-			r === "idle-caught-up" && y();
+			r === "idle-caught-up" && b();
 			return;
 		}
 		t.warn("cdc: watchdog detected a stalled reader — forcing reconnect", {
 			reader: s,
 			primary: n,
 			stalledForMs: Date.now() - f
-		}), T("watchdog: stream stalled (no events while primary advanced)", /* @__PURE__ */ Error("cdc watchdog stall"));
+		}), D("watchdog: stream stalled (no events while primary advanced)", /* @__PURE__ */ Error("cdc watchdog stall"));
 	};
-	return g = setInterval(() => {
-		E();
-	}, v), g.unref && g.unref(), {
+	return _ = setInterval(() => {
+		O();
+	}, y), _.unref && _.unref(), {
 		stop: async () => {
-			u = !0, g &&= (clearInterval(g), null);
+			u = !0, _ &&= (clearInterval(_), null);
 			try {
 				l?.stop();
 			} catch (e) {
 				t.warn("cdc: error stopping binlog reader", {}, e);
 			}
 		},
-		currentPosition: () => s
+		currentPosition: () => s,
+		setUndecodableTables: async (t) => {
+			let n = new Set(t);
+			if (n.size === r.size && [...n].every((e) => r.has(e))) return !1;
+			r.clear();
+			for (let e of n) r.add(e);
+			if (u) return !1;
+			if (p) return await (m ?? Promise.resolve()), !0;
+			p = !0;
+			try {
+				try {
+					l?.stop();
+				} catch {}
+				return await G(500), !u && (s === null && e.onResync?.(), await T(s), b(), !0);
+			} catch (e) {
+				return p = !1, await D("re-attach after an exclusion refresh failed", e), !1;
+			} finally {
+				p = !1;
+			}
+		}
 	};
-}, be = /* @__PURE__ */ new Set(["1213", "1205"]), xe = (e) => {
+}, Ee = /* @__PURE__ */ new Set(["1213", "1205"]), De = (e) => {
 	let t = e;
 	for (let e = 0; e < 5 && typeof t == "object" && t; e++) {
 		let e = t.errno;
@@ -255,8 +308,8 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		t = t.cause;
 	}
 }, q = (e) => {
-	let t = xe(e);
-	return t !== void 0 && be.has(t);
+	let t = De(e);
+	return t !== void 0 && Ee.has(t);
 }, J = (e) => q(e) ? "retry" : "noRetry", Y = (e) => {
 	if (e == null) return "null";
 	let t = typeof e;
@@ -266,19 +319,19 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	if (Array.isArray(e)) return `[${e.map(Y).join(",")}]`;
 	let n = e;
 	return `{${Object.keys(n).sort().map((e) => `${JSON.stringify(e)}:${Y(n[e])}`).join(",")}}`;
-}, Se = (e) => {
+}, Oe = (e) => {
 	let t = Y(e), n = 2166136261;
 	for (let e = 0; e < t.length; e++) n ^= t.charCodeAt(e), n = Math.imul(n, 16777619);
 	return (n >>> 0).toString(36);
-}, Ce = (e, t) => {
+}, ke = (e, t) => {
 	let n = setTimeout(e, t);
 	typeof n.unref == "function" && n.unref();
-}, we = class {
+}, Ae = class {
 	variant;
 	ttlMs;
 	schedule;
 	seen = /* @__PURE__ */ new Map();
-	constructor(e, t = 6e4, n = Ce) {
+	constructor(e, t = 6e4, n = ke) {
 		this.variant = e, this.ttlMs = t, this.schedule = n;
 	}
 	key(e) {
@@ -292,7 +345,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		} catch {
 			r = t;
 		}
-		return `${e.table} ${e.op} ${String(n)} ${Se(r)}`;
+		return `${e.table} ${e.op} ${String(n)} ${Oe(r)}`;
 	}
 	admit(e) {
 		let t = this.key(e);
@@ -312,9 +365,9 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	1062,
 	1586
 ]), Z = async (e) => {
-	let t = e.variant ?? "mysql", n = P({ scope: `voltro:${t}` }), a = e.changeStrategy ?? "inline", o = a;
+	let t = e.variant ?? "mysql", n = I({ scope: `voltro:${t}` }), a = e.changeStrategy ?? "inline", o = a;
 	a === "cdc" && !e.cdcConfig && (n.warn("changeStrategy='cdc' requires cdcConfig (serverId + connection); falling back to 'inline'."), o = "inline");
-	let s = e.tracerLayer ? r.mergeAll(e.sqlLayer, e.tracerLayer) : e.sqlLayer, c = i.make(s), l = new Q(await c.runPromise(F), c, t, o);
+	let s = e.tracerLayer ? r.mergeAll(e.sqlLayer, e.tracerLayer) : e.sqlLayer, c = i.make(s), l = new Q(await c.runPromise(L), c, t, o);
 	return o === "cdc" && e.cdcConfig && await l.startCdcConsumer(e.cdcConfig), l;
 }, Q = class e {
 	sql;
@@ -326,20 +379,26 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	inflightTxns = 0;
 	log;
 	cdcHandle = null;
+	cdcIncludeTables = void 0;
+	cdcExcluded = [];
+	cdcReporter;
 	cdcCheckpointTimer = null;
+	cdcAdminRuntime = null;
 	cdcPendingPosition = null;
 	cdcReplicaId = "";
 	cdcStreamName = "default";
 	cdcGate;
 	reportEagerFallback;
 	constructor(e, t, n, r = "inline", i = null, a, o) {
-		this.sql = e, this.runtime = t, this.variant = n, this.changeStrategy = r, this.namespace = i, this.log = P({ scope: `voltro:${n}` }), this.reportEagerFallback = te(this.log), this.emitter = a ?? new ce(), re(this.emitter), this.cdcGate = o ?? new we(n);
+		this.sql = e, this.runtime = t, this.variant = n, this.changeStrategy = r, this.namespace = i, this.log = I({ scope: `voltro:${n}` }), this.cdcReporter = ye((e, t) => {
+			e === "error" ? this.log.error(t) : e === "warn" ? this.log.warn(t) : this.log.info(t);
+		}), this.reportEagerFallback = k(this.log), this.emitter = a ?? new oe(), M(this.emitter), this.cdcGate = o ?? new Ae(n);
 	}
 	withNamespace(t) {
 		return t === this.namespace ? this : new e(this.sql, this.runtime, this.variant, this.changeStrategy, t, this.emitter, this.cdcGate);
 	}
 	nsT(e) {
-		return ne(this.namespace, e);
+		return j(this.namespace, e);
 	}
 	get dialectId() {
 		return this.variant;
@@ -351,7 +410,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		};
 	}
 	async executeQuery(e, t, r) {
-		let i = x(e, this.sql, this.namespace), a = t ? n.provideService(i, I, t) : i, o = await O(this.variant, "select", () => this.runtime.runPromise(a));
+		let i = x(e, this.sql, this.namespace), a = t ? n.provideService(i, R, t) : i, o = await A(this.variant, "select", () => this.runtime.runPromise(a));
 		return S(o, e.table, this.variant);
 	}
 	get supportsInsertReturning() {
@@ -364,10 +423,10 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		return !1;
 	}
 	async executeInsert(e, t, r, i, a) {
-		t = M(e, t);
+		t = P(e, t);
 		let o = this.sql;
 		if (this.supportsInsertReturning) {
-			let s = o`INSERT INTO ${o(this.nsT(e))} ${o.insert(C(t, e))} RETURNING *`, c = r ? n.provideService(s, I, r) : s, l = (await this.runtime.runPromise(c))[0];
+			let s = o`INSERT INTO ${o(this.nsT(e))} ${o.insert(C(t, e))} RETURNING *`, c = r ? n.provideService(s, R, r) : s, l = (await this.runtime.runPromise(c))[0];
 			if (!l) throw Error(`MysqlStore.insert: no row returned for table '${e}'`);
 			return await this.routeEvent({
 				table: e,
@@ -386,9 +445,9 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 				new: t
 			}, i, r, a), t;
 		}
-		let l = o`INSERT INTO ${o(this.nsT(e))} ${o.insert(s)}`, u = r ? n.provideService(l, I, r) : l;
+		let l = o`INSERT INTO ${o(this.nsT(e))} ${o.insert(s)}`, u = r ? n.provideService(l, R, r) : l;
 		await this.runtime.runPromise(u);
-		let d = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${c}`, f = r ? n.provideService(d, I, r) : d, p = (await this.runtime.runPromise(f))[0];
+		let d = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${c}`, f = r ? n.provideService(d, R, r) : d, p = (await this.runtime.runPromise(f))[0];
 		if (!p) throw Error(`MysqlStore.insert: row not found post-insert in '${e}'`);
 		return await this.routeEvent({
 			table: e,
@@ -401,16 +460,16 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		let i = this.sql;
 		return this.runPinned(r, (r) => n.gen(this, function* () {
 			let a = i`INSERT INTO ${i(this.nsT(e))} ${i.insert(t)}`;
-			yield* n.provideService(a, I, r);
-			let o = (yield* n.provideService(i`SELECT LAST_INSERT_ID() AS ${i("lastId")}`, I, r))[0]?.lastId;
-			return o === void 0 || Number(o) === 0 ? yield* n.fail(/* @__PURE__ */ Error(`MysqlStore.insert: LAST_INSERT_ID() returned no id for '${e}' — is the primary key AUTO_INCREMENT?`)) : (yield* n.provideService(i`SELECT * FROM ${i(this.nsT(e))} WHERE ${i("id")} = ${o}`, I, r))[0] || (yield* n.fail(/* @__PURE__ */ Error(`MysqlStore.insert: row not found post-insert in '${e}'`)));
+			yield* n.provideService(a, R, r);
+			let o = (yield* n.provideService(i`SELECT LAST_INSERT_ID() AS ${i("lastId")}`, R, r))[0]?.lastId;
+			return o === void 0 || Number(o) === 0 ? yield* n.fail(/* @__PURE__ */ Error(`MysqlStore.insert: LAST_INSERT_ID() returned no id for '${e}' — is the primary key AUTO_INCREMENT?`)) : (yield* n.provideService(i`SELECT * FROM ${i(this.nsT(e))} WHERE ${i("id")} = ${o}`, R, r))[0] || (yield* n.fail(/* @__PURE__ */ Error(`MysqlStore.insert: row not found post-insert in '${e}'`)));
 		}), "insert");
 	}
 	async runPinned(e, t, r) {
 		if (e) return this.runtime.runPromise(t(e));
 		this.inflightTxns++;
 		try {
-			let e = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(I), (e) => a.isNone(e) ? n.fail(/* @__PURE__ */ Error(`MysqlStore.${r}: TransactionConnection missing.`)) : t(e.value)))), i = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(q)), o = e.pipe(n.retry(i), n.withSpan(`store.${r}`, { attributes: {
+			let e = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(R), (e) => a.isNone(e) ? n.fail(/* @__PURE__ */ Error(`MysqlStore.${r}: TransactionConnection missing.`)) : t(e.value)))), i = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(q)), o = e.pipe(n.retry(i), n.withSpan(`store.${r}`, { attributes: {
 				"db.system": this.variant,
 				"db.operation": r
 			} }));
@@ -420,16 +479,16 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		}
 	}
 	async executeInsertMany(e, t, r, i, a) {
-		if (t = se(e, t), t.length === 0) return [];
+		if (t = ae(e, t), t.length === 0) return [];
 		let o = this.sql, s = t.map((t) => C(t, e)), c = _(s, g(this.variant));
 		if (this.supportsInsertReturning) {
 			let t = (t) => o`INSERT INTO ${o(this.nsT(e))} ${o.insert(t)} RETURNING *`, s;
 			if (c.length === 1) {
-				let e = t(c[0]), i = r ? n.provideService(e, I, r) : e;
+				let e = t(c[0]), i = r ? n.provideService(e, R, r) : e;
 				s = await this.runtime.runPromise(i);
 			} else if (r) {
 				let e = [];
-				for (let i of c) e.push(...await this.runtime.runPromise(n.provideService(t(i), I, r)));
+				for (let i of c) e.push(...await this.runtime.runPromise(n.provideService(t(i), R, r)));
 				s = e;
 			} else s = await this.runtime.runPromise(o.withTransaction(n.map(n.forEach(c, t, { concurrency: 1 }), (e) => e.flat())));
 			for (let t of s) await this.routeEvent({
@@ -454,16 +513,16 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		if (l.some((e) => e === void 0)) throw Error("MysqlStore.insertMany: rows mix client-supplied and missing 'id's — supply an id for every row or none (AUTO_INCREMENT recovery).");
 		let u = (t) => o`INSERT INTO ${o(this.nsT(e))} ${o.insert(t)}`;
 		if (c.length === 1) {
-			let e = r ? n.provideService(u(c[0]), I, r) : u(c[0]);
+			let e = r ? n.provideService(u(c[0]), R, r) : u(c[0]);
 			await this.runtime.runPromise(e);
-		} else if (r) for (let e of c) await this.runtime.runPromise(n.provideService(u(e), I, r));
+		} else if (r) for (let e of c) await this.runtime.runPromise(n.provideService(u(e), R, r));
 		else await this.runtime.runPromise(o.withTransaction(n.forEach(c, u, {
 			concurrency: 1,
 			discard: !0
 		})));
 		let d = _(l.map((e) => ({ id: e })), g(this.variant)), f = [];
 		for (let t of d) {
-			let i = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} IN ${o.in(t.map((e) => e.id))}`, a = r ? n.provideService(i, I, r) : i;
+			let i = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} IN ${o.in(t.map((e) => e.id))}`, a = r ? n.provideService(i, R, r) : i;
 			f.push(...await this.runtime.runPromise(a));
 		}
 		let p = new Map(f.map((e) => [e.id, e])), m = l.map((e) => p.get(e)).filter((e) => e !== void 0);
@@ -481,19 +540,19 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			let a = [];
 			for (let o of t) {
 				let t = i`INSERT INTO ${i(this.nsT(e))} ${i.insert(o)}`;
-				yield* n.provideService(t, I, r);
-				let s = (yield* n.provideService(i`SELECT LAST_INSERT_ID() AS ${i("firstId")}`, I, r))[0]?.firstId;
+				yield* n.provideService(t, R, r);
+				let s = (yield* n.provideService(i`SELECT LAST_INSERT_ID() AS ${i("firstId")}`, R, r))[0]?.firstId;
 				if (s === void 0 || Number(s) === 0) return yield* n.fail(/* @__PURE__ */ Error(`MysqlStore.insertMany: LAST_INSERT_ID() returned no id for '${e}' — is the primary key AUTO_INCREMENT?`));
-				let c = Number(s), l = yield* n.provideService(i`SELECT * FROM ${i(this.nsT(e))} WHERE ${i("id")} BETWEEN ${c} AND ${c + o.length - 1} ORDER BY ${i("id")} ASC`, I, r);
+				let c = Number(s), l = yield* n.provideService(i`SELECT * FROM ${i(this.nsT(e))} WHERE ${i("id")} BETWEEN ${c} AND ${c + o.length - 1} ORDER BY ${i("id")} ASC`, R, r);
 				a.push(...l);
 			}
 			return a;
 		}), "insert");
 	}
 	async executePatchJson(e, t, r, i, a, o, s) {
-		let c = this.sql, l = r.split("."), u = l[0], d = l.slice(1), f = JSON.stringify(i ?? null), p = d.length === 0 ? "$" : `$.${d.join(".")}`, m = c`UPDATE ${c(this.nsT(e))} SET ${c(u)} = JSON_SET(COALESCE(${c(u)}, '{}'), ${p}, CAST(${f} AS JSON)) WHERE ${c("id")} = ${t}`, h = a ? n.provideService(m, I, a) : m, g = await this.runtime.runPromise(h);
+		let c = this.sql, l = r.split("."), u = l[0], d = l.slice(1), f = JSON.stringify(i ?? null), p = d.length === 0 ? "$" : `$.${d.join(".")}`, m = c`UPDATE ${c(this.nsT(e))} SET ${c(u)} = JSON_SET(COALESCE(${c(u)}, '{}'), ${p}, CAST(${f} AS JSON)) WHERE ${c("id")} = ${t}`, h = a ? n.provideService(m, R, a) : m, g = await this.runtime.runPromise(h);
 		if (g && typeof g.affectedRows == "number" && g.affectedRows === 0) return null;
-		let _ = c`SELECT * FROM ${c(this.nsT(e))} WHERE ${c("id")} = ${t}`, v = a ? n.provideService(_, I, a) : _, y = (await this.runtime.runPromise(v))[0];
+		let _ = c`SELECT * FROM ${c(this.nsT(e))} WHERE ${c("id")} = ${t}`, v = a ? n.provideService(_, R, a) : _, y = (await this.runtime.runPromise(v))[0];
 		return y ? (await this.routeEvent({
 			table: e,
 			op: "update",
@@ -504,7 +563,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	async executeUpdate(e, t, r, i, a, o) {
 		let s = this.sql;
 		if (this.supportsUpdateReturning) {
-			let c = s`UPDATE ${s(this.nsT(e))} SET ${s.update(C(r, e))} WHERE ${s("id")} = ${t} RETURNING *`, l = i ? n.provideService(c, I, i) : c, u = (await this.runtime.runPromise(l))[0];
+			let c = s`UPDATE ${s(this.nsT(e))} SET ${s.update(C(r, e))} WHERE ${s("id")} = ${t} RETURNING *`, l = i ? n.provideService(c, R, i) : c, u = (await this.runtime.runPromise(l))[0];
 			return u ? (await this.routeEvent({
 				table: e,
 				op: "update",
@@ -512,9 +571,9 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 				new: u
 			}, a, i, o), u) : null;
 		}
-		let c = s`UPDATE ${s(this.nsT(e))} SET ${s.update(C(r, e))} WHERE ${s("id")} = ${t}`, l = i ? n.provideService(c, I, i) : c, u = await this.runtime.runPromise(l);
+		let c = s`UPDATE ${s(this.nsT(e))} SET ${s.update(C(r, e))} WHERE ${s("id")} = ${t}`, l = i ? n.provideService(c, R, i) : c, u = await this.runtime.runPromise(l);
 		if (u && typeof u.affectedRows == "number" && u.affectedRows === 0) return null;
-		let d = s`SELECT * FROM ${s(this.nsT(e))} WHERE ${s("id")} = ${t}`, f = i ? n.provideService(d, I, i) : d, p = (await this.runtime.runPromise(f))[0];
+		let d = s`SELECT * FROM ${s(this.nsT(e))} WHERE ${s("id")} = ${t}`, f = i ? n.provideService(d, R, i) : d, p = (await this.runtime.runPromise(f))[0];
 		return p ? (await this.routeEvent({
 			table: e,
 			op: "update",
@@ -525,7 +584,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	async executeDelete(e, t, r, i, a) {
 		let o = this.sql;
 		if (this.supportsDeleteReturning) {
-			let s = o`DELETE FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t} RETURNING *`, c = r ? n.provideService(s, I, r) : s, l = (await this.runtime.runPromise(c))[0];
+			let s = o`DELETE FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t} RETURNING *`, c = r ? n.provideService(s, R, r) : s, l = (await this.runtime.runPromise(c))[0];
 			return l ? (await this.routeEvent({
 				table: e,
 				op: "delete",
@@ -533,9 +592,9 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 				new: null
 			}, i, r, a), !0) : !1;
 		}
-		let s = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t}`, c = r ? n.provideService(s, I, r) : s, l = (await this.runtime.runPromise(c))[0];
+		let s = o`SELECT * FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t}`, c = r ? n.provideService(s, R, r) : s, l = (await this.runtime.runPromise(c))[0];
 		if (!l) return !1;
-		let u = o`DELETE FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t}`, d = r ? n.provideService(u, I, r) : u;
+		let u = o`DELETE FROM ${o(this.nsT(e))} WHERE ${o("id")} = ${t}`, d = r ? n.provideService(u, R, r) : u;
 		return await this.runtime.runPromise(d), await this.routeEvent({
 			table: e,
 			op: "delete",
@@ -545,17 +604,17 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	}
 	async appendInTxn(e, t, r) {
 		let i = this.sql, a = i`INSERT INTO ${i(this.nsT(e))} ${i.insert(C(t, e))}`;
-		await this.runtime.runPromise(r ? n.provideService(a, I, r) : a);
+		await this.runtime.runPromise(r ? n.provideService(a, R, r) : a);
 	}
 	async maxInTxn(e, t, r, i) {
-		let a = this.sql, o = Object.entries(r).map(([e, t]) => a`${a(e)} = ${t}`), s = a`SELECT MAX(${a(t)}) AS ${a("m")} FROM ${a(this.nsT(e))} WHERE ${a.and(o)}`, c = (await this.runtime.runPromise(i ? n.provideService(s, I, i) : s))[0]?.m;
+		let a = this.sql, o = Object.entries(r).map(([e, t]) => a`${a(e)} = ${t}`), s = a`SELECT MAX(${a(t)}) AS ${a("m")} FROM ${a(this.nsT(e))} WHERE ${a.and(o)}`, c = (await this.runtime.runPromise(i ? n.provideService(s, R, i) : s))[0]?.m;
 		return c == null ? null : Number(c);
 	}
 	async routeEvent(e, t, n = null, r) {
 		if (e = {
 			...p(r),
 			...e
-		}, ie(e.table) && await oe({
+		}, N(e.table) && await ie({
 			append: (e, t) => this.appendInTxn(e, t, n),
 			maxOf: (e, t, r) => this.maxInTxn(e, t, r, n)
 		}, {
@@ -567,7 +626,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			subjectId: e.subjectId
 		}), this.changeStrategy === "cdc") {
 			let t = (e.op === "delete" ? e.old : e.new)?.id;
-			t != null && k(m(e.table, e.op, t), {
+			t != null && ee(m(e.table, e.op, t), {
 				...e.traceId === void 0 ? {} : { traceId: e.traceId },
 				...e.subjectId === void 0 ? {} : { subjectId: e.subjectId }
 			});
@@ -605,12 +664,12 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			}
 			return await this.executeUpdate(e, o.id, a, r, i) ?? o;
 		}
-		return N((n) => this.executeInsert(e, t, r, i, n));
+		return F((n) => this.executeInsert(e, t, r, i, n));
 	}
 	async executeMariadbUpsert(e, t, r, i, a, o) {
 		let s = this.sql, c = C(t, e), l = Object.keys(c).filter((e) => c[e] !== void 0), u = r.update === void 0 ? l.filter((e) => e !== "id" && !r.conflictColumns.includes(e)) : r.update, d = u.length > 0 ? s.csv(u.map((e) => s`${s(e)} = VALUES(${s(e)})`)) : s`${s(r.conflictColumns[0])} = VALUES(${s(r.conflictColumns[0])})`, f = await this.runPinned(i, (i) => n.tryPromise({
 			try: async () => {
-				let a = s`INSERT INTO ${s(this.nsT(e))} ${s.insert(c)} ON DUPLICATE KEY UPDATE ${d} RETURNING *`, o = (await this.runtime.runPromise(n.provideService(a, I, i)))[0];
+				let a = s`INSERT INTO ${s(this.nsT(e))} ${s.insert(c)} ON DUPLICATE KEY UPDATE ${d} RETURNING *`, o = (await this.runtime.runPromise(n.provideService(a, R, i)))[0];
 				if (!o) throw Error(`MysqlStore.upsert: no row returned for table '${e}'`);
 				let l = t.id;
 				if (l != null && o.id !== l) throw Error(`MysqlStore.upsert: the row written to '${e}' is not the row that was passed in. Upserting id '${String(l)}' matched an existing row with id '${String(o.id)}' on a DIFFERENT unique constraint than the conflictColumns [${r.conflictColumns.join(", ")}] you named, so that row would have been updated and yours never written. Nothing was changed. Name the constraint that actually collides, or resolve the duplicate first.`);
@@ -626,7 +685,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		}, a, i, o), f;
 	}
 	async executeInsertIgnore(e, t, r, i, a, o) {
-		if (t = M(e, t), t.id === void 0) return await this.findByConflict(e, t, r.conflictColumns, i) || N((n) => this.executeInsert(e, t, i, a, n));
+		if (t = P(e, t), t.id === void 0) return await this.findByConflict(e, t, r.conflictColumns, i) || F((n) => this.executeInsert(e, t, i, a, n));
 		let s = await this.runPinned(i, (i) => n.tryPromise({
 			try: () => this.decideInsertIgnore(e, t, r, i),
 			catch: (e) => e
@@ -639,7 +698,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		}, a, i, o), s.row;
 	}
 	async decideInsertIgnore(e, t, r, i) {
-		let a = this.sql, o = C(t, e), s = (e) => this.runtime.runPromise(n.provideService(e, I, i));
+		let a = this.sql, o = C(t, e), s = (e) => this.runtime.runPromise(n.provideService(e, R, i));
 		if (this.supportsInsertReturning) {
 			let n = (await s(a`INSERT IGNORE INTO ${a(this.nsT(e))} ${a.insert(o)} RETURNING *`))[0];
 			if (n) return {
@@ -690,7 +749,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		if (e === null) return [];
 		try {
 			let t = this.sql`SHOW WARNINGS`.unprepared;
-			return (await this.runtime.runPromise(n.provideService(t, I, e))).map((e) => ({
+			return (await this.runtime.runPromise(n.provideService(t, R, e))).map((e) => ({
 				code: Number(e.Code ?? e.code ?? 0),
 				message: String(e.Message ?? e.message ?? "")
 			}));
@@ -700,7 +759,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	}
 	async findByConflict(e, t, r, i) {
 		if (r.length === 0) return;
-		let a = this.sql, o = r.map((e) => a`${a(e)} = ${t[e]}`), s = a`SELECT * FROM ${a(this.nsT(e))} WHERE ${a.and(o)} LIMIT 1`, c = i ? n.provideService(s, I, i) : s;
+		let a = this.sql, o = r.map((e) => a`${a(e)} = ${t[e]}`), s = a`SELECT * FROM ${a(this.nsT(e))} WHERE ${a.and(o)} LIMIT 1`, c = i ? n.provideService(s, R, i) : s;
 		return (await this.runtime.runPromise(c))[0];
 	}
 	query(e) {
@@ -708,13 +767,13 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	}
 	raw(e, t) {
 		let n = b(e, this.sql);
-		return O(this.variant, "raw", () => this.runtime.runPromise(n));
+		return A(this.variant, "raw", () => this.runtime.runPromise(n));
 	}
 	async runWithEager(e, t) {
-		if (!ee(e)) return this.executeQuery(e, t);
+		if (!D(e)) return this.executeQuery(e, t);
 		let r = this.variant === "mariadb" ? "mariadb" : "mysql", i = this.namespace === null ? v(e, this.sql, r) : null;
 		if (i !== null) try {
-			let e = t ? n.provideService(i.fragment, I, t) : i.fragment, r = await O(this.variant, "select", () => this.runtime.runPromise(e));
+			let e = t ? n.provideService(i.fragment, R, t) : i.fragment, r = await A(this.variant, "select", () => this.runtime.runPromise(e));
 			return i.decode(r);
 		} catch (t) {
 			if (t instanceof u) throw t;
@@ -731,42 +790,51 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			reason: "not-compilable"
 		});
 		let a = await this.executeQuery(e, t);
-		return f(a, e.eager, e.sourceTable ?? A(e.table), (e) => this.executeQuery(e, t));
+		return f(a, e.eager, e.sourceTable ?? te(e.table), (e) => this.executeQuery(e, t));
 	}
 	getInternalRunWithEager() {
 		return this.runWithEager.bind(this);
 	}
+	async writeWithRecorders(e, t) {
+		let r = [], i = await this.runPinned(null, (i) => n.tryPromise({
+			try: () => e(t, i, r),
+			catch: (e) => e
+		}), "insert");
+		for (let e of r) this.emitChange(e);
+		return i;
+	}
 	async localWrite(e, t, n) {
-		return O(this.variant, e, async () => {
-			if (this.changeStrategy !== "cdc") return N(n);
+		let r = (e) => N(t) ? this.writeWithRecorders(n, e) : n(e, null, null);
+		return A(this.variant, e, async () => {
+			if (this.changeStrategy !== "cdc") return F(r);
 			h(t);
 			try {
-				return await N(n);
+				return await F(r);
 			} finally {
 				w(t);
 			}
 		});
 	}
 	insert(e, t) {
-		return this.localWrite("insert", e, (n) => this.executeInsert(e, t, null, null, n));
+		return this.localWrite("insert", e, (n, r, i) => this.executeInsert(e, t, r, i, n));
 	}
 	insertMany(e, t) {
-		return this.localWrite("insert", e, (n) => this.executeInsertMany(e, t, null, null, n));
+		return this.localWrite("insert", e, (n, r, i) => this.executeInsertMany(e, t, r, i, n));
 	}
 	patchJson(e, t, n, r) {
-		return this.localWrite("update", e, (i) => this.executePatchJson(e, t, n, r, null, null, i));
+		return this.localWrite("update", e, (i, a, o) => this.executePatchJson(e, t, n, r, a, o, i));
 	}
 	upsert(e, t, n) {
-		return this.localWrite("upsert", e, (r) => this.executeUpsert(e, t, n, null, null, r));
+		return this.localWrite("upsert", e, (r, i, a) => this.executeUpsert(e, t, n, i, a, r));
 	}
 	insertIgnore(e, t, n) {
-		return this.localWrite("upsert", e, (r) => this.executeInsertIgnore(e, t, n, null, null, r));
+		return this.localWrite("upsert", e, (r, i, a) => this.executeInsertIgnore(e, t, n, i, a, r));
 	}
 	update(e, t, n) {
-		return this.localWrite("update", e, (r) => this.executeUpdate(e, t, n, null, null, r));
+		return this.localWrite("update", e, (r, i, a) => this.executeUpdate(e, t, n, i, a, r));
 	}
 	delete(e, t) {
-		return this.localWrite("delete", e, (n) => this.executeDelete(e, t, null, null, n));
+		return this.localWrite("delete", e, (n, r, i) => this.executeDelete(e, t, r, i, n));
 	}
 	async updateMany(e, t, r) {
 		if (this.supportsUpdateReturning) {
@@ -782,13 +850,13 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		let i = this.sql, o = y(r.where, i, this.namespace);
 		this.changeStrategy === "cdc" && h(e), this.inflightTxns++;
 		try {
-			let r = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(I), (r) => {
+			let r = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(R), (r) => {
 				if (a.isNone(r)) return n.fail(/* @__PURE__ */ Error("MysqlStore.updateMany: TransactionConnection missing."));
 				let s = r.value, c = i`SELECT id FROM ${i(this.nsT(e))} WHERE ${o} FOR UPDATE`, l = i`UPDATE ${i(this.nsT(e))} SET ${i.update(C(t, e))} WHERE ${o}`;
-				return n.flatMap(n.provideService(c, I, s), (t) => {
+				return n.flatMap(n.provideService(c, R, s), (t) => {
 					if (t.length === 0) return n.succeed([]);
 					let r = t.map((e) => e.id), a = i`SELECT * FROM ${i(this.nsT(e))} WHERE ${i("id")} IN ${i.in(r)}`;
-					return n.flatMap(n.provideService(l, I, s), () => n.provideService(a, I, s));
+					return n.flatMap(n.provideService(l, R, s), () => n.provideService(a, R, s));
 				});
 			}))), c = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(q)), l = r.pipe(n.retry(c), n.withSpan("store.updateMany", { attributes: {
 				"db.system": this.variant,
@@ -821,10 +889,10 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		}
 		this.changeStrategy === "cdc" && h(e), this.inflightTxns++;
 		try {
-			let t = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(I), (t) => {
+			let t = n.suspend(() => this.sql.withTransaction(n.flatMap(n.serviceOption(R), (t) => {
 				if (a.isNone(t)) return n.fail(/* @__PURE__ */ Error("MysqlStore.deleteMany: TransactionConnection missing."));
 				let o = t.value, s = r`SELECT * FROM ${r(this.nsT(e))} WHERE ${i} FOR UPDATE`, c = r`DELETE FROM ${r(this.nsT(e))} WHERE ${i}`;
-				return n.flatMap(n.provideService(s, I, o), (e) => e.length === 0 ? n.succeed(e) : n.as(n.provideService(c, I, o), e));
+				return n.flatMap(n.provideService(s, R, o), (e) => e.length === 0 ? n.succeed(e) : n.as(n.provideService(c, R, o), e));
 			}))), o = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(q)), c = t.pipe(n.retry(o), n.withSpan("store.deleteMany", { attributes: {
 				"db.system": this.variant,
 				"db.operation": "delete"
@@ -843,23 +911,27 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		}
 	}
 	emitChange(e) {
-		D(e.table) && (this.changeStrategy === "cdc" && !this.cdcGate.admit(e) || this.emitter.emit("change", e));
+		O(e.table) && (this.changeStrategy === "cdc" && !this.cdcGate.admit(e) || this.emitter.emit("change", e));
 	}
 	async startCdcConsumer(e) {
 		if (this.cdcHandle) return;
-		await this.assertBinlogConfig(), this.cdcReplicaId = e.replicaId;
-		let t = await this.readCdcOffset(e.replicaId) ?? await this.resolveBinlogEnd(), n = await this.findUndecodableCdcTables(e.includeTables);
-		for (let e of n) this.log.error(W(e));
-		this.cdcHandle = await K({
+		await this.assertBinlogConfig(), this.cdcReplicaId = e.replicaId, this.cdcAdminRuntime = i.make(z({
+			...e.connection,
+			maxConnections: 1
+		}));
+		let t = await this.readCdcOffset(e.replicaId), n = t !== null && await this.binlogFileExists(t.filename);
+		t !== null && !n && this.log.warn(`cdc: the persisted offset points at ${t.filename}, which the server no longer has (the binlog was purged or rotated away while this replica was down). Starting at the current end instead — changes written in the gap are not replayed, and subscriptions self-heal on the next change.`);
+		let r = (n ? t : null) ?? await this.resolveBinlogEnd(), a = await this.findUndecodableCdcTables(e.includeTables);
+		this.cdcIncludeTables = e.includeTables, this.cdcExcluded = a, this.cdcReporter.announce(a, e.exclusionRefreshFollows === !0), this.cdcHandle = await K({
 			connection: e.connection,
 			serverId: e.serverId,
 			variant: this.variant,
 			...e.includeTables ? { includeTables: e.includeTables } : {},
-			...n.length > 0 ? { undecodableTables: n } : {},
+			...a.length > 0 ? { undecodableTables: a } : {},
 			...e.watchdogIntervalMs === void 0 ? {} : { watchdogIntervalMs: e.watchdogIntervalMs },
 			...e.stallThresholdMs === void 0 ? {} : { stallThresholdMs: e.stallThresholdMs },
 			...e.keepAliveInitialDelayMs === void 0 ? {} : { keepAliveInitialDelayMs: e.keepAliveInitialDelayMs },
-			startPosition: t,
+			startPosition: r,
 			onChange: (e) => this.injectExternalChange(e),
 			onPosition: (e) => {
 				this.cdcPendingPosition = e;
@@ -880,6 +952,16 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		if (t.format !== "ROW") throw Error(`${this.variant} binlog CDC requires binlog_format=ROW (got '${t.format}'). Set --binlog-format=ROW, or CDC=0 for inline emit.`);
 		t.rowImage !== "FULL" && this.log.warn(`cdc: binlog_row_image='${t.rowImage}' (expected FULL) — UPDATE/DELETE before-images may be incomplete. Set --binlog-row-image=FULL.`);
 	}
+	async binlogFileExists(e) {
+		let t = this.cdcAdminRuntime;
+		if (t === null) return !0;
+		try {
+			let r = await t.runPromise(n.flatMap(L, (e) => e`SHOW BINARY LOGS`.unprepared));
+			return r.length === 0 || r.some((t) => (t.Log_name ?? t.log_name) === e);
+		} catch (e) {
+			return this.log.debug(`cdc: could not list binary logs (${e?.message ?? String(e)}) — trusting the persisted offset`), !0;
+		}
+	}
 	async resolveBinlogEnd() {
 		let e = this.sql, t = this.variant === "mysql" ? e`SHOW BINARY LOG STATUS`.unprepared : e`SHOW MASTER STATUS`.unprepared, n = this.variant === "mysql" ? e`SHOW MASTER STATUS`.unprepared : e`SHOW BINARY LOG STATUS`.unprepared, r = async (e) => {
 			let t = (await this.runtime.runPromise(e))[0];
@@ -887,7 +969,8 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 				filename: t.File,
 				position: Number(t.Position)
 			} : null;
-		};
+		}, i = await this.resolveBinlogEndOverCdc();
+		if (i !== null) return i;
 		try {
 			return await r(t);
 		} catch {
@@ -898,6 +981,19 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			}
 		}
 	}
+	async resolveBinlogEndOverCdc() {
+		let e = this.cdcAdminRuntime;
+		if (e === null) return null;
+		let t = (e) => n.flatMap(L, (t) => t`${t.unsafe(e)}`.unprepared);
+		for (let n of this.variant === "mysql" ? ["SHOW BINARY LOG STATUS", "SHOW MASTER STATUS"] : ["SHOW MASTER STATUS", "SHOW BINARY LOG STATUS"]) try {
+			let r = (await e.runPromise(t(n)))[0];
+			if (r?.File) return {
+				filename: r.File,
+				position: Number(r.Position)
+			};
+		} catch {}
+		return null;
+	}
 	async readCdcOffset(e) {
 		try {
 			let t = this.sql, n = (await this.runtime.runPromise(t`
@@ -965,13 +1061,35 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	getInternalExecuteInsertIgnore() {
 		return this.executeInsertIgnore.bind(this);
 	}
+	async emptyTables(e) {
+		await this.emptyTablesOn(e, null);
+	}
+	async incomingForeignKeys(e) {
+		if (e.length === 0) return [];
+		let t = this.sql;
+		return (await this.runtime.runPromise(t`
+        SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME
+        FROM information_schema.KEY_COLUMN_USAGE
+        WHERE TABLE_SCHEMA = DATABASE()
+          AND REFERENCED_TABLE_NAME IN ${t.in(e)}
+          AND TABLE_NAME NOT IN ${t.in(e)}`)).map((e) => ({
+			from: e.TABLE_NAME,
+			column: e.COLUMN_NAME,
+			to: e.REFERENCED_TABLE_NAME
+		}));
+	}
+	async emptyTablesOn(e, t) {
+		if (e.length === 0) return;
+		let r = this.sql, i = (e) => this.nsT(e), a = (e) => r.unsafe(`SET FOREIGN_KEY_CHECKS = ${+!!e}`).unprepared, o = n.acquireUseRelease(a(!1), () => n.forEach(e, (e) => r`DELETE FROM ${r(i(e))}`, { discard: !0 }), () => n.orDie(n.ignore(a(!0)))), s = t === null ? r.withTransaction(o) : n.provideService(o, R, t);
+		await this.runtime.runPromise(s);
+	}
 	async transactional(e) {
 		this.inflightTxns++;
 		try {
-			return await ae({
+			return await re({
 				...this.txnSpec("MysqlStore.transactional"),
 				work: e,
-				makeView: (e, t) => new Te(this, e, t)
+				makeView: (e, t) => new je(this, e, t)
 			});
 		} finally {
 			this.inflightTxns--;
@@ -1002,16 +1120,29 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		return this.changeStrategy === "cdc" ? "fleet" : "local";
 	}
 	injectExternalChange(e) {
-		if (this.changeStrategy === "cdc" && !this.cdcGate.admit(e) || !D(e.table)) return;
+		if (this.changeStrategy === "cdc" && !this.cdcGate.admit(e) || !O(e.table)) return;
 		let t = (e.op === "delete" ? e.old : e.new)?.id;
-		j(e.table, e.op, t, (t) => {
+		ne(e.table, e.op, t, (t) => {
 			this.emitter.emit("change", T(e, t));
 		});
 	}
 	run(e) {
 		return this.runtime.runPromise(e);
 	}
+	async refreshChangeCaptureExclusions() {
+		if (!this.cdcHandle) return {
+			stillExcluded: [],
+			readmitted: [],
+			newlyExcluded: []
+		};
+		let e = await this.findUndecodableCdcTables(this.cdcIncludeTables), t = be(this.cdcExcluded, e);
+		return this.cdcReporter.settle(t), this.cdcExcluded = e, (t.readmitted.length > 0 || t.newlyExcluded.length > 0) && await this.cdcHandle.setUndecodableTables(e), t;
+	}
 	async close(e = 5e3) {
+		if (this.cdcReporter.dispose(), this.cdcAdminRuntime) {
+			let e = this.cdcAdminRuntime;
+			this.cdcAdminRuntime = null, await e.dispose().catch(() => void 0);
+		}
 		if (this.cdcCheckpointTimer &&= (clearInterval(this.cdcCheckpointTimer), null), this.cdcHandle) {
 			let e = this.cdcHandle.currentPosition();
 			e && (this.cdcPendingPosition = e), await this.flushCdcOffset(), await this.cdcHandle.stop(), this.cdcHandle = null;
@@ -1029,7 +1160,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	async ping() {
 		await this.runtime.runPromise(this.sql`SELECT 1`);
 	}
-}, Te = class {
+}, je = class {
 	parent;
 	txn;
 	attr;
@@ -1041,6 +1172,9 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	query(e) {
 		return this.parent.getInternalRunWithEager()(e, this.txn);
 	}
+	emptyTables(e) {
+		return this.parent.emptyTablesOn(e, this.txn);
+	}
 	insert(e, t) {
 		return this.parent.getInternalExecuteInsert()(e, t, this.txn, this.events, this.attr);
 	}
@@ -1102,12 +1236,12 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 			this.events.length = 0;
 		}
 	}
-}, $ = (e) => e.__mysqlReplicationFriend ?? null, Ee = () => ({
+}, $ = (e) => e.__mysqlReplicationFriend ?? null, Me = () => ({
 	async capturePrimaryPosition(e) {
 		let t = $(e);
 		if (t === null) throw Error("mysqlReplicationAdapter: primary is not a MysqlStore (missing __mysqlReplicationFriend).");
 		return t.runEffect(n.gen(function* () {
-			let e = yield* F, r = (t.variant === "mariadb" ? yield* e`SELECT @@global.gtid_current_pos AS gtid` : yield* e`SELECT @@global.gtid_executed AS gtid`)[0]?.gtid;
+			let e = yield* L, r = (t.variant === "mariadb" ? yield* e`SELECT @@global.gtid_current_pos AS gtid` : yield* e`SELECT @@global.gtid_executed AS gtid`)[0]?.gtid;
 			return typeof r == "string" ? r : yield* n.die("mysql/mariadb did not return a GTID set");
 		}));
 	},
@@ -1115,14 +1249,14 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 		let t = $(e);
 		if (t === null) throw Error("mysqlReplicationAdapter: replica is not a MysqlStore.");
 		return t.runEffect(n.gen(function* () {
-			let e = yield* F, r = (t.variant === "mariadb" ? yield* e`SELECT @@global.gtid_current_pos AS gtid` : yield* e`SELECT @@global.gtid_executed AS gtid`)[0]?.gtid;
+			let e = yield* L, r = (t.variant === "mariadb" ? yield* e`SELECT @@global.gtid_current_pos AS gtid` : yield* e`SELECT @@global.gtid_executed AS gtid`)[0]?.gtid;
 			return typeof r == "string" ? r : yield* n.die("mysql/mariadb replica did not return a GTID set");
 		}));
 	},
 	compare(e, t) {
 		return "behind";
 	}
-}), De = {
+}), Ne = {
 	id: "mysql",
 	makeSqlLayer: (e) => H(e),
 	makeStore: (e) => Z({
@@ -1131,7 +1265,7 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	}),
 	compileContains: (e, t, n) => n`${e} LIKE ${`%${t.replace(/[\\%_]/g, (e) => `\\${e}`)}%`} ESCAPE '\\'`,
 	retryFilter: J
-}, Oe = {
+}, Pe = {
 	id: "mariadb",
 	makeSqlLayer: (e) => H(e),
 	makeStore: (e) => Z({
@@ -1142,4 +1276,4 @@ var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	retryFilter: J
 };
 //#endregion
-export { c as CDC_OFFSETS_TABLE, e as MysqlClient, d as _voltroCdcOffsetsTable, V as connectionFromConfig, z as makeMysqlSqlLayer, H as makeMysqlSqlLayerFromConfig, Z as makeMysqlStore, Oe as mariadbDialect, De as mysqlDialect, Ee as mysqlReplicationAdapter, J as mysqlRetryFilter, K as startBinlogCdc };
+export { c as CDC_OFFSETS_TABLE, e as MysqlClient, d as _voltroCdcOffsetsTable, V as connectionFromConfig, z as makeMysqlSqlLayer, H as makeMysqlSqlLayerFromConfig, Z as makeMysqlStore, Pe as mariadbDialect, Ne as mysqlDialect, Me as mysqlReplicationAdapter, J as mysqlRetryFilter, K as startBinlogCdc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/sql-mysql",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "description": "MySQL/MariaDB dialect adapter for Voltro's cross-dialect DataStore (mariadb binlog CDC; mysql inline reactivity).",
   "keywords": [
     "voltro",
@@ -35,8 +35,8 @@
   "dependencies": {
     "@effect/sql": "^0.52.0",
     "@effect/sql-mysql2": "^0.53.0",
-    "@voltro/database": "0.43.1",
-    "@voltro/logger": "0.43.1"
+    "@voltro/database": "0.44.0",
+    "@voltro/logger": "0.44.0"
   },
   "optionalDependencies": {
     "@vlasky/zongji": "^0.9.0"