@voltro/database 0.44.1 → 0.46.0

package/dist/index.d.ts

@@ -819,7 +819,6 @@ export declare const clearResidencyConfig: () => void;
 /** Test seam — drop all registrations. */
 export declare const clearRetentions: () => void;
 
-/** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearTableRegistry: () => void;
 
 /** Test seam / dev-restart seam. */
@@ -2658,6 +2657,25 @@ export declare const defineSeed: (input: SeedDefinitionInput) => SeedDefinition;
 
 export declare const denseRank: (alias?: string) => WindowBuilder;
 
+/**
+ * A deterministic primary key over `parts`, of constant length.
+ *
+ * `derivedRowId('rowver', table, rowId, version)` → `rowver_<32 hex>` — 39
+ * characters for that prefix, no matter what the parts are.
+ *
+ * Use this wherever a framework table's `id` is COMPOSED from values it does not
+ * control. Where the id is generated (a typeid, a uuid) or built from something
+ * provably bounded (a timestamp, a counter), it is not needed.
+ */
+export declare const derivedRowId: (prefix: string, ...parts: ReadonlyArray<string | number>) => string;
+
+/**
+ * The longest id {@link derivedRowId} can return for a prefix — computed, not
+ * asserted after the fact, so a test can state the bound without constructing
+ * inputs and hoping it picked the worst one.
+ */
+export declare const derivedRowIdLength: (prefix: string) => number;
+
 /**
  * Walk the schema outward from `subjectTable` and return every route to a table
  * holding that subject's rows.
@@ -2732,6 +2750,30 @@ export declare const deriveTypeIdPrefix: (tableName: string) => string;
  */
 export declare const describeDriverError: (err: unknown) => string | undefined;
 
+/**
+ * The TYPE of every binding in a row, and never a value.
+ *
+ * `ER_WRONG_ARGUMENTS` / 1210 is reported as "incorrect arguments", which reads
+ * like a count problem and often is not: a statement with twelve columns and
+ * twelve placeholders is internally consistent, and the driver is refusing one
+ * VALUE it cannot bind. Measured against mariadb 11.8 / mysql2 3.22, and the
+ * result is why this exists at all:
+ *
+ *   value bound to a prepared statement   mariadb   mysql
+ *   plain object                          1210      accepted
+ *   array                                 1210      accepted
+ *   bigint / Invalid Date / NaN           accepted  (Invalid Date → 1292)
+ *
+ * So the same row is bindable on one engine of the family and not the other,
+ * which is exactly the shape of a suite where mariadb falls and mysql passes in
+ * one run. Knowing WHICH of twelve bindings is an object is the whole diagnosis,
+ * and it is not derivable from the error.
+ *
+ * Types only. A value here would be row data in a log line, which is the reason
+ * the statement itself is carried only in its placeholder form.
+ */
+export declare const describeRowBindings: (row: Readonly<Record<string, unknown>>) => string;
+
 /**
  * Parse JSON-stringified array values back to JS arrays on the read
  * side. Tolerates `null` (NULL column → null in JS), pre-deserialised
@@ -3476,6 +3518,14 @@ export declare interface HybridSearchOptions {
  */
 export declare const id: (options?: IdSchemeInput) => ColumnBuilder<string, "id", boolean>;
 
+/**
+ * The width an `id()` column is emitted at on the dialects that need one
+ * (`VARCHAR(64)` / `NVARCHAR(64)`). Exported so the rule has ONE spelling: a
+ * check that hard-codes 64 somewhere else is a second definition waiting to
+ * disagree with this one.
+ */
+export declare const ID_COLUMN_MAX_LENGTH = 64;
+
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
  * `table()` walks the fields. For `typeid`, the prefix is always
@@ -3685,6 +3735,27 @@ export declare const inSubquery: <RowOf = Record<string, unknown>, K extends key
 
 export declare const integer: () => ColumnBuilder<number, "integer", boolean>;
 
+/** One unfinished destructive run, as the boot sees it. */
+export declare interface InterruptedReplace {
+    readonly id: string;
+    readonly startedAt: Date;
+    readonly tables: number;
+    readonly capture: string | null;
+    readonly via: string;
+}
+
+/**
+ * What the boot says when it finds one.
+ *
+ * A REFUSAL, not a warning, and the asymmetry is deliberate: serving an
+ * application over a database that was emptied and not refilled is the outcome
+ * this exists to prevent, and it is indistinguishable from normal operation
+ * from the inside. The cost of being wrong in the other direction is a boot that
+ * stops until a person looks — which is what you want anyway if a destructive
+ * import did not finish.
+ */
+export declare const interruptedReplaceRefusal: (rows: ReadonlyArray<InterruptedReplace>) => string | undefined;
+
 /** `INTERSECT` — rows present in EVERY input. */
 export declare const intersect: (...queries: ReadonlyArray<QueryWithDescriptorAny>) => Query<Row, string>;
 
@@ -5704,6 +5775,8 @@ export declare interface RelationsSpec {
     readonly relations: RelationMap;
 }
 
+export declare const REPLACE_IN_PROGRESS_TABLE = "_voltro_replace_in_progress";
+
 export declare const requireActors: () => (() => TableLike);
 
 /** Required-by-name lookup — throws when missing so the call site
@@ -7383,6 +7456,25 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/**
+ * Remove ONE name this process added for a bounded operation.
+ *
+ * Deliberately narrow, and the narrowness is the point. `clearTableRegistry`
+ * wipes everything and exists for tests; an app's tables are registered once at
+ * boot and never leave. This is for the opposite shape: a name a single
+ * operation OWNS for its duration and must take with it — the staging tables a
+ * `--mode replace` registers so its typed writes can find the target's column
+ * metadata, then unregisters when the swap is done.
+ *
+ * Leaving one behind is not cosmetic. `allRegisteredTables()` feeds the declared
+ * set, the boot differ and `voltro doctor`, so a leftover staging clone would
+ * read as a table the app declares and nobody created.
+ *
+ * Returns whether anything was removed, so a `finally` that runs twice does not
+ * have to pretend it knows.
+ */
+export declare const unregisterTable: (tableName: string) => boolean;
+
 export declare const unregisterWriteRecorder: (id: string) => void;
 
 /**
@@ -7719,6 +7811,16 @@ export declare const _voltroMigrationsTable: TableLike;
 
 export declare const _voltroMssqlCdcOffsetsTable: TableLike;
 
+/**
+ * The one row a destructive import leaves behind while it is destructive.
+ *
+ * Never more than one in practice — a second concurrent `replace` against one
+ * database is already a mistake — but the table is not keyed on a constant, so
+ * two runs produce two rows and the boot names both rather than one overwriting
+ * the other's evidence.
+ */
+export declare const _voltroReplaceInProgressTable: TableLike;
+
 /**
  * `_voltro_seeds` — one row per registered seed. Written to by the
  * seed runner as each seed's lifecycle changes. Unlike migrations,