@voltro/database 0.40.0 → 0.42.0

package/dist/index.d.ts

@@ -765,6 +765,19 @@ export declare const chunkRowsForInsert: <T extends Record<string, unknown>>(row
  */
 export declare const claimPendingAttribution: (key: string) => WriteAttribution | undefined;
 
+/**
+ * Classify a driver failure — already flattened by `extractDbCause` — into the
+ * safe facts above, or `undefined` when it is not a constraint violation at all
+ * (a deadlock, a dead connection, a timeout, a syntax error).
+ *
+ * `operation` is the write the framework was performing. It is consulted for
+ * ONE thing: sqlite reports both FK directions as the same bare
+ * `FOREIGN KEY constraint failed` with no name and no column, so a delete that
+ * trips it is `foreignKeyInUse` and an insert is `foreignKey`. Every other
+ * dialect states the direction itself and the operation is not consulted.
+ */
+export declare const classifyConstraintViolation: (dbCause: Record<string, unknown>, operation?: string) => ConstraintFacts | undefined;
+
 /** Wipe — used by tests + the dev-loop hot-reload. */
 export declare const clearEnumRenames: () => void;
 
@@ -1865,6 +1878,48 @@ export declare interface ConnectionIdentityInput {
     readonly database?: string | undefined;
 }
 
+/**
+ * The SAFE facts about a constraint violation: which rule, and the NAME of the
+ * constraint / column it fired on. Never a value, and never the driver's
+ * sentence.
+ *
+ * That exclusion is the whole design, and it is measured, not cautious:
+ *
+ *   - postgres attaches `detail: "Failing row contains (t4, l1, null, null,
+ *     null)."` to a not-null and a check violation — **the entire row**, every
+ *     column, including anything a table marked `.sensitive()`.
+ *   - mysql/mariadb: `Duplicate entry 's1' for key 'tasks.slug'`.
+ *   - mssql: `The duplicate key value is (s1).` and, on truncation,
+ *     `Truncated value: '…'`.
+ *
+ * So "just pass the driver message through" is not a smaller version of this —
+ * it is a different feature, one that ships row contents to whoever provoked
+ * the error. A constraint NAME is schema, the same class of fact the framework
+ * already puts on the wire in `TableValidationFailed.table`; a row is data.
+ *
+ * Everything here is captured as an anchored identifier group out of the
+ * driver text — never a slice of it — so a regex that fails to match yields
+ * `undefined` rather than a sentence that happens to contain a value.
+ */
+export declare interface ConstraintFacts {
+    readonly kind: ConstraintKind;
+    /** The constraint / index name, when the dialect names one. */
+    readonly constraint?: string;
+    /** The column, when the dialect names one instead of (or beside) a constraint. */
+    readonly column?: string;
+}
+
+/**
+ * Which integrity rule the database refused on.
+ *
+ * `foreignKey` and `foreignKeyInUse` are the two DIRECTIONS of one constraint
+ * and mean opposite things to a caller — "the row you pointed at does not
+ * exist" vs "you may not remove this row, others still point at it". A UI
+ * branches differently on each, so they are separate members rather than one
+ * member plus a string a caller would have to grep.
+ */
+export declare type ConstraintKind = 'foreignKey' | 'foreignKeyInUse' | 'unique' | 'notNull' | 'check';
+
 /** Case-insensitive substring match on a text column. Non-indexable —
  *  always evaluated as an unindexed leaf (the matcher's pre-filter only
  *  recognizes eq/in/range). Lowers to `ILIKE '%…%'` on Postgres. */
@@ -2343,6 +2398,46 @@ export declare const decimal: (precision: number, scale?: number) => ColumnBuild
  */
 export declare const declareEnumRename: (enumName: string, rename: EnumValueRename) => void;
 
+/**
+ * Read an encrypted field, in EITHER encoding.
+ *
+ * ── Why this reads two forms when there is only one writer ─────────────────
+ *
+ * Because the old form is already on somebody's production disk, and a fix that
+ * requires rewriting it before the app works is not a fix — it is an outage with
+ * a migration attached. "No back-compat" is about not keeping old CODE paths; a
+ * row written last month is data, and data is read where it is.
+ *
+ * ── Why this is deterministic and not a heuristic ──────────────────────────
+ *
+ * The two forms are `encrypt(JSON.stringify(v))` and `encrypt(v)`. After
+ * decrypting, they are told apart by what the plaintext PARSES to, against the
+ * column's declared type:
+ *
+ *   - parse THROWS               → raw form. A JSON encoding always parses.
+ *   - parse yields a STRING      → JSON form. `JSON.stringify` of any string
+ *                                  yields a quoted string, and a raw secret is
+ *                                  not quoted (see the one exception below).
+ *   - parse yields a NON-string  → depends on the column:
+ *       · a TEXT-like column can only hold a string, so a number/object here is
+ *         the raw form being parsed by accident (`"12345"` → `12345`) → raw.
+ *       · a number / boolean / json column stores exactly that, so the parsed
+ *         value IS the value → JSON form.
+ *
+ * No branch guesses. `expected` is the column's declared type; omit it (the
+ * `string → string` escape hatch) and the text-like rule applies, which is
+ * correct for a caller that can only have written a string.
+ *
+ * ── The one case nothing can separate, stated rather than hidden ───────────
+ *
+ * A raw secret whose literal text is `"abc"` — quotes included as characters —
+ * is byte-identical to the JSON encoding of `abc`. No algorithm can tell them
+ * apart, because they are the same bytes. A token or key never looks like that;
+ * it is written here so the next reader does not go looking for the branch that
+ * handles it.
+ */
+export declare const decodeFieldValue: (cipher: FieldCipher, ciphertext: string, expected?: string) => unknown;
+
 export declare type DecoderDialectId = 'postgres' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql' | 'turso';
 
 /**
@@ -2753,6 +2848,35 @@ export declare interface EagerRootPlan {
 
 declare type EmptyMerge = unknown;
 
+/**
+ * THE encoding for an encrypted field. One definition, called by every writer
+ * and every reader — the store middleware, the raw-SQL escape hatch
+ * (`encryptField` / `decryptField` in `@voltro/runtime`), and the
+ * `voltro db encrypt-column` backfill.
+ *
+ * ── Why this is one function and not three copies ──────────────────────────
+ *
+ * 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
+ * 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
+ * rotation the whole time.
+ *
+ * The JSON form wins because it is the only one that can carry a non-string: an
+ * `.encrypted()` column may be a number or a json column, and `encrypt(v)` for
+ * those was already lossy. The escape hatch's `string → string` signature is
+ * unchanged by it — a stringified string parses back to the same string.
+ *
+ * ── The distinction the error has to make ──────────────────────────────────
+ *
+ * A GCM failure and a JSON failure are different diagnoses with different
+ * remedies, and collapsing them is what cost the consumer a day. `decodeFieldValue`
+ * therefore decrypts and decodes as two separate steps and says which one failed.
+ */
+export declare const encodeFieldValue: (cipher: FieldCipher, value: unknown) => string;
+
 /**
  * Serialize a row's json()/array() cells to JSON strings so they can be
  * bound as scalar SQL parameters. Symmetric to `decodeRowsFromSchema`.
@@ -2901,6 +3025,8 @@ export declare const expires: () => MixinDefinition<{
  */
 export declare const externalChangeEvent: (event: ChangeEvent, attribution?: Partial<ChangeEventMeta>) => ChangeEvent;
 
+export declare const extractDbCause: (err: unknown) => Record<string, unknown>;
+
 /** The subset of `@voltro/logger`'s logger this module needs. Structural so
  *  this package keeps its browser-safe import surface. */
 export declare interface FallbackLogger {
@@ -3449,6 +3575,15 @@ export declare const isFieldDecryptionError: (e: unknown) => e is FieldDecryptio
 /** Type-guard for the discovery walker. */
 export declare const isFileMigration: (value: unknown) => value is FileMigration;
 
+/**
+ * Foreign-key violation, either direction, across every dialect. Derived from
+ * `classifyConstraintViolation` rather than re-listing the codes: this
+ * predicate and the classifier disagreeing is invisible until a tenant-FK
+ * failure quietly stops being typed, and mssql already spent a release in
+ * exactly that state (547 was read off `.code`, where it never appears).
+ */
+export declare const isForeignKeyViolation: (dbCause: Record<string, unknown>) => boolean;
+
 /** True when `name` is a live table the framework / its runtime engines create
  *  but no user schema declares — never plan a drop for it. */
 export declare const isFrameworkOwnedLiveTable: (name: string) => boolean;
@@ -3462,6 +3597,18 @@ export declare const isLocalFirst: (table: LocalFirstMarked) => boolean;
 
 export declare const isMigrationDefinition: (value: unknown) => value is MigrationDefinition;
 
+/**
+ * MySQL and MariaDB. They share a driver, a quoting style and most of a
+ * grammar — and they are NOT interchangeable in DDL.
+ *
+ * The one that has already cost us: **MySQL/InnoDB silently discards a
+ * column-inline `REFERENCES` clause** (parsed, thrown away, no warning, CREATE
+ * succeeds), while MariaDB honours it and creates the constraint. Measured on
+ * mysql 8.4 and mariadb 11. Anything referential that this family emits has to
+ * be table-level to work on both.
+ */
+export declare const isMysqlFamily: (dialect: DialectId) => boolean;
+
 /**
  * True when the connection string points at a Neon serverless-postgres host
  * (`*.neon.tech` / `*.neon.build`, including the `-pooler` endpoints). Neon's
@@ -3477,6 +3624,21 @@ export declare const isNull: <RowOf = Record<string, unknown>, K extends keyof R
 
 export declare const isPrimaryKeyConflictError: (err: unknown) => err is PrimaryKeyConflictError;
 
+/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
+ *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
+ *  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 /
+ *  observability layer name the failure instead of reading an opaque SqlError. */
+export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+
+/** Is this ciphertext in the OLD raw encoding? Used by `voltro db encrypt-column`
+ *  to normalise a column without touching rows that are already current. Answers
+ *  `undefined` when the two forms coincide (a numeric column, or a value that
+ *  parses to itself) — nothing to do either way. */
+export declare const isRawEncoding: (cipher: FieldCipher, ciphertext: string, expected?: string) => boolean | undefined;
+
 /** Can THIS deployment serve the region? */
 export declare const isRegionServable: (region: string, config: ResidencyConfig) => boolean;