@voltro/database 0.84.0 → 0.86.0

package/dist/sql.d.ts

@@ -1,13 +1,13 @@
-import { ConfigError } from 'effect';
-import { Connection } from '@effect/sql/SqlConnection';
+import { Config } from 'effect';
+import { Connection } from 'effect/sql/SqlConnection';
 import { Effect } from 'effect';
-import { Fragment } from '@effect/sql/Statement';
+import { Fragment } from 'effect/sql/Statement';
 import { Layer } from 'effect';
 import { Schema } from 'effect';
-import { SqlClient } from '@effect/sql';
-import { SqlError } from '@effect/sql/SqlError';
-import { SqlError as SqlError_2 } from '@effect/sql';
-import { Statement } from '@effect/sql';
+import { SqlClient } from 'effect/sql';
+import { SqlError } from 'effect/sql/SqlError';
+import { SqlError as SqlError_2 } from 'effect/sql';
+import { Statement } from 'effect/sql';
 
 /** Every hash this source may have been recorded under: its own, and the body
  *  before each framework edit in {@link FRAMEWORK_MIGRATION_EDITS}. */
@@ -359,7 +359,12 @@ export declare interface ApplyPlanCtx {
      * migration was a framework bug. `voltro db apply` did exactly that for two
      * releases while `voltro dev`'s boot diff, which uses this parameter, did not.
      */
-    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError, SqlClient.SqlClient>;
+    /** The applier supplies `execution` for every pre-execution replan (including
+     * interrupted-run reconciliation), and `convergence` only after planned work.
+     * Review-bound callers must validate full content in the execution phase before
+     * projecting their transactional/online subsets. Ordinary auto-diff callers
+     * can ignore the phase and adapt to the current schema as before. */
+    readonly replan: (sql: SqlClient.SqlClient, phase?: 'execution' | 'convergence') => Effect.Effect<MigrationPlan, SqlError, SqlClient.SqlClient>;
     /**
      * The declared store charset — the one `replan` plans with. Here only for
      * the resume ledger this creates before the first statement: nothing declares
@@ -810,7 +815,8 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
      */
     readonly fkAutoIndex?: boolean;
     /**
-     * This id-shaped scalar names something outside the local relational graph.
+     * This id-shaped scalar deliberately has no single foreign key target,
+     * including external-system ids and local polymorphic targets.
      * Set by `.externalId()` so schema audits do not guess a local FK from the
      * column name. Metadata only; it emits no constraint or DDL.
      */
@@ -1241,7 +1247,8 @@ declare interface ColumnDefinition_2<TsType, Type extends ColumnType_2 = ColumnT
      */
     readonly fkAutoIndex?: boolean;
     /**
-     * This id-shaped scalar names something outside the local relational graph.
+     * This id-shaped scalar deliberately has no single foreign key target,
+     * including external-system ids and local polymorphic targets.
      * Set by `.externalId()` so schema audits do not guess a local FK from the
      * column name. Metadata only; it emits no constraint or DDL.
      */
@@ -2576,7 +2583,7 @@ declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' |
  * Resolve the live dialect from the `SqlClient`.
  *
  * `sql.onDialectOrElse` collapses the six voltro dialects onto four driver
- * tokens: mysql+mariadb share `mysql` (one `@effect/sql-mysql2` client) and
+ * tokens: mysql+mariadb share `mysql` (one `effect/sql-mysql2` client) and
  * sqlite+turso share `sqlite`. That collapse is fine for every consumer here —
  * the paired dialects behave identically for everything this module decides.
  *
@@ -3143,7 +3150,7 @@ export declare interface FileMigration {
 export declare interface FileMigrationContext {
     /**
      * The escape hatch, and it asks for a reason. `raw('why')` returns the
-     * `@effect/sql` client — `sql.unsafe(...)`, `sql\`...\``,
+     * `effect/sql` client — `sql.unsafe(...)`, `sql\`...\``,
      * `sql.onDialectOrElse({...})` — for the one thing neither `store` nor
      * `schema` expresses. The reason is required (an empty one throws), it is
      * what `voltro doctor` lists beside every migration that reaches for raw
@@ -3415,6 +3422,11 @@ export declare interface HeldMigrationLock {
     /** Release the lock and return its connection to the pool. Idempotent only
      *  in the sense that the dialect statements are; call it once. */
     readonly release: Effect.Effect<void, SqlError>;
+    /** The reserved connection holding the lock (none on sqlite). Idle between
+     *  its keep-alive touches, so work that needs a connection OTHER than its
+     *  transaction's — a visibility probe — reads through this one instead of
+     *  reserving a third: the migration's contract is two connections. */
+    readonly connection: Connection | undefined;
 }
 
 /**
@@ -3574,11 +3586,17 @@ declare type IndexField = string | {
 declare type IndexKind = 'btree' | 'gist' | 'gin' | 'brin' | 'hnsw';
 
 /**
- * Per-kind tuning options. Today only `hnsw` carries knobs (the pgvector
- * build-time params). `m` controls graph connectivity (default 16),
+ * Per-kind tuning options. GIN supports a single-column operator class;
+ * HNSW supports pgvector build-time parameters. `m` controls graph connectivity (default 16),
  * `efConstruction` the build-time candidate-list size (default 64).
  */
 declare interface IndexKindOptions {
+    /** PostgreSQL GIN operator class for a single plain column.
+     * `gin_trgm_ops` installs pg_trgm and accelerates contains/ILIKE searches.
+     */
+    readonly gin?: {
+        readonly opclass: string;
+    };
     readonly hnsw?: {
         readonly m?: number;
         readonly efConstruction?: number;
@@ -3889,7 +3907,7 @@ export declare type MigrationModuleImporter = (file: string) => Promise<Record<s
  * `log` and the two probes the store can answer about its own shape
  * (`tableExists`, `columnExists`) work without one; each refusal names what to
  * do instead. Also raised at construction when what was handed in as `sql` is not
- * an `@effect/sql` client, or when a SQL-backed store arrives without the
+ * an `effect/sql` client, or when a SQL-backed store arrives without the
  * client it executes on — both are refused before a body can run rather
  * than surfacing as a TypeError from inside the first helper that touches
  * the client.
@@ -4741,7 +4759,7 @@ export declare const previewMigrationSquash: (options: Pick<SquashOptions, "befo
  * Eager provisioning is the APP's move (call this from a seed/startup over its
  * own tenant table); the framework has no tenant registry to enumerate.
  */
-export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
+export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, Config.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /** Internal offline publication. Receipt and published image share the same
  * commit as table replacement. Retry verifies receipt/schema/retained artifacts
@@ -4773,6 +4791,11 @@ export declare const publishSqliteDecimalStage: (sql: SqlClient.SqlClient, reque
 declare interface QueryDescriptor<R = Row> {
     readonly table: string;
     readonly predicate: Predicate | undefined;
+    /** Additional reactive invalidation sources, independent of SQL row selection.
+     * The runtime merges a query handler's declared `source` tables here. Changes
+     * to these tables recheck subscription authority even when SQL rows do not
+     * change. They add no joins, predicates or cross-tenant access. */
+    readonly dependentTables?: ReadonlyArray<string>;
     /** Phantom — carries the row type through to `store.query()`. Never set at
      *  runtime; erased entirely by the compiler. */
     readonly __row?: R;
@@ -5063,6 +5086,11 @@ declare interface QueryDescriptor<R = Row> {
 declare interface QueryDescriptor_2<R = Row_2> {
     readonly table: string;
     readonly predicate: Predicate_2 | undefined;
+    /** Additional reactive invalidation sources, independent of SQL row selection.
+     * The runtime merges a query handler's declared `source` tables here. Changes
+     * to these tables recheck subscription authority even when SQL rows do not
+     * change. They add no joins, predicates or cross-tenant access. */
+    readonly dependentTables?: ReadonlyArray<string>;
     /** Phantom — carries the row type through to `store.query()`. Never set at
      *  runtime; erased entirely by the compiler. */
     readonly __row?: R;
@@ -5681,7 +5709,7 @@ declare type Row = Readonly<Record<string, unknown>>;
 declare type Row_2 = Readonly<Record<string, unknown>>;
 
 /** Addresses one row: its `id`, or the columns of an explicit primary key. */
-declare type RowKey = string | Readonly<Record<string, unknown>>;
+declare type RowKey = string | number | Readonly<Record<string, unknown>>;
 
 /** The context a rule predicate is evaluated with. */
 declare interface RuleContext {
@@ -5776,7 +5804,7 @@ export declare interface RunFileBasedMigrationsCtx {
  * `voltro_isr_cache` so framework releases that grow new columns
  * don't crash old DBs at boot.
  */
-export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
+export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, Config.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Run `applySchema` against a fresh SqlClient from the provided sqlLayer.
@@ -5786,7 +5814,7 @@ export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sq
  * `dialect` is passed through to the DDL emitter so SQL types + reactive
  * trigger emission match the underlying engine.
  */
-export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
+export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, Config.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Execute ONE planned operation with the applier's own per-dialect
@@ -6053,6 +6081,8 @@ declare interface SpatialClause_2 {
     readonly order?: 'asc' | 'desc';
 }
 
+export declare const splitStatements: (sql: string) => ReadonlyArray<string>;
+
 /**
  * The `sql` template tag — captures a tagged-template literal into a
  * {@link RawSqlFragment} descriptor without binding it to any client.
@@ -6360,10 +6390,9 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
     /**
      * The plugin references DECLARED on this table, surviving `table()`.
      *
-     * `pluginRefSpecOf` reads a column BUILDER, and materialisation replaces it
-     * with a plain field descriptor — so without this the declaration is
-     * unreadable the moment the table exists, and any tool deriving structure
-     * from the schema sees an ordinary `text()` column.
+     * Derived from column metadata on every table rebuild, including columns
+     * contributed by mixins. Consumers can inspect these rules without knowing
+     * the private metadata on each materialized scalar definition.
      */
     readonly appliedPluginRefs?: ReadonlyArray<{
         readonly column: string;
@@ -6410,7 +6439,7 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * BEFORE every INSERT. Populated by `.validate(schema)`. Set
      * per-table at table-construction time; immutable thereafter.
      */
-    readonly insertSchema?: Schema.Schema.Any;
+    readonly insertSchema?: Schema.Top;
     /**
      * Optional `effect/Schema` the framework decodes a patch against
      * BEFORE every UPDATE. Populated by `.validatePatch(schema)`. The
@@ -6419,7 +6448,7 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * are checked. Set per-table at table-construction time; immutable
      * thereafter.
      */
-    readonly validatePatchSchema?: Schema.Schema.Any;
+    readonly validatePatchSchema?: Schema.Top;
     with: <const Mixins extends ReadonlyArray<AnyMixin>>(...mixins: Mixins) => Table<Name, Fields & MergeMixinFields<Mixins>, Reactive, IxNames>;
     /**
      * Attach an effect/Schema that validates EVERY insert against the
@@ -6447,7 +6476,7 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * `id` and `createdAt` are already filled in by the time the
      * decoder sees the row.
      */
-    validate: <S extends Schema.Schema.Any>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
+    validate: <S extends Schema.Top>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
     /**
      * Attach an effect/Schema that validates UPDATE patches against the
      * table. The framework wraps the schema in `Schema.partial`, so a
@@ -6478,7 +6507,7 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * wrapping is applied for you, so don't pre-wrap fields in
      * `Schema.optional`.
      */
-    validatePatch: <S extends Schema.Schema.Any>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
+    validatePatch: <S extends Schema.Struct<Schema.Struct.Fields>>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
     /**
      * Declare a (possibly composite) secondary index on the table.
      *
@@ -6860,8 +6889,8 @@ declare interface TableIndex {
      */
     readonly kind?: IndexKind;
     /**
-     * Per-kind tuning knobs. Today only `hnsw` (`kindOptions.hnsw.{m,
-     * efConstruction, opclass}`). Ignored for kinds that don't read it.
+     * Per-kind tuning: `gin.opclass` or `hnsw.{m, efConstruction, opclass}`.
+     * Ignored for kinds that do not read the corresponding options.
      */
     readonly kindOptions?: IndexKindOptions;
     /**