@dbsp/adapter-pgsql 1.11.2 → 3.0.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { ExpressionRef, IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ModelIR as ModelIR$1 } from '@dbsp/core';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1 } from '@dbsp/core';
 export { normalizeSQL } from '@dbsp/core';
 import * as _dbsp_types from '@dbsp/types';
-import { ColumnListInput, ParamIntent, JsonAggOrderByEntry, DialectCapabilities, ModelIR, DbCasing, ColumnIR, HierarchyIR, MutationReturningItem, WhereIntent, Adapter, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, QueryIntent } from '@dbsp/types';
+import { DialectCapabilities, ModelIR, ColumnListInput, ParamIntent, JsonAggOrderByEntry, IndexIR, HierarchyIR, Adapter, DbCasing, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, ColumnIR, MutationReturningItem, WhereIntent, QueryIntent } from '@dbsp/types';
 import * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
 import { Pool, PoolClient } from 'pg';
@@ -99,6 +99,253 @@ declare function getNamingPluginForDbCasing(casing: 'snake_case' | 'camelCase' |
 
 type BindingNameRegistry = ReadonlySet<string>;
 
+/**
+ * Immutable context passed to all handlers during compilation.
+ */
+interface CompilerContext {
+    /** Naming convention transformer */
+    readonly naming: NamingPlugin;
+    /** Schema name for table qualification (optional) */
+    readonly schema?: string;
+    /** Dialect capabilities for adapter-layer SQL surface gates */
+    readonly dialectCapabilities?: DialectCapabilities;
+    /** Root table name for the query */
+    readonly rootTable: string;
+    /** Current table alias (for JOINs) */
+    readonly currentAlias?: string;
+    /** Final relation path/name → SQL join alias map for relation-aware expression contexts */
+    readonly aliases?: ReadonlyMap<string, string>;
+    /** Maximum recursive depth (default: 100) */
+    readonly maxRecursiveDepth: number;
+    /** Optional callback for raw SQL audit trail */
+    readonly onRawSQL?: (sql: string) => void;
+    /** Default primary key column name for convention fallbacks (default: 'id') */
+    readonly defaultPkColumnName?: string;
+    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
+    readonly deriveFkColumnName?: FkColumnDerivation;
+    /** Alias of the outer (parent) query — used for FieldRef scope:'outer' resolution in EXISTS subqueries */
+    readonly outerAlias?: string;
+    /** Query-local CTE/binding names that must not be schema-qualified. */
+    readonly bindingNames?: BindingNameRegistry;
+    /**
+     * Optional callback to compile a QueryIntent into an AST Node (SubLink subselect).
+     * Set by PlanCompiler when compiling selectCustomExpression — enables SubqueryExpressionIntent
+     * to embed a fully compiled sub-SELECT into the parent SELECT column list.
+     *
+     * @param query - The inner QueryIntent to compile
+     * @param paramOffset - Current outer paramIndex; inner $N are renumbered by this offset
+     * @returns The compiled SelectStmt AST node and the inner parameters
+     */
+    readonly compileSubquery?: (query: _dbsp_types.QueryIntent, paramOffset: number) => {
+        ast: Node;
+        parameters: readonly unknown[];
+    };
+    /**
+     * Optional recursive compiler for NQL-origin SELECT expression values nested
+     * inside handler arguments, such as coalesce(upper(name), :fallback) or
+     * (price + :a) * :b.
+     */
+    readonly compileNqlSelectExpression?: (value: unknown, ctx: CompilerContext, state: CompilerState) => Node;
+    /**
+     * Optional callback to compile a custom fn() FILTER (WHERE ...) condition.
+     * Set by PlanCompiler to keep WHERE-dispatcher dependencies out of expression
+     * handlers while still applying FILTER in every expression position.
+     */
+    readonly compileCustomFnFilter?: (filterIntent: _dbsp_types.WhereIntent, ctx: CompilerContext, state: CompilerState) => Node | undefined;
+    /**
+     * Optional ModelIR for type-aware parameter casting.
+     * When provided, WHERE comparisons emit `$N::type` to eliminate
+     * PostgreSQL type inference ambiguity for nullable columns.
+     */
+    readonly model?: ModelIR;
+}
+/**
+ * Mutable state maintained during compilation.
+ */
+interface CompilerState {
+    /** Collected parameters in order */
+    parameters: unknown[];
+    /** Current parameter index (1-based for PostgreSQL) */
+    paramIndex: number;
+    /** Registered CTEs for the query */
+    ctes: Map<string, Node>;
+    /** Table aliases in use */
+    aliases: Map<string, string>;
+    /** JOIN clauses accumulated */
+    joins: Node[];
+}
+/**
+ * Base decision interface matching core's PlanDecision structure.
+ */
+interface Decision {
+    readonly type: string;
+    readonly table?: string;
+    readonly column?: string;
+    readonly alias?: string;
+    readonly operator?: string;
+    readonly value?: unknown;
+    readonly paramIndex?: number;
+    readonly dataType?: string;
+    readonly direction?: 'ASC' | 'DESC';
+    readonly nulls?: 'FIRST' | 'LAST';
+    readonly joinType?: 'inner' | 'left';
+    readonly sourceColumn?: ColumnListInput;
+    readonly targetColumn?: ColumnListInput;
+    readonly targetTable?: string;
+    readonly function?: string;
+    /** Apply DISTINCT to a SELECT-list aggregate (e.g. COUNT(DISTINCT col)). */
+    readonly distinct?: boolean;
+    readonly args?: readonly unknown[];
+    readonly conditions?: readonly Decision[];
+    readonly columns?: readonly string[];
+    readonly values?: readonly unknown[];
+    readonly set?: readonly {
+        column: string;
+        value: unknown;
+    }[];
+    readonly limit?: number | ParamIntent | {
+        paramIndex: number;
+    };
+    readonly offset?: number | ParamIntent | {
+        paramIndex: number;
+    };
+    readonly strategy?: 'join' | 'lateral' | 'json_agg' | 'cte';
+    readonly relation?: string;
+    readonly relationName?: string;
+    readonly relationPath?: string;
+    readonly hydrationPrefix?: string;
+    readonly include?: readonly Decision[];
+    readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
+    readonly foreignKey?: ColumnListInput;
+    readonly parentKey?: ColumnListInput;
+    readonly orderByFallback?: boolean;
+    readonly children?: readonly Decision[];
+    readonly partition?: readonly string[];
+    readonly orderBy?: readonly {
+        column: string;
+        direction?: 'ASC' | 'DESC';
+    }[] | readonly JsonAggOrderByEntry[];
+    readonly frame?: string;
+    readonly maxDepth?: number;
+    readonly pathColumn?: string;
+    readonly cycleDetection?: boolean;
+    readonly selectColumn?: string;
+    readonly aggregate?: string;
+    /**
+     * Apply DISTINCT to a scalar subquery's aggregate (e.g. AVG(DISTINCT price)).
+     * Deliberately NOT named `distinct` — `assertNoDroppedDecisionModifiers`
+     * (subquery-emission.ts) treats a top-level `distinct === true` on ANY
+     * subquery decision as an unsupported query-level DISTINCT modifier and
+     * throws. This field is scoped to the aggregate projection only, so it
+     * must not collide with that generic guard.
+     */
+    readonly aggregateDistinct?: boolean;
+    readonly subqueryOperator?: string;
+    readonly traversal?: string;
+    readonly traversals?: readonly {
+        traversal: string;
+        targetColumn?: string;
+    }[];
+    readonly isRecursive?: boolean;
+    readonly fkColumn?: string;
+    readonly pkColumn?: string;
+    readonly expandRelation?: string;
+    readonly relationColumns?: readonly string[];
+    readonly columnAliases?: Readonly<Record<string, string>>;
+    readonly jsonPath?: readonly unknown[];
+    readonly jsonMode?: 'json' | 'text';
+    readonly _compiledFilterWhere?: _pgsql_types.Node;
+    readonly filterWhere?: _pgsql_types.Node;
+    readonly expressionIntent?: unknown;
+    readonly escape?: string;
+    /**
+     * Provenance: the ORIGINAL QueryIntent before lowering.
+     * Set by every lowering site (convertIn, convertSubquery, normalizeToDecision,
+     * dispatchWhere, mapInSubqueryCondition) so that `buildPredicateSubquerySelect`
+     * (subquery-emission.ts) can validate the true caller intent rather than the
+     * stripped-down lowered decision fields.
+     *
+     * Required for IN / scalar / inSubquery / notInSubquery decisions.
+     * Optional on other decision types.
+     */
+    readonly subqueryIntent?: _dbsp_types.QueryIntent;
+}
+/**
+ * Handler for WHERE clause conditions.
+ * Transforms condition decisions into PostgreSQL AST expressions.
+ */
+interface WhereHandler {
+    /** Operator(s) this handler supports */
+    readonly operators: readonly string[];
+    /**
+     * Compile a WHERE condition to AST.
+     * @param decision The condition decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @param dispatch Callback to compile nested conditions
+     * @returns PostgreSQL AST node for the condition
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState, dispatch: WhereDispatcher): Node;
+}
+/**
+ * Dispatcher for recursive WHERE compilation.
+ */
+type WhereDispatcher = (decision: Decision, ctx: CompilerContext, state: CompilerState) => Node;
+/**
+ * Handler for SELECT expressions.
+ * Transforms expression decisions into PostgreSQL AST nodes.
+ */
+interface ExpressionHandler {
+    /** Expression type(s) this handler supports */
+    readonly types: readonly string[];
+    /**
+     * Safe to use when a function name comes from NQL text.
+     *
+     * Raw/escape-hatch handlers must not set this. NQL-origin function names use
+     * this opt-in surface only, then fall back to generic FuncCall emission.
+     */
+    readonly nqlSafe?: boolean;
+    /**
+     * Compile an expression to AST.
+     * @param decision The expression decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @returns PostgreSQL AST node for the expression
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
+}
+/**
+ * Handler for include/relation strategies.
+ * Transforms include decisions into PostgreSQL constructs (JOIN, LATERAL, json_agg, CTE).
+ */
+interface IncludeHandler {
+    /** Strategy this handler implements */
+    readonly strategy: 'join' | 'lateral' | 'json_agg' | 'cte';
+    /**
+     * Compile an include to AST.
+     * @param decision The include decision
+     * @param ctx Immutable compiler context
+     * @param state Mutable compiler state
+     * @returns Object with modifications to apply
+     */
+    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): IncludeResult;
+}
+/**
+ * Result of include compilation.
+ */
+interface IncludeResult {
+    /** Additional target list items (SELECT columns) */
+    targets?: Node[];
+    /** JOIN to add to FROM clause */
+    join?: Node;
+    /** Additional JOINs for cascaded includes (e.g., flat deep nesting) */
+    additionalJoins?: Node[];
+    /** CTE to add to WITH clause */
+    cte?: Node;
+    /** Subquery for LATERAL */
+    lateral?: Node;
+}
+
 type PlanExpressionOrderBy = readonly {
     field: string;
     direction?: 'asc' | 'desc';
@@ -459,11 +706,9 @@ declare class PlanCompiler {
     private compileCaseValue;
     /**
      * Compile a custom ExpressionIntent (customFn, customOp, ref, cast, unary,
-     * array, function, subquery, …) to an AST node, applying the customFn FILTER
-     * clause. Shared by the `selectCustomExpression` target path and CASE
-     * THEN/ELSE values so both render the full expression surface identically
-     * (every expression kind + FILTER), rather than one path silently binding
-     * expressions as parameters or dropping FILTER.
+     * array, function, subquery, …) to an AST node through the shared expression
+     * compiler. Shared by the `selectCustomExpression` target path and CASE
+     * THEN/ELSE values so both render the full expression surface identically.
      */
     private compileCustomExpressionNode;
     private compileInsert;
@@ -494,7 +739,11 @@ declare function compilePlan(plan: SimplifiedPlanReport, options?: CompilerOptio
 interface GenerateDDLOptions {
     /** Include DROP TABLE IF EXISTS statements before CREATE TABLE */
     readonly includeDropStatements?: boolean;
-    /** Database schema name (e.g., 'public', 'tenant_123') */
+    /**
+     * Database schema name (e.g., 'public', 'tenant_123').
+     * Required when emitted DDL would otherwise mix non-default target-scoped
+     * custom types/enums with unqualified table SQL.
+     */
     readonly schemaName?: string;
     /**
      * Automatically create indexes on foreign key columns.
@@ -520,1302 +769,326 @@ interface GenerateDDLOptions {
  * @returns Array of DDL statements in dependency order
  */
 declare function generateDDL(schema: ModelIR, options?: GenerateDDLOptions): string[];
-
+declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin): string;
 /**
- * Schema Comparison Engine (DDL-PROV Block 1)
- *
- * Compares two ModelIRs (schema definition vs database state)
- * and produces a structured diff of changes needed.
+ * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
  *
- * @module schema-diff
+ * Keep this as the single representability predicate for generated schema
+ * omission and destructive-drop classification: both sides must agree on the
+ * exact validation surface used by generateCreateIndex().
  */
-
-type ChangeKind = 'create_table' | 'drop_table' | 'add_column' | 'drop_column' | 'alter_column_type' | 'alter_column_nullable' | 'alter_column_default' | 'alter_column_unique' | 'add_primary_key' | 'drop_primary_key' | 'add_foreign_key' | 'drop_foreign_key' | 'alter_foreign_key' | 'validate_constraint' | 'create_index' | 'drop_index' | 'add_check_constraint' | 'drop_check_constraint' | 'create_enum' | 'alter_enum_add_value' | 'drop_enum' | 'alter_column_collation' | 'alter_column_identity' | 'add_comment' | 'drop_comment' | 'create_extension' | 'drop_extension' | 'create_sequence' | 'alter_sequence' | 'drop_sequence' | 'enable_rls' | 'disable_rls' | 'create_policy' | 'drop_policy';
-interface SchemaChange {
-    readonly kind: ChangeKind;
-    readonly table: string;
-    readonly column?: string;
-    readonly destructive: boolean;
-    readonly details: string;
-    /** Additional metadata for SQL generation */
-    readonly meta?: Readonly<Record<string, unknown>>;
-}
-interface DiffSummary {
-    readonly tables: {
-        readonly added: number;
-        readonly dropped: number;
-    };
-    readonly columns: {
-        readonly added: number;
-        readonly dropped: number;
-        readonly altered: number;
-    };
-    readonly indexes: {
-        readonly added: number;
-        readonly dropped: number;
-    };
-    readonly constraints: {
-        readonly added: number;
-        readonly dropped: number;
-        readonly altered: number;
-    };
-}
-interface SchemaDiff {
-    readonly changes: readonly SchemaChange[];
-    readonly hasDestructive: boolean;
-    readonly summary: DiffSummary;
-}
-interface CompareSchemataOptions {
-    /**
-     * Database naming convention.
-     * When set, schema model names (camelCase) are converted to DB format
-     * (e.g. snake_case) before comparison with the introspected model.
-     */
-    dbCasing?: DbCasing;
-    /** Dialect capabilities — comparisons for unsupported features will be skipped */
-    readonly dialectCapabilities?: DialectCapabilities;
-    /**
-     * When `true`, extensions present in the live DB but absent from the model
-     * schema are silently ignored — no `drop_extension` change is emitted for them.
-     * Only extensions explicitly declared in the model are managed (created if missing).
-     *
-     * Use this when the database image pre-installs extensions that the application
-     * schema does not own (e.g. pgvector, pg_search bundled in a custom Postgres image).
-     * Default: `false` (full-sync behaviour — unmanaged DB extensions produce a
-     * `drop_extension` entry).
-     */
-    readonly ignoreUnmanagedExtensions?: boolean;
-}
-/**
- * Compare two ModelIRs and produce a structured diff.
- *
- * @param schema - The desired schema (from definition)
- * @param db - The current database state (from introspection)
- * @param options - Optional comparison settings (e.g. dbCasing)
- * @returns SchemaDiff with all changes needed to bring DB in sync with schema
- */
-declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions): SchemaDiff;
+declare function canGenerateCreateIndex(tableName: string, idx: IndexIR, schemaName?: string | undefined, naming?: NamingPlugin): boolean;
 
 /**
- * Migration SQL Generator (DDL-PROV Block 1)
+ * PostgreSQL Schema Introspection (ADAPTER-006)
  *
- * Generates ordered SQL statements from a SchemaDiff.
- * Statements are topologically sorted: DROP constraints → DROP objects → CREATE objects → ADD constraints.
+ * Queries information_schema/pg_catalog to build ModelIR
+ * from an existing database. Supports:
+ * - Table/column/PK discovery
+ * - FK → bidirectional relation inference
+ * - Hierarchy detection (adjacency + edge-table)
+ * - Include/exclude filtering
  *
- * @module migration-sql
+ * @module introspection
  */
 
-interface MigrationSQLOptions {
-    /** Schema namespace (default: none — unqualified) */
-    readonly schemaName?: string;
-    /** Whether to include destructive changes (drops) */
-    readonly includeDestructive?: boolean;
-    /** Automatically create indexes on FK columns for new tables (default: true) */
-    readonly fkAutoIndex?: boolean;
-    /** Dialect capabilities — migration SQL for unsupported features will be filtered */
-    readonly dialectCapabilities?: DialectCapabilities;
+/** The minimum every schema-level operation needs: which schema. */
+interface SchemaScopeOptions {
+    /** Schema name to operate on (default: 'public') */
+    readonly schema?: string;
 }
 /**
- * Generate ordered SQL statements from a SchemaDiff.
- *
- * Topological order:
- * 0.  DROP FK/CHECK constraints (must drop before referenced tables)
- * 1.  DROP indexes
- * 2.  DROP columns
- * 3.  DROP primary keys
- * 4.  DROP tables, DROP ENUMs
- * 5.  CREATE ENUMs (must exist before tables that use them)
- * 6.  CREATE tables
- * 7.  ADD columns
- * 8.  ALTER columns (type, nullable, default)
- * 9.  ADD primary keys / column UNIQUE constraints
- * 10. ADD FK constraints (must add after referenced tables exist)
- * 11. ALTER FK (drop + re-add)
- * 12. CREATE indexes
- * 13. ADD CHECK constraints
- * 14. ALTER ENUM ADD VALUE (must be last — has transaction visibility caveats in PG)
- * 15. COMMENT ON TABLE / COLUMN (very last)
+ * Introspection additionally chooses WHICH TABLES to read. It is a read-only
+ * path, so narrowing it is safe — that is why the table filters live here and
+ * nowhere else.
  */
-declare function generateMigrationSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+interface IntrospectionOptions extends SchemaScopeOptions {
+    /** Tables to exclude (glob patterns: * matches any chars) */
+    readonly exclude?: readonly string[];
+    /** Tables to include (default: all). Applied before exclude. */
+    readonly include?: readonly string[];
+}
+/** Hierarchy pattern detected during introspection */
 /**
- * Generate ordered DOWN SQL statements from a SchemaDiff.
- *
- * Reverses the topological order used in UP migrations:
- * phases run in descending order (11, 10, 9, ..., 0).
- *
- * Irreversible changes (drops that lose data) produce SQL WARNING comments.
+ * Hierarchy pattern detected during introspection.
+ * Alias of {@link HierarchyIR} from \@dbsp/types — kept here for
+ * public-API backwards compatibility (re-exported from \@dbsp/adapter-pgsql).
  */
-declare function generateDownSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
-
+type DetectedHierarchy = HierarchyIR;
+/** Extended ModelIR with hierarchy metadata */
+interface IntrospectedModelIR extends ModelIR {
+    readonly hierarchies: readonly DetectedHierarchy[];
+    readonly introspectedAt: Date;
+    readonly warnings: readonly string[];
+}
 /**
- * Migration File Format v2 — UP + DOWN sections.
+ * Introspect a database through a pool.
  *
- * File format:
- *   -- dbsp:destructive: true|false
- *   <UP statements>;
- *   -- DOWN
- *   <DOWN statements>;
+ * This does NOT accept a checked-out `PoolClient`, and that is deliberate. A
+ * client may be sitting inside a transaction that belongs to its owner, and a
+ * catalog query that fails there aborts *their* transaction. Protecting that
+ * needs a savepoint, and knowing whether to take one needs the caller to say
+ * whose transaction it is — which is what `PgsqlAdapter`'s `borrowedClient`
+ * declaration is for. Guessing it from the object's shape is the exact defect
+ * this adapter was rewritten to remove.
  *
- * The separator `-- DOWN` must be on its own line (SC-25).
+ * Saying so in a comment is not enough: `CatalogQueryExecutor` is structural, so
+ * a `PoolClient` — which has a `query()` — satisfies it, and the prose would have
+ * been the only thing standing in the way. It is branded instead, and only the
+ * adapter's own protected executor carries the brand. A client cannot be passed
+ * here at all.
  *
- * @module ddl/migration-file
- */
-
-/**
- * Result of parsing a migration file's UP/DOWN sections.
- */
-interface ParsedMigrationFile {
-    readonly upStatements: readonly string[];
-    readonly downStatements: readonly string[];
-    readonly hasDown: boolean;
-    readonly destructive?: boolean | undefined;
-}
-/**
- * Generate a migration file content with UP and DOWN sections.
- */
-declare function generateMigrationFile(diff: SchemaDiff, options?: MigrationSQLOptions & {
-    name?: string;
-}): string;
-/**
- * Parse a migration file into UP and DOWN sections.
- * Separator: `^\s*-- DOWN\s*$` (strict regex, own line only — SC-25)
- */
-declare function parseMigrationFile(content: string): ParsedMigrationFile;
-/**
- * Check if SQL statements contain destructive operations.
- * Destructive: DROP TABLE, DROP COLUMN, lossy ALTER COLUMN TYPE
+ * So: hold a client, use `new PgsqlAdapter(client, { borrowedClient: true })`
+ * and call `.introspect()` on it.
  */
-declare function isDestructiveDown(downStatements: readonly string[]): boolean;
+declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
 
 /**
- * Migration Tracker — `_dbsp_migrations` table CRUD.
+ * PgsqlAdapter - Implements the Adapter interface for PostgreSQL using native pg driver.
  *
- * Manages the tracking table that records which migrations
- * have been applied to a database.
+ * This adapter wraps a pg Pool instance and provides the unified
+ * adapter interface for the db-semantic-planner ORM.
+ *
+ * @module pgsql-adapter
  */
 
-interface MigrationRecord {
-    /** Migration filename (e.g., "0001_create_users.sql") */
-    readonly name: string;
-    /** SHA-256 checksum of the migration file content */
-    readonly checksum: string;
-    /** When the migration was applied */
-    readonly appliedAt: Date;
-    /** Schema version at time of this migration */
-    readonly schemaVersion: number;
-    /** Whether this migration contains destructive changes */
-    readonly destructive: boolean;
+declare class PgsqlRawSqlTransactionControlError extends Error {
+    readonly dbspRawSqlTransactionControl = true;
+    constructor(cause: unknown);
+}
+declare class PgsqlTransactionAbortedCommitError extends Error {
+    readonly dbspTransactionAbortedCommit = true;
+    constructor(cause: unknown);
+}
+declare class PgsqlTransactionAbortedError extends Error {
+    readonly dbspTransactionAborted = true;
+    constructor(cause: unknown);
 }
 /**
- * Acquire a session-level advisory lock for migration operations.
- *
- * @deprecated Use {@link withMigrationLock} instead — pool.query may release
- * the connection (and the lock) before the migration completes.
+ * Options for PgsqlAdapter.
  */
-declare function acquireMigrationLock(pool: Pool): Promise<void>;
+interface PgsqlAdapterOptions {
+    /** Schema name for multi-tenant queries */
+    readonly schemaName?: string;
+    /**
+     * DB column casing convention (intuitive semantics).
+     * - `'snake_case'`: DB columns are snake_case → transform to camelCase for JS
+     * - `'camelCase'`: DB columns are camelCase → no transformation
+     * - `'preserve'`: No transformation
+     */
+    readonly dbCasing?: DbCasing;
+    /** Optional model for WHERE compilation */
+    readonly model?: ModelIR;
+    /** Optional logger for debug/error messages */
+    readonly logger?: AdapterLogger;
+    /** Default primary key column name for convention fallbacks (default: 'id') */
+    readonly defaultPkColumnName?: string;
+    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
+    readonly deriveFkColumnName?: FkColumnDerivation;
+}
+interface PgsqlPoolAdapterOptions extends PgsqlAdapterOptions {
+    readonly borrowedClient?: false;
+}
+interface PgsqlBorrowedClientAdapterOptions extends PgsqlAdapterOptions {
+    /** This connection belongs to the caller. dbsp never releases it. */
+    readonly borrowedClient: true;
+    /**
+     * Let dbsp run transactions on your connection, through a savepoint.
+     *
+     * When your connection is already inside a transaction, dbsp creates a
+     * savepoint and rolls back dbsp's changes after that savepoint if the callback
+     * fails. `RELEASE SAVEPOINT` does not commit; it merges the work into your
+     * surrounding transaction, so a callback that succeeded is still undone if you
+     * later roll back. Deferred constraints or triggers can still make your outer
+     * `COMMIT` fail after dbsp has returned. `SET LOCAL` changes inside the callback
+     * remain in effect for the rest of your transaction after the savepoint is
+     * released. `ON COMMIT DROP` and `ON COMMIT DELETE ROWS` fire at your transaction
+     * boundary, not at the savepoint. Sequences are not transactional:
+     * `nextval`/`setval` are not reclaimed by a savepoint rollback. Session-level
+     * advisory locks ignore rollback; transaction-level advisory locks taken by a
+     * successful callback last until your transaction ends.
+     *
+     * Transaction control through raw SQL inside a scope dbsp is managing is
+     * unsupported. `COMMIT`, `ROLLBACK`, and `PREPARE TRANSACTION` end the
+     * transaction dbsp is working inside; dbsp detects that and fails loudly, but
+     * the data is already whatever your statement made it. Raw savepoint control
+     * (`SAVEPOINT`, `RELEASE SAVEPOINT`, `ROLLBACK TO SAVEPOINT`) can alter the
+     * savepoint stack before dbsp sees the command tag; dbsp poisons the scope, but
+     * it cannot make that command un-run. Manage your transaction outside dbsp's
+     * calls.
+     */
+    readonly managedTransactions?: true;
+}
 /**
- * Release the session-level advisory lock for migration operations.
+ * Adapter implementation for PostgreSQL using native pg driver.
  *
- * @deprecated Use {@link withMigrationLock} instead.
- */
-declare function releaseMigrationLock(pool: Pool): Promise<void>;
-/**
- * Execute a callback under an advisory lock using a dedicated client.
- * The lock is held for the duration of the callback.
- * The client is released (and lock freed) after the callback completes.
- */
-declare function withMigrationLock<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
-/**
- * Ensure the migrations tracking table exists.
- * Auto-migrates existing tables that lack `schema_version`/`destructive` columns,
- * and backfills `schema_version` by `applied_at` order for rows still at 0.
- */
-declare function ensureMigrationsTable(pool: Pool): Promise<void>;
-/**
- * Get all applied migrations, ordered by name.
- */
-declare function getAppliedMigrations(pool: Pool): Promise<readonly MigrationRecord[]>;
-/**
- * Record a migration as applied.
- */
-declare function recordMigration(pool: Pool, name: string, checksum: string, schemaVersion: number, destructive: boolean): Promise<void>;
-/**
- * Check if a specific migration has been applied.
- */
-declare function isMigrationApplied(pool: Pool, name: string): Promise<boolean>;
-/**
- * Get the next schema version number (max + 1, or 1 if no migrations).
- */
-declare function getNextSchemaVersion(pool: Pool): Promise<number>;
-/**
- * Remove a migration record (for rollback).
- */
-declare function removeMigrationRecord(pool: Pool, name: string): Promise<void>;
-
-/**
- * Type Mapping - Maps ModelIR ColumnType to PostgreSQL data types
+ * @typeParam DB - Database schema type
  *
- * Supports both manual schemas and introspected schemas (preserving originalDbType).
- * Handles auto-increment via SERIAL/BIGSERIAL types.
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
  *
- * @module ddl/type-mapping
- */
-
-/**
- * Map ColumnType to PostgreSQL data type string.
- *
- * Uses originalDbType if available (from introspection), otherwise
- * falls back to reasonable PostgreSQL defaults.
- *
- * @param col - Column definition from ModelIR
- * @returns PostgreSQL type string (e.g., 'VARCHAR(255)', 'SERIAL', 'JSONB')
- */
-declare function mapColumnType(col: ColumnIR): string;
-/**
- * Map OnDeleteAction to PostgreSQL syntax.
- */
-declare function mapOnDeleteAction(action?: string): string;
-
-/**
- * EXPLAIN Statement Compiler
- *
- * Generates PostgreSQL EXPLAIN statements with various options.
- * Supports:
- * - ANALYZE (execute and show actual run times)
- * - FORMAT (text, json, xml, yaml)
- * - VERBOSE, COSTS, BUFFERS, TIMING, SETTINGS
- */
-
-/**
- * Output format for EXPLAIN results.
- */
-type ExplainFormat = 'text' | 'json' | 'xml' | 'yaml';
-/**
- * Options for EXPLAIN statement.
- */
-interface ExplainOptions {
-    /** Execute the query and show actual run times */
-    analyze?: boolean;
-    /** Show more detailed output */
-    verbose?: boolean;
-    /** Show cost estimates (default: true) */
-    costs?: boolean;
-    /** Show buffer usage (requires analyze) */
-    buffers?: boolean;
-    /** Show actual timing (requires analyze) */
-    timing?: boolean;
-    /** Show non-default settings */
-    settings?: boolean;
-    /** Output format */
-    format?: ExplainFormat;
-}
-/**
- * Build an EXPLAIN statement wrapping a query.
- *
- * @param query - The query to explain (SelectStmt, InsertStmt, etc.)
- * @param options - EXPLAIN options
- * @returns ExplainStmt AST node
- *
- * @example
- * ```typescript
- * const selectAst = { SelectStmt: { ... } };
- * const explainAst = buildExplain(selectAst, { analyze: true, format: 'json' });
- * // Produces: EXPLAIN (ANALYZE, FORMAT JSON) SELECT ...
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPgsqlAdapter(pool);
+ * const orm = createOrm({ model, adapter });
  * ```
  */
-declare function buildExplain(query: Node, options?: ExplainOptions): Node;
-/**
- * Build EXPLAIN ANALYZE with JSON format (common pattern).
- *
- * @param query - The query to explain
- * @returns ExplainStmt with ANALYZE and JSON format
- */
-declare function buildExplainAnalyzeJson(query: Node): Node;
-/**
- * Build simple EXPLAIN (plan only, no execution).
- *
- * @param query - The query to explain
- * @returns ExplainStmt with default options
- */
-declare function buildExplainPlan(query: Node): Node;
-/**
- * Build verbose EXPLAIN with costs and buffers.
- *
- * @param query - The query to explain
- * @returns ExplainStmt with verbose options
- */
-declare function buildExplainVerbose(query: Node): Node;
-/**
- * Parse EXPLAIN JSON output to get execution statistics.
- *
- * @param jsonOutput - The JSON string from EXPLAIN (ANALYZE, FORMAT JSON)
- * @returns Parsed plan with execution statistics
- */
-declare function parseExplainJson(jsonOutput: string): ExplainPlan[];
-/**
- * Parsed EXPLAIN plan structure (simplified).
- */
-interface ExplainPlan {
-    Plan: {
-        'Node Type': string;
-        'Relation Name'?: string;
-        Alias?: string;
-        'Startup Cost'?: number;
-        'Total Cost'?: number;
-        'Plan Rows'?: number;
-        'Plan Width'?: number;
-        'Actual Startup Time'?: number;
-        'Actual Total Time'?: number;
-        'Actual Rows'?: number;
-        'Actual Loops'?: number;
-        Plans?: ExplainPlan['Plan'][];
-    };
-    'Planning Time'?: number;
-    'Execution Time'?: number;
-    Triggers?: unknown[];
-}
-/**
- * Extract total execution time from EXPLAIN ANALYZE JSON output.
- *
- * @param plans - Parsed EXPLAIN plans
- * @returns Total execution time in milliseconds
- */
-declare function getTotalExecutionTime(plans: ExplainPlan[]): number;
-/**
- * Extract row counts from EXPLAIN ANALYZE JSON output.
- *
- * @param plans - Parsed EXPLAIN plans
- * @returns Object with estimated and actual row counts
- */
-declare function getRowEstimates(plans: ExplainPlan[]): {
-    estimated: number;
-    actual: number;
-};
-
-/**
- * ParadeDB Extension Wrappers
- *
- * Type-safe query builders for ParadeDB BM25 full-text search.
- * All functions return ExpressionRef instances that can be used in:
- * - SELECT: .column(score('id').as('score'))
- * - WHERE:  .where(bm25Search('symbols', query, { name: 3.0, doc: 1.0 }))
- * - ORDER BY: .orderBy(score('id'), 'desc')
- *
- * @remarks
- * ParadeDB functions accept both named and positional arguments.
- * This module uses named args via namedArg() for parse(), which produces:
- *   paradedb.parse(field => 'field_name', query_string => $1)
- * Named parameter syntax is supported via the NamedArgExpressionIntent (EXT-NAMED-PARAMS).
- */
-
-/**
- * BM25 relevance score for a row.
- *
- * Use in SELECT and ORDER BY to retrieve and sort by full-text relevance.
- * Requires a BM25 index on the table.
- *
- * @param keyField - The key field of the BM25 index (typically the primary key, e.g. 'id')
- * @returns ExpressionRef that compiles to: paradedb.score("keyField")
- *
- * @example
- * orm.select('symbols').column(score('id').as('score')).orderBy(score('id'), 'desc')
- * // → paradedb.score("id") AS "score"
- */
-declare function score(keyField: string): ExpressionRef;
-/**
- * Parse a single-field BM25 query expression.
- *
- * Compiles to: paradedb.parse(field => 'field_name', query_string => $N)
- *
- * @param field - Column name to search in (must be indexed in the BM25 index)
- * @param query - Query string value (will be bound as a parameter)
- * @returns ExpressionRef for use with boost() or booleanSearch()
- *
- * @example
- * parse('name', 'hello world')
- * // → paradedb.parse(field => 'name', query_string => $1)
- */
-declare function parse(field: string, query: ExpressionRef | unknown): ExpressionRef;
-/**
- * Apply a boost multiplier to a BM25 sub-expression.
- *
- * Compiles to: paradedb.boost(factor, expr)
- *
- * @param factor - Boost multiplier (e.g. 3.0 for 3x weight)
- * @param expr - Expression to boost (typically a parse() call)
- * @returns ExpressionRef for use with booleanSearch()
- *
- * @example
- * boost(3.0, parse('name', 'hello'))
- * // → paradedb.boost(3.0, paradedb.parse('name', $1))
- */
-declare function boost(factor: number, expr: ExpressionRef): ExpressionRef;
-/**
- * Combine multiple BM25 sub-expressions with boolean OR logic.
- *
- * Compiles to: paradedb.boolean(expr1, expr2, ...)
- *
- * @param exprs - One or more sub-expressions (typically boost() calls)
- * @returns ExpressionRef for use on the right side of the @@@ operator
- *
- * @example
- * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
- * // → paradedb.boolean(paradedb.boost(3.0, ...), paradedb.boost(1.0, ...))
- */
-/**
- * Combine multiple BM25 sub-expressions with boolean OR logic.
- *
- * Compiles to: paradedb.boolean(should => ARRAY[expr1, expr2, ...])
- *
- * @param exprs - One or more sub-expressions (typically boost() calls)
- * @returns ExpressionRef for use on the right side of the @@@ operator
- *
- * @example
- * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
- * // → paradedb.boolean(should => ARRAY[paradedb.boost(3.0, ...), paradedb.boost(1.0, ...)])
- */
-declare function booleanSearch(exprs: ExpressionRef[]): ExpressionRef;
-/**
- * Full BM25 multi-field search with per-field boost weights.
- *
- * Produces: table @@@ paradedb.boolean(boost1, boost2, ...)
- *
- * Each field in `fieldBoosts` generates a `paradedb.boost(weight, paradedb.parse(field, $N))`
- * sub-expression. The same query string is used for all fields (single parameter binding).
- *
- * @param table - Table alias for the left side of the @@@ operator
- * @param query - Query string (bound as a single $N parameter, shared across all fields)
- * @param fieldBoosts - Map of column name → boost weight
- * @returns ExpressionRef for use in .where()
- *
- * @example
- * bm25Search('s', searchTerm, {
- *   name_searchable: 3.0,
- *   name: 1.0,
- *   signature: 1.5,
- *   doc_searchable: 1.0,
- * })
- * // → s @@@ paradedb.boolean(
- * //     paradedb.boost(3.0, paradedb.parse('name_searchable', $1)),
- * //     paradedb.boost(1.0, paradedb.parse('name', $1)),
- * //     paradedb.boost(1.5, paradedb.parse('signature', $1)),
- * //     paradedb.boost(1.0, paradedb.parse('doc_searchable', $1))
- * //   )
- *
- * @remarks
- * The query parameter is shared: all parse() calls reference the same $N slot.
- * If you need different query strings per field, compose parse()/boost()/booleanSearch() manually.
- *
- * @remarks
- * ParadeDB's boolean() function accepts both positional args and the named
- * `should => ARRAY[...]` syntax. This wrapper uses positional args.
- * Named parameter syntax is deferred to EXT-NAMED-PARAMS.
- */
-declare function bm25Search(table: string, query: unknown, fieldBoosts: Record<string, number>): ExpressionRef;
-
-/**
- * PostgreSQL built-in function helpers.
- *
- * Thin wrappers around core expression primitives for common PostgreSQL functions.
- * Same pattern as pgvector.ts and paradedb.ts.
- */
-
-/**
- * Generate a series of values: generate_series(start, stop[, step])
- *
- * Returns a set of values from start to stop (inclusive), with an optional step.
- * Commonly used with CTE for batch operations.
- *
- * @example generateSeries(1, 100) → generate_series(1, 100)
- * @example generateSeries(0, 50, 5) → generate_series(0, 50, 5)
- */
-declare function generateSeries(start: number, stop: number, step?: number): ExpressionRef;
-/**
- * Get next value from a sequence: nextval('sequence_name')
- *
- * @example nextval('order_id_seq') → nextval('order_id_seq')
- */
-declare function nextval(sequenceName: string): ExpressionRef;
-
-/**
- * pgvector Extension Wrappers
- *
- * Type-safe query builders for pgvector distance operators.
- * All functions return ExpressionRef instances that can be used in:
- * - SELECT: .column(cosineDistance('vector', qv).as('score'))
- * - WHERE:  .where(cosineDistance('vector', qv).gte(0.5))
- * - ORDER BY: .orderBy(rawDistance('vector', qv), 'asc')
- */
-
-/**
- * Cosine similarity: 1 - (col <=> vector)
- *
- * Score in [0, 1], higher = more similar.
- * Use in SELECT to get a similarity score.
- *
- * @example
- * orm.select('embeddings').column(cosineDistance('vector', qv).as('score'))
- */
-declare function cosineDistance(column: string, vector: number[]): ExpressionRef;
-/**
- * Raw cosine distance: col <=> vector
- *
- * Lower = closer. Index-friendly — use in ORDER BY for ANN search.
- * Do NOT use in SELECT as a similarity score (lower = closer is counterintuitive).
- *
- * @example
- * orm.select('embeddings').orderBy(rawDistance('vector', qv), 'asc')
- */
-declare function rawDistance(column: string, vector: number[]): ExpressionRef;
-/**
- * L2 (Euclidean) distance: col <-> vector
- *
- * @example
- * orm.select('embeddings').orderBy(l2Distance('vector', qv), 'asc')
- */
-declare function l2Distance(column: string, vector: number[]): ExpressionRef;
-/**
- * Inner product distance: col <#> vector (negative inner product)
- *
- * For maximum inner product search: ORDER BY innerProduct('vector', qv) ASC.
- *
- * @example
- * orm.select('embeddings').orderBy(innerProduct('vector', qv), 'asc')
- */
-declare function innerProduct(column: string, vector: number[]): ExpressionRef;
-/**
- * Get the number of dimensions of a vector column: vector_dims(col)
- *
- * Returns an integer — the dimension count of the stored vector.
- * Useful for sanity-checking that embeddings match the expected model dimension.
- *
- * @example
- * orm.from(embeddings).columns([vectorDims('vector').as('dim')]).first()
- * // → SELECT vector_dims("t0"."vector") AS "dim" FROM "embeddings" AS "t0"
- */
-declare function vectorDims(column: string): ExpressionRef;
-
-/**
- * Immutable context passed to all handlers during compilation.
- */
-interface CompilerContext {
-    /** Naming convention transformer */
-    readonly naming: NamingPlugin;
-    /** Schema name for table qualification (optional) */
-    readonly schema?: string;
-    /** Dialect capabilities for adapter-layer SQL surface gates */
-    readonly dialectCapabilities?: DialectCapabilities;
-    /** Root table name for the query */
-    readonly rootTable: string;
-    /** Current table alias (for JOINs) */
-    readonly currentAlias?: string;
-    /** Final relation path/name → SQL join alias map for relation-aware expression contexts */
-    readonly aliases?: ReadonlyMap<string, string>;
-    /** Maximum recursive depth (default: 100) */
-    readonly maxRecursiveDepth: number;
-    /** Optional callback for raw SQL audit trail */
-    readonly onRawSQL?: (sql: string) => void;
-    /** Default primary key column name for convention fallbacks (default: 'id') */
-    readonly defaultPkColumnName?: string;
-    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
-    readonly deriveFkColumnName?: FkColumnDerivation;
-    /** Alias of the outer (parent) query — used for FieldRef scope:'outer' resolution in EXISTS subqueries */
-    readonly outerAlias?: string;
-    /** Query-local CTE/binding names that must not be schema-qualified. */
-    readonly bindingNames?: BindingNameRegistry;
+declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
+    private readonly pool;
+    private readonly client;
+    private readonly borrowedClient;
+    private readonly managedTransactions;
+    private readonly adapterManagedTransaction;
+    private readonly scopeToken;
+    private readonly scopeState;
+    private readonly schemaName;
+    private readonly _dbCasing;
+    private readonly naming;
+    private readonly model;
+    private readonly logger;
+    private readonly _capabilities;
+    private readonly defaultPk;
+    private readonly deriveFk;
     /**
-     * Optional callback to compile a QueryIntent into an AST Node (SubLink subselect).
-     * Set by PlanCompiler when compiling selectCustomExpression — enables SubqueryExpressionIntent
-     * to embed a fully compiled sub-SELECT into the parent SELECT column list.
+     * Create a new PgsqlAdapter.
      *
-     * @param query - The inner QueryIntent to compile
-     * @param paramOffset - Current outer paramIndex; inner $N are renumbered by this offset
-     * @returns The compiled SelectStmt AST node and the inner parameters
+     * Ownership of the connection is **declared**, never inferred. Handing over a
+     * `PoolClient` means nothing on its own — it says the object has a `release()`
+     * method, not that a transaction is open or that the caller owns the lifecycle.
+     * Pass `borrowedClient: true` to say so.
+     *
+     * @param pool - a pg.Pool, a caller-owned pg.PoolClient (with `borrowedClient: true`),
+     *   or nothing at all for compile-only mode
+     * @param options - configuration; declares connection ownership
      */
-    readonly compileSubquery?: (query: _dbsp_types.QueryIntent, paramOffset: number) => {
-        ast: Node;
-        parameters: readonly unknown[];
-    };
+    constructor(pool?: Pool | undefined, options?: PgsqlPoolAdapterOptions);
+    constructor(pool: Pool, options?: PgsqlPoolAdapterOptions);
+    constructor(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions);
+    constructor(pool: undefined, options?: PgsqlAdapterOptions);
     /**
-     * Optional recursive compiler for NQL-origin SELECT expression values nested
-     * inside handler arguments, such as coalesce(upper(name), :fallback) or
-     * (price + :a) * :b.
+     * Shared compilation dependencies — built lazily from adapter fields.
+     * Passed to compiler sub-modules instead of `this`.
      */
-    readonly compileNqlSelectExpression?: (value: unknown, ctx: CompilerContext, state: CompilerState) => Node;
     /**
-     * Optional ModelIR for type-aware parameter casting.
-     * When provided, WHERE comparisons emit `$N::type` to eliminate
-     * PostgreSQL type inference ambiguity for nullable columns.
+     * Return a new PgsqlAdapterOptions that merges current config with overrides.
+     * Ensures that all configuration fields (logger, defaultPkColumnName,
+     * deriveFkColumnName, etc.) are propagated to scoped/transactional adapters.
      */
-    readonly model?: ModelIR;
-}
-/**
- * Mutable state maintained during compilation.
- */
-interface CompilerState {
-    /** Collected parameters in order */
-    parameters: unknown[];
-    /** Current parameter index (1-based for PostgreSQL) */
-    paramIndex: number;
-    /** Registered CTEs for the query */
-    ctes: Map<string, Node>;
-    /** Table aliases in use */
-    aliases: Map<string, string>;
-    /** JOIN clauses accumulated */
-    joins: Node[];
-}
-/**
- * Base decision interface matching core's PlanDecision structure.
- */
-interface Decision {
-    readonly type: string;
-    readonly table?: string;
-    readonly column?: string;
-    readonly alias?: string;
-    readonly operator?: string;
-    readonly value?: unknown;
-    readonly paramIndex?: number;
-    readonly dataType?: string;
-    readonly direction?: 'ASC' | 'DESC';
-    readonly nulls?: 'FIRST' | 'LAST';
-    readonly joinType?: 'inner' | 'left';
-    readonly sourceColumn?: ColumnListInput;
-    readonly targetColumn?: ColumnListInput;
-    readonly targetTable?: string;
-    readonly function?: string;
-    /** Apply DISTINCT to a SELECT-list aggregate (e.g. COUNT(DISTINCT col)). */
-    readonly distinct?: boolean;
-    readonly args?: readonly unknown[];
-    readonly conditions?: readonly Decision[];
-    readonly columns?: readonly string[];
-    readonly values?: readonly unknown[];
-    readonly set?: readonly {
-        column: string;
-        value: unknown;
-    }[];
-    readonly limit?: number | ParamIntent | {
-        paramIndex: number;
-    };
-    readonly offset?: number | ParamIntent | {
-        paramIndex: number;
-    };
-    readonly strategy?: 'join' | 'lateral' | 'json_agg' | 'cte';
-    readonly relation?: string;
-    readonly relationName?: string;
-    readonly relationPath?: string;
-    readonly hydrationPrefix?: string;
-    readonly include?: readonly Decision[];
-    readonly relationType?: 'belongsTo' | 'hasMany' | 'hasOne';
-    readonly foreignKey?: ColumnListInput;
-    readonly parentKey?: ColumnListInput;
-    readonly orderByFallback?: boolean;
-    readonly children?: readonly Decision[];
-    readonly partition?: readonly string[];
-    readonly orderBy?: readonly {
-        column: string;
-        direction?: 'ASC' | 'DESC';
-    }[] | readonly JsonAggOrderByEntry[];
-    readonly frame?: string;
-    readonly maxDepth?: number;
-    readonly pathColumn?: string;
-    readonly cycleDetection?: boolean;
-    readonly selectColumn?: string;
-    readonly aggregate?: string;
+    private cloneOptions;
+    private buildCompileDeps;
+    private requireNqlCompileModel;
+    private assertNqlBindingNamesDisjointFromTables;
+    private compileNqlMutation;
+    private compileNqlBundleLeaf;
+    private compileNqlBundle;
     /**
-     * Apply DISTINCT to a scalar subquery's aggregate (e.g. AVG(DISTINCT price)).
-     * Deliberately NOT named `distinct` — `assertNoDroppedDecisionModifiers`
-     * (subquery-emission.ts) treats a top-level `distinct === true` on ANY
-     * subquery decision as an unsupported query-level DISTINCT modifier and
-     * throws. This field is scoped to the aggregate projection only, so it
-     * must not collide with that generic guard.
+     * Returns the pool/client executor, or throws if in compile-only mode.
      */
-    readonly aggregateDistinct?: boolean;
-    readonly subqueryOperator?: string;
-    readonly traversal?: string;
-    readonly traversals?: readonly {
-        traversal: string;
-        targetColumn?: string;
-    }[];
-    readonly isRecursive?: boolean;
-    readonly fkColumn?: string;
-    readonly pkColumn?: string;
-    readonly expandRelation?: string;
-    readonly relationColumns?: readonly string[];
-    readonly columnAliases?: Readonly<Record<string, string>>;
-    readonly jsonPath?: readonly unknown[];
-    readonly jsonMode?: 'json' | 'text';
-    readonly _compiledFilterWhere?: _pgsql_types.Node;
-    readonly filterWhere?: _pgsql_types.Node;
-    readonly expressionIntent?: unknown;
-    readonly escape?: string;
+    private requireConnection;
+    /** Adapter capabilities for feature detection */
+    get capabilities(): AdapterCapabilities;
+    /** PostgreSQL dialect capabilities for planner strategy selection */
+    get dialectCapabilities(): DialectCapabilities;
     /**
-     * Provenance: the ORIGINAL QueryIntent before lowering.
-     * Set by every lowering site (convertIn, convertSubquery, normalizeToDecision,
-     * dispatchWhere, mapInSubqueryCondition) so that `buildPredicateSubquerySelect`
-     * (subquery-emission.ts) can validate the true caller intent rather than the
-     * stripped-down lowered decision fields.
+     * DB column casing convention used by this adapter.
+     */
+    get dbCasing(): DbCasing;
+    /**
+     * Get the underlying pg Pool or borrowed PoolClient instance.
+     */
+    getPoolInstance(): Pool | PoolClient;
+    /**
+     * Compile a plan to executable SQL.
      *
-     * Required for IN / scalar / inSubquery / notInSubquery decisions.
-     * Optional on other decision types.
+     * When passed a direct `CompiledNqlQuery`, the adapter trusts that the bundle
+     * has already been semantically validated by the NQL compiler. This method
+     * still performs adapter-owned SQL safety checks for emitted binding names
+     * before CTE emission.
      */
-    readonly subqueryIntent?: _dbsp_types.QueryIntent;
-}
-/**
- * Handler for WHERE clause conditions.
- * Transforms condition decisions into PostgreSQL AST expressions.
- */
-interface WhereHandler {
-    /** Operator(s) this handler supports */
-    readonly operators: readonly string[];
+    compile<T = unknown>(plan: PlanReport | CompiledNqlQuery, options?: CompileOptions): CompiledQuery<T>;
     /**
-     * Compile a WHERE condition to AST.
-     * @param decision The condition decision
-     * @param ctx Immutable compiler context
-     * @param state Mutable compiler state
-     * @param dispatch Callback to compile nested conditions
-     * @returns PostgreSQL AST node for the condition
+     * Compile a plan with includes, returning subquery include metadata (DX-033).
      */
-    compile(decision: Decision, ctx: CompilerContext, state: CompilerState, dispatch: WhereDispatcher): Node;
-}
-/**
- * Dispatcher for recursive WHERE compilation.
- */
-type WhereDispatcher = (decision: Decision, ctx: CompilerContext, state: CompilerState) => Node;
-/**
- * Handler for SELECT expressions.
- * Transforms expression decisions into PostgreSQL AST nodes.
- */
-interface ExpressionHandler {
-    /** Expression type(s) this handler supports */
-    readonly types: readonly string[];
+    compileWithIncludes<T = unknown>(plan: PlanReport, options?: CompileOptions): CompileResultWithIncludes<T>;
     /**
-     * Safe to use when a function name comes from NQL text.
+     * Compile a subquery include query for given parent IDs (DX-033).
+     * Generates: SELECT * FROM targetTable WHERE foreignKey IN ($1, $2, ...)
      *
-     * Raw/escape-hatch handlers must not set this. NQL-origin function names use
-     * this opt-in surface only, then fall back to generic FuncCall emission.
+     * @param info - Subquery include metadata
+     * @param parentIds - Parent record IDs to fetch related records for
+     * @param options - Compile options
+     * @returns Compiled query for fetching related records
      */
-    readonly nqlSafe?: boolean;
+    compileSubqueryInclude(info: SubqueryIncludeInfo, parentIds: readonly unknown[], options?: CompileOptions): CompiledQuery;
     /**
-     * Compile an expression to AST.
-     * @param decision The expression decision
-     * @param ctx Immutable compiler context
-     * @param state Mutable compiler state
-     * @returns PostgreSQL AST node for the expression
+     * Compile a FROM-less SELECT expression to SQL.
+     *
+     * Produces: SELECT <expr>
+     * Example: SELECT nextval('my_seq')
+     *
+     * @param expr - ExpressionIntent to evaluate
+     * @returns Compiled SQL and parameters
      */
-    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
-}
-/**
- * Handler for include/relation strategies.
- * Transforms include decisions into PostgreSQL constructs (JOIN, LATERAL, json_agg, CTE).
- */
-interface IncludeHandler {
-    /** Strategy this handler implements */
-    readonly strategy: 'join' | 'lateral' | 'json_agg' | 'cte';
+    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
     /**
-     * Compile an include to AST.
-     * @param decision The include decision
-     * @param ctx Immutable compiler context
-     * @param state Mutable compiler state
-     * @returns Object with modifications to apply
+     * Compile an insert intent to executable SQL.
+     *
+     * Strategy switch (per CompileOptions):
+     * - rows <= batchThreshold (default 50): VALUES ($1,$2),($3,$4),...
+     * - rows > batchThreshold OR batchThreshold === 0: SELECT unnest($1::type[]),...
      */
-    compile(decision: Decision, ctx: CompilerContext, state: CompilerState): IncludeResult;
-}
-/**
- * Result of include compilation.
- */
-interface IncludeResult {
-    /** Additional target list items (SELECT columns) */
-    targets?: Node[];
-    /** JOIN to add to FROM clause */
-    join?: Node;
-    /** Additional JOINs for cascaded includes (e.g., flat deep nesting) */
-    additionalJoins?: Node[];
-    /** CTE to add to WITH clause */
-    cte?: Node;
-    /** Subquery for LATERAL */
-    lateral?: Node;
-}
-
-/**
- * PostgreSQL Schema Introspection (ADAPTER-006)
- *
- * Queries information_schema/pg_catalog to build ModelIR
- * from an existing database. Supports:
- * - Table/column/PK discovery
- * - FK → bidirectional relation inference
- * - Hierarchy detection (adjacency + edge-table)
- * - Include/exclude filtering
- *
- * @module introspection
- */
-
-/** Options for database introspection */
-interface IntrospectionOptions {
-    /** Tables to exclude (glob patterns: * matches any chars) */
-    readonly exclude?: readonly string[];
-    /** Tables to include (default: all). Applied before exclude. */
-    readonly include?: readonly string[];
-    /** Schema name to introspect (default: 'public') */
-    readonly schema?: string;
-}
-/** Hierarchy pattern detected during introspection */
-/**
- * Hierarchy pattern detected during introspection.
- * Alias of {@link HierarchyIR} from \@dbsp/types — kept here for
- * public-API backwards compatibility (re-exported from \@dbsp/adapter-pgsql).
- */
-type DetectedHierarchy = HierarchyIR;
-/** Extended ModelIR with hierarchy metadata */
-interface IntrospectedModelIR extends ModelIR {
-    readonly hierarchies: readonly DetectedHierarchy[];
-    readonly introspectedAt: Date;
-    readonly warnings: readonly string[];
-}
-declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
-
-/**
- * Mutation Compiler
- *
- * Compiles INSERT, UPDATE, and DELETE statements from plan decisions.
- * Supports:
- * - INSERT with values/from subquery
- * - INSERT with RETURNING
- * - UPDATE with SET and WHERE
- * - DELETE with WHERE
- * - RETURNING clause for all mutations
- */
-
-/**
- * Configuration for INSERT compilation
- */
-interface InsertConfig {
-    /** Table to insert into */
-    table: string;
-    /** Columns to insert */
-    columns: string[];
-    /** Values for each column (array of rows) */
-    values: unknown[][];
-    /** Columns to return (RETURNING clause) */
-    returning?: string[];
-    /** Alias-aware RETURNING projection items */
-    returningItems?: readonly MutationReturningItem[];
-    /** Subquery for INSERT ... SELECT */
-    selectQuery?: Node;
-    /** Column database types for type-cast emission (e.g. range types) */
-    columnTypes?: Record<string, string>;
-}
-/**
- * Configuration for UPDATE compilation
- */
-interface UpdateConfig {
-    /** Table to update */
-    table: string;
-    /** Column-value pairs to set */
-    set: {
-        column: string;
-        value: unknown;
-    }[];
-    /** WHERE conditions */
-    where?: Decision[];
-    /** Columns to return (RETURNING clause) */
-    returning?: string[];
-    /** Alias-aware RETURNING projection items */
-    returningItems?: readonly MutationReturningItem[];
-    /** Column database types for type-cast emission (e.g. range types) */
-    columnTypes?: Record<string, string>;
-}
-/**
- * Configuration for DELETE compilation
- */
-interface DeleteConfig {
-    /** Table to delete from */
-    table: string;
-    /** WHERE conditions */
-    where?: Decision[];
-    /** Columns to return (RETURNING clause) */
-    returning?: string[];
-    /** Alias-aware RETURNING projection items */
-    returningItems?: readonly MutationReturningItem[];
-}
-/**
- * Compile an INSERT statement from configuration.
- */
-declare function compileInsert(config: InsertConfig, ctx: CompilerContext, state: CompilerState): Node;
-/**
- * Compile an UPDATE statement from configuration.
- */
-declare function compileUpdate(config: UpdateConfig, ctx: CompilerContext, state: CompilerState): Node;
-declare function compileDelete(config: DeleteConfig, ctx: CompilerContext, state: CompilerState): Node;
-/**
- * Compile a mutation decision to AST.
- * Determines mutation type from decision.type and delegates.
- */
-declare function compileMutation(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
-
-/**
- * Upsert (INSERT ... ON CONFLICT) Compiler
- *
- * Compiles UPSERT statements with ON CONFLICT handling.
- * Supports:
- * - ON CONFLICT DO NOTHING
- * - ON CONFLICT DO UPDATE SET ...
- * - Conflict target (columns or constraint name)
- * - WHERE clause for conflict resolution
- */
-
-/**
- * Conflict resolution strategy
- */
-type ConflictAction = 'nothing' | 'update';
-/**
- * Conflict target specification
- */
-interface ConflictTarget {
-    /** Column names that form the unique constraint */
-    columns?: string[];
-    /** Named constraint */
-    constraint?: string;
-    /** WHERE clause for partial index */
-    where?: Decision[];
-}
-/**
- * Configuration for UPSERT compilation
- */
-interface UpsertConfig {
-    /** Table to upsert into */
-    table: string;
-    /** Columns to insert */
-    columns: string[];
-    /** Values for each column (array of rows) */
-    values: unknown[][];
-    /** Conflict target (unique columns or constraint) */
-    conflictTarget: ConflictTarget;
-    /** What to do on conflict */
-    conflictAction: ConflictAction;
-    /** Columns to update on conflict (for 'update' action) */
-    updateColumns?: string[];
-    /** Optional WHERE clause for ON CONFLICT DO UPDATE */
-    actionWhere?: Decision[];
-    /** Optional direct WHERE intent for ON CONFLICT DO UPDATE */
-    actionWhereIntent?: WhereIntent;
-    /** Compile the direct action WHERE intent using the caller's WHERE compiler */
-    compileActionWhere?: (where: WhereIntent, state: CompilerState) => Node;
-    /** Use EXCLUDED.column for update values (default: true) */
-    useExcluded?: boolean;
-    /** Columns to return (RETURNING clause) */
-    returning?: string[];
-    /** Alias-aware RETURNING projection items */
-    returningItems?: readonly MutationReturningItem[];
-    /** Optional column type hints for unnest casting (schema-driven) */
-    columnTypes?: Record<string, string>;
+    compileInsert(intent: InsertIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Raw SQL expressions for specific update columns.
-     * These are injected verbatim into the ON CONFLICT DO UPDATE SET clause.
-     * Keys are logical column names (before naming plugin), values are raw SQL fragments.
-     *
-     * @warning SECURITY: fragments are inserted without parameterization.
-     *   Only use with hardcoded expressions. Never with user input.
-     *
-     * @example { last_parsed: 'now()', count: 'excluded.count + 1' }
+     * Compile an insert-from intent to executable SQL (NQL-ALIGN).
+     * INSERT INTO target (cols) SELECT cols FROM source WHERE ... LIMIT ... RETURNING ...
      */
-    updateExpressions?: Record<string, string>;
-}
-/**
- * Build ON CONFLICT clause for INSERT statement.
- */
-declare function buildOnConflictClause(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): OnConflictClause;
-/**
- * Compile a complete UPSERT statement.
- */
-declare function compileUpsert(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): Node;
-/**
- * Build EXCLUDED.column reference.
- * EXCLUDED is a special table alias in ON CONFLICT ... DO UPDATE
- * that refers to the row that would have been inserted.
- */
-declare function excludedRef(column: string, naming: {
-    toDatabase: (s: string) => string;
-}): Node;
-/**
- * Build conditional update using COALESCE.
- *
- * Produces: COALESCE(EXCLUDED.col, table.col)
- * This keeps existing value if new value is NULL.
- */
-declare function conditionalUpdate(column: string, table: string, ctx: CompilerContext): Node;
-
-/**
- * @module naming
- * Utilities for resolving database names to logical model names.
- *
- * The ModelIR.getTable() method expects logical (camelCase) names,
- * but the adapter often works with database (snake_case) names.
- * This module bridges that gap.
- */
-
-/**
- * Resolve a database table name to the corresponding logical model name.
- *
- * Converts the DB name using the naming convention, then looks it up in the model.
- * Falls back to exact match if conversion doesn't find a match.
- *
- * @param model - The model IR to search in
- * @param dbName - Database table name (e.g. "post_comments")
- * @param convention - Naming convention used by the adapter
- * @returns The logical table name if found, undefined otherwise
- *
- * @example
- * ```typescript
- * // With camelCase convention:
- * resolveLogicalName(model, "post_comments", "camelCase") // → "postComments"
- * resolveLogicalName(model, "posts", "camelCase")         // → "posts"
- * resolveLogicalName(model, "unknown", "camelCase")       // → undefined
- * ```
- */
-declare function resolveLogicalName(model: ModelIR, dbName: string, casing: DbCasing): string | undefined;
-
-/**
- * ParamRef validation and helpers for PostgreSQL AST
- *
- * ParamRef nodes represent parameterized query placeholders ($1, $2, etc.)
- * This module provides validation and creation helpers for safe AST construction.
- */
-
-/**
- * Validation result for ParamRef nodes
- */
-interface ParamRefValidationResult {
-    valid: boolean;
-    errors: string[];
-}
-/**
- * Validates a ParamRef node
- *
- * Rules:
- * - `number` must be a positive integer (1-based indexing)
- * - `number` must not exceed reasonable bounds (e.g., 65535)
- */
-declare function validateParamRef(paramRef: ParamRef): ParamRefValidationResult;
-/**
- * Creates a validated ParamRef node
- * @throws Error if validation fails
- */
-declare function createParamRef(number: number, location?: number): Node;
-/**
- * Creates a TypeCast node wrapping a ParamRef
- * Example: $1::integer, $2::text[]
- */
-declare function createTypeCastParamRef(paramNumber: number, typeName: string, isArray?: boolean, location?: number): Node;
-/**
- * Creates an A_Expr node for equality comparison with ParamRef
- * Example: col = $1
- */
-declare function createEqualityExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
-/**
- * Creates a FuncCall node for ANY() with ParamRef
- * Example: col = ANY($1) for array parameter matching
- */
-declare function createAnyExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
-/**
- * Collects all ParamRef nodes from an AST, validating each
- * Returns validation results for all found ParamRefs
- */
-declare function collectAndValidateParamRefs(node: unknown): {
-    paramRefs: Array<{
-        paramRef: ParamRef;
-        path: string;
-    }>;
-    validationResults: ParamRefValidationResult[];
-    allValid: boolean;
-};
-
-/**
- * PgsqlAdapter - Implements the Adapter interface for PostgreSQL using native pg driver.
- *
- * This adapter wraps a pg Pool instance and provides the unified
- * adapter interface for the db-semantic-planner ORM.
- *
- * @module pgsql-adapter
- */
-
-/**
- * Options for PgsqlAdapter.
- */
-interface PgsqlAdapterOptions {
-    /** Schema name for multi-tenant queries */
-    readonly schemaName?: string;
+    compileInsertFrom(intent: InsertFromIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * DB column casing convention (intuitive semantics).
-     * - `'snake_case'`: DB columns are snake_case → transform to camelCase for JS
-     * - `'camelCase'`: DB columns are camelCase → no transformation
-     * - `'preserve'`: No transformation
+     * Compile an update intent to executable SQL.
      */
-    readonly dbCasing?: DbCasing;
-    /** Optional model for WHERE compilation */
-    readonly model?: ModelIR;
-    /** Optional logger for debug/error messages */
-    readonly logger?: AdapterLogger;
-    /** Default primary key column name for convention fallbacks (default: 'id') */
-    readonly defaultPkColumnName?: string;
-    /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
-    readonly deriveFkColumnName?: FkColumnDerivation;
-}
-/**
- * Adapter implementation for PostgreSQL using native pg driver.
- *
- * @typeParam DB - Database schema type
- *
- * @example
- * ```typescript
- * import { Pool } from 'pg';
- * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
- *
- * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const adapter = createPgsqlAdapter(pool);
- * const orm = createOrm({ model, adapter });
- * ```
- */
-declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
-    private readonly pool;
-    private readonly client;
-    private readonly schemaName;
-    private readonly _dbCasing;
-    private readonly naming;
-    private readonly model;
-    private readonly logger;
-    private readonly _capabilities;
-    private readonly defaultPk;
-    private readonly deriveFk;
+    compileUpdate(intent: UpdateIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Create a new PgsqlAdapter.
+     * Compile a batch update intent to executable SQL using unnest FROM strategy (BATCH-001).
      *
-     * @param pool - pg.Pool instance, PoolClient (transactions), or undefined (compile-only mode)
-     * @param options - Optional configuration
-     */
-    constructor(pool?: Pool | PoolClient | undefined, options?: PgsqlAdapterOptions);
-    /**
-     * Shared compilation dependencies — built lazily from adapter fields.
-     * Passed to compiler sub-modules instead of `this`.
+     * Generates:
+     *   UPDATE "table" SET "update_col" = t."update_col" [, "scalar_col" = $N]
+     *   FROM unnest(CAST($1 AS type[]), CAST($2 AS type[])) AS t("match_col", "update_col")
+     *   WHERE "table"."match_col" = t."match_col"
+     *   [RETURNING ...]
      */
+    compileBatchUpdate(intent: BatchUpdateIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Return a new PgsqlAdapterOptions that merges current config with overrides.
-     * Ensures that all configuration fields (logger, defaultPkColumnName,
-     * deriveFkColumnName, etc.) are propagated to scoped/transactional adapters.
+     * Compile a delete intent to executable SQL.
      */
-    private cloneOptions;
-    private buildCompileDeps;
-    private requireNqlCompileModel;
-    private assertNqlBindingNamesDisjointFromTables;
-    private compileNqlMutation;
-    private compileNqlBundleLeaf;
-    private compileNqlBundle;
+    compileDelete(intent: DeleteIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Returns the pool/client executor, or throws if in compile-only mode.
+     * Compile an upsert intent to executable SQL (DX-026).
      */
-    private requireConnection;
-    /** Adapter capabilities for feature detection */
-    get capabilities(): AdapterCapabilities;
-    /** PostgreSQL dialect capabilities for planner strategy selection */
-    get dialectCapabilities(): DialectCapabilities;
+    compileUpsert(intent: UpsertIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * DB column casing convention used by this adapter.
+     * Compile an upsert-from intent to executable SQL (NQL-BIND).
+     * INSERT INTO target SELECT ... FROM source ON CONFLICT (cols) DO UPDATE SET ...
      */
-    get dbCasing(): DbCasing;
+    compileUpsertFrom(intent: UpsertFromIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Get the underlying pg Pool instance.
+     * Compile a recursive CTE plan to executable SQL.
+     * Supports adjacency-list and edge-table traversal modes.
      */
-    getPoolInstance(): Pool;
+    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
     /**
-     * Compile a plan to executable SQL.
+     * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
      *
-     * When passed a direct `CompiledNqlQuery`, the adapter trusts that the bundle
-     * has already been semantically validated by the NQL compiler. This method
-     * still performs adapter-owned SQL safety checks for emitted binding names
-     * before CTE emission.
+     * Strategy: compile CTE nodes to SQL fragments, compile outer query
+     * independently (parameters starting at $1), then renumber outer params
+     * to start after CTE params and prepend WITH clause.
      */
-    compile<T = unknown>(plan: PlanReport | CompiledNqlQuery, options?: CompileOptions): CompiledQuery<T>;
+    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
     /**
-     * Compile a plan with includes, returning subquery include metadata (DX-033).
+     * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
      */
-    compileWithIncludes<T = unknown>(plan: PlanReport, options?: CompileOptions): CompileResultWithIncludes<T>;
-    /**
-     * Compile a subquery include query for given parent IDs (DX-033).
-     * Generates: SELECT * FROM targetTable WHERE foreignKey IN ($1, $2, ...)
-     *
-     * @param info - Subquery include metadata
-     * @param parentIds - Parent record IDs to fetch related records for
-     * @param options - Compile options
-     * @returns Compiled query for fetching related records
-     */
-    compileSubqueryInclude(info: SubqueryIncludeInfo, parentIds: readonly unknown[], options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a FROM-less SELECT expression to SQL.
-     *
-     * Produces: SELECT <expr>
-     * Example: SELECT nextval('my_seq')
-     *
-     * @param expr - ExpressionIntent to evaluate
-     * @returns Compiled SQL and parameters
-     */
-    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
-    /**
-     * Compile an insert intent to executable SQL.
-     *
-     * Strategy switch (per CompileOptions):
-     * - rows <= batchThreshold (default 50): VALUES ($1,$2),($3,$4),...
-     * - rows > batchThreshold OR batchThreshold === 0: SELECT unnest($1::type[]),...
-     */
-    compileInsert(intent: InsertIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile an insert-from intent to executable SQL (NQL-ALIGN).
-     * INSERT INTO target (cols) SELECT cols FROM source WHERE ... LIMIT ... RETURNING ...
-     */
-    compileInsertFrom(intent: InsertFromIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile an update intent to executable SQL.
-     */
-    compileUpdate(intent: UpdateIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a batch update intent to executable SQL using unnest FROM strategy (BATCH-001).
-     *
-     * Generates:
-     *   UPDATE "table" SET "update_col" = t."update_col" [, "scalar_col" = $N]
-     *   FROM unnest(CAST($1 AS type[]), CAST($2 AS type[])) AS t("match_col", "update_col")
-     *   WHERE "table"."match_col" = t."match_col"
-     *   [RETURNING ...]
-     */
-    compileBatchUpdate(intent: BatchUpdateIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a delete intent to executable SQL.
-     */
-    compileDelete(intent: DeleteIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile an upsert intent to executable SQL (DX-026).
-     */
-    compileUpsert(intent: UpsertIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile an upsert-from intent to executable SQL (NQL-BIND).
-     * INSERT INTO target SELECT ... FROM source ON CONFLICT (cols) DO UPDATE SET ...
-     */
-    compileUpsertFrom(intent: UpsertFromIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a recursive CTE plan to executable SQL.
-     * Supports adjacency-list and edge-table traversal modes.
-     */
-    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
-     *
-     * Strategy: compile CTE nodes to SQL fragments, compile outer query
-     * independently (parameters starting at $1), then renumber outer params
-     * to start after CTE params and prepend WITH clause.
-     */
-    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
-    /**
-     * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
-     */
-    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
-    private compileSetOperationWithBindings;
+    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    private compileSetOperationWithBindings;
     /**
      * Create a dump for observability.
      */
@@ -1854,6 +1127,9 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Internal: Stream with an existing client using cursors.
      */
     private streamWithClient;
+    private streamWithManagedClient;
+    private streamWithManagedClientSavepointScope;
+    private streamWithClientTransaction;
     /**
      * Introspect the database schema and return a ModelIR.
      *
@@ -1870,8 +1146,83 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     introspect(options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
     /**
      * Execute a callback within a database transaction.
+     *
+     * ## What this guarantees
+     *
+     * The callback's work commits together or not at all; a statement issued inside
+     * the transaction never executes after its boundary, even if you forget to
+     * `await` it; a nested `transaction()` is a real savepoint; and the connection
+     * never goes back to the pool with a transaction still open on it.
+     *
+     * ## What it cannot guarantee, and you should know before you reach for raw SQL
+     *
+     * **Raw SQL that ends the transaction ends it.** `COMMIT`, `ROLLBACK` and
+     * `PREPARE TRANSACTION` issued through `executeRaw` — or through several commands
+     * in one call — reach PostgreSQL and take effect *before* dbsp is told what they
+     * were: the command tag arrives after the statement has run. dbsp detects it, kills
+     * the scope so nothing else escapes, and throws — but **it cannot un-run what your
+     * statement already did**, and `transaction()` rejecting does not mean nothing was
+     * committed.
+     *
+     * The same holds for session state raw SQL creates: a sequence that advanced stays
+     * advanced, an advisory lock stays held, a `PREPARE` or a `SET` you issued survives
+     * on a pooled connection. dbsp cleans up only what dbsp created.
+     *
+     * This is the contract of an escape hatch, not an oversight — see #327. If you need
+     * transaction control, own the transaction: take a client, `BEGIN` on it yourself,
+     * and hand dbsp a `borrowedClient` **without** `managedTransactions`. dbsp will then
+     * contain its own statements inside *your* transaction instead of the other way round.
      */
     transaction<T>(fn: (adapter: Adapter<DB>) => Promise<T>): Promise<T>;
+    /**
+     * Execute scratch PostgreSQL work in a scope that always rolls back on success.
+     *
+     * This is intentionally PostgreSQL-adapter-specific. It is used for catalog
+     * shaped scratch DDL such as CHECK expression canonicalisation, where the
+     * caller needs PostgreSQL's rendering but must not keep the scratch objects.
+     * Rollback here is cleanup of dbsp-created work, not a sandbox for arbitrary
+     * session effects.
+     */
+    withScratchScope<T>(fn: (adapter: PgsqlAdapter<DB>) => Promise<T>): Promise<T>;
+    private createManagedClientAdapter;
+    private createChildTransactionObserver;
+    private observeChildTransaction;
+    private markChildTransactionObserved;
+    private refreshScopeChildrenFailure;
+    private transactionWithManagedClient;
+    private transactionWithManagedClientSavepointScope;
+    private transactionWithClientTransaction;
+    private releaseClient;
+    private rollbackAndReleaseSavepoint;
+    private rollbackSavepoint;
+    private releaseSavepoint;
+    private rollbackTransactionIfOpen;
+    private classifyTransactionStateError;
+    private probeTransactionState;
+    private classifySavepointReleaseFailure;
+    private rollbackSavepointAfterReleaseFailure;
+    private enterTransactionScope;
+    private enterSavepointScope;
+    private pushClientScope;
+    private currentClientScope;
+    private assertCanUseClient;
+    private assertUsableScopeAncestors;
+    private findClientScope;
+    private assertScopeNotPoisoned;
+    private throwIfScopePoisoned;
+    private scopePoisonOutranksError;
+    private poisonScopeState;
+    private poisonClientScope;
+    private poisonClientScopeStack;
+    private runWithScopeStatementLock;
+    private closeScope;
+    private closeScopeAndAssertChildren;
+    private drainScopeStatements;
+    private drainScopeChildren;
+    private assertScopeChildrenSettled;
+    private drainScopeWork;
+    private executeScopeBoundaryStatement;
+    private assertCommitSucceeded;
     /**
      * Create a schema-scoped adapter for multi-tenant queries.
      */
@@ -1880,6 +1231,15 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Execute raw SQL directly.
      *
      * ⚠️  WARNING: Use parameter placeholders ($1, $2, etc.) for all values.
+     *
+     * Transaction control through raw SQL inside a scope dbsp is managing is
+     * unsupported. `COMMIT`, `ROLLBACK`, and `PREPARE TRANSACTION` end the
+     * transaction dbsp is working inside; dbsp detects that and fails loudly, but
+     * the data is already whatever your statement made it. Raw savepoint control
+     * (`SAVEPOINT`, `RELEASE SAVEPOINT`, `ROLLBACK TO SAVEPOINT`) can alter the
+     * savepoint stack before dbsp sees the command tag; dbsp poisons the scope, but
+     * it cannot make that command un-run. Manage your transaction outside dbsp's
+     * calls.
      */
     executeRaw<T = unknown>(sql: string, parameters?: readonly unknown[]): Promise<T[]>;
     /**
@@ -1901,17 +1261,35 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     executeDDL(sql: string): Promise<void>;
     /**
-     * Whether this adapter instance is scoped inside a transaction.
-     * Guards unsafe DDL operations (VACUUM, CREATE INDEX CONCURRENTLY).
+     * Whether a transaction is open on this adapter's connection.
+     * This is true for dbsp-managed scopes and for borrowed pg clients whose
+     * ReadyForQuery status says the caller has an open transaction.
      *
      * @since DDL-TABLE-001
      */
     get inTransaction(): boolean;
+    private adapterManagedScopeIsLive;
+    private executeQueryProtectingOpenTransaction;
+    private executeConnectionStatement;
+    private executeConnectionStatementUnlocked;
+    private executeConnectionStatementInSavepoint;
+    private issueConnectionQuery;
+    private assertNoMultiCommandRawCall;
+    private assertNoTransactionControlCommand;
+    private assertPrepareDidNotEndTransaction;
+    /**
+     * Resolve the explicit schema for a catalog read: an explicit argument, else
+     * the adapter's configured schema, else `undefined` (resolve in-query). NOT a
+     * hard-coded 'public' — an unresolved schema is handled by the SQL, which
+     * finds the table's schema search_path-aware, in the SAME session, so a
+     * non-public search_path and a pooled connection both stay correct.
+     */
+    private explicitSchema;
     /**
      * List all indexes on a table by querying pg_indexes.
      *
      * @param table - Table name
-     * @param schema - Schema name (defaults to adapter schema or 'public')
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
      */
     listIndexes(table: string, schema?: string, options?: {
         namePattern?: string;
@@ -1921,93 +1299,1047 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      *
      * @param name - Index name
      * @param table - Table name
-     * @param schema - Schema name (defaults to adapter schema or 'public')
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
      */
     indexExists(name: string, table: string, schema?: string): Promise<boolean>;
     /**
-     * Return the total storage size of a table in bytes.
+     * Return the total storage size of a table in bytes (includes indexes and TOAST).
+     *
+     * The table name is a SQL identifier — it is double-quoted, not parameterized,
+     * because PostgreSQL does not allow parameterized table names in FROM clauses.
+     * With no known schema the table is left unqualified so ::regclass resolves it
+     * through search_path (the same table an unqualified reference would hit).
      *
      * @param table - Table name
-     * @param schema - Schema name (defaults to adapter schema or 'public')
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
+     */
+    storageSize(table: string, schema?: string): Promise<number>;
+    /**
+     * Generate SQL for TRUNCATE TABLE.
+     * Implements TableDDLGeneratorAdapter.generateTruncate.
+     */
+    generateTruncate(table: string, schema?: string, options?: TruncateOptions): string;
+    /**
+     * Generate SQL for VACUUM.
+     * Implements TableDDLGeneratorAdapter.generateVacuum.
+     */
+    generateVacuum(table: string, schema?: string, options?: VacuumOptions): string;
+    /**
+     * Generate SQL for ALTER TABLE ... ALTER COLUMN.
+     * Implements TableDDLGeneratorAdapter.generateAlterColumn.
+     */
+    generateAlterColumn(table: string, column: string, options: AlterColumnOptions, schema?: string): string;
+    /**
+     * Generate SQL for CREATE INDEX.
+     * Implements TableDDLGeneratorAdapter.generateCreateIndex.
+     */
+    generateCreateIndex(table: string, options: CreateIndexOptions, schema?: string): string;
+    /**
+     * Generate SQL for DROP INDEX.
+     * Implements TableDDLGeneratorAdapter.generateDropIndex.
+     */
+    generateDropIndex(name: string, options?: DropIndexOptions): string;
+    /**
+     * Validate an identifier (table name, column name, schema name).
+     */
+    validateIdentifier(value: string, type: string): void;
+}
+/**
+ * Create a PgsqlAdapter from a pg Pool instance.
+ *
+ * @param pool - pg Pool instance
+ * @param options - Optional configuration
+ * @returns A new PgsqlAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPgsqlAdapter(pool);
+ *
+ * // With naming convention
+ * const adapter = createPgsqlAdapter(pool, { dbCasing: 'snake_case' });
+ * ```
+ */
+declare function createPgsqlAdapter<DB = unknown>(pool: Pool, options?: PgsqlPoolAdapterOptions): PgsqlAdapter<DB>;
+declare function createPgsqlAdapter<DB = unknown>(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions): PgsqlAdapter<DB>;
+/**
+ * Creates a compile-only PgsqlAdapter for SQL generation without a database connection.
+ *
+ * All compilation methods (compile, compileInsert, etc.), createDump(), and generateDDL()
+ * work normally. Execution methods (execute, stream, transaction, etc.) throw an error.
+ *
+ * @example
+ * ```typescript
+ * import { createPgsqlCompileOnlyAdapter } from '@dbsp/adapter-pgsql';
+ * import { createOrm } from '@dbsp/core';
+ *
+ * const adapter = createPgsqlCompileOnlyAdapter();
+ * const orm = createOrm({ model, adapter });
+ * const dump = await orm.select('users').dump();
+ * console.log(dump.sql);
+ * ```
+ */
+declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): CompileOnlyAdapter;
+
+/**
+ * Schema Comparison Engine (DDL-PROV Block 1)
+ *
+ * Compares two ModelIRs (schema definition vs database state)
+ * and produces a structured diff of changes needed.
+ *
+ * @module schema-diff
+ */
+
+type ChangeKind = 'create_table' | 'drop_table' | 'add_column' | 'drop_column' | 'alter_column_type' | 'alter_column_nullable' | 'alter_column_default' | 'alter_column_unique' | 'add_primary_key' | 'drop_primary_key' | 'add_foreign_key' | 'drop_foreign_key' | 'alter_foreign_key' | 'validate_constraint' | 'create_index' | 'drop_index' | 'add_check_constraint' | 'drop_check_constraint' | 'create_enum' | 'alter_enum_add_value' | 'drop_enum' | 'alter_column_collation' | 'alter_column_identity' | 'add_comment' | 'drop_comment' | 'create_extension' | 'drop_extension' | 'create_sequence' | 'alter_sequence' | 'drop_sequence' | 'enable_rls' | 'disable_rls' | 'create_policy' | 'drop_policy';
+interface SchemaChange {
+    readonly kind: ChangeKind;
+    readonly table: string;
+    readonly column?: string;
+    readonly destructive: boolean;
+    readonly details: string;
+    /** Additional metadata for SQL generation */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface DiffSummary {
+    readonly tables: {
+        readonly added: number;
+        readonly dropped: number;
+    };
+    readonly columns: {
+        readonly added: number;
+        readonly dropped: number;
+        readonly altered: number;
+    };
+    readonly indexes: {
+        readonly added: number;
+        readonly dropped: number;
+    };
+    readonly constraints: {
+        readonly added: number;
+        readonly dropped: number;
+        readonly altered: number;
+    };
+}
+interface SchemaDiff {
+    readonly changes: readonly SchemaChange[];
+    readonly hasDestructive: boolean;
+    readonly summary: DiffSummary;
+}
+interface CompareSchemataOptions {
+    /**
+     * Database naming convention.
+     * When set, schema model names (camelCase) are converted to DB format
+     * (e.g. snake_case) before comparison with the introspected model.
+     */
+    dbCasing?: DbCasing;
+    /** Dialect capabilities — comparisons for unsupported features will be skipped */
+    readonly dialectCapabilities?: DialectCapabilities;
+    /**
+     * When `true`, extensions present in the live DB but absent from the model
+     * schema are silently ignored — no `drop_extension` change is emitted for them.
+     * Only extensions explicitly declared in the model are managed (created if missing).
+     *
+     * Use this when the database image pre-installs extensions that the application
+     * schema does not own (e.g. pgvector, pg_search bundled in a custom Postgres image).
+     * Default: `false` (full-sync behaviour — unmanaged DB extensions produce a
+     * `drop_extension` entry).
+     */
+    readonly ignoreUnmanagedExtensions?: boolean;
+    /**
+     * Strict compile-only mode for callers that require convergence guarantees.
+     *
+     * `compareSchemata()` is intentionally pure and cannot ask PostgreSQL to
+     * canonicalise raw-SQL expression surfaces. By default it keeps the historic
+     * best-effort raw string comparison for CHECK expressions, partial-index
+     * predicates, and index expressions. Set this flag to throw when either model
+     * contains one of those surfaces so a caller cannot accidentally rely on a
+     * compile-only diff for a convergence-sensitive check.
+     *
+     * Live PostgreSQL callers should use `comparePgsqlDatabaseSchema()`, which
+     * canonicalises CHECK constraint expressions before calling this function.
+     * Partial-index predicates and index expressions are not canonicalised by the
+     * live helper and are rejected there when this strict flag is set.
+     */
+    readonly requireExpressionCanonicalization?: boolean;
+}
+declare class ExpressionCanonicalizationUnavailableError extends Error {
+    readonly surfaces: readonly string[];
+    constructor(surfaces: readonly string[]);
+}
+/**
+ * Compare two ModelIRs and produce a structured diff.
+ *
+ * @param schema - The desired schema (from definition)
+ * @param db - The current database state (from introspection)
+ * @param options - Optional comparison settings (e.g. dbCasing)
+ * @returns SchemaDiff with all changes needed to bring DB in sync with schema
+ */
+declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions): SchemaDiff;
+
+interface ComparePgsqlDatabaseSchemaOptions extends CompareSchemataOptions, SchemaScopeOptions {
+    /**
+     * Whether to canonicalise PostgreSQL CHECK constraint expressions before
+     * comparing. Defaults to `true`. Set to `false` only for compatibility with
+     * legacy raw-string live diffs.
+     *
+     * Live canonicalisation creates temporary scratch tables and missing desired
+     * enum types inside an adapter scratch scope whose successful cleanup is
+     * rollback. The database role needs permission to create temporary tables,
+     * and enum-dependent checks may need permission to create the pending enum
+     * type. If PostgreSQL refuses that scratch DDL, non-strict mode warns and
+     * falls back to best-effort raw string comparison for the affected CHECK
+     * constraints.
+     */
+    readonly canonicalizeExpressions?: boolean;
+    /**
+     * Receives live CHECK canonicalisation warnings. Defaults to console.warn.
      */
+    readonly onWarning?: (message: string) => void;
+    /**
+     * Diff that the caller just applied before this live re-diff. Used only when
+     * CHECK expressions are compared by raw text to fail loudly if the exact same
+     * expression-surface drift appears again after re-introspection.
+     */
+    readonly previouslyAppliedDiff?: SchemaDiff;
+}
+declare class NonConvergentSchemaDiffError extends Error {
+    readonly table: string;
+    readonly constraint: string;
+    readonly desiredExpression: string;
+    readonly databaseExpression: string;
+    constructor(table: string, constraint: string, desiredExpression: string, databaseExpression: string);
+}
+/** An enum value this diff adds, reported as a candidate cause — never asserted. */
+interface AddedEnumValue {
+    readonly enumName: string;
+    readonly value: string;
+}
+declare class CheckConstraintNewEnumValueError extends Error {
+    readonly table: string;
+    readonly constraint: string;
+    readonly addedEnumValues: readonly AddedEnumValue[];
+    constructor(table: string, constraint: string, addedEnumValues: readonly AddedEnumValue[]);
+}
+/**
+ * Live PostgreSQL schema diff: introspect, canonicalise desired CHECK
+ * constraint expressions through PostgreSQL, then call the pure synchronous
+ * schema comparator.
+ *
+ * If CHECK canonicalisation falls back while the same diff adds a plausibly
+ * referenced enum value, the diff is refused. dbsp currently applies each
+ * migration in one transaction, and PostgreSQL forbids using a newly added enum
+ * value in that same transaction; emitting the CHECK would produce a migration
+ * that cannot run. Apply the enum addition by itself first, then add or update
+ * the CHECK constraint in a later migration.
+ *
+ * Partial-index predicates and index expressions are intentionally not
+ * canonicalised here; non-strict diffs compare them by raw string, and strict
+ * diffs reject them.
+ */
+declare function comparePgsqlDatabaseSchema(adapter: PgsqlAdapter, desired: ModelIR, options?: ComparePgsqlDatabaseSchemaOptions): Promise<SchemaDiff>;
+declare function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff: SchemaDiff, currentDiff: SchemaDiff, rawCheckExpressionSurfaces?: ReadonlySet<string>): void;
+
+/**
+ * Migration SQL Generator (DDL-PROV Block 1)
+ *
+ * Generates ordered SQL statements from a SchemaDiff.
+ * Statements are topologically sorted: DROP constraints → DROP objects → CREATE objects → ADD constraints.
+ *
+ * @module migration-sql
+ */
+
+interface MigrationSQLOptions {
+    /**
+     * Schema namespace (default: none — unqualified).
+     * Required when emitted migration SQL would otherwise mix non-default
+     * target-scoped custom types/enums with unqualified table SQL.
+     */
+    readonly schemaName?: string;
+    /** Whether to include destructive changes (drops) */
+    readonly includeDestructive?: boolean;
+    /** Automatically create indexes on FK columns for new tables (default: true) */
+    readonly fkAutoIndex?: boolean;
+    /** Dialect capabilities — migration SQL for unsupported features will be filtered */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/**
+ * Generate ordered SQL statements from a SchemaDiff.
+ *
+ * Topological order:
+ * 0.  DROP FK/CHECK constraints (must drop before referenced tables)
+ * 1.  DROP indexes
+ * 2.  DROP columns
+ * 3.  DROP primary keys
+ * 4.  DROP tables, DROP ENUMs
+ * 5.  CREATE ENUMs (must exist before tables that use them)
+ * 6.  CREATE tables
+ * 7.  ADD columns
+ * 8.  ALTER columns (type, nullable, default)
+ * 9.  ADD primary keys / column UNIQUE constraints
+ * 10. ADD FK constraints (must add after referenced tables exist)
+ * 11. ALTER FK (drop + re-add)
+ * 12. CREATE indexes
+ * 13. ADD CHECK constraints
+ * 14. ALTER ENUM ADD VALUE (must be last — has transaction visibility caveats in PG)
+ * 15. COMMENT ON TABLE / COLUMN (very last)
+ */
+declare function generateMigrationSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+/**
+ * Generate ordered DOWN SQL statements from a SchemaDiff.
+ *
+ * Reverses the topological order used in UP migrations:
+ * phases run in descending order (11, 10, 9, ..., 0).
+ *
+ * Irreversible changes (drops that lose data) produce SQL WARNING comments.
+ */
+declare function generateDownSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+
+/**
+ * Migration File Format v2 — UP + DOWN sections.
+ *
+ * File format:
+ *   -- dbsp:destructive: true|false
+ *   <UP statements>;
+ *   -- DOWN
+ *   <DOWN statements>;
+ *
+ * The separator `-- DOWN` must be on its own line (SC-25).
+ *
+ * @module ddl/migration-file
+ */
+
+/**
+ * Result of parsing a migration file's UP/DOWN sections.
+ */
+interface ParsedMigrationFile {
+    readonly upStatements: readonly string[];
+    readonly downStatements: readonly string[];
+    readonly hasDown: boolean;
+    readonly destructive?: boolean | undefined;
+}
+/**
+ * Generate a migration file content with UP and DOWN sections.
+ */
+declare function generateMigrationFile(diff: SchemaDiff, options?: MigrationSQLOptions & {
+    name?: string;
+}): string;
+/**
+ * Parse a migration file into UP and DOWN sections.
+ * Separator: `^\s*-- DOWN\s*$` (strict regex, own line only — SC-25)
+ */
+declare function parseMigrationFile(content: string): ParsedMigrationFile;
+/**
+ * Check if SQL statements contain destructive operations.
+ * Destructive: DROP TABLE, DROP COLUMN, lossy ALTER COLUMN TYPE
+ */
+declare function isDestructiveDown(downStatements: readonly string[]): boolean;
+
+/**
+ * Migration Tracker — `_dbsp_migrations` table CRUD.
+ *
+ * Manages the tracking table that records which migrations
+ * have been applied to a database.
+ */
+
+interface MigrationRecord {
+    /** Migration filename (e.g., "0001_create_users.sql") */
+    readonly name: string;
+    /** SHA-256 checksum of the migration file content */
+    readonly checksum: string;
+    /** When the migration was applied */
+    readonly appliedAt: Date;
+    /** Schema version at time of this migration */
+    readonly schemaVersion: number;
+    /** Whether this migration contains destructive changes */
+    readonly destructive: boolean;
+}
+/**
+ * Execute a callback under an advisory lock using a dedicated client.
+ * The lock is held for the duration of the callback.
+ * The client is released (and lock freed) after the callback completes.
+ */
+declare function withMigrationLock<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
+/**
+ * Ensure the migrations tracking table exists.
+ * Auto-migrates existing tables that lack `schema_version`/`destructive` columns,
+ * and backfills `schema_version` by `applied_at` order for rows still at 0.
+ */
+declare function ensureMigrationsTable(pool: Pool): Promise<void>;
+/**
+ * Get all applied migrations, ordered by name.
+ */
+declare function getAppliedMigrations(pool: Pool): Promise<readonly MigrationRecord[]>;
+/**
+ * Record a migration as applied.
+ */
+declare function recordMigration(pool: Pool, name: string, checksum: string, schemaVersion: number, destructive: boolean): Promise<void>;
+/**
+ * Check if a specific migration has been applied.
+ */
+declare function isMigrationApplied(pool: Pool, name: string): Promise<boolean>;
+/**
+ * Get the next schema version number (max + 1, or 1 if no migrations).
+ */
+declare function getNextSchemaVersion(pool: Pool): Promise<number>;
+/**
+ * Remove a migration record (for rollback).
+ */
+declare function removeMigrationRecord(pool: Pool, name: string): Promise<void>;
+
+/**
+ * Type Mapping - Maps ModelIR ColumnType to PostgreSQL data types
+ *
+ * Supports both manual schemas and introspected schemas (preserving originalDbType).
+ * Handles auto-increment via SERIAL/BIGSERIAL types.
+ *
+ * @module ddl/type-mapping
+ */
+
+/**
+ * Map ColumnType to PostgreSQL data type string.
+ *
+ * Uses originalDbType if available (from introspection), otherwise
+ * falls back to reasonable PostgreSQL defaults.
+ *
+ * @param col - Column definition from ModelIR
+ * @returns PostgreSQL type string (e.g., 'VARCHAR(255)', 'SERIAL', 'JSONB')
+ */
+declare function mapColumnType(col: ColumnIR, targetSchema?: string): string;
+/**
+ * Map OnDeleteAction to PostgreSQL syntax.
+ */
+declare function mapOnDeleteAction(action?: string): string;
+
+/**
+ * EXPLAIN Statement Compiler
+ *
+ * Generates PostgreSQL EXPLAIN statements with various options.
+ * Supports:
+ * - ANALYZE (execute and show actual run times)
+ * - FORMAT (text, json, xml, yaml)
+ * - VERBOSE, COSTS, BUFFERS, TIMING, SETTINGS
+ */
+
+/**
+ * Output format for EXPLAIN results.
+ */
+type ExplainFormat = 'text' | 'json' | 'xml' | 'yaml';
+/**
+ * Options for EXPLAIN statement.
+ */
+interface ExplainOptions {
+    /** Execute the query and show actual run times */
+    analyze?: boolean;
+    /** Show more detailed output */
+    verbose?: boolean;
+    /** Show cost estimates (default: true) */
+    costs?: boolean;
+    /** Show buffer usage (requires analyze) */
+    buffers?: boolean;
+    /** Show actual timing (requires analyze) */
+    timing?: boolean;
+    /** Show non-default settings */
+    settings?: boolean;
+    /** Output format */
+    format?: ExplainFormat;
+}
+/**
+ * Build an EXPLAIN statement wrapping a query.
+ *
+ * @param query - The query to explain (SelectStmt, InsertStmt, etc.)
+ * @param options - EXPLAIN options
+ * @returns ExplainStmt AST node
+ *
+ * @example
+ * ```typescript
+ * const selectAst = { SelectStmt: { ... } };
+ * const explainAst = buildExplain(selectAst, { analyze: true, format: 'json' });
+ * // Produces: EXPLAIN (ANALYZE, FORMAT JSON) SELECT ...
+ * ```
+ */
+declare function buildExplain(query: Node, options?: ExplainOptions): Node;
+/**
+ * Build EXPLAIN ANALYZE with JSON format (common pattern).
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with ANALYZE and JSON format
+ */
+declare function buildExplainAnalyzeJson(query: Node): Node;
+/**
+ * Build simple EXPLAIN (plan only, no execution).
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with default options
+ */
+declare function buildExplainPlan(query: Node): Node;
+/**
+ * Build verbose EXPLAIN with costs and buffers.
+ *
+ * @param query - The query to explain
+ * @returns ExplainStmt with verbose options
+ */
+declare function buildExplainVerbose(query: Node): Node;
+/**
+ * Parse EXPLAIN JSON output to get execution statistics.
+ *
+ * @param jsonOutput - The JSON string from EXPLAIN (ANALYZE, FORMAT JSON)
+ * @returns Parsed plan with execution statistics
+ */
+declare function parseExplainJson(jsonOutput: string): ExplainPlan[];
+/**
+ * Parsed EXPLAIN plan structure (simplified).
+ */
+interface ExplainPlan {
+    Plan: {
+        'Node Type': string;
+        'Relation Name'?: string;
+        Alias?: string;
+        'Startup Cost'?: number;
+        'Total Cost'?: number;
+        'Plan Rows'?: number;
+        'Plan Width'?: number;
+        'Actual Startup Time'?: number;
+        'Actual Total Time'?: number;
+        'Actual Rows'?: number;
+        'Actual Loops'?: number;
+        Plans?: ExplainPlan['Plan'][];
+    };
+    'Planning Time'?: number;
+    'Execution Time'?: number;
+    Triggers?: unknown[];
+}
+/**
+ * Extract total execution time from EXPLAIN ANALYZE JSON output.
+ *
+ * @param plans - Parsed EXPLAIN plans
+ * @returns Total execution time in milliseconds
+ */
+declare function getTotalExecutionTime(plans: ExplainPlan[]): number;
+/**
+ * Extract row counts from EXPLAIN ANALYZE JSON output.
+ *
+ * @param plans - Parsed EXPLAIN plans
+ * @returns Object with estimated and actual row counts
+ */
+declare function getRowEstimates(plans: ExplainPlan[]): {
+    estimated: number;
+    actual: number;
+};
+
+interface CheckConstraintCanonicalizationWarning {
+    readonly table: string;
+    readonly constraint: string;
+    readonly message: string;
+    readonly cause: unknown;
+}
+interface CanonicalizeCheckConstraintsOptions {
+    /** Database schema that owns the target tables and target-scoped enum types. */
+    readonly schemaName?: string;
+    /** Naming convention used when matching desired table names to DB table names. */
+    readonly dbCasing?: DbCasing;
+    /** Called when PostgreSQL CHECK canonicalisation fails and raw comparison is used. */
+    readonly onWarning?: (warning: CheckConstraintCanonicalizationWarning) => void;
+    /** Throw instead of falling back to raw comparison when canonicalisation fails. */
+    readonly requireCanonicalization?: boolean;
+}
+type PgsqlCanonicalizationScope = Pick<Adapter, 'executeRaw' | 'transaction'>;
+declare class CheckConstraintCanonicalizationError extends Error {
+    readonly table: string;
+    readonly constraints: readonly string[];
+    readonly cause: unknown;
+    constructor(table: string, constraints: readonly string[], cause: unknown);
+}
+/**
+ * Canonicalise PostgreSQL CHECK constraint expressions in a desired model.
+ *
+ * CHECK constraints are canonicalised by creating a transaction-local temp table
+ * with the desired table's column definitions (borrowing live database type
+ * detail for existing columns when the desired model omits it), adding the
+ * authored CHECK constraints to that temp table, and reading PostgreSQL's
+ * `pg_get_constraintdef()` rendering. The caller must provide a rollback-only
+ * scratch scope; that rollback is cleanup for dbsp-created scratch objects, not
+ * a sandbox for arbitrary session effects.
+ * Missing desired enum types are also created inside that scratch scope before
+ * scratch tables.
+ * Scratch columns include only names and types; defaults, identity, uniqueness,
+ * nullability, and other table-shape clauses are deliberately omitted.
+ *
+ * The returned expression is the full `CHECK (...)` clause. Bare authored
+ * predicates are accepted and become full CHECK clauses.
+ *
+ * PostgreSQL does not allow an enum value added by `ALTER TYPE ... ADD VALUE`
+ * to be used in the same transaction that added it. Because dbsp currently
+ * emits and applies each migration in one transaction, the live diff layer
+ * deliberately refuses CHECK constraints that fall back while the same diff adds
+ * a plausibly referenced enum value. Splitting that into multiple transaction
+ * phases is a separate migration-runner feature.
+ *
+ * This does not canonicalise partial-index predicates or index expressions, so
+ * those surfaces may still compare by raw text in non-strict diffs.
+ */
+declare function canonicalizeCheckConstraints(adapter: PgsqlCanonicalizationScope, desired: ModelIR, dbModel: ModelIR, options?: CanonicalizeCheckConstraintsOptions): Promise<ModelIR>;
+
+/**
+ * ParadeDB Extension Wrappers
+ *
+ * Type-safe query builders for ParadeDB BM25 full-text search.
+ * All functions return ExpressionRef instances that can be used in:
+ * - SELECT: .column(score('id').as('score'))
+ * - WHERE:  .where(bm25Search('symbols', query, { name: 3.0, doc: 1.0 }))
+ * - ORDER BY: .orderBy(score('id'), 'desc')
+ *
+ * @remarks
+ * ParadeDB functions accept both named and positional arguments.
+ * This module uses named args via namedArg() for parse(), which produces:
+ *   paradedb.parse(field => 'field_name', query_string => $1)
+ * Named parameter syntax is supported via the NamedArgExpressionIntent (EXT-NAMED-PARAMS).
+ */
+
+/**
+ * BM25 relevance score for a row.
+ *
+ * Use in SELECT and ORDER BY to retrieve and sort by full-text relevance.
+ * Requires a BM25 index on the table.
+ *
+ * @param keyField - The key field of the BM25 index (typically the primary key, e.g. 'id')
+ * @returns ExpressionRef that compiles to: paradedb.score("keyField")
+ *
+ * @example
+ * orm.select('symbols').column(score('id').as('score')).orderBy(score('id'), 'desc')
+ * // → paradedb.score("id") AS "score"
+ */
+declare function score(keyField: string): ExpressionRef;
+/**
+ * Parse a single-field BM25 query expression.
+ *
+ * Compiles to: paradedb.parse(field => 'field_name', query_string => $N)
+ *
+ * @param field - Column name to search in (must be indexed in the BM25 index)
+ * @param query - Query string value (will be bound as a parameter)
+ * @returns ExpressionRef for use with boost() or booleanSearch()
+ *
+ * @example
+ * parse('name', 'hello world')
+ * // → paradedb.parse(field => 'name', query_string => $1)
+ */
+declare function parse(field: string, query: ExpressionRef | unknown): ExpressionRef;
+/**
+ * Apply a boost multiplier to a BM25 sub-expression.
+ *
+ * Compiles to: paradedb.boost(factor, expr)
+ *
+ * @param factor - Boost multiplier (e.g. 3.0 for 3x weight)
+ * @param expr - Expression to boost (typically a parse() call)
+ * @returns ExpressionRef for use with booleanSearch()
+ *
+ * @example
+ * boost(3.0, parse('name', 'hello'))
+ * // → paradedb.boost(3.0, paradedb.parse('name', $1))
+ */
+declare function boost(factor: number, expr: ExpressionRef): ExpressionRef;
+/**
+ * Combine multiple BM25 sub-expressions with boolean OR logic.
+ *
+ * Compiles to: paradedb.boolean(expr1, expr2, ...)
+ *
+ * @param exprs - One or more sub-expressions (typically boost() calls)
+ * @returns ExpressionRef for use on the right side of the @@@ operator
+ *
+ * @example
+ * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
+ * // → paradedb.boolean(paradedb.boost(3.0, ...), paradedb.boost(1.0, ...))
+ */
+/**
+ * Combine multiple BM25 sub-expressions with boolean OR logic.
+ *
+ * Compiles to: paradedb.boolean(should => ARRAY[expr1, expr2, ...])
+ *
+ * @param exprs - One or more sub-expressions (typically boost() calls)
+ * @returns ExpressionRef for use on the right side of the @@@ operator
+ *
+ * @example
+ * booleanSearch([boost(3.0, parse('name', q)), boost(1.0, parse('doc', q))])
+ * // → paradedb.boolean(should => ARRAY[paradedb.boost(3.0, ...), paradedb.boost(1.0, ...)])
+ */
+declare function booleanSearch(exprs: ExpressionRef[]): ExpressionRef;
+/**
+ * Full BM25 multi-field search with per-field boost weights.
+ *
+ * Produces: table @@@ paradedb.boolean(boost1, boost2, ...)
+ *
+ * Each field in `fieldBoosts` generates a `paradedb.boost(weight, paradedb.parse(field, $N))`
+ * sub-expression. The same query string is used for all fields (single parameter binding).
+ *
+ * @param table - Table alias for the left side of the @@@ operator
+ * @param query - Query string (bound as a single $N parameter, shared across all fields)
+ * @param fieldBoosts - Map of column name → boost weight
+ * @returns ExpressionRef for use in .where()
+ *
+ * @example
+ * bm25Search('s', searchTerm, {
+ *   name_searchable: 3.0,
+ *   name: 1.0,
+ *   signature: 1.5,
+ *   doc_searchable: 1.0,
+ * })
+ * // → s @@@ paradedb.boolean(
+ * //     paradedb.boost(3.0, paradedb.parse('name_searchable', $1)),
+ * //     paradedb.boost(1.0, paradedb.parse('name', $1)),
+ * //     paradedb.boost(1.5, paradedb.parse('signature', $1)),
+ * //     paradedb.boost(1.0, paradedb.parse('doc_searchable', $1))
+ * //   )
+ *
+ * @remarks
+ * The query parameter is shared: all parse() calls reference the same $N slot.
+ * If you need different query strings per field, compose parse()/boost()/booleanSearch() manually.
+ *
+ * @remarks
+ * ParadeDB's boolean() function accepts both positional args and the named
+ * `should => ARRAY[...]` syntax. This wrapper uses positional args.
+ * Named parameter syntax is deferred to EXT-NAMED-PARAMS.
+ */
+declare function bm25Search(table: string, query: unknown, fieldBoosts: Record<string, number>): ExpressionRef;
+
+/**
+ * PostgreSQL built-in function helpers.
+ *
+ * Thin wrappers around core expression primitives for common PostgreSQL functions.
+ * Same pattern as pgvector.ts and paradedb.ts.
+ */
+
+/**
+ * Generate a series of values: generate_series(start, stop[, step])
+ *
+ * Returns a set of values from start to stop (inclusive), with an optional step.
+ * Commonly used with CTE for batch operations.
+ *
+ * @example generateSeries(1, 100) → generate_series(1, 100)
+ * @example generateSeries(0, 50, 5) → generate_series(0, 50, 5)
+ */
+declare function generateSeries(start: number, stop: number, step?: number): ExpressionRef;
+/**
+ * Get next value from a sequence: nextval('sequence_name')
+ *
+ * @example nextval('order_id_seq') → nextval('order_id_seq')
+ */
+declare function nextval(sequenceName: string): ExpressionRef;
+
+/**
+ * pgvector Extension Wrappers
+ *
+ * Type-safe query builders for pgvector distance operators.
+ * All functions return ExpressionRef instances that can be used in:
+ * - SELECT: .column(cosineDistance('vector', qv).as('score'))
+ * - WHERE:  .where(cosineDistance('vector', qv).gte(0.5))
+ * - ORDER BY: .orderBy(rawDistance('vector', qv), 'asc')
+ */
+
+/**
+ * Cosine similarity: 1 - (col <=> vector)
+ *
+ * Score in [0, 1], higher = more similar.
+ * Use in SELECT to get a similarity score.
+ *
+ * @example
+ * orm.select('embeddings').column(cosineDistance('vector', qv).as('score'))
+ */
+declare function cosineDistance(column: string, vector: number[]): ExpressionRef;
+/**
+ * Raw cosine distance: col <=> vector
+ *
+ * Lower = closer. Index-friendly — use in ORDER BY for ANN search.
+ * Do NOT use in SELECT as a similarity score (lower = closer is counterintuitive).
+ *
+ * @example
+ * orm.select('embeddings').orderBy(rawDistance('vector', qv), 'asc')
+ */
+declare function rawDistance(column: string, vector: number[]): ExpressionRef;
+/**
+ * L2 (Euclidean) distance: col <-> vector
+ *
+ * @example
+ * orm.select('embeddings').orderBy(l2Distance('vector', qv), 'asc')
+ */
+declare function l2Distance(column: string, vector: number[]): ExpressionRef;
+/**
+ * Inner product distance: col <#> vector (negative inner product)
+ *
+ * For maximum inner product search: ORDER BY innerProduct('vector', qv) ASC.
+ *
+ * @example
+ * orm.select('embeddings').orderBy(innerProduct('vector', qv), 'asc')
+ */
+declare function innerProduct(column: string, vector: number[]): ExpressionRef;
+/**
+ * Get the number of dimensions of a vector column: vector_dims(col)
+ *
+ * Returns an integer — the dimension count of the stored vector.
+ * Useful for sanity-checking that embeddings match the expected model dimension.
+ *
+ * @example
+ * orm.from(embeddings).columns([vectorDims('vector').as('dim')]).first()
+ * // → SELECT vector_dims("t0"."vector") AS "dim" FROM "embeddings" AS "t0"
+ */
+declare function vectorDims(column: string): ExpressionRef;
+
+/**
+ * Mutation Compiler
+ *
+ * Compiles INSERT, UPDATE, and DELETE statements from plan decisions.
+ * Supports:
+ * - INSERT with values/from subquery
+ * - INSERT with RETURNING
+ * - UPDATE with SET and WHERE
+ * - DELETE with WHERE
+ * - RETURNING clause for all mutations
+ */
+
+/**
+ * Configuration for INSERT compilation
+ */
+interface InsertConfig {
+    /** Table to insert into */
+    table: string;
+    /** Columns to insert */
+    columns: string[];
+    /** Values for each column (array of rows) */
+    values: unknown[][];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Alias-aware RETURNING projection items */
+    returningItems?: readonly MutationReturningItem[];
+    /** Subquery for INSERT ... SELECT */
+    selectQuery?: Node;
+    /** Column database types for type-cast emission (e.g. range types) */
+    columnTypes?: Record<string, string>;
+}
+/**
+ * Configuration for UPDATE compilation
+ */
+interface UpdateConfig {
+    /** Table to update */
+    table: string;
+    /** Column-value pairs to set */
+    set: {
+        column: string;
+        value: unknown;
+    }[];
+    /** WHERE conditions */
+    where?: Decision[];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Alias-aware RETURNING projection items */
+    returningItems?: readonly MutationReturningItem[];
+    /** Column database types for type-cast emission (e.g. range types) */
+    columnTypes?: Record<string, string>;
+}
+/**
+ * Configuration for DELETE compilation
+ */
+interface DeleteConfig {
+    /** Table to delete from */
+    table: string;
+    /** WHERE conditions */
+    where?: Decision[];
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Alias-aware RETURNING projection items */
+    returningItems?: readonly MutationReturningItem[];
+}
+/**
+ * Compile an INSERT statement from configuration.
+ */
+declare function compileInsert(config: InsertConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Compile an UPDATE statement from configuration.
+ */
+declare function compileUpdate(config: UpdateConfig, ctx: CompilerContext, state: CompilerState): Node;
+declare function compileDelete(config: DeleteConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Compile a mutation decision to AST.
+ * Determines mutation type from decision.type and delegates.
+ */
+declare function compileMutation(decision: Decision, ctx: CompilerContext, state: CompilerState): Node;
+
+/**
+ * Upsert (INSERT ... ON CONFLICT) Compiler
+ *
+ * Compiles UPSERT statements with ON CONFLICT handling.
+ * Supports:
+ * - ON CONFLICT DO NOTHING
+ * - ON CONFLICT DO UPDATE SET ...
+ * - Conflict target (columns or constraint name)
+ * - WHERE clause for conflict resolution
+ */
+
+/**
+ * Conflict resolution strategy
+ */
+type ConflictAction = 'nothing' | 'update';
+/**
+ * Conflict target specification
+ */
+interface ConflictTarget {
+    /** Column names that form the unique constraint */
+    columns?: string[];
+    /** Named constraint */
+    constraint?: string;
+    /** WHERE clause for partial index */
+    where?: Decision[];
+}
+/**
+ * Configuration for UPSERT compilation
+ */
+interface UpsertConfig {
+    /** Table to upsert into */
+    table: string;
+    /** Columns to insert */
+    columns: string[];
+    /** Values for each column (array of rows) */
+    values: unknown[][];
+    /** Conflict target (unique columns or constraint) */
+    conflictTarget: ConflictTarget;
+    /** What to do on conflict */
+    conflictAction: ConflictAction;
+    /** Columns to update on conflict (for 'update' action) */
+    updateColumns?: string[];
+    /** Optional WHERE clause for ON CONFLICT DO UPDATE */
+    actionWhere?: Decision[];
+    /** Optional direct WHERE intent for ON CONFLICT DO UPDATE */
+    actionWhereIntent?: WhereIntent;
+    /** Compile the direct action WHERE intent using the caller's WHERE compiler */
+    compileActionWhere?: (where: WhereIntent, state: CompilerState) => Node;
+    /** Use EXCLUDED.column for update values (default: true) */
+    useExcluded?: boolean;
+    /** Columns to return (RETURNING clause) */
+    returning?: string[];
+    /** Alias-aware RETURNING projection items */
+    returningItems?: readonly MutationReturningItem[];
+    /** Optional column type hints for unnest casting (schema-driven) */
+    columnTypes?: Record<string, string>;
     /**
-     * Return the total storage size of a table in bytes (includes indexes and TOAST).
+     * Raw SQL expressions for specific update columns.
+     * These are injected verbatim into the ON CONFLICT DO UPDATE SET clause.
+     * Keys are logical column names (before naming plugin), values are raw SQL fragments.
      *
-     * The table name is a SQL identifier — it is double-quoted, not parameterized,
-     * because PostgreSQL does not allow parameterized table names in FROM clauses.
+     * @warning SECURITY: fragments are inserted without parameterization.
+     *   Only use with hardcoded expressions. Never with user input.
      *
-     * @param table - Table name
-     * @param schema - Schema name (defaults to adapter schema or 'public')
-     */
-    storageSize(table: string, schema?: string): Promise<number>;
-    /**
-     * Generate SQL for TRUNCATE TABLE.
-     * Implements TableDDLGeneratorAdapter.generateTruncate.
-     */
-    generateTruncate(table: string, schema?: string, options?: TruncateOptions): string;
-    /**
-     * Generate SQL for VACUUM.
-     * Implements TableDDLGeneratorAdapter.generateVacuum.
-     */
-    generateVacuum(table: string, schema?: string, options?: VacuumOptions): string;
-    /**
-     * Generate SQL for ALTER TABLE ... ALTER COLUMN.
-     * Implements TableDDLGeneratorAdapter.generateAlterColumn.
-     */
-    generateAlterColumn(table: string, column: string, options: AlterColumnOptions, schema?: string): string;
-    /**
-     * Generate SQL for CREATE INDEX.
-     * Implements TableDDLGeneratorAdapter.generateCreateIndex.
-     */
-    generateCreateIndex(table: string, options: CreateIndexOptions, schema?: string): string;
-    /**
-     * Generate SQL for DROP INDEX.
-     * Implements TableDDLGeneratorAdapter.generateDropIndex.
-     */
-    generateDropIndex(name: string, options?: DropIndexOptions): string;
-    /**
-     * Validate an identifier (table name, column name, schema name).
+     * @example { last_parsed: 'now()', count: 'excluded.count + 1' }
      */
-    validateIdentifier(value: string, type: string): void;
+    updateExpressions?: Record<string, string>;
 }
 /**
- * Create a PgsqlAdapter from a pg Pool instance.
- *
- * @param pool - pg Pool instance
- * @param options - Optional configuration
- * @returns A new PgsqlAdapter instance
- *
- * @example
- * ```typescript
- * import { Pool } from 'pg';
- * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
+ * Build ON CONFLICT clause for INSERT statement.
+ */
+declare function buildOnConflictClause(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): OnConflictClause;
+/**
+ * Compile a complete UPSERT statement.
+ */
+declare function compileUpsert(config: UpsertConfig, ctx: CompilerContext, state: CompilerState): Node;
+/**
+ * Build EXCLUDED.column reference.
+ * EXCLUDED is a special table alias in ON CONFLICT ... DO UPDATE
+ * that refers to the row that would have been inserted.
+ */
+declare function excludedRef(column: string, naming: {
+    toDatabase: (s: string) => string;
+}): Node;
+/**
+ * Build conditional update using COALESCE.
  *
- * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
- * const adapter = createPgsqlAdapter(pool);
+ * Produces: COALESCE(EXCLUDED.col, table.col)
+ * This keeps existing value if new value is NULL.
+ */
+declare function conditionalUpdate(column: string, table: string, ctx: CompilerContext): Node;
+
+/**
+ * @module naming
+ * Utilities for resolving database names to logical model names.
  *
- * // With naming convention
- * const adapter = createPgsqlAdapter(pool, { dbCasing: 'snake_case' });
- * ```
+ * The ModelIR.getTable() method expects logical (camelCase) names,
+ * but the adapter often works with database (snake_case) names.
+ * This module bridges that gap.
  */
-declare function createPgsqlAdapter<DB = unknown>(pool: Pool, options?: PgsqlAdapterOptions): PgsqlAdapter<DB>;
+
 /**
- * Creates a compile-only PgsqlAdapter for SQL generation without a database connection.
+ * Resolve a database table name to the corresponding logical model name.
  *
- * All compilation methods (compile, compileInsert, etc.), createDump(), and generateDDL()
- * work normally. Execution methods (execute, stream, transaction, etc.) throw an error.
+ * Converts the DB name using the naming convention, then looks it up in the model.
+ * Falls back to exact match if conversion doesn't find a match.
+ *
+ * @param model - The model IR to search in
+ * @param dbName - Database table name (e.g. "post_comments")
+ * @param convention - Naming convention used by the adapter
+ * @returns The logical table name if found, undefined otherwise
  *
  * @example
  * ```typescript
- * import { createPgsqlCompileOnlyAdapter } from '@dbsp/adapter-pgsql';
- * import { createOrm } from '@dbsp/core';
- *
- * const adapter = createPgsqlCompileOnlyAdapter();
- * const orm = createOrm({ model, adapter });
- * const dump = await orm.select('users').dump();
- * console.log(dump.sql);
+ * // With camelCase convention:
+ * resolveLogicalName(model, "post_comments", "camelCase") // → "postComments"
+ * resolveLogicalName(model, "posts", "camelCase")         // → "posts"
+ * resolveLogicalName(model, "unknown", "camelCase")       // → undefined
  * ```
  */
-declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): CompileOnlyAdapter;
+declare function resolveLogicalName(model: ModelIR, dbName: string, casing: DbCasing): string | undefined;
+
+/**
+ * ParamRef validation and helpers for PostgreSQL AST
+ *
+ * ParamRef nodes represent parameterized query placeholders ($1, $2, etc.)
+ * This module provides validation and creation helpers for safe AST construction.
+ */
+
+/**
+ * Validation result for ParamRef nodes
+ */
+interface ParamRefValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates a ParamRef node
+ *
+ * Rules:
+ * - `number` must be a positive integer (1-based indexing)
+ * - `number` must not exceed reasonable bounds (e.g., 65535)
+ */
+declare function validateParamRef(paramRef: ParamRef): ParamRefValidationResult;
+/**
+ * Creates a validated ParamRef node
+ * @throws Error if validation fails
+ */
+declare function createParamRef(number: number, location?: number): Node;
+/**
+ * Creates a TypeCast node wrapping a ParamRef
+ * Example: $1::integer, $2::text[]
+ */
+declare function createTypeCastParamRef(paramNumber: number, typeName: string, isArray?: boolean, location?: number): Node;
+/**
+ * Creates an A_Expr node for equality comparison with ParamRef
+ * Example: col = $1
+ */
+declare function createEqualityExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
+/**
+ * Creates a FuncCall node for ANY() with ParamRef
+ * Example: col = ANY($1) for array parameter matching
+ */
+declare function createAnyExpr(columnName: string, paramNumber: number, tableName?: string, location?: number): Node;
+/**
+ * Collects all ParamRef nodes from an AST, validating each
+ * Returns validation results for all found ParamRefs
+ */
+declare function collectAndValidateParamRefs(node: unknown): {
+    paramRefs: Array<{
+        paramRef: ParamRef;
+        path: string;
+    }>;
+    validationResults: ParamRefValidationResult[];
+    allValid: boolean;
+};
 
 /**
  * Redact sensitive values in a query dump's `params` array before logging.
@@ -2319,5 +2651,15 @@ declare function validateIdentifiers(identifiers: Record<string, 'table' | 'colu
  * NOT for use in SQL - use validateIdentifier + AST helpers for that.
  */
 declare function sanitizeForDisplay(value: string): string;
+/**
+ * Validate a raw SQL expression used in DDL contexts (defaults, policy USING/CHECK).
+ * Rejects injection vectors: semicolons, line-comment markers, block-comment markers.
+ *
+ * @security Called before any ModelIR-sourced string is interpolated into DDL.
+ * @param sql The raw SQL expression string to validate.
+ * @param context Human-readable context label for the error message.
+ * @throws Error if the expression contains forbidden characters.
+ */
+declare function validateSqlExpression(sql: string, context: string): void;
 
-export { type BatchValuesJoinDecision, CamelCaseNamingPlugin, type ChangeKind, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, type ExplainFormat, type ExplainOptions, type ExplainPlan, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, type LeafCompileFn, type MigrationRecord, type MigrationSQLOptions, type NamingPlugin, type ParamRefValidationResult, type ParsedMigrationFile, PgsqlAdapter, type PgsqlAdapterOptions, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type SchemaChange, type SchemaDiff, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquireMigrationLock, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, collectAndValidateParamRefs, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAnyExpr, createEqualityExpr, createLeafCompileFn, createParamRef, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createTypeCastParamRef, defaultFkDerivation, ensureMigrationsTable, excludedRef, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, parse, parseExplainJson, parseMigrationFile, rawDistance, recordMigration, redactParams, releaseMigrationLock, removeMigrationRecord, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, vectorDims, withMigrationLock };
+export { type AddedEnumValue, type BatchValuesJoinDecision, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, type ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, type LeafCompileFn, type MigrationRecord, type MigrationSQLOptions, type NamingPlugin, NonConvergentSchemaDiffError, type ParamRefValidationResult, type ParsedMigrationFile, PgsqlAdapter, type PgsqlAdapterOptions, type PgsqlBorrowedClientAdapterOptions, type PgsqlPoolAdapterOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, assertNoRepeatedExpressionSurfaceDrift, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAnyExpr, createEqualityExpr, createLeafCompileFn, createParamRef, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createTypeCastParamRef, defaultFkDerivation, ensureMigrationsTable, excludedRef, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, parse, parseExplainJson, parseMigrationFile, rawDistance, recordMigration, redactParams, removeMigrationRecord, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };