@voltro/sql-mysql 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -39,6 +39,194 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.43.0] — 2026-08-18
+
+### ⚠ BREAKING
+
+- **@voltro/data-transfer, @voltro/cli** — `DanglingReferenceError` is now `RowsRefusedError`, and it separates the rows that failed from the rows that failed because those rows did.
+
+  **The name.** The import raised it for EVERY row still refused after deferred-FK resolution, whatever the reason — a NOT NULL violation, a duplicate key, a value the database computes for itself. The tag named ONE possible cause and put it where a reader looks first, so any other refusal arrived mislabelled. The new name states the outcome; each row's `reason` states the cause, which is where a cause can honestly be claimed.
+
+  **The split.** A row is `derived` when one of its reference columns holds the primary key of another row that also failed in this run: it could not have landed whatever it contained, so its reason describes the parent's problem. The relation is transitive, decided from the DATA (the failed ids against the reference-typed values), so no schema knowledge is needed. `primaryCount` is the number an operator acts on, `rows` lists primary failures FIRST so the cap never spends its budget on consequences, and the CLI leads with both numbers:
+
+  ```
+  import refused 300 row(s), of which 1 are the actual failures — the rest could
+  not land because a row they reference did not.
+    teams t1  foreign key teams_ibfk_1: the referenced row does not exist [1452]
+    … and 299 row(s) behind them. Fix the 1 above and re-run; they resolve with
+    their parents.
+  ```
+
+  In an FK-dense bundle one refused parent takes its whole subtree with it, so the length of a flat list says how connected the data is, not how many problems there are — and the single row that explains all of them sits somewhere in the middle of it.
+
+  The codemod rewrites the import and every use of the symbol. It does NOT rewrite a tag STRING (`Effect.catchTag('DanglingReferenceError', …)`, `err._tag === '…'`) — change those to `'RowsRefusedError'` — and the payload gained `primaryCount` plus a `derived` flag per row.
+
+### Fixed
+
+- **@voltro/cli** — `voltro doctor`'s `subject-write-no-guard` rule reads the DESCRIPTOR before it reports. It looked only at the executor, and the access decision is not declared there.
+
+  Every form of access decision the framework has — `internal: true`, `guards: [...]`, `openAccess:` — is declared on the DESCRIPTOR. So an app that declares them properly got a finding for each one, and on a codebase whose procedures are mostly `internal: true` the rule fires on essentially all of them and is wrong essentially every time.
+
+  That is worse than a rule that finds nothing: it is the longest line in the report and it reads like a security finding, so it teaches the reader to skim the place a real finding would have appeared.
+
+  The premise was structurally impossible for most of them, and the framework says so itself: `security.defaultDeny` refuses at boot any wire-exposed procedure declaring neither `guards:` nor `openAccess:`. So "an anonymous caller reaches the write" can only be true of an `openAccess` procedure. That is what the rule looks for now — plus the handler check it always honoured, plus an ownership comparison against `subject.id`, which is the refusal the rule says is missing. Where no descriptor can be read, it says nothing: the claim is about a declaration, and a finding whose evidence was never opened is the failure mode this fixes.
+
+  The `use:` line changed with it. It recommended `.guard(requireScope('…'))`; the shipped guide teaches declarative `guards:` and calls a hand-written per-executor scope check the thing `guards:` exists to delete. A rule may not recommend the shape the guide argues against.
+- **@voltro/database, @voltro/data-transfer** — A `voltro data` transfer no longer carries GENERATED column values, and no longer loses every row that has one.
+
+  The export wrote the computed values into the bundle and the import sent them back in the `INSERT` column list. MariaDB refuses that for any value except NULL (`1906: The value specified for generated column 'x' in table 't' has been ignored`); postgres refuses a non-DEFAULT value outright. So the transfer failed per ROW, not per table, and only for the rows whose generated value was non-NULL.
+
+  That selectivity is the dangerous part. `.uniqueActive()` lowers to exactly such a column on mysql/mariadb — a STORED generated column holding the key while the row is live and NULL once it is soft-deleted — so the refused rows are the LIVE ones and the accepted ones are the tombstones. A table can come out looking like "a few rows failed" or empty, depending only on how many of its rows are deleted, and any table with a foreign key into it fails behind it.
+
+  Both ends are fixed from one source of truth: **introspection now reports generated columns on every dialect** (`generatedAs`, from `information_schema.generation_expression` on mysql/mariadb, `is_generated` on postgres, `PRAGMA table_xinfo`'s hidden flag on sqlite, `sys.computed_columns` on mssql). It was declared-side only before — invisible to the planner, which does not compare it, and load-bearing for anything that writes rows back.
+
+  The exporter omits those columns, values and all. The importer strips them from every incoming row using the TARGET's snapshot, because a bundle already written still carries them and a file on disk is data, read where it is.
+
+  **`voltro serve`'s admin export/import needed a second fix, and without it this one reached only the direct transport.** The running instance hands those handlers `declaredSnapshot(tables)` — no dialect — and `.uniqueActive()` lowers to a generated column only when the snapshot knows the engine. So over `--target api` the snapshot described a schema with no generated columns while the database had several, and the export wrote their values back into the bundle exactly as before. It passes the dialect now (the variable was already on the next line).
+
+  `generatedAs` is also kept OUT of the schema fingerprint. Introspection can read the fact back but not a comparable value — the engine returns its own normalisation of the expression, never the declared spelling — so hashing it would make declared and live disagree permanently: a schema nobody touched reporting a changed declaration on every boot, and a transfer target that matches its bundle exactly refused as drifted.
+
+  Covered by a live mariadb→mariadb and mysql→mysql round trip over a `.uniqueActive()` table with live and soft-deleted rows, asserting the target recomputed the value rather than that the row merely arrived.
+- **@voltro/sql-mysql** — On mysql/mariadb, a write REJECTED by the database through `insertIgnore` was reported as a conflict when the caller was not inside a transaction — and never reached the caller as a typed `ConstraintViolation` at all.
+
+  Two causes, both measured against live MySQL 8.4 and MariaDB 11.
+
+  **The connection.** `INSERT IGNORE` demotes every error to a warning, so the store reads `SHOW WARNINGS` to tell a rejection from a conflict. That describes the last statement on a CONNECTION, and outside a transaction every statement acquires its own from the pool — so the read was unattributable and came back empty. The rejected write then surfaced as "the insert was skipped as a conflict, but no existing row matches conflictColumns […] the constraint that fired is unknown", whose enumeration lists only conflict causes. A rejection described as a conflict is the exact sentence this path was fixed once already for producing; it survived on the path that had no transaction to read on. The store now pins one connection for the whole decision — the same pinning `insertRecoverAutoId` does for `LAST_INSERT_ID()`.
+
+  **The classification.** The store swallowed the driver's error and raised a prose one of its own, so `classifyConstraintViolation` had nothing to read: this was the one write path where the typed error could not fire, while every other one produced it. The warning IS the driver's payload — `INSERT IGNORE` only changed how it was delivered — so it is handed on in the shape the driver would have thrown. A rejection now arrives as the same `ConstraintViolation { kind: 'foreignKey', … }` a plain `insert` produces. Nothing new crosses the wire: the classifier extracts the constraint NAME as a delimited group, never the sentence.
+
+  This is the default `voltro data import` path (`--mode append`, `--on-conflict skip`, without `--atomic`), so a row rejected by a foreign key was reported to the operator as a conflict with an unknown cause.
+
+  `constraintViolation.integration.test.ts` now asserts the `insertIgnore` seam per dialect against live postgres 17, MySQL 8.4, MariaDB 11 and SQL Server 2022. It was the missing assertion behind a claim derived from the wiring — the classification does sit on all ten write paths, which is not the same as a classifiable error arriving on all ten.
+- **@voltro/protocol, @voltro/runtime** — The framework's store errors — `ConstraintViolation`, `TenantScopeViolation`, `TenantRowNotFound`, `ServerOnlyColumnWrite`, `TableValidationFailed`, `StoreOperationFailed` — are exported from `@voltro/protocol` and can therefore be declared in a descriptor's `error:` union. They could not be.
+
+  They lived in `@voltro/runtime`, which reaches `node:child_process`, `node:http` and `node:crypto`. A descriptor is loaded VALUE-LEVEL by the web client (the `RpcClient` needs every procedure's Schema), so a descriptor importing from there is refused at boot by the browser-safety guard — correctly. The typed half of these errors was therefore unreachable: the docs told you to declare them, and the boot said no.
+
+  What that leaves is the untyped half only. The error still arrives as an `InternalError` carrying a readable sentence, so telling `foreignKey` ("the row you picked is gone") from `foreignKeyInUse` ("this row is still referenced") — two different messages for the user — means parsing that sentence. Over a set of generated delete mutations that is a string comparison per procedure, which is the thing the typed error exists to delete.
+
+  `@voltro/runtime` re-exports all six, so server code is unchanged. The classes have no server dependency of any kind — the file imports `Schema` from `effect` and nothing else, and `browserSafetyGuard.test.ts` now pins a descriptor that declares one, so moving them back reads as a boot failure rather than as a passing rename.
+- **@voltro/database, @voltro/sql-mysql** — A blocked `alter-column-type` told every dialect to write a postgres cast.
+
+  The refusal is correct — a bare type change may not be value-preserving, so it is refused until acknowledged. Its `fix:` line was not:
+
+  ```
+  acknowledge it on the column: `.narrowedFrom('json', { using: 'meta::text' })`
+  ```
+
+  `USING <expr>` is postgres syntax and a postgres capability. The mysql arm of the applier emits `MODIFY COLUMN`, the mssql arm `ALTER COLUMN`, and sqlite rebuilds the table — none of them can carry a cast expression and none of them reads `using`. So an operator on any other engine was handed a line to paste into their schema containing syntax their database has never seen, inside an argument that is discarded. A refusal is read as an instruction, and the more carefully it is read the more thoroughly a wrong one is followed.
+
+  The fix line is dialect-aware now: postgres keeps the `using` half, everything else gets `.narrowedFrom('<type>')` plus the fact that the engine converts in place — because a refusal that offers no expressible fix reads as "the framework cannot do this at all".
+
+  Covered on live MySQL and MariaDB by both halves at once: what the refusal SAYS, and that following it applies AND converges with the row intact. A message test alone would keep passing over a broken apply; a convergence test alone is what let the wrong message survive this long.
+
+  Also on the same path: `upsert` with a PARTIAL row (one omitting a NOT NULL column that has no default) failed on MariaDB and succeeded on MySQL. The native `INSERT … ON DUPLICATE KEY UPDATE` validates its insert half even when only the update half runs, so the row was rejected although the target existed and only needed patching. A partial row takes the lookup path on both engines now; the single-statement form still covers the complete-row case, which is what a data transfer and every generated CRUD write send.
+- **@voltro/sql-mysql** — On MariaDB, `upsert` could write a DIFFERENT row than the one it was given and report success.
+
+  `INSERT … ON DUPLICATE KEY UPDATE` fires on ANY unique key, not on the one named in `conflictColumns`. So an incoming row whose (say) `email` already belonged to a different primary key updated THAT row instead — and since `id` is excluded from the SET list, the row the caller handed over was never written. Measured on a live server: the call returned a row, the target kept the old id, the new row was absent, and the existing row had silently taken the incoming values. A bulk transfer on top of that prints `import complete` over missing data, which is the worst failure shape available: there is nothing to investigate.
+
+  The two engines of the family disagreed here, which is part of why it survived. The non-RETURNING path (MySQL) looks the row up by `conflictColumns` first, does not find it, and lets the INSERT fail with a duplicate-key error. Loud was always right.
+
+  Both refuse now, with a message naming both ids and the fact that the collision was on a constraint other than the one named. The check runs inside a transaction — a short one of the store's own when the caller is not already in one — so the wrong row is rolled back rather than reported after the fact: detecting this afterwards still leaves someone else's row overwritten.
+
+---
+
+## [0.42.0] — 2026-08-17
+
+### ⚠ BREAKING
+
+- **@voltro/cli, @voltro/data-transfer** — **Two security defects on the data-transfer surface, both found by using the feature rather than by reading it.**
+
+  **A `{ profile }` in an admin-export request could name a PATH.** `loadProfile` resolved the client's string with `resolve(cwd, x)` — which returns an absolute path unchanged and lets `../` traverse — and the resolved file is `await import()`ed, which RUNS it. So a holder of the data-transfer secret could make the api process execute any file on the pod: an escalation from "can export prod data" to "can run code", and chainable on an instance whose object storage is a filesystem the same caller can write to.
+
+  `POST /_voltro/admin/export` now accepts a NAME only — `[A-Za-z0-9_-]{1,64}`, resolved under `data-profiles/` and checked to be contained there. **Migration: if you passed a path over `--target api`, move the file to `data-profiles/<name>.ts` and pass `<name>`.** `voltro data export --profile` on a DIRECT target still accepts a path: it runs on the operator's own machine, where a path is not an escalation. No user-authored code changes, so `codemod: none`.
+
+  **An unrecognised masking action copied the value through.** `applyAction` ended in `return input.value`, so a profile with a typo in the action shape (`{ action: 'fake', kind: 'email' }` instead of `{ fake: 'email' }`) exported every row of a `.sensitive()` column verbatim — with a 200 and an audit line counting the column as masked. Measured against a live instance: a masked export of two users came back carrying both real addresses.
+
+  The applier now throws, and `planMasking` refuses the policy BEFORE a row is read: `MaskingError` gained `invalidActions`, reported separately from `unclassified` because the fixes differ — one needs a classification, the other needs the policy corrected.
+
+### Added
+
+- **@voltro/runtime** — A write the database refuses on an integrity rule now raises a typed `ConstraintViolation` instead of an opaque `SqlError`. It carries `{ kind, table, operation, constraint?, column? }`, where `kind` is one of `foreignKey` · `foreignKeyInUse` · `unique` · `notNull` · `check`. Declare it in a procedure's `error:` to pattern-match it; undeclared it still reaches the client as an `InternalError` carrying its own sentence rather than `Failed to execute statement`.
+
+  It carries NAMES and never the driver's message, which on most engines contains row data — postgres attaches the complete failing row to a not-null and a check violation, mysql and mssql echo the duplicate value. Classification is measured against live postgres 17, MySQL 8.4, MariaDB 11, SQL Server 2022 and sqlite.
+
+  Raised from one guard covering every write op (insert · insertMany · upsert · insertIgnore · update · updateMany · delete · deleteMany · hardDelete · patchJson); the tenant-FK case still resolves to `TenantScopeViolation` first.
+
+### Fixed
+
+- **@voltro/cli, @voltro/data-transfer** — `voltro data import|export` — four defects on the `--target api` path, all found by a consumer seeding a fresh cluster from a bundle.
+
+  **A flag this command does not read is now an ERROR.** `--dry-run` and `--tables` were accepted on the import path and dropped in silence: a preview against a production-shaped cluster ran the import instead (2905 rows, then a 500), and a run narrowed to a one-row table wrote all 10 593. Both are one defect — an argument parser that ignores what it does not understand — so every `voltro data` subcommand now declares the flags it reads per target and refuses the rest, naming the flag and what to use instead.
+
+  **`--dry-run` and `--tables` now work on the import, on BOTH targets.** A dry run reaches every verdict a real run reaches (schema fit, cross-dialect portability, mode legality, the table selection) and stops before the first write; the api path carries them as `x-import-dry-run` / `x-import-tables` and echoes `{ dryRun: true, wrote: false }`. A `--tables` name the bundle does not carry is refused, listing what it does. `--dry-run` on an api EXPORT is refused rather than ignored — previewing a read protects nothing.
+
+  **The schema-drift pre-flight compares the INTERSECTION, not whole schemas.** A bundle's fingerprint covers its source schema regardless of export scope, and two environments never have identical whole schemas, so the check refused every cross-environment seed with a diff whose every line said the difference changes nothing — making `--force` the routine way to import and removing the protection it guards. It now reports only what would break the load: a carried table or column the target lacks, a type mismatch, or a column the target REQUIRES that the bundle carries no value for.
+
+  **A failed row says why.** `reason` was `Failed to execute statement` for every one of 2905 rows. It now names the constraint and the rule (`foreign key tasks_laneId_fkey: the referenced row does not exist [23503]`), or the driver's own message with its code, or — where there is no driver under the failure — the error from the layer that refused.
+
+  Also: `voltro data inspect` accepts a directory bundle instead of dying inside the archive reader with a JSON parse error (`--target api` always unpacks into a directory, even when the path ends in `.vbundle`).
+
+  **Three more, found by running the whole thing against live MariaDB and MySQL** rather than against sqlite:
+
+  - A re-run of a COMPLETED import wrote nothing and reported the bundle's full row count — the resume ledger lives in the bundle directory, so truncating a target and re-importing printed `import complete … 10593 rows` over an empty database. Resume is right; being quiet about it was not. It now warns, names the skipped tables, and says which ledger file to delete. - The deferred-FK recovery pass OVERWROTE the diagnosis. When a held row cannot be written, the resolver retries it with every `reference` column nulled to break a cycle — and that attempt's failure replaced the original reason, so a row whose real problem was one column reported a not-null violation on a column the framework itself had nulled. The recovery attempt no longer records a reason. - MySQL/MariaDB errno **1364** (a statement that OMITS a column which is NOT NULL with no default) is classified as a not-null violation. postgres reports 23502 for that situation and mssql 515, so the mysql family was the only one where "you did not supply a required column" came back unclassified.
+- **@voltro/database** — CHECK constraints were invisible to introspection on **MySQL** — and with them every `.oneOf()` column and every `json_valid` marker.
+
+  `information_schema.check_constraints` differs between the two engines of the family: MariaDB carries `TABLE_NAME`, MySQL does not have that column at all. The introspector selected it, the query errored, and an `Effect.orElseSucceed` turned that into an empty list. A swallowed error and an empty result read identically, which is why this needed a two-engine test to surface. The query JOINs `information_schema.table_constraints` for the name now, which both engines answer.
+
+  `parseEnumCheck` also learned MySQL's rendering. The same clause is stored differently:
+
+  mariadb 11 `status` in ('draft','live','done') mysql 8.4 (`status` in (_latin1'draft',_latin1'live',_latin1'done'))
+
+  MySQL puts a charset introducer before each literal, which the pattern — written against MariaDB's form — did not read. Both are pinned in `enumCheckParity.test.ts`.
+
+  Neither fix completes the round trip on MySQL: `.oneOf()` still comes back unclassified there. That is asserted as a known gap in `oneOfCheck.mariadb.integration.test.ts` (which fails the moment it starts working) and written up in `plans/open/framework/mysql-oneof-roundtrip.md`.
+- **@voltro/database** — `voltro db apply` works on MySQL. It could not create a table with an index, and could not drop a column, on that engine at all.
+
+  `IF [NOT] EXISTS` outside `CREATE`/`DROP TABLE` is a MariaDB extension — MySQL rejects it with ER_PARSE_ERROR (measured on 8.4 for `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE … DROP COLUMN IF EXISTS`, and `ADD COLUMN IF NOT EXISTS`). The applier emitted the first two, because `@effect/sql-mysql2` reports the dialect `mysql` for both engines and the shared branch had only ever run against MariaDB. A `reference()` column gets an index by default, so in practice most tables were affected.
+
+  The applier now asks the SERVER which engine it is (`SELECT VERSION()`; MariaDB stamps itself into the string) and emits the plain form on MySQL. The idempotency `IF [NOT] EXISTS` provided moves into the statement runner, which tolerates exactly the errnos meaning "already in the requested state" — 1061 for a duplicate index name, 1091 for dropping something absent. The engine is read from the connection rather than from `DB_DIALECT` or `variant`, because the DDL has to be legal for the server that receives it and those are what an operator typed.
+
+  Verified against live MySQL 8.4 and MariaDB 11: a schema evolution — create, add column, add index, drop column — applied through `applyPlan` on both, converging at every step, plus a replayed plan (what a resume does) that must not error on the statements it repeats.
+
+  **sqlite had the same defect, found by the new cross-dialect scenario on its first run.** `ALTER TABLE … DROP COLUMN IF EXISTS` is accepted by postgres, mssql and MariaDB and rejected by sqlite — and the generic emitter, shaped for postgres, is what sqlite used. So `voltro db apply` could not drop a column on sqlite either. The conditional form is now emitted only where it is legal, and the "already dropped" case is tolerated per dialect (`idempotentDdl.ts`).
+
+  `runDialectParity` gained a schema-evolution scenario — create, add column, add index, drop column, applied for real with a convergence check after each step — so the migration APPLIER is now covered on all five dialects. It previously had one scenario covering one op kind, while twenty-two covered the store; that split is why four emitter defects survived.
+
+  **And a fifth, found by making one MariaDB-only suite two-sided.** `text().unique()` on an unbounded text column created a table on MariaDB and failed the CREATE outright on MySQL: `BLOB/TEXT column 'x' used in key specification without a key length`. The bring-up emitter (`migrate.ts`) wrote an inline `UNIQUE`; the declarative applier had always written a separate PREFIXED unique index. The two emitters disagreeing on one statement is the failure shape this package's own notes describe, and only one engine said so.
+
+  `migrate.ts` emits the prefixed index now, through the same `indexStmt` that already owns the per-dialect `IF NOT EXISTS` rule, and names it `<table>_<column>_key` to match the applier's — so the two paths produce the same object.
+
+  **Note the behaviour change on MariaDB.** It accepted the inline form by backing it with a HASH long-unique index, whose hidden `DB_ROW_HASH_n` column breaks the binlog CDC reader (documented in `packages/database/CLAUDE.md`). Uniqueness on such a column is now enforced on the first 191 characters rather than the whole value — which is what `voltro db apply` already did, and what MySQL can express at all. Bound the column with `text().maxLength(n)` if you need full-value uniqueness.
+- **@voltro/sql-mysql** — `insertIgnore` on MySQL was a different feature from `insertIgnore` on MariaDB — and the difference could turn a conflict into an error.
+
+  The whole diagnostic apparatus — the refusal to report a REJECTED write as a conflict, and the message naming the constraint that actually fired — sat behind a `variant === 'mariadb'` branch. MySQL took an `else` that used no `INSERT IGNORE` at all: look for a row matching the conflict columns, insert if there is none. That cannot hold the one property the method exists for. A caller that looks before anyone else writes sees nothing, so the write it then makes is the one that raises the duplicate-key error `insertIgnore` promises never to raise — reproduced deterministically against both engines with an uncommitted holder (the lookup cannot see the holder's row; the insert cannot proceed until it commits).
+
+  Underneath sat the reason a straight port would still have produced nothing: **MySQL answers a PREPARED `SHOW WARNINGS` with 1295 ER_UNSUPPORTED_PS**, and the warning read is deliberately failure-tolerant (a diagnostic must never replace the caller's real problem), so it returned an empty list — indistinguishable from a statement that raised nothing. MariaDB accepts both protocols. The read goes through the text protocol now, the same spelling the binlog path already used for `SHOW MASTER STATUS`.
+
+  Both engines now run one `INSERT IGNORE` and reach one decision function. What differs is only the probe for "did it land": MariaDB has `INSERT IGNORE … RETURNING *`; MySQL has no RETURNING, so the row's own key answers instead. `SELECT ROW_COUNT()` — the obvious alternative — cannot be used: measured on both engines, it reports 1/0 correctly but CLEARS the warning list on MySQL, and run the other way round returns `-1` because `SHOW WARNINGS` is then the last statement. The count and the diagnosis cannot both be had; the diagnosis is the one worth having.
+
+  Found by converting the suite that covers this to run on both engines, which is also where every MySQL assertion in it had been reporting the driver's generic `Failed to execute statement`.
+- **@voltro/database** — A `reference()` column now creates a real foreign key on **MySQL**. It did not before: MySQL/InnoDB parses a column-inline `REFERENCES` clause and discards it — no constraint, no warning, the `CREATE TABLE` succeeds — while MariaDB honours the identical clause. Both engines reach the same emitter (the driver reports the dialect `mysql` for either), and every mysql-family integration suite in the repo runs against MariaDB, so referential integrity that postgres, MariaDB, mssql and sqlite all enforced was silently absent on MySQL.
+
+  Both emitters now write a table-level `CONSTRAINT <table>_<column>_fkey FOREIGN KEY …` inside the `CREATE TABLE`, which both engines honour and which `CREATE TABLE IF NOT EXISTS` keeps idempotent. Existing MariaDB schemas are unaffected — the introspected snapshot carries no constraint name, so nothing re-plans.
+
+  Verified against live MySQL 8.4: the constraint is in the catalog, the server refuses an orphan row, introspection reads it back, and the re-plan is empty.
+- **@voltro/sql-turso, @voltro/testing** — A migration on turso applied correctly and then reported itself as failed: `voltro db apply` ran an `add-column`, re-planned to prove convergence, saw the column still missing, proposed the same operation again, and the second execution died with `duplicate column name`. No fingerprint was recorded, so every subsequent boot re-proposed the same work — and the error named the migration applier, which had done nothing wrong.
+
+  The client caches one prepared statement per connection per SQL text, and a prepared statement carries the schema it was prepared against. So a cached `PRAGMA table_info(t)` keeps answering with the old columns after a DDL — it is never re-prepared, so sqlite's schema-cookie re-preparation never runs. The invalidation for this existed, on the unprepared path (`sql.unsafe`) only, and the migration path sends its DDL through the PREPARED one. The statement that changed the schema and the cache that had to be dropped were on the same connection, one function apart, with nothing connecting them.
+
+  Any schema-changing statement now drops that connection's cached statements, whichever path it arrived on.
+
+  Three hypotheses were measured and disproven before this one — an applier retry (each operation is issued once), an MVCC snapshot (two raw libsql clients both see the DDL), and a pool-wide cache problem (four connections held open together, the PRAGMA prepared on each, a DDL on one: the other three answer correctly, because SQLite bumps the schema cookie and the driver re-prepares on the connections that did not make the change).
+
+  The two `runDialectParity` scenarios that drive the migration applier were skipped for turso on the strength of that misreading. They run now, and the per-fixture opt-out that carried the skip is deleted: it was holding a defect open while reading like a documented limitation.
+
+  **`apiSurface: compatible`, and the reason is a date rather than an argument.** Removing `DialectFixture.skipApplierScenarios` moves a line in `@voltro/testing`'s golden, so the changelog's narrowing detector flags it — and it is right to, because that detector's baseline is `origin/main`. But the field never reached a RELEASE: it was added after `v0.41.0` and deleted before this one, both inside the same unreleased range. `git show v0.41.0:packages/testing/etc/testing-dialect.api.md` does not contain it. No published version ever offered it, so no consumer can have set it, and there is nothing to migrate.
+
+  Worth writing down because the first reading of this was wrong in the safe direction: it was filed `BREAKING` with a codemod on the strength of "an optional field disappeared from a published package's surface", which is the right instinct and the wrong conclusion here. **"Removed relative to main" is not "removed relative to what users have"** — a symbol that lives and dies between two tags trips the detector while breaking nobody, and the difference is only visible by asking the last TAG rather than the last commit.
+
+---
+
 ## [0.41.0] — 2026-08-17
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -364,6 +364,20 @@ export declare class MysqlStore implements DataStore {
      */
     private maxInTxn;
     private routeEvent;
+    /**
+     * Could this row be INSERTed on its own?
+     *
+     * True when every declared column that is NOT NULL, has no default of any
+     * kind, and is not computed by the database carries a value. That is exactly
+     * the condition `INSERT … ON DUPLICATE KEY UPDATE` imposes on its insert half
+     * — the server validates it even when the update half is the one that runs.
+     *
+     * Unknown table (a raw handle, a plugin store, a seed against an unregistered
+     * name) → treated as complete: the registry is the only source for this, and
+     * guessing "partial" would move every such write onto the slower path for a
+     * question we cannot answer.
+     */
+    private isCompleteInsertRow;
     private executeUpsert;
     /**
      * MariaDB 10.5+ native upsert:
@@ -376,7 +390,28 @@ export declare class MysqlStore implements DataStore {
     private executeMariadbUpsert;
     private executeInsertIgnore;
     /**
-     * The warnings MariaDB raised for the statement that just ran on `txn`.
+     * The `INSERT IGNORE` itself and what its outcome MEANS, on one connection.
+     *
+     * Split out from the caller purely so that "one connection" is a property of
+     * the signature rather than of whoever remembers to pass one: every read here
+     * is about the statement that just ran on `conn`, and a single pooled acquire
+     * in the middle makes the diagnosis describe someone else's statement.
+     */
+    private decideInsertIgnore;
+    /**
+     * What a SKIPPED `INSERT IGNORE` means — one decision, both engines.
+     *
+     * It is a separate method because the two engines reach it by different
+     * probes (RETURNING on MariaDB, a keyed re-read on MySQL) and a per-engine
+     * copy of THIS is what would drift: the codes, the wording, and the refusal
+     * to call a rejection a conflict are the same statement about the same
+     * feature. The warnings are passed IN rather than read here, because they
+     * have to be read before any other statement touches the connection and the
+     * caller is the only place that ordering is visible.
+     */
+    private resolveSkippedInsertIgnore;
+    /**
+     * The warnings the server raised for the statement that just ran on `txn`.
      *
      * Only meaningful inside a transaction, and that is why the parameter is not
      * optional. `SHOW WARNINGS` reports the last statement on the CONNECTION, and
@@ -468,7 +503,7 @@ export declare class MysqlStore implements DataStore {
      * and `isRetryableMysqlFailure` (deadlock / lock-wait timeout). Retry,
      * commit-defect promotion, attribution threading and exit settling are shared
      * — this store carried its own copy of the last one for a release after
-     * postgres was fixed, and a consumer on MariaDB paid for it. See
+     * postgres was fixed, and a deployment on MariaDB paid for it. See
      * `transactionOutcome.ts`.
      */
     private txnSpec;

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, hasEagerLoads as E, isTableReactive as D, makeEagerFallbackReporter as ee, observeDbOp as O, qualifyTable as te, raiseChangeListenerCeiling as ne, recordsTable as re, registerPendingAttribution as ie, requireTable as k, resolveEchoAttribution as A, runStoreTransaction as j, runWriteRecorders as ae, stampGeneratedId as M, stampGeneratedIds as oe, withCapturedAttribution as N } from "@voltro/database";
-import { EventEmitter as se } from "node:events";
+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";
 //#region src/sqlLayer.ts
-var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
+var le = (e) => e ? { rejectUnauthorized: !1 } : void 0, ue = (e) => {
 	let t = e.acquireTimeoutMs ?? l;
 	return t > 0 ? t : void 0;
 }, L = (e) => {
 	let t = e.acquireQueueLimit;
 	return t !== void 0 && t > 0 ? t : void 0;
 }, R = (e) => {
-	let t = e.ssl === void 0 ? void 0 : ce(e.ssl), n = le(e), r = L(e);
+	let t = e.ssl === void 0 ? void 0 : le(e.ssl), n = ue(e), r = L(e);
 	return {
 		...t === void 0 ? {} : { ssl: t },
 		...n === void 0 ? {} : { connectTimeout: n },
@@ -67,20 +67,20 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		...e.ssl === void 0 ? {} : { ssl: e.ssl },
 		...t
 	};
-}, 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, W = (e) => e.msSinceProgress < e.stallThresholdMs ? "healthy" : e.primary !== null && !U(e.primary, e.reader) ? "idle-caught-up" : "reconnect", ue = (e) => (e instanceof Error ? e.message : String(e ?? "")).includes("schema changed between binlog event and metadata fetch"), de = (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;
-}, fe = "\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", G = (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).`, pe = 3e5, me = 3, he = (e, t) => {
-	let n = [...e.filter((e) => t - e < pe), 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", 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];
 	return {
-		verdict: n.length >= me ? "persistent" : "backlog",
+		verdict: n.length >= ge ? "persistent" : "backlog",
 		hits: n
 	};
-}, ge = /* @__PURE__ */ new Set([
+}, ve = /* @__PURE__ */ new Set([
 	"writerows",
 	"updaterows",
 	"deleterows"
-]), _e = /\b(alter|rename|drop|create)\s+(table|column)?/i, K = (e) => new Promise((t) => setTimeout(t, e)), q = async (e) => {
+]), 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;
 	try {
 		n = (await import("@vlasky/zongji")).default;
@@ -96,14 +96,14 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 			o = n.binlogName;
 			return;
 		}
-		if (r === "query" && n.query && _e.test(n.query)) {
+		if (r === "query" && n.query && ye.test(n.query)) {
 			l && (l.tableMap = {});
 			return;
 		}
 		if (n.nextPosition && o && (s = {
 			filename: o,
 			position: n.nextPosition
-		}, e.onPosition?.(s)), !ge.has(r)) return;
+		}, e.onPosition?.(s)), !ve.has(r)) return;
 		let u = n.tableMap[n.tableId];
 		if (!u || u.parentSchema !== a) return;
 		let d = u.tableName;
@@ -181,11 +181,11 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 					try {
 						l?.stop();
 					} catch {}
-					if (d++, await K(Math.min(3e4, 500 * 2 ** Math.min(d, 6))), u) return;
-					let i = s, a = C(n), c = !a && ue(n), f = !1;
+					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 = de(n), i = e ?? "<unknown>", { verdict: a, hits: o } = he(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(G(i)));
+						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 {
@@ -209,14 +209,14 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 				l?.stop();
 			} catch {}
 			let n = e.resolveStartPosition ? await e.resolveStartPosition().catch(() => null) : null;
-			o = n?.filename ?? null, e.onResync?.(), await K(500), await w(n);
+			o = n?.filename ?? null, e.onResync?.(), await G(500), await w(n);
 		} else throw n;
 	}
 	let E = async () => {
 		if (u || p || Date.now() - f < _) return;
 		let n = null;
 		if (e.resolveStartPosition && (n = await e.resolveStartPosition().catch(() => null)), u || p) return;
-		let r = W({
+		let r = de({
 			msSinceProgress: Date.now() - f,
 			stallThresholdMs: _,
 			primary: n,
@@ -245,7 +245,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		},
 		currentPosition: () => s
 	};
-}, ve = /* @__PURE__ */ new Set(["1213", "1205"]), ye = (e) => {
+}, be = /* @__PURE__ */ new Set(["1213", "1205"]), xe = (e) => {
 	let t = e;
 	for (let e = 0; e < 5 && typeof t == "object" && t; e++) {
 		let e = t.errno;
@@ -254,31 +254,31 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		if (typeof n == "string") return n;
 		t = t.cause;
 	}
-}, J = (e) => {
-	let t = ye(e);
-	return t !== void 0 && ve.has(t);
-}, Y = (e) => J(e) ? "retry" : "noRetry", X = (e) => {
+}, q = (e) => {
+	let t = xe(e);
+	return t !== void 0 && be.has(t);
+}, J = (e) => q(e) ? "retry" : "noRetry", Y = (e) => {
 	if (e == null) return "null";
 	let t = typeof e;
 	if (t === "bigint") return `${e}n`;
 	if (t !== "object") return JSON.stringify(e);
 	if (e instanceof Date) return `"${e.toISOString()}"`;
-	if (Array.isArray(e)) return `[${e.map(X).join(",")}]`;
+	if (Array.isArray(e)) return `[${e.map(Y).join(",")}]`;
 	let n = e;
-	return `{${Object.keys(n).sort().map((e) => `${JSON.stringify(e)}:${X(n[e])}`).join(",")}}`;
-}, be = (e) => {
-	let t = X(e), n = 2166136261;
+	return `{${Object.keys(n).sort().map((e) => `${JSON.stringify(e)}:${Y(n[e])}`).join(",")}}`;
+}, Se = (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);
-}, xe = (e, t) => {
+}, Ce = (e, t) => {
 	let n = setTimeout(e, t);
 	typeof n.unref == "function" && n.unref();
-}, Se = class {
+}, we = class {
 	variant;
 	ttlMs;
 	schedule;
 	seen = /* @__PURE__ */ new Map();
-	constructor(e, t = 6e4, n = xe) {
+	constructor(e, t = 6e4, n = Ce) {
 		this.variant = e, this.ttlMs = t, this.schedule = n;
 	}
 	key(e) {
@@ -292,7 +292,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		} catch {
 			r = t;
 		}
-		return `${e.table} ${e.op} ${String(n)} ${be(r)}`;
+		return `${e.table} ${e.op} ${String(n)} ${Se(r)}`;
 	}
 	admit(e) {
 		let t = this.key(e);
@@ -307,16 +307,16 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	get pending() {
 		return this.seen.size;
 	}
-}, Z = /* @__PURE__ */ new Set([
+}, X = /* @__PURE__ */ new Set([
 	1022,
 	1062,
 	1586
-]), Q = async (e) => {
+]), Z = async (e) => {
 	let t = e.variant ?? "mysql", n = P({ 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 Ce(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(F), c, t, o);
 	return o === "cdc" && e.cdcConfig && await l.startCdcConsumer(e.cdcConfig), l;
-}, Ce = class e {
+}, Q = class e {
 	sql;
 	runtime;
 	variant;
@@ -333,13 +333,13 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	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 = ee(this.log), this.emitter = a ?? new se(), ne(this.emitter), this.cdcGate = o ?? new Se(n);
+		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);
 	}
 	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 te(this.namespace, e);
+		return ne(this.namespace, e);
 	}
 	get dialectId() {
 		return this.variant;
@@ -410,7 +410,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		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.insert: TransactionConnection missing.")) : t(e.value)))), i = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(J)), o = e.pipe(n.retry(i), n.withSpan("store.insert", { attributes: {
+			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: {
 				"db.system": this.variant,
 				"db.operation": r
 			} }));
@@ -420,7 +420,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		}
 	}
 	async executeInsertMany(e, t, r, i, a) {
-		if (t = oe(e, t), t.length === 0) return [];
+		if (t = se(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;
@@ -555,7 +555,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		if (e = {
 			...p(r),
 			...e
-		}, re(e.table) && await ae({
+		}, ie(e.table) && await oe({
 			append: (e, t) => this.appendInTxn(e, t, n),
 			maxOf: (e, t, r) => this.maxInTxn(e, t, r, n)
 		}, {
@@ -567,7 +567,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 			subjectId: e.subjectId
 		}), this.changeStrategy === "cdc") {
 			let t = (e.op === "delete" ? e.old : e.new)?.id;
-			t != null && ie(m(e.table, e.op, t), {
+			t != null && k(m(e.table, e.op, t), {
 				...e.traceId === void 0 ? {} : { traceId: e.traceId },
 				...e.subjectId === void 0 ? {} : { subjectId: e.subjectId }
 			});
@@ -578,8 +578,15 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		}
 		this.emitChange(e);
 	}
+	isCompleteInsertRow(e, t) {
+		let n = E(e);
+		if (n === void 0) return !0;
+		let r = n.fields;
+		for (let [e, n] of Object.entries(r)) if (n !== void 0 && n.nullable !== !0 && n.hasDefault !== !0 && n.defaultValue === void 0 && n.defaultFactory === void 0 && n.computed === void 0 && n.generatedAs === void 0 && n.idScheme === void 0 && t[e] === void 0) return !1;
+		return !0;
+	}
 	async executeUpsert(e, t, n, r, i, a) {
-		if (this.variant === "mariadb" && typeof n.update != "function") return this.executeMariadbUpsert(e, t, {
+		if (this.variant === "mariadb" && typeof n.update != "function" && this.isCompleteInsertRow(e, t)) return this.executeMariadbUpsert(e, t, {
 			conflictColumns: n.conflictColumns,
 			...n.update === void 0 ? {} : { update: n.update }
 		}, r, i);
@@ -601,38 +608,79 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		return N((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 = s`INSERT INTO ${s(this.nsT(e))} ${s.insert(c)} ON DUPLICATE KEY UPDATE ${d} RETURNING *`, p = i ? n.provideService(f, I, i) : f, m = (await this.runtime.runPromise(p))[0];
-		if (!m) throw Error(`MysqlStore.upsert: no row returned for table '${e}'`);
-		let h = t.id !== void 0 && t.id === m.id ? "insert" : "update";
+		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];
+				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.`);
+				return o;
+			},
+			catch: (e) => e
+		}), "upsert"), p = t.id !== void 0 && t.id === f.id ? "insert" : "update";
 		return await this.routeEvent({
 			table: e,
-			op: h,
+			op: p,
 			old: null,
-			new: m
-		}, a, i, o), m;
+			new: f
+		}, a, i, o), f;
 	}
 	async executeInsertIgnore(e, t, r, i, a, o) {
-		if (t = M(e, t), this.variant === "mariadb") {
-			let s = this.sql, c = s`INSERT IGNORE INTO ${s(this.nsT(e))} ${s.insert(C(t, e))} RETURNING *`, l = i ? n.provideService(c, I, i) : c, u = (await this.runtime.runPromise(l))[0];
-			if (u) return await this.routeEvent({
-				table: e,
-				op: "insert",
-				old: null,
-				new: u
-			}, a, i, o), u;
-			let d = await this.readWarnings(i), f = d.find((e) => !Z.has(e.code));
-			if (f !== void 0) throw Error(`MysqlStore.insertIgnore: the insert into '${e}' was REJECTED, not skipped as a conflict. INSERT IGNORE downgrades every error to a warning, and the warning was: [${f.code}] ${f.message}. Nothing was written and nothing conflicted — fix the cause above.`);
-			let p = await this.findByConflict(e, t, r.conflictColumns, i);
-			if (p) return p;
-			let m = d[0];
-			throw Error(`MysqlStore.insertIgnore: the insert was skipped as a conflict, but no existing row matches conflictColumns [${r.conflictColumns.join(", ")}] on '${e}'. ` + (m === void 0 ? "The warning could not be read on this connection, so the constraint that fired is unknown — it may be a second unique index, or the primary key under another name. " : `The constraint that actually fired: [${m.code}] ${m.message}. `) + "insertIgnore models ONE conflict target: name the columns of the constraint that actually collides, or handle the violation yourself.");
+		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));
+		let s = await this.runPinned(i, (i) => n.tryPromise({
+			try: () => this.decideInsertIgnore(e, t, r, i),
+			catch: (e) => e
+		}), "insertIgnore");
+		return s.kind === "landed" && await this.routeEvent({
+			table: e,
+			op: "insert",
+			old: null,
+			new: s.row
+		}, 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));
+		if (this.supportsInsertReturning) {
+			let n = (await s(a`INSERT IGNORE INTO ${a(this.nsT(e))} ${a.insert(o)} RETURNING *`))[0];
+			if (n) return {
+				kind: "landed",
+				row: n
+			};
+			let c = await this.readWarnings(i);
+			return {
+				kind: "existing",
+				row: await this.resolveSkippedInsertIgnore(e, t, r, c, i)
+			};
+		}
+		await s(a`INSERT IGNORE INTO ${a(this.nsT(e))} ${a.insert(o)}`);
+		let c = await this.readWarnings(i);
+		if (!c.some((e) => X.has(e.code))) {
+			let n = (await s(a`SELECT * FROM ${a(this.nsT(e))} WHERE ${a("id")} = ${t.id}`))[0];
+			if (n) return {
+				kind: "landed",
+				row: n
+			};
 		}
-		return await this.findByConflict(e, t, r.conflictColumns, i) || N((n) => this.executeInsert(e, t, i, a, n));
+		return {
+			kind: "existing",
+			row: await this.resolveSkippedInsertIgnore(e, t, r, c, i)
+		};
+	}
+	async resolveSkippedInsertIgnore(e, t, n, r, i) {
+		let a = r.find((e) => !X.has(e.code));
+		if (a !== void 0) throw Error(`MysqlStore.insertIgnore: the insert into '${e}' was REJECTED, not skipped as a conflict. INSERT IGNORE downgrades every error to a warning, and the warning was: [${a.code}] ${a.message}. Nothing was written and nothing conflicted — fix the cause above.`, { cause: {
+			errno: a.code,
+			sqlMessage: a.message
+		} });
+		let o = await this.findByConflict(e, t, n.conflictColumns, i);
+		if (o) return o;
+		let s = r[0];
+		throw Error(`MysqlStore.insertIgnore: the insert was skipped as a conflict, but no existing row matches conflictColumns [${n.conflictColumns.join(", ")}] on '${e}'. ` + (s === void 0 ? "The warning could not be read on this connection, so the constraint that fired is unknown — it may be a second unique index, or the primary key under another name. " : `The constraint that actually fired: [${s.code}] ${s.message}. `) + "insertIgnore models ONE conflict target: name the columns of the constraint that actually collides, or handle the violation yourself.");
 	}
 	async findUndecodableCdcTables(e) {
 		if (this.variant !== "mariadb") return [];
 		try {
-			let t = (await this.runtime.runPromise(this.sql.unsafe(fe))).map((e) => String(e.tableName ?? e.TABLE_NAME ?? "")).filter((e) => e !== "");
+			let t = (await this.runtime.runPromise(this.sql.unsafe(me))).map((e) => String(e.tableName ?? e.TABLE_NAME ?? "")).filter((e) => e !== "");
 			return e === void 0 ? t : t.filter((t) => e.includes(t));
 		} catch (e) {
 			return this.log.debug(`cdc: could not probe for undecodable tables — ${e?.message ?? String(e)}`), [];
@@ -641,7 +689,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	async readWarnings(e) {
 		if (e === null) return [];
 		try {
-			let t = this.sql`SHOW WARNINGS`;
+			let t = this.sql`SHOW WARNINGS`.unprepared;
 			return (await this.runtime.runPromise(n.provideService(t, I, e))).map((e) => ({
 				code: Number(e.Code ?? e.code ?? 0),
 				message: String(e.Message ?? e.message ?? "")
@@ -663,7 +711,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 		return O(this.variant, "raw", () => this.runtime.runPromise(n));
 	}
 	async runWithEager(e, t) {
-		if (!E(e)) return this.executeQuery(e, t);
+		if (!ee(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));
@@ -683,7 +731,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 			reason: "not-compilable"
 		});
 		let a = await this.executeQuery(e, t);
-		return f(a, e.eager, e.sourceTable ?? k(e.table), (e) => this.executeQuery(e, t));
+		return f(a, e.eager, e.sourceTable ?? A(e.table), (e) => this.executeQuery(e, t));
 	}
 	getInternalRunWithEager() {
 		return this.runWithEager.bind(this);
@@ -742,7 +790,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 					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));
 				});
-			}))), c = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(J)), l = r.pipe(n.retry(c), n.withSpan("store.updateMany", { attributes: {
+			}))), 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,
 				"db.operation": "update"
 			} })), u = await this.runtime.runPromise(l);
@@ -777,7 +825,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 				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));
-			}))), o = s.exponential("10 millis").pipe(s.compose(s.recurs(3)), s.whileInput(J)), c = t.pipe(n.retry(o), n.withSpan("store.deleteMany", { attributes: {
+			}))), 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"
 			} })), l = await this.runtime.runPromise(c);
@@ -801,8 +849,8 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (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(G(e));
-		this.cdcHandle = await q({
+		for (let e of n) this.log.error(W(e));
+		this.cdcHandle = await K({
 			connection: e.connection,
 			serverId: e.serverId,
 			variant: this.variant,
@@ -920,10 +968,10 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	async transactional(e) {
 		this.inflightTxns++;
 		try {
-			return await j({
+			return await ae({
 				...this.txnSpec("MysqlStore.transactional"),
 				work: e,
-				makeView: (e, t) => new we(this, e, t)
+				makeView: (e, t) => new Te(this, e, t)
 			});
 		} finally {
 			this.inflightTxns--;
@@ -935,7 +983,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 			dialect: this.variant === "mariadb" ? "mariadb" : "mysql",
 			withTransaction: (e) => this.sql.withTransaction(e),
 			runPromiseExit: (e) => this.runtime.runPromiseExit(e),
-			isRetryable: J,
+			isRetryable: q,
 			span: {
 				name: "store.transactional",
 				attributes: {
@@ -956,7 +1004,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	injectExternalChange(e) {
 		if (this.changeStrategy === "cdc" && !this.cdcGate.admit(e) || !D(e.table)) return;
 		let t = (e.op === "delete" ? e.old : e.new)?.id;
-		A(e.table, e.op, t, (t) => {
+		j(e.table, e.op, t, (t) => {
 			this.emitter.emit("change", T(e, t));
 		});
 	}
@@ -981,7 +1029,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	async ping() {
 		await this.runtime.runPromise(this.sql`SELECT 1`);
 	}
-}, we = class {
+}, Te = class {
 	parent;
 	txn;
 	attr;
@@ -1054,7 +1102,7 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 			this.events.length = 0;
 		}
 	}
-}, $ = (e) => e.__mysqlReplicationFriend ?? null, Te = () => ({
+}, $ = (e) => e.__mysqlReplicationFriend ?? null, Ee = () => ({
 	async capturePrimaryPosition(e) {
 		let t = $(e);
 		if (t === null) throw Error("mysqlReplicationAdapter: primary is not a MysqlStore (missing __mysqlReplicationFriend).");
@@ -1074,24 +1122,24 @@ var ce = (e) => e ? { rejectUnauthorized: !1 } : void 0, le = (e) => {
 	compare(e, t) {
 		return "behind";
 	}
-}), Ee = {
+}), De = {
 	id: "mysql",
 	makeSqlLayer: (e) => H(e),
-	makeStore: (e) => Q({
+	makeStore: (e) => Z({
 		...e,
 		variant: "mysql"
 	}),
 	compileContains: (e, t, n) => n`${e} LIKE ${`%${t.replace(/[\\%_]/g, (e) => `\\${e}`)}%`} ESCAPE '\\'`,
-	retryFilter: Y
-}, De = {
+	retryFilter: J
+}, Oe = {
 	id: "mariadb",
 	makeSqlLayer: (e) => H(e),
-	makeStore: (e) => Q({
+	makeStore: (e) => Z({
 		...e,
 		variant: "mariadb"
 	}),
 	compileContains: (e, t, n) => n`${e} LIKE ${`%${t.replace(/[\\%_]/g, (e) => `\\${e}`)}%`} ESCAPE '\\'`,
-	retryFilter: Y
+	retryFilter: J
 };
 //#endregion
-export { c as CDC_OFFSETS_TABLE, e as MysqlClient, d as _voltroCdcOffsetsTable, V as connectionFromConfig, z as makeMysqlSqlLayer, H as makeMysqlSqlLayerFromConfig, Q as makeMysqlStore, De as mariadbDialect, Ee as mysqlDialect, Te as mysqlReplicationAdapter, Y as mysqlRetryFilter, q 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, Oe as mariadbDialect, De as mysqlDialect, Ee as mysqlReplicationAdapter, J as mysqlRetryFilter, K as startBinlogCdc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/sql-mysql",
-  "version": "0.41.0",
+  "version": "0.43.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.41.0",
-    "@voltro/logger": "0.41.0"
+    "@voltro/database": "0.43.0",
+    "@voltro/logger": "0.43.0"
   },
   "optionalDependencies": {
     "@vlasky/zongji": "^0.9.0"