@dbsp/adapter-pgsql 1.11.2 → 2.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';
 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, 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 * 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,6 +769,15 @@ 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;
+/**
+ * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
+ *
+ * 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().
+ */
+declare function canGenerateCreateIndex(tableName: string, idx: IndexIR, schemaName?: string | undefined, naming?: NamingPlugin): boolean;
 
 /**
  * Schema Comparison Engine (DDL-PROV Block 1)
@@ -606,7 +864,11 @@ declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: Compare
  */
 
 interface MigrationSQLOptions {
-    /** Schema namespace (default: none — unqualified) */
+    /**
+     * 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;
@@ -706,19 +968,6 @@ interface MigrationRecord {
     /** Whether this migration contains destructive changes */
     readonly destructive: boolean;
 }
-/**
- * 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.
- */
-declare function acquireMigrationLock(pool: Pool): Promise<void>;
-/**
- * Release the session-level advisory lock for migration operations.
- *
- * @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.
@@ -770,7 +1019,7 @@ declare function removeMigrationRecord(pool: Pool, name: string): Promise<void>;
  * @param col - Column definition from ModelIR
  * @returns PostgreSQL type string (e.g., 'VARCHAR(255)', 'SERIAL', 'JSONB')
  */
-declare function mapColumnType(col: ColumnIR): string;
+declare function mapColumnType(col: ColumnIR, targetSchema?: string): string;
 /**
  * Map OnDeleteAction to PostgreSQL syntax.
  */
@@ -1095,247 +1344,6 @@ declare function innerProduct(column: string, vector: number[]): ExpressionRef;
  */
 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;
-    /**
-     * 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 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;
-}
-
 /**
  * PostgreSQL Schema Introspection (ADAPTER-006)
  *
@@ -1907,11 +1915,19 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * @since DDL-TABLE-001
      */
     get inTransaction(): boolean;
+    /**
+     * 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,23 +1937,19 @@ 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.
-     *
-     * @param table - Table name
-     * @param schema - Schema name (defaults to adapter schema or 'public')
-     */
     /**
      * 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>;
     /**
@@ -2319,5 +2331,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 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, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, collectAndValidateParamRefs, 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 };