@voltro/database 0.83.1 → 0.84.0

package/dist/index.d.ts

@@ -1637,6 +1637,14 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * column is just `bytes` with server-merge semantics.
      */
     readonly crdtManaged?: boolean;
+    /**
+     * End-to-end-sealed CRDT marker, set by `crdtSealed()`. The column holds an
+     * append-only LOG of encrypted CRDT updates the server cannot read: the
+     * write path appends an incoming frame (or applies a client's snapshot
+     * frame) and never decodes or merges — clients holding the key do. Same
+     * `bytes` storage and zero DDL churn as `crdtManaged`.
+     */
+    readonly crdtSealed?: boolean;
     /**
      * Optimistic-concurrency marker, set by `.version()`.
      *
@@ -1694,6 +1702,7 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * MUST be `<= precision`. See {@link ColumnDefinition.precision}.
      */
     readonly scale?: number;
+    /* Excluded from this release type: sqliteDecimalEncoding */
     /**
      * Vector dimensionality. Populated only when `type === 'vector'`.
      * The migration emitter uses it to size the column DDL —
@@ -1965,6 +1974,10 @@ declare interface ColumnSnapshot {
      */
     readonly precision?: number;
     readonly scale?: number;
+    /** Physical SQLite-family exact-decimal representation. Absent on ordinary
+     * NUMERIC columns. The marker is observable schema state, not a DSL hint:
+     * changing it requires data conversion, never a plain SQL type cast. */
+    readonly sqliteDecimalEncoding?: 'sortable-v1';
     /**
      * Id-generation scheme for `type: 'id'` columns. Mirrors
      * `ColumnDefinition.idScheme.kind` so the applier can tell a numeric
@@ -2157,24 +2170,8 @@ export declare const compileEagerJson: (descriptor: QueryDescriptor, sql: SqlCon
  */
 export declare const compileJsonPatch: (sql: SqlConstructor, dialect: DialectId, path: string, value: unknown, source?: Statement.Fragment) => Statement.Fragment;
 
-/**
- * Lower a `Predicate` AST to a SQL `Fragment` suitable for use inside a
- * WHERE clause. Identifiers are quoted via `sql(col)`; values flow through
- * `sql\`${v}\`` as parameters — no string concatenation, no injection.
- */
-export declare const compilePredicate: (predicate: Predicate, sql: SqlConstructor, namespace?: QueryNamespace, 
-/**
- * The table this predicate filters, when the caller knows it. Supplied so a
- * leaf's VALUE can be coerced to the column's shape — `eq('capturedAt',
- * epochMs)` against a `timestamp()` column otherwise compiles to
- * `WHERE capturedAt = 1767916800000` and matches nothing, silently. The write
- * path has always encoded; this closes the asymmetry.
- *
- * Optional because `compilePredicate` is also called for JOIN conditions and
- * by callers that hold only the AST. Absent → no coercion, i.e. exactly the
- * previous behaviour.
- */
-table?: string) => Statement.Fragment;
+/** Compile a standalone predicate; SELECT supplies its own lexical CTE scope. */
+export declare const compilePredicate: (predicate: Predicate, sql: SqlConstructor, namespace?: QueryNamespace, table?: string) => Statement.Fragment;
 
 /**
  * Rebind a captured {@link RawSqlFragment} onto a live `sql`
@@ -2193,6 +2190,7 @@ export declare const compileRawFragment: <Row extends object = Record<string, un
  * Shared by SELECT and DML RETURNING; other dialects retain native projection. */
 export declare const compileRowProjection: (table: string, sql: SqlConstructor, projection?: ReadonlyArray<string>) => Statement.Fragment;
 
+/** Compile a public query descriptor; recursive CTE terms use their SQL scope. */
 export declare const compileSelect: <Row extends object>(descriptor: QueryDescriptor, sql: SqlConstructor, namespace?: QueryNamespace) => Statement.Statement<Row>;
 
 /** Compose the durable identity written to `_voltro_cdcout_claims.changeKey`. */
@@ -2413,6 +2411,22 @@ export declare const count: (alias?: string) => AggregateColumn<number>;
 
 export declare const countDistinct: (column: string, alias?: string) => AggregateColumn<number>;
 
+/**
+ * A CONVERGING COUNTER column — likes, stock reservations, votes, a running
+ * total — that any number of clients increment and decrement concurrently,
+ * offline too, without losing a single step. A plain `integer()` column read,
+ * incremented and written back by two clients at once keeps one of the two
+ * increments; this keeps both.
+ *
+ * Each writer (one client session) accumulates its own increments and
+ * decrements under its own key, and the value is the sum over all writers, so
+ * concurrent steps commute. Storage, nullability and the authoritative server
+ * merge are those of `crdtText()` — the column stores the encoded CRDT state
+ * as `bytes`. Read the number with `@voltro/local-first`'s
+ * `crdtCounterValue(state)`; bind it in React with `useCrdtCounter`.
+ */
+export declare const crdtCounter: () => ColumnBuilder<Uint8Array | null, "bytes">;
+
 /**
  * A whole collaborative DOCUMENT as a column — rich text, nested maps/arrays,
  * whatever the CRDT backend's document model holds. `crdtText()` is the
@@ -2450,6 +2464,22 @@ export declare const crdtManagedColumns: (table: TableLike) => ReadonlyArray<str
  *  folds and the capture paths (undo, row history) exclude. */
 export declare const crdtManagedColumnsOf: (table: TableLike) => ReadonlyArray<string>;
 
+/**
+ * An END-TO-END ENCRYPTED collaborative column: clients encrypt every CRDT
+ * update with a key the server never sees (AES-GCM, `@voltro/local-first`'s
+ * `seal` option on `useCrdtText` / `useCrdtDoc` / `useCrdtCounter`), and the
+ * server stores an append-only log of the sealed frames. It cannot read,
+ * validate or merge the content — clients decrypt and merge locally, which is
+ * why the convergence still holds — and a client's snapshot frame compacts the
+ * log without losing a frame appended concurrently.
+ *
+ * Trade-offs, by construction: `crdt.validate` and server-side restore cannot
+ * see the content, and the downstream lane ships the log, not an increment.
+ * The size limits still apply. Choose it for content the operator must not be
+ * able to read.
+ */
+export declare const crdtSealed: () => ColumnBuilder<Uint8Array | null, "bytes">;
+
 /**
  * CRDT-managed text column — a field whose value is a CONFLICT-FREE replicated
  * text document rather than a plain string. Two clients editing it at the same
@@ -3122,19 +3152,20 @@ export declare interface DbOpSample {
 }
 
 /**
- * Fixed-point exact-decimal column — money, tax rates, anything where
- * floating-point rounding is unacceptable. Emits `NUMERIC(precision, scale)`
- * on postgres and `DECIMAL(precision, scale)` on mysql / mariadb / mssql;
- * sqlite / turso have no fixed-point type, so it's `NUMERIC` affinity storing
- * the value as text.
+ * Fixed-point exact-decimal column for money, tax rates and other values
+ * that must not pass through floating-point arithmetic. Emits
+ * `NUMERIC(precision, scale)` on postgres and `DECIMAL(precision, scale)`
+ * on mysql / mariadb / mssql. SQLite, native Turso and libSQL use exact,
+ * order-preserving encoded TEXT storage, including declared defaults.
+ * Existing NUMERIC columns require a reviewed offline conversion.
  *
- * The row type is **`string`**, NOT `number`, on purpose: a JS `number` is an
- * IEEE-754 double and silently loses precision past ~15-17 significant digits
- * (`0.1 + 0.2 !== 0.3`), so a `DECIMAL(38,9)` value round-tripped through a JS
- * number would corrupt. The drivers already hand these back as strings
- * (node-postgres, mysql2), and the row decoder coerces the mssql numeric back
- * to a string, so the value is lossless end-to-end. Do arithmetic with a
- * decimal library (or in SQL), not JS `+`.
+ * The row type is **`string`**, NOT `number`: JavaScript numbers lose
+ * precision beyond roughly 15–17 significant digits. SQLite-family stores
+ * encode writes and decode reads at the declared scale. MSSQL's driver
+ * can already have rounded large values before string decoding; use a
+ * text projection for values beyond the driver's numeric precision.
+ * Use a decimal library or supported typed query-builder operations for
+ * arithmetic. Raw SQL must not treat encoded TEXT as a decimal number.
  *
  * ```ts
  * price:   decimal(12, 2),   // up to 9_999_999_999.99
@@ -3226,8 +3257,11 @@ export declare const decodeRowsForTable: <T extends Record<string, unknown>>(row
  * Unknown tables (not registered) pass through unchanged — this is
  * the case for the framework's internal cluster-runtime tables and
  * for ad-hoc raw-SQL paths that bypass the typed-table mechanism.
+ * Pass the SELECT descriptor when decoding a compileSelect result: explicitly
+ * encoded SQLite queries return logical projections, not physical table rows.
+ * Omit it for DML RETURNING, whose cells retain their storage representation.
  */
-export declare const decodeRowsFromSchema: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, tableName: string, dialect: DecoderDialectId) => ReadonlyArray<T>;
+export declare const decodeRowsFromSchema: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, tableName: string, dialect: DecoderDialectId, query?: QueryDescriptor) => ReadonlyArray<T>;
 
 /**
  * Decrypt every `.encrypted()` column's value on read. A value that
@@ -3752,8 +3786,8 @@ declare type EmptyMerge = unknown;
 export declare const encodeFieldValue: (cipher: FieldCipher, value: unknown, binding?: FieldBinding) => string;
 
 /**
- * Serialize selected json()/array()/vector() cells to JSON strings so they can be
- * bound as scalar SQL parameters. Symmetric to `decodeRowsFromSchema`.
+ * Serialize selected JSON-like cells and explicitly marked decimal storage
+ * values so they can be bound as scalar SQL parameters. Symmetric to `decodeRowsFromSchema`.
  * No-op for tables with no json/array columns (cost: one map build +
  * a per-cell type lookup). Unknown tables pass through unchanged.
  */