@voltro/database 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -39,6 +39,36 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.47.0] — 2026-08-22
+
+### Changed
+
+- **@voltro/database, @voltro/data-transfer, @voltro/cli, @voltro/plugin-storage** — A `--mode replace` no longer writes per-row history, and three things that were reported alongside it.
+
+  **Write recorders are suspended for a `replace`.** A replace SETS a state; it does not change rows, so a per-row history entry describes something that did not happen. A deployment measured what that costs: they run `versioningPlugin({ timing: 'in-transaction' })` on 70 of 80 tables, so one import wrote 242 950 history rows and doubled the write load of the most expensive run they make — and those rows were the source of refused writes they spent three rounds diagnosing.
+
+  The deciding argument is not the cost. **The import path had already decided this, and the recorder was the one layer that did not hear.** These routes write through the RAW store on purpose — no tenant scoping, no row filter, no `audit()` stamping. A recorder fired anyway because it hangs one level below the wrapper. Suspending it makes the layers agree.
+
+  Suspended for `replace` only: an `upsert` or an `append` CHANGES existing state, which is exactly what a recorder is for. Scoped per execution context rather than by a switch, because an import runs while the app serves requests and a process-global flag would silently drop recording for everything concurrent with it. And every such run SAYS what it suspended — dropping history quietly would be the same defect in a nicer costume.
+
+  This also removes the reason a staged `replace` used to fall back. A recorder is keyed by table name, so a staged write found none and the recorder never ran; rather than record inconsistently, the run took the slower path. For the deployment above that meant the staged path could never activate — permanently, on every environment.
+
+  **`voltro codegen` wrote a truncated table declaration.** It discovered tables with the walk that collects the rpc GROUP's inputs — descriptors, workflows, events, and deliberately no `*.entity.ts`. So the generated `voltro-tables.generated.d.ts` listed the framework's tables plus `actors`, which the framework injects. Measured downstream: 37 names where a `voltro dev` boot writes 117, and 299 `TS2322` errors from every `source:` naming one of their own tables. The way in was our own message — `voltro test` refuses a stale rpc group and tells you to run `voltro codegen`. Table discovery has its own walk now, and a test compares the two walks' RESULTS on a real tree rather than trusting they mean the same thing.
+
+  **The eager-relation doctor rule missed the state that is most wrong.** It resolved relations only against the tables a query already DECLARED, on the reasoning that the base is virtually always in `source:`. Measured: a query reading `projects` while declaring only `projectTeams` produced no finding at all, while the same query with the base added produced two. The base is a fact about the executor, so it is read from the executor now.
+
+  **A rollback capture says when its path shares the root filesystem.** The 409 answered "is storage configured", which is not the question — a `filesystem` provider pointed at a container directory with no volume behind it passes it and dies with the pod. What a process CAN observe is that a mounted volume is a different filesystem: `pathDurability` compares device ids, and a capture landing on the same device as `/` says so. Three-valued on purpose, and explicitly not an alarm on a development machine, where everything is one device and nothing is a pod.
+
+  **And the import records ITSELF, once.** Dropping per-row history left an operator asking "was this data imported, and when" with nothing to read, and trading too much for none is not obviously the better trade. `_voltro_data_imports` carries one row per RUN: the mode, the transport, the bundle, the SOURCE deployment's schema fingerprint, the counts, and — for the run an operator is actually looking for — the failure. It is written for a failed import as well as a finished one; a trail that only records successes goes quiet exactly when it is needed.
+
+  Best effort, unlike the interrupted-replace marker, and the difference is deliberate: the marker is a safety interlock and a run that cannot write it must not proceed, while history is valuable and not load-bearing. A target that has not been migrated yet still imports, and says the trace could not be written.
+
+  Two things it learned from being wired. The table is `.nonReactive()` — nobody subscribes to "an import happened", and a reactive bookkeeping write showed up in every suite that counts the LOAD's writes. And it is written only when the target actually DECLARES the table: the in-memory store accepts a write to any name, so an absent table cannot be detected by the write failing, and inventing the row would put a framework write into every embedder's counts.
+
+  **Measured at the reported magnitude.** 114 tables, 243 048 rows, real MariaDB, staged replace: the whole run takes 56.5s and the DESTRUCTIVE TRANSACTION takes **1.13s**. The window in which a dead process can leave a half-replaced target is the second number; before this it was the first.
+
+---
+
 ## [0.46.0] — 2026-08-22
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -2750,6 +2750,14 @@ export declare const deriveTypeIdPrefix: (tableName: string) => string;
  */
 export declare const describeDriverError: (err: unknown) => string | undefined;
 
+/**
+ * The line an operator reads.
+ *
+ * States the outcome first. "An import ran" is not the question — "did it
+ * finish, and what did it bring" is.
+ */
+export declare const describeImportRun: (run: ImportRun) => string;
+
 /**
  * The TYPE of every binding in a row, and never a value.
  *
@@ -3573,6 +3581,22 @@ export declare type IdSchemeInput = undefined | {
 
 export declare type IdSchemeKind = 'typeid' | 'ulid' | 'numeric' | 'snowflake' | 'custom';
 
+export declare const IMPORT_RUNS_TABLE = "_voltro_data_imports";
+
+/** One import, as the inspector reads it back. */
+export declare interface ImportRun {
+    readonly id: string;
+    readonly startedAt: Date;
+    readonly finishedAt: Date | null;
+    readonly mode: string;
+    readonly via: string;
+    readonly bundle: string | null;
+    readonly sourceFingerprint: string | null;
+    readonly tablesWritten: number;
+    readonly rowsWritten: number;
+    readonly failure: string | null;
+}
+
 export declare interface IndexAuditIssue {
     readonly kind: IndexAuditIssueKind;
     readonly table: string;
@@ -5583,14 +5607,6 @@ export declare interface RecordedWrite {
     readonly procedure?: string | undefined;
 }
 
-/**
- * Is ANY recorder interested in `table`?
- *
- * The stores call this on every write, so it is the hot path: a store with no
- * recorders registered pays one `Map.size` check and nothing else, and never
- * awaits. Keeping `routeEvent`'s cost at zero for the default configuration is
- * what makes shipping this as an opt-in honest.
- */
 export declare const recordsTable: (table: string) => boolean;
 
 /**
@@ -6669,6 +6685,22 @@ export declare const sum: (column: string, alias?: string) => AggregateColumn;
 
 export declare const sumOver: (column: string, alias?: string) => WindowBuilder;
 
+export declare const suspendWriteRecorders: <A>(fn: () => Promise<A>) => Promise<A>;
+
+/**
+ * The same suspension for a caller holding an EFFECT.
+ *
+ * Not `suspendWriteRecorders(() => Effect.runPromise(effect))`: that runs the
+ * effect in a SECOND runtime, and the importer's table phase came back with no
+ * progress at all when it was written that way. Entering and leaving the scope
+ * around the effect keeps ONE runtime — the same shape `restrictingReadsEffect`
+ * uses in `@voltro/runtime`, where the async-local's survival across Effect's
+ * scheduling was measured.
+ *
+ * Nests, so a caller that is already suspended stays suspended on the way out.
+ */
+export declare const suspendWriteRecordersEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+
 /**
  * Drain one table's over-TTL backlog. The DELETE itself is injected
  * (`deleteOlderThan` returns the number of rows it removed in one batch); the
@@ -7772,6 +7804,16 @@ export declare const _voltroCdcOffsetsTable: TableLike;
  */
 export declare const _voltroIdempotencyTable: TableLike;
 
+/**
+ * One import, as an operator asks about it.
+ *
+ * Deliberately small. Everything here answers a question somebody has actually
+ * asked while looking at unexpected data — "where did this come from", "when",
+ * "did it finish" — and nothing here is a per-row fact, because that is the
+ * thing this replaces.
+ */
+export declare const _voltroImportRunsTable: TableLike;
+
 /**
  * `_voltro_kv` — the durable key-value store behind `ctx.kv` / the `Kv`
  * service when `KV_BACKEND=database` (the default for sql apps). One row per
@@ -7949,4 +7991,7 @@ export declare interface WriteAttribution {
 
 export declare type WriteRecorder = (port: TxnRecorderPort, write: RecordedWrite) => Promise<void>;
 
+/** Are recorders suspended right here? Exported so a caller can SAY so. */
+export declare const writeRecordersSuspended: () => boolean;
+
 export { }