@voltro/database 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -39,6 +39,97 @@ _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

package/dist/index.d.ts

@@ -173,7 +173,7 @@ export declare const attachEagerLoads: (rows: ReadonlyArray<Row_2>, spec: WithSp
  * Returns an object with the keys OMITTED rather than set to `undefined`, so an
  * unattributed event is byte-identical to one from before this existed — no
  * `traceId: undefined` appearing in a snapshot, a broadcast payload, or a
- * consumer's `Object.keys`.
+ * deployment's `Object.keys`.
  *
  * **Call it where the event is CREATED, not where it is delivered.** A
  * transactional write queues its events and flushes them after commit, by which
@@ -222,7 +222,7 @@ export declare const auditTableIndexes: (table: Table<string, Record<string, Col
  *  so an insert need not supply them. Name-based on purpose: a hand-declared
  *  `createdAt` with no default reads as optional here (the lenient direction —
  *  never rejects valid code), while the mixin-managed ones are always filled.
- *  Runtime tuple + the type derived from it, so a consumer that must skip these
+ *  Runtime tuple + the type derived from it, so a deployment that must skip these
  *  at runtime (e.g. `@voltro/testing`'s `fixtureRow`, which fills only
  *  caller-owned required columns) reads the SAME list the insert-row type uses —
  *  no second copy to drift. */
@@ -651,7 +651,7 @@ export declare type ChangeEvent = {
      * How the event reached this process. Absent/'inline' = emitted by this
      * process's own write path; 'injected' = delivered over a cross-instance
      * transport (`injectExternalChange` — the broadcast bus or a CDC
-     * consumer). A consumer that must act exactly once per change
+     * consumer). A deployment that must act exactly once per change
      * FLEET-WIDE combines this with `DataStore.changeScope`: on a
      * `'local'`-scope store, acting on non-injected events covers each
      * change exactly once (on its writer); on a `'fleet'`-scope store every
@@ -2858,7 +2858,7 @@ declare type EmptyMerge = unknown;
  *
  * It was three. The store wrote `encrypt(JSON.stringify(v))`, the escape hatch
  * wrote `encrypt(v)`, and the backfill wrote `encrypt(v)`. All three produce the
- * `enc:v1:` envelope and NOTHING distinguishes them. A consumer wrote session
+ * `enc:v1:` envelope and NOTHING distinguishes them. A deployment wrote session
  * rows through the escape hatch and read them through the store, which threw
  * `FieldDecryptionError` blaming the key — the key was right; the ENCODING was
  * not. Eight of their ten session rows, and the failure looked like a key
@@ -3556,7 +3556,7 @@ export declare const isBranchNamespace: (namespace: string) => boolean;
  * `isRelationsSpec` rejects it (registering nothing has no meaning), which is
  * right, but the caller then cannot tell it apart from a module with no
  * `relations(...)` export at all. `voltro dev` reported both as *"no relations(...)
- * export found"*, and a consumer with 368 relations files got exactly one warning
+ * export found"*, and a deployment with 368 relations files got exactly one warning
  * pointing at a file that HAS the export:
  *
  *     export const easyProxyIntegrationsRelations = relations(easyProxyIntegrations, ({ one }) => ({
@@ -3629,7 +3629,7 @@ export declare const isPrimaryKeyConflictError: (err: unknown) => err is Primary
  *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
  *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
  *  transient error — a re-run just repeats the runaway, so it must not retry
- *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
+ *  (`servePipeline`'s transient set deliberately excludes it). Lets a deployment /
  *  observability layer name the failure instead of reading an opaque SqlError. */
 export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
 
@@ -3925,7 +3925,7 @@ export declare interface ManyToManyRelation {
  * the dangerous one: an empty `IN ()` gets dropped, and a DROPPED predicate does
  * not narrow — it WIDENS, to the whole tenant. Here it is safe (the SQL
  * compiler emits `FALSE`, the in-memory evaluator returns false, and both are
- * pinned by tests) but an adopting team wrote `eq('id', '')` instead, because
+ * pinned by tests) but an adopting project wrote `eq('id', '')` instead, because
  * they could not tell from the outside and would not bet a visibility rule on
  * it. They were right not to.
  *
@@ -5434,7 +5434,7 @@ export declare const registerPendingAttribution: (key: string, attribution: Writ
  * Register a single `relations()` spec. Multiple specs on the same
  * source MERGE — a second spec adds to the first one. A name
  * collision between two DIFFERENT specs throws here so the offending
- * declaration site is the error scope, not a downstream consumer.
+ * declaration site is the error scope, not a downstream deployment.
  *
  * Re-registering the SAME relation object is a no-op, mirroring
  * `registerTable`'s `existing === table` tolerance — and for the same reason:
@@ -5461,7 +5461,7 @@ export declare const registerRelations: (spec: RelationsSpec) => void;
  *
  * ── Two registrations for one table used to be a silent last-write-wins ─────
  *
- * A consumer registered `_voltro_schedule_claims` at 1 hour from a startup, and
+ * A deployment registered `_voltro_schedule_claims` at 1 hour from a startup, and
  * one second later the framework registered its own default for the same table.
  * Ours won, nothing said so, and their startup went on logging `bounded to 1h`
  * at every boot while the table kept everything younger than the framework's
@@ -5752,7 +5752,7 @@ export declare interface RetentionSpec {
      * The environment variable that changes this TTL, for the boot announcement.
      *
      * A standing DELETE whose only control is a variable you have to already know
-     * the name of is how a consumer lost 1 944 freshly-migrated rows to a 180-day
+     * the name of is how a deployment lost 1 944 freshly-migrated rows to a 180-day
      * default — and then got it wrong a second time by setting it in a running pod
      * rather than in a file, where the next deploy would have reverted it. Naming
      * it in the boot line is what turns "you have to know" into "you were told".
@@ -5946,7 +5946,7 @@ export declare type SchemaChangeSeedHook = (event: SchemaChangeSeedEvent) => Pro
  * inferred {@link Table} generic pulls its method signatures into the emitted
  * `.d.ts`, and those reference the private `ColumnBuilder` class — which
  * TypeScript refuses to name across the boundary (TS4094). `SchemaTable`
- * exposes only the plain-data surface a consumer of a contributed table
+ * exposes only the plain-data surface a deployment of a contributed table
  * actually reads (`.tableName`, `.fields`, `.appliedIndexes`), so it names
  * cleanly and stays browser-safe (pure interfaces, no builder, no server
  * imports). A concrete `Table<...>` is assignable to it.
@@ -6093,7 +6093,7 @@ export declare interface SeedStore {
      * The primitive an idempotent restore is actually built on: `upsertByUnique`
      * costs a read per row and OVERWRITES what it finds, which is wrong when the
      * live row is newer than the snapshot. This is one statement per row and
-     * leaves an existing row alone. Reported by a consumer restoring 1361 rows
+     * leaves an existing row alone. Reported from a real deployment restoring 1361 rows
      * across 167 tables in multiple passes for FK order — with only
      * `upsertByUnique` available, every pass re-read and re-wrote everything.
      */
@@ -6342,7 +6342,7 @@ export declare interface StreamTableOptions {
     readonly where?: Predicate;
     /** Rows per DB page. Larger = fewer round-trips, more per-page memory.
      *  Default 1000. This is the READ page size; it is independent of any
-     *  downstream write/checkpoint chunking a consumer layers on. */
+     *  downstream write/checkpoint chunking a deployment layers on. */
     readonly chunkSize?: number;
     /** Pass-through of the reactive scope opt-outs. For a faithful physical
      *  export use the RAW dialect store (no scoping applied at all); these
@@ -7624,7 +7624,7 @@ export declare interface WindowSpec {
  * request behind this write", so the result does not look like a defect; it looks
  * like a schedule. In a compliance trail that asymmetry is the whole problem.
  *
- * A consumer could not reproduce it across 2700 writes at 96-way concurrency with
+ * A deployment could not reproduce it across 2700 writes at 96-way concurrency with
  * every core saturated — which is good evidence the window is narrow at their load
  * and no evidence at all that it is closed. Their own framing is why this is being
  * closed structurally rather than left: *"impossible beats unlikely when the

package/dist/sql.d.ts

@@ -817,7 +817,7 @@ export declare interface ColumnSnapshot {
      * never reached the comparison. So the differ was not comparing lengths wrongly
      * — it could not see them. Adding `.maxLength(n)` to an EXISTING column planned
      * zero operations and reported "schema is up to date" while the live column
-     * stayed `longtext`. A consumer hit that trying to apply the documented remedy
+     * stayed `longtext`. A deployment hit that trying to apply the documented remedy
      * for MariaDB's hash long-unique, and their contrast is what pinned it: a column
      * bounded AT CREATION was `varchar(64)` (DDL path, fine), one bounded afterwards
      * stayed `longtext` (diff path, blind).
@@ -2408,7 +2408,7 @@ export declare const reactiveTriggerName: (tableName: string, channel: string) =
  * dimension at all, so `db plan` reports 0 operations and `db apply` reports
  * "schema is up to date" while the drift detector is simultaneously telling
  * you 500 tables have no trigger, and pointing at `voltro db apply` as the
- * remedy. Reported by a consumer with 525 tables and 27 triggers, all 27 on
+ * remedy. Reported from a real deployment with 525 tables and 27 triggers, all 27 on
  * framework tables.
  *
  * A single instance is unaffected — its own writes reach its own subscribers