@voltro/database 0.81.0 → 0.83.0

package/dist/index.d.ts

@@ -668,6 +668,10 @@ export declare interface CdcConfig {
         readonly username: string;
         readonly password: string;
         readonly database: string;
+        /** TLS for the reader's own connection — the same `ConnectionConfig.ssl`
+         *  the app's pool resolved. A reader that dropped it connected in
+         *  plaintext, and a server that requires TLS refused change capture. */
+        readonly ssl?: boolean;
     };
     /** Watchdog cadence + stall threshold (ms) for the binlog reader's
      *  liveness safety net. Defaults (probe 15s / stall 25s) suit production;
@@ -767,6 +771,9 @@ export declare type ChangeEvent = {
      *     re-read failed, or the row was already gone). Re-read or resync.
      */
     readonly oversized?: 'rehydrated' | 'tombstone' | 'unrecovered';
+    /** A net-change feed may coalesce intermediate writes and supply current
+     * images or delete keys only. It cannot support exact historical replay. */
+    readonly netChange?: true;
     /**
      * How the event reached this process. Absent/'inline' = emitted by this
      * process's own write path; 'injected' = delivered over a cross-instance
@@ -967,7 +974,7 @@ export declare const coercePredicateValue: (columnType: ColumnType | undefined,
 /** Same, for the array-valued operators (`inSet` / `notInSet`). */
 export declare const coercePredicateValues: (columnType: ColumnType | undefined, values: ReadonlyArray<unknown>) => ReadonlyArray<unknown>;
 
-/** The value half of {@link coercePredicateForSqlite}. */
+/** Convert scalar/list predicate values to SQLite driver bindings. */
 export declare const coerceValueForSqlite: (value: unknown) => unknown;
 
 /**
@@ -992,7 +999,7 @@ export declare const collectSubqueries: (predicate: Predicate) => Generator<{
  * database.orders.where(eq('orgId', oid))
  *   .groupBy(['status'])
  *   .aggregate({ status: column<string>('status'), count: count() })
- * // rows: { status: string; count: number | Date | null }[]
+ * // rows: { status: string; count: number }[]
  * ```
  */
 export declare const column: <T = string | number | boolean | Date | null>(columnName: string, alias?: string) => AggregateColumn<T>;
@@ -1832,6 +1839,14 @@ export declare type ColumnInput = {
  *  or is nullable. */
 declare type ColumnOptionalForInsert<K extends PropertyKey, D> = K extends AutoFilledColumn ? true : ColumnHasDefault<D> extends true ? true : null extends InferColumn<D> ? true : false;
 
+export declare const columnRef: (column: string) => ColumnReference;
+
+/** An explicit, serializable reference to another column in the current row. */
+export declare interface ColumnReference {
+    readonly _tag: 'ColumnReference';
+    readonly column: string;
+}
+
 /**
  * The per-column mapping, over a column DEFINITION — what `table.fields` holds.
  *
@@ -2174,6 +2189,10 @@ table?: string) => Statement.Fragment;
  */
 export declare const compileRawFragment: <Row extends object = Record<string, unknown>>(fragment: RawSqlFragment, sql: SqlConstructor) => Statement.Statement<Row>;
 
+/** Preserve declared bigint columns before SQLite drivers convert them to JS numbers.
+ * Shared by SELECT and DML RETURNING; other dialects retain native projection. */
+export declare const compileRowProjection: (table: string, sql: SqlConstructor, projection?: ReadonlyArray<string>) => Statement.Fragment;
+
 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`. */
@@ -2390,9 +2409,9 @@ export declare interface CoreTableRegistration {
     readonly tenants?: () => TableLike;
 }
 
-export declare const count: (alias?: string) => AggregateColumn;
+export declare const count: (alias?: string) => AggregateColumn<number>;
 
-export declare const countDistinct: (column: string, alias?: string) => AggregateColumn;
+export declare const countDistinct: (column: string, alias?: string) => AggregateColumn<number>;
 
 /**
  * A whole collaborative DOCUMENT as a column — rich text, nested maps/arrays,
@@ -3795,7 +3814,7 @@ export declare interface EnumValueRename {
     readonly to: string;
 }
 
-export declare const eq: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const eq: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
 /** Escape LIKE/ILIKE wildcard metacharacters (`\` `%` `_`) so a
  *  user-supplied substring is matched literally. Paired with an
@@ -3943,6 +3962,13 @@ export declare interface FieldCipher {
      * feature, and the reader must not fall back to an unbound read.
      */
     readonly decrypt: (ciphertext: string, binding?: FieldBinding) => string;
+    /**
+     * `true` when only a PREVIOUS key opens this value — a cipher built with the
+     * keys a rotation retires (`makeFieldCipher(current, previous)`). What
+     * `voltro db encrypt-column` rewrites, so the previous key can go. Absent on
+     * a cipher with one key.
+     */
+    readonly sealedWithPreviousKey?: (ciphertext: string, binding?: FieldBinding) => boolean;
 }
 
 /**
@@ -4284,9 +4310,9 @@ export declare const getResidencyConfig: () => ResidencyConfig | undefined;
 
 export declare const getTable: (tableName: string) => TableLike | undefined;
 
-export declare const gt: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const gt: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
-export declare const gte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const gte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
 /**
  * Convenience: detect whether a descriptor declares any eager loads.
@@ -4731,6 +4757,8 @@ export declare const isBoundCiphertext: (value: unknown) => value is string;
  *  tenant namespace). */
 export declare const isBranchNamespace: (namespace: string) => boolean;
 
+export declare const isColumnReference: (value: unknown) => value is ColumnReference;
+
 /** True when the key names columns rather than an id. */
 export declare const isCompositeRowKey: (key: RowKey) => key is Readonly<Record<string, unknown>>;
 
@@ -5062,9 +5090,9 @@ export declare const localFirstTables: (schema: Readonly<Record<string, LocalFir
     readonly tableName: string;
 }>>) => ReadonlyArray<string>;
 
-export declare const lt: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const lt: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
-export declare const lte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const lte: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
 /**
  * Build the store-scoped fallback reporter: counts EVERY occurrence, logs a
@@ -5189,7 +5217,10 @@ export declare type MaterializedMixinFields<Input extends FieldsInput> = Resolve
 
 export declare const materializeFields: <F extends FieldsInput>(fields: F) => FieldDefinitions<F>;
 
-export declare const max: (column: string, alias?: string) => AggregateColumn;
+export declare const max: <C extends string>(column: C, alias?: string) => AggregateColumn & {
+    readonly op: "max";
+    readonly column: C;
+};
 
 /** Strictest identifier length across supported dialects (Postgres). */
 export declare const MAX_IDENTIFIER_LENGTH = 63;
@@ -5424,7 +5455,10 @@ export declare interface MigrationStepContext {
     readonly progress: (done: number, total: number) => Effect.Effect<void, never, never>;
 }
 
-export declare const min: (column: string, alias?: string) => AggregateColumn;
+export declare const min: <C extends string>(column: C, alias?: string) => AggregateColumn & {
+    readonly op: "min";
+    readonly column: C;
+};
 
 /**
  * The `conflictColumns` an upsert names that cannot match its conflict target.
@@ -5558,7 +5592,7 @@ export declare interface NeonBranchOptions {
     readonly parentBranch?: string;
 }
 
-export declare const neq: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K]) => PredicateLeaf;
+export declare const neq: <RowOf = Record<string, unknown>, K extends keyof RowOf & string = keyof RowOf & string>(column: K, value: RowOf[K] | ColumnReference) => PredicateLeaf;
 
 /** Advance the branch lifecycle; throws on an illegal transition (so a
  *  double-destroy or a provision-after-destroyed can't corrupt state). */
@@ -6120,7 +6154,7 @@ Joins extends JoinsMap = {}> {
      *   - grouped (via Q2's `.groupBy()`): one row per group
      */
     aggregate: <Spec extends Record<string, AggregateColumn<unknown>>>(spec: Spec) => Query<{
-        [K in keyof Spec]: Spec[K] extends AggregateColumn<infer T> ? T : never;
+        [K in keyof Spec]: ResolveAggregateResult<Spec[K], RowOf, Joins>;
     }, IxNames, Joins>;
     /**
      * Add `GROUP BY` columns. Composes with `.aggregate({...})` to
@@ -6152,8 +6186,16 @@ Joins extends JoinsMap = {}> {
      *
      * Multiple `.matching()` calls override the predicate (FTS is a
      * single-string concept; no AND-merge).
+     *
+     * `{ prefix: true }` matches each query word as a word beginning and
+     * requires every word — `tomato` finds `tomatoes` — on postgres
+     * (`to_tsquery` with `:*`), mysql/mariadb (BOOLEAN MODE `+word*`) and
+     * sqlite (FTS5 `"word"*`); mssql's LIKE and the in-memory store already
+     * match that way.
      */
-    matching: (indexName: string, query: string) => Query<RowOf, IxNames, Joins>;
+    matching: (indexName: string, query: string, options?: {
+        readonly prefix?: boolean;
+    }) => Query<RowOf, IxNames, Joins>;
     /**
      * Request a relevance-ranking column for the active `.matching(...)`
      * search and (by default) order results best-match-first. Must be
@@ -6259,7 +6301,7 @@ Joins extends JoinsMap = {}> {
      * const rootId = '...'
      * const anchor    = queryFor(orgs).where(eq('id', rootId))
      * const recursion = queryFor(orgs).as('child')
-     *   .innerJoin('descendants', 'parent', eq('parent.id', 'child.parentId'))
+     *   .innerJoin('descendants', 'parent', eq('parent.id', columnRef('child.parentId')))
      * const tree = queryFor(orgs)
      *   .recursiveCte('descendants', union(anchor, recursion).descriptor)
      *   .where(eq('id', rootId))
@@ -6298,7 +6340,7 @@ Joins extends JoinsMap = {}> {
      *
      * ```ts
      * queryFor(posts).as('children')
-     *   .innerJoin('posts', 'parents', eq('parents.id', 'children.parentId'))
+     *   .innerJoin('posts', 'parents', eq('parents.id', columnRef('children.parentId')))
      * ```
      */
     innerJoin: {
@@ -6330,7 +6372,7 @@ Joins extends JoinsMap = {}> {
      * ```ts
      * const rows = await store.query(
      *   queryFor(posts).as('children')
-     *     .innerJoin('posts', 'parents', eq('parents.id', 'children.parentId'))
+     *     .innerJoin('posts', 'parents', eq('parents.id', columnRef('children.parentId')))
      *     .selectJoined({
      *       childId:     'children.id',
      *       childTitle:  'children.title',
@@ -6523,6 +6565,16 @@ export declare interface QueryDescriptor<R = Row> {
             readonly alias: string;
             readonly order: boolean;
         };
+        /** Each query word matches as a word BEGINNING (`tomato` finds
+         *  `tomatoes`), every word required — `.matching(…, { prefix: true })`. */
+        readonly prefix?: boolean;
+        /**
+         * Set by a store whose engine keeps no full-text index (Turso's MVCC mode
+         * has no FTS5): the match compiles to a case-insensitive LIKE over the
+         * covered columns, ranked by how many of them hit — the same fallback as
+         * mssql. Never set by the query builder.
+         */
+        readonly fallback?: 'like';
     };
     /**
      * Common-Table-Expression definitions (Q4) — `WITH <name> AS (...)`.
@@ -6581,6 +6633,8 @@ export declare interface QueryDescriptor<R = Row> {
     readonly joins?: ReadonlyArray<{
         readonly kind: 'inner' | 'left';
         readonly table: string;
+        /** Declared shape for typed joins; name-only joins use the table registry. */
+        readonly sourceTable?: TableLike;
         readonly alias: string;
         readonly on: Predicate;
     }>;
@@ -7129,6 +7183,12 @@ declare type Resolve<T> = {
  */
 export declare const resolveActorSnapshot: (store: ActorLookupStore, subjectId: string | null | undefined, subjectType: string) => Promise<AuditActor | undefined>;
 
+/** Resolve extrema from the source column while retaining explicit projection types. */
+export declare type ResolveAggregateResult<A, RowOf, Joins extends JoinsMap> = A extends {
+    readonly op: 'min' | 'max';
+    readonly column: infer C extends string;
+} ? ResolveJoinedSource<C, RowOf, Joins> | null : A extends AggregateColumn<infer T> ? T : never;
+
 /**
  * Pick the branch mechanism. Prioritises the Neon copy-on-write fast-path when
  * the owned DB is Neon AND the branch snapshots parent data (`seed: 'copy'`);
@@ -7236,6 +7296,9 @@ export declare interface RetentionSpec {
     readonly table: string;
     /** Timestamp column compared against the cutoff (rows strictly older are purged). */
     readonly timeColumn: string;
+    /** Additional timestamps that keep a row while any is within the TTL.
+     * Null timestamps do not protect a row. All columns use the same cutoff. */
+    readonly activityColumns?: ReadonlyArray<string>;
     /** Rows whose `timeColumn` is older than `now - ttlMs` are eligible for purge. */
     readonly ttlMs: number;
     /**
@@ -7912,6 +7975,11 @@ export declare type SqlConstructor = Statement.Constructor;
  * SQLite extended code).
  */
 export declare interface SqlDialect {
+    /** Runner storage supported by this resolved connection. Local/embedded
+     * stores must not advertise shared ownership of a remote workflow journal.
+     * Omission retains the dialect family's default.
+     */
+    readonly workflowRunnerStorage?: (connection: ConnectionConfig) => 'memory' | 'sql';
     readonly id: DialectId;
     readonly makeSqlLayer: (conn: ConnectionConfig) => Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>;
     readonly makeStore: (options: MakeStoreOptions) => Promise<DataStore>;
@@ -8022,12 +8090,12 @@ export declare const stampGeneratedId: <T extends Record<string, unknown>>(table
 export declare const stampGeneratedIds: <T extends Record<string, unknown>>(table: string, rows: ReadonlyArray<T>) => ReadonlyArray<T>;
 
 /**
- * Prefix match on a text column — `startsWith('key', 'awb_')`.
+ * Prefix match on a text column — `startsWith('key', 'acme_')`.
  *
  * **Case-SENSITIVE**, unlike {@link contains}, and the asymmetry is deliberate
  * rather than an oversight. `contains` is a search primitive (a human typing
  * into a box), so folding case is what they mean. A prefix is a NAMESPACE — a
- * key prefix, a path segment, a tenant-scoped id — where `awb_` and `AWB_` are
+ * key prefix, a path segment, a tenant-scoped id — where `acme_` and `ACME_` are
  * two different namespaces and quietly merging them is a bug. It also matches
  * the semantics of the JS method it is named after.
  *
@@ -9593,6 +9661,18 @@ export declare const _voltroMigrationsTable: SchemaTable;
 
 export declare const _voltroMssqlCdcOffsetsTable: TableLike;
 
+/**
+ * `_voltro_plugin_migrations` — which plugin `extendSchema.migrations` steps ran.
+ *
+ * It was created by a hand-written `id TEXT PRIMARY KEY`, which MariaDB and
+ * MySQL refuse (errno 1170), so a plugin that shipped a migration could not run
+ * it on the MySQL family at all. Declared here, it goes through the same
+ * per-dialect bootstrap as the migration ledgers — and the declared store
+ * charset with them. The snake_case column names are the ones existing ledgers
+ * already carry on postgres and sqlite.
+ */
+export declare const _voltroPluginMigrationsTable: SchemaTable;
+
 /**
  * The one row a destructive import leaves behind while it is destructive.
  *