@voltro/database 0.80.0 → 0.82.0

package/dist/index.d.ts

@@ -767,6 +767,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 +970,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 +995,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>;
@@ -2174,6 +2177,11 @@ 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 their 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 +2398,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,
@@ -3943,6 +3951,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;
 }
 
 /**
@@ -5189,7 +5204,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 +5442,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.
@@ -6120,7 +6141,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 +6173,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
@@ -6523,6 +6552,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 (...)`.
@@ -7129,6 +7168,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 +7281,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;
     /**
@@ -8022,12 +8070,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.
  *
@@ -9581,22 +9629,6 @@ export declare const _voltroIdempotencyTable: SchemaTable;
 
 export declare const _voltroKvTable: SchemaTable;
 
-/**
- * `_voltro_migration_plans` — one row per declarative-diff plan
- * application. Written by the planner-based applier (Workstream G).
- *
- * Different from `_voltro_migrations` above:
- *   - `_voltro_migrations` tracks individual FILE-based migration runs
- *     (one row per migration file in `migrations/*.ts`).
- *   - `_voltro_migration_plans` tracks DECLARATIVE plan applications
- *     (one row per `voltro db apply` invocation — each plan may contain
- *     many concrete ops in `operations`).
- *
- * Both coexist while the framework supports both styles. The planner-based
- * system is the canonical "Workstream G Herzstück" path; file-based is
- * the escape-hatch for split/merge/data-move migrations the diff can't
- * infer.
- */
 export declare const _voltroMigrationPlansTable: SchemaTable;
 
 /**
@@ -9609,6 +9641,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.
  *
@@ -9658,6 +9702,19 @@ export declare const _voltroReplaceInProgressTable: TableLike;
  */
 export declare const _voltroReplicaObservationsTable: SchemaTable;
 
+/**
+ * `_voltro_schema_owner` — which APP this database's schema belongs to. One row.
+ *
+ * Two apps pointed at one database each diff the schema against their OWN
+ * declarations, so each sees the other's tables as undeclared and plans to drop
+ * them. The row makes the second app refuse to boot before it plans anything —
+ * see `migrations/schemaOwner.ts`.
+ *
+ * Bootstrapped by the migration boot (like the migration ledgers) and NOT part
+ * of the declared set, so adding it moves no app's schema fingerprint.
+ */
+export declare const _voltroSchemaOwnerTable: SchemaTable;
+
 /**
  * `_voltro_seeds` — one row per registered seed. Written to by the
  * seed runner as each seed's lifecycle changes. Unlike migrations,