@voltro/database 0.41.0 → 0.43.0

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
@@ -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. */
@@ -2803,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
@@ -2970,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 {
@@ -3499,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 }) => ({
@@ -3518,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;
@@ -3531,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
@@ -3546,6 +3624,15 @@ 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 deployment /
+ *  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
@@ -3838,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.
  *
@@ -5347,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:
@@ -5374,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
@@ -5665,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".
@@ -5859,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.
@@ -6006,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.
      */
@@ -6255,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
@@ -7537,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