@dbsp/adapter-pgsql 2.0.0 → 3.1.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { ExpressionRef, IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ModelIR as ModelIR$1 } from '@dbsp/core';
+import * as _dbsp_core from '@dbsp/core';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, ExecutionCoordinator, CapabilityDescriptor } from '@dbsp/core';
 export { normalizeSQL } from '@dbsp/core';
 import * as _dbsp_types 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 { 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, OutputDescriptor, QueryIntent, OperationKindRef, SemanticArtifactRef, TransitionRunJournal, ObservationIssuer, ObservationContext, TypeRef, ExpressionValue, CollationRef, LogicalIdentity, PhysicalOperation, OperationEffectAssessment, EvidenceObservation, FingerprintManifest, DurableIntentRecord, IssuedObservation, ApplyGuard, AdvisoryObservation, TransactionalCompletionRecord, StepJournal, UnsafeNativeFragment, ResourceAddress, ExecutableAssertion, Assumption, TransitionRule, TransitionCompositionFact, TrustRoot, RequiredEnumLabelIR } from '@dbsp/types';
 import * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
 import { Pool, PoolClient } from 'pg';
@@ -727,6 +728,39 @@ declare class PlanCompiler {
  */
 declare function compilePlan(plan: SimplifiedPlanReport, options?: CompilerOptions): CompiledResult;
 
+type IndexRenderKey = {
+    readonly column?: string | undefined;
+    readonly expression?: string | undefined;
+    readonly opclass?: string | undefined;
+};
+type IndexRenderSpec = {
+    readonly name: string;
+    readonly table: string;
+    readonly schema?: string | undefined;
+    readonly unique: boolean;
+    readonly method?: string | undefined;
+    readonly keys: readonly IndexRenderKey[];
+    readonly include?: readonly string[] | undefined;
+    readonly nullsNotDistinct?: boolean | undefined;
+    readonly with?: Readonly<Record<string, unknown>> | undefined;
+    readonly where?: string | undefined;
+    readonly concurrently?: boolean | undefined;
+    readonly ifNotExists?: boolean | undefined;
+};
+type IndexCapabilityContext = {
+    readonly caps: DialectCapabilities;
+    readonly targetVersion?: string | undefined;
+};
+type IndexFeature = 'INCLUDE' | 'PARTIAL INDEX' | 'EXPRESSION INDEX' | 'INDEX METHOD' | 'OPCLASS' | 'NULLS NOT DISTINCT';
+declare class IndexFeatureUnsupportedError extends Error {
+    readonly indexName: string;
+    readonly unsupportedFeatures: readonly IndexFeature[];
+    constructor(indexName: string, unsupportedFeatures: readonly IndexFeature[], message: string);
+}
+declare function assertCreateIndexSupported(spec: IndexRenderSpec, ctx?: IndexCapabilityContext): void;
+declare function assertCreateIndexesSupported(specs: readonly IndexRenderSpec[], ctx?: IndexCapabilityContext): void;
+declare function renderCreateIndex(spec: IndexRenderSpec, ctx?: IndexCapabilityContext): string;
+
 /**
  * DDL Generator - Generates PostgreSQL DDL statements from ModelIR
  *
@@ -753,7 +787,7 @@ interface GenerateDDLOptions {
     readonly fkAutoIndex?: boolean;
     /** Naming plugin for identifier transformation */
     readonly naming?: NamingPlugin;
-    /** Dialect capabilities — DDL passes for unsupported features will be skipped */
+    /** Dialect capabilities — unsupported index features throw during DDL generation */
     readonly dialectCapabilities?: DialectCapabilities;
 }
 /**
@@ -769,7 +803,7 @@ 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;
+declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin, context?: IndexCapabilityContext): string;
 /**
  * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
  *
@@ -780,912 +814,168 @@ declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName
 declare function canGenerateCreateIndex(tableName: string, idx: IndexIR, schemaName?: string | undefined, naming?: NamingPlugin): boolean;
 
 /**
- * Schema Comparison Engine (DDL-PROV Block 1)
+ * PostgreSQL Schema Introspection (ADAPTER-006)
  *
- * Compares two ModelIRs (schema definition vs database state)
- * and produces a structured diff of changes needed.
+ * 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 schema-diff
+ * @module introspection
  */
 
-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;
+/** The minimum every schema-level operation needs: which schema. */
+interface SchemaScopeOptions {
+    /** Schema name to operate on (default: 'public') */
+    readonly schema?: 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
+ * 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 compareSchemata(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions): SchemaDiff;
-
+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 */
 /**
- * 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
+ * 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).
  */
-
-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;
+type DetectedHierarchy = HierarchyIR;
+/** Extended ModelIR with hierarchy metadata */
+interface IntrospectedModelIR extends ModelIR {
+    readonly hierarchies: readonly DetectedHierarchy[];
+    readonly introspectedAt: Date;
+    readonly warnings: readonly string[];
 }
 /**
- * Generate ordered SQL statements from a SchemaDiff.
+ * Introspect a database through a pool.
  *
- * 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.
+ * 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.
  *
- * Reverses the topological order used in UP migrations:
- * phases run in descending order (11, 10, 9, ..., 0).
+ * 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.
  *
- * Irreversible changes (drops that lose data) produce SQL WARNING comments.
+ * So: hold a client, use `new PgsqlAdapter(client, { borrowedClient: true })`
+ * and call `.introspect()` on it.
  */
-declare function generateDownSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
+declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
 
 /**
- * Migration File Format v2 — UP + DOWN sections.
- *
- * File format:
- *   -- dbsp:destructive: true|false
- *   <UP statements>;
- *   -- DOWN
- *   <DOWN statements>;
+ * PgsqlAdapter - Implements the Adapter interface for PostgreSQL using native pg driver.
  *
- * The separator `-- DOWN` must be on its own line (SC-25).
+ * This adapter wraps a pg Pool instance and provides the unified
+ * adapter interface for the db-semantic-planner ORM.
  *
- * @module ddl/migration-file
+ * @module pgsql-adapter
  */
 
-/**
- * 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;
+declare class PgsqlRawSqlTransactionControlError extends Error {
+    readonly dbspRawSqlTransactionControl = true;
+    constructor(cause: unknown);
 }
-/**
- * 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;
+declare class PgsqlTransactionAbortedCommitError extends Error {
+    readonly dbspTransactionAbortedCommit = true;
+    constructor(cause: unknown);
+}
+declare class PgsqlTransactionAbortedError extends Error {
+    readonly dbspTransactionAborted = true;
+    constructor(cause: unknown);
 }
 /**
- * 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.
+ * Options for PgsqlAdapter.
  */
-declare function getAppliedMigrations(pool: Pool): Promise<readonly MigrationRecord[]>;
+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;
+}
 /**
- * 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;
-};
-
-/**
- * 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;
-
-/**
- * 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>;
-    /**
-     * 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' }
-     */
-    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;
-    /**
-     * 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;
-}
-/**
- * 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 });
- * ```
+ * 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 borrowedClient;
+    private readonly managedTransactions;
+    private readonly adapterManagedTransaction;
+    private readonly scopeToken;
+    private readonly scopeState;
     private readonly schemaName;
     private readonly _dbCasing;
     private readonly naming;
@@ -1697,10 +987,19 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     /**
      * Create a new PgsqlAdapter.
      *
-     * @param pool - pg.Pool instance, PoolClient (transactions), or undefined (compile-only mode)
-     * @param options - Optional configuration
+     * 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
      */
-    constructor(pool?: Pool | PoolClient | undefined, options?: PgsqlAdapterOptions);
+    constructor(pool?: Pool | undefined, options?: PgsqlPoolAdapterOptions);
+    constructor(pool: Pool, options?: PgsqlPoolAdapterOptions);
+    constructor(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions);
+    constructor(pool: undefined, options?: PgsqlAdapterOptions);
     /**
      * Shared compilation dependencies — built lazily from adapter fields.
      * Passed to compiler sub-modules instead of `this`.
@@ -1715,7 +1014,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private requireNqlCompileModel;
     private assertNqlBindingNamesDisjointFromTables;
     private compileNqlMutation;
-    private compileNqlBundleLeaf;
+    private compileNqlBundleLeafEnvelope;
     private compileNqlBundle;
     /**
      * Returns the pool/client executor, or throws if in compile-only mode.
@@ -1730,9 +1029,9 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     get dbCasing(): DbCasing;
     /**
-     * Get the underlying pg Pool instance.
+     * Get the underlying pg Pool or borrowed PoolClient instance.
      */
-    getPoolInstance(): Pool;
+    getPoolInstance(): Pool | PoolClient;
     /**
      * Compile a plan to executable SQL.
      *
@@ -1765,7 +1064,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * @param expr - ExpressionIntent to evaluate
      * @returns Compiled SQL and parameters
      */
-    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
+    compileSelectExpression<T = unknown>(expr: ExpressionIntent): CompiledQuery<T>;
     /**
      * Compile an insert intent to executable SQL.
      *
@@ -1810,7 +1109,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Compile a recursive CTE plan to executable SQL.
      * Supports adjacency-list and edge-table traversal modes.
      */
-    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    compileRecursive<T = unknown>(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
     /**
      * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
      *
@@ -1818,11 +1117,11 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * independently (parameters starting at $1), then renumber outer params
      * to start after CTE params and prepend WITH clause.
      */
-    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
+    compileCteQuery<T = unknown>(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery<T>;
     /**
      * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
      */
-    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    compileSetOperation<T = unknown>(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
     private compileSetOperationWithBindings;
     /**
      * Create a dump for observability.
@@ -1858,10 +1157,16 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * @returns AsyncIterableIterator that yields rows one by one
      */
     stream<T>(query: CompiledQuery<T>, options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+    /** Stream raw SQL directly using the same cursor machinery as stream(). */
+    streamRaw<T = unknown>(sql: string, parameters?: readonly unknown[], options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+    private streamCursor;
     /**
      * Internal: Stream with an existing client using cursors.
      */
     private streamWithClient;
+    private streamWithManagedClient;
+    private streamWithManagedClientSavepointScope;
+    private streamWithClientTransaction;
     /**
      * Introspect the database schema and return a ModelIR.
      *
@@ -1878,8 +1183,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.
      */
@@ -1888,6 +1268,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[]>;
     /**
@@ -1909,12 +1298,22 @@ 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
@@ -1978,48 +1377,1008 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     generateDropIndex(name: string, options?: DropIndexOptions): string;
     /**
-     * Validate an identifier (table name, column name, schema name).
+     * 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 — unsupported index features throw during migration SQL generation */
+    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>;
+    /**
+     * 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' }
      */
-    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;
+};
+
+declare function derivePostgresqlCapabilitiesForVersion(version: string): DialectCapabilities;
 
 /**
  * Redact sensitive values in a query dump's `params` array before logging.
@@ -2051,6 +2410,28 @@ declare const DEFAULT_REDACTION_PATTERNS: ReadonlyArray<RegExp>;
  */
 declare function redactParams(params: readonly unknown[], config: RedactionConfig): readonly unknown[];
 
+declare const projectionEnvelopeBrand: unique symbol;
+type ProjectionEnvelope<T = unknown> = {
+    readonly [projectionEnvelopeBrand]: true;
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+    readonly ast?: Node;
+    readonly projection: ProjectionState;
+    readonly hydrationPlan?: PlanReport;
+    readonly __resultType?: T;
+};
+type ProjectionState = {
+    readonly kind: 'known';
+    readonly outputs: ReadonlyMap<string, OutputProjection>;
+} | {
+    readonly kind: 'dropped';
+    readonly reason: ProjectionDropReason;
+    readonly hadConvertibleSource: boolean;
+};
+type OutputProjection = OutputDescriptor;
+
+type ProjectionDropReason = 'set-operation-positional-merge' | 'raw-recursive-cte-positional-merge' | 'unknown-raw-sql' | 'unsupported-source';
+
 /**
  * Set operation compiler (UNION / INTERSECT / EXCEPT)
  *
@@ -2059,37 +2440,33 @@ declare function redactParams(params: readonly unknown[], config: RedactionConfi
  */
 
 /**
- * Compiled SQL with positional parameters.
+ * Compiled set-operation SQL with positional parameters.
  */
-interface SetOperationResult {
-    readonly sql: string;
-    readonly parameters: readonly unknown[];
-}
+type SetOperationResult<T = unknown> = CompiledQuery<T>;
 /**
- * Function that compiles a single QueryIntent leaf to SQL + parameters.
+ * Function that compiles a single QueryIntent leaf to a projection envelope, or
+ * a compiled query that can be bridged into one.
  * Provided by the caller to decouple from adapter internals.
  */
-type LeafCompileFn = (query: QueryIntent) => {
-    sql: string;
-    parameters: readonly unknown[];
-};
+type LeafCompileResult = ProjectionEnvelope | CompiledQuery;
+type LeafCompileFn = (query: QueryIntent) => LeafCompileResult;
 /**
  * Recursively compile a SetOperationIntent to SQL with merged parameters.
  *
- * Each leaf QueryIntent is compiled via `compileFn`. When merging left and
- * right branches, the right side's `$N` placeholders are renumbered so they
- * don't collide with the left side's parameters.
+ * Each leaf QueryIntent is compiled via `compileFn` to a projection envelope.
+ * When merging left and right branches, the right side's `$N` placeholders are
+ * renumbered so they don't collide with the left side's parameters. The final
+ * set operation drops positional projection provenance through the envelope so
+ * `finalizeEnvelope` owns the set-operation `js` fail-loud behavior.
  *
  * @param intent - The set operation intent (recursive tree)
- * @param compileFn - Compiles a single QueryIntent to SQL + params
+ * @param compileFn - Compiles a single QueryIntent to an envelope-compatible result
  * @returns Combined SQL string and merged parameter array
  *
  * @example
  * ```typescript
- * const result = compileSetOperation(setOpIntent, (query) => {
- *   const planReport = plan(query, model, { dialectCapabilities });
- *   return adapter.compile(planReport, { model });
- * });
+ * const compileFn = createLeafCompileFn(adapter, model, plan);
+ * const result = compileSetOperation(setOpIntent, compileFn);
  * console.log(result.sql);        // (SELECT ...) UNION (SELECT ...)
  * console.log(result.parameters);  // [...leftParams, ...rightParams]
  * ```
@@ -2108,10 +2485,7 @@ declare function compileSetOperation(intent: SetOperationIntent, compileFn: Leaf
 declare function createLeafCompileFn(adapter: {
     compile(plan: PlanReport, options: CompileOptions & {
         model: ModelIR$1;
-    }): {
-        sql: string;
-        parameters: readonly unknown[];
-    };
+    }): CompiledQuery;
     dialectCapabilities: DialectCapabilities;
 }, model: ModelIR$1, planFn: (intent: QueryIntent, model: ModelIR$1, options: {
     dialectCapabilities: DialectCapabilities;
@@ -2273,6 +2647,550 @@ declare function buildStreamingStatements(query: Node, config?: StreamConfig): {
     close: Node;
 };
 
+declare const PG_OPERATION_PACK_ARTIFACT: SemanticArtifactRef;
+declare const PG_RULE_PACK_ARTIFACT: SemanticArtifactRef;
+declare const PG_INTROSPECTION_ARTIFACT: SemanticArtifactRef;
+declare const ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND: OperationKindRef;
+declare const ALTER_TYPE_ADD_VALUE_OPERATION_KIND: OperationKindRef;
+declare const ATTACH_LOGICAL_IDENTITY_OPERATION_KIND: OperationKindRef;
+declare const MANUAL_SQL_OPERATION_KIND: OperationKindRef;
+declare const SET_NOT_NULL_RULE_ID = "postgresql.column.set-not-null";
+declare const ADD_CHECK_RULE_ID = "postgresql.table.add-check";
+declare const ENUM_ADD_VALUE_RULE_ID = "postgresql.enum.add-value";
+declare const LOGICAL_IDENTITY_ADOPTION_RULE_ID = "postgresql.logical-identity.adopt";
+declare const DBSP_META_SCHEMA = "dbsp_meta";
+declare const DBSP_TRANSITION_RUN_TABLE = "dbsp_transition_run";
+declare const DBSP_TRANSITION_JOURNAL_TABLE = "dbsp_transition_journal";
+declare const DBSP_LOGICAL_IDENTITY_TABLE = "dbsp_logical_identity";
+declare const COLUMN_EXISTS_OBSERVATION = "postgresql.column.exists";
+declare const ENUM_TYPE_EXISTS_OBSERVATION = "postgresql.enum-type.exists";
+declare const ENUM_LABEL_VISIBLE_OBSERVATION = "postgresql.enum-label.visible";
+declare const ALTER_AUTHORITY_OBSERVATION = "postgresql.table.alter-authority";
+declare const ENGINE_VERSION_OBSERVATION = "postgresql.engine.version-supported";
+declare const LOGICAL_IDENTITY_CARRIER_OBSERVATION = "postgresql.logical-identity.carrier-state";
+declare const NO_NULLS_GUARD = "NO_NULLS";
+
+type QueryResultLike = {
+    readonly rows: readonly Record<string, unknown>[];
+};
+type TransitionJournalQueryable = {
+    query(sql: string, params?: readonly unknown[]): Promise<QueryResultLike>;
+};
+declare function renderCreateDbspMetaSchemaSql(): string;
+declare function renderCreateTransitionRunTableSql(): string;
+declare function renderCreateTransitionJournalTableSql(): string;
+declare function ensureTransitionJournal(executor: TransitionJournalQueryable): Promise<void>;
+declare function readTransitionJournal(executor: TransitionJournalQueryable, runId: string): Promise<TransitionRunJournal>;
+
+type ObservationTarget = {
+    readonly table: string;
+    readonly column?: string;
+    readonly constraint?: string;
+    readonly index?: string;
+    readonly schema?: string;
+};
+type EnumObservationTarget = {
+    readonly type: string;
+    readonly label?: string;
+    readonly schema?: string;
+};
+declare function createPgObservationIssuer(): ObservationIssuer;
+declare function readPgObservationContext(target: unknown, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget): Promise<ObservationContext>;
+
+interface SetNotNullColumnShapeExpectation {
+    readonly kind: 'postgresql.set-not-null.column-shape.v1';
+    readonly name: string;
+    readonly nullability: {
+        readonly from: true;
+        readonly to: boolean;
+    };
+    readonly type: TypeRef;
+    readonly default: ExpressionValue | null;
+    readonly collation: CollationRef;
+    readonly identity: 'always' | 'byDefault' | null;
+    readonly generated: string | null;
+    readonly autoIncrement: boolean;
+    readonly unique: boolean;
+    readonly uniqueConstraintName: string | null;
+    readonly logicalIdentity?: LogicalIdentity | null;
+    readonly comment: string | null;
+    readonly target?: ColumnDefaultAttestationTarget;
+}
+interface ColumnDefaultAttestationTarget {
+    readonly database?: string;
+    readonly schema?: string;
+    readonly table: string;
+    readonly column: string;
+}
+
+type AlterColumnSetNotNullPayload = {
+    readonly table: string;
+    readonly column: string;
+    readonly schema?: string;
+    readonly expectedColumnShape?: SetNotNullColumnShapeExpectation;
+};
+type TransitionExecutionClient$3 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAlterColumnSetNotNullSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function renderSetNotNullLockSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function renderNoNullsCheckSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function beforeAfterFingerprints$3(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAlterColumnSetNotNullOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$3;
+    checkout(target: unknown): Promise<TransitionExecutionClient$3>;
+    release(client: TransitionExecutionClient$3, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$3, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$3): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$3, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$3, operation: PhysicalOperation, _effects: OperationEffectAssessment, context: ObservationContext): Promise<void>;
+    observeContext(client: TransitionExecutionClient$3, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$3, operation: PhysicalOperation, context: ObservationContext, _phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(client: TransitionExecutionClient$3, operation: PhysicalOperation, guard: ApplyGuard, context: ObservationContext): Promise<{
+        passed: boolean;
+        observations: AdvisoryObservation[];
+        recovery: readonly _dbsp_types.RecoveryArtefact[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$3, operation: PhysicalOperation, context: ObservationContext, duringGuards?: readonly ApplyGuard[]): Promise<{
+        kind: string;
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$3, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$3): Promise<void>;
+    rollback(client: TransitionExecutionClient$3): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$3, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type AlterTypeAddValuePayload = {
+    readonly schema: string;
+    readonly type: string;
+    readonly label: string;
+    readonly after?: string;
+    readonly expectedBefore: readonly string[];
+    readonly expectedAfter: readonly string[];
+};
+type TransitionExecutionClient$2 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAlterTypeAddValueSql(payload: AlterTypeAddValuePayload, context: ObservationContext): string;
+declare function beforeAfterFingerprints$2(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAlterTypeAddValueOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    operationKind: _dbsp_types.OperationKindRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$2;
+    checkout(target: unknown): Promise<TransitionExecutionClient$2>;
+    release(client: TransitionExecutionClient$2, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$2, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$2): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$2, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$2, operation: PhysicalOperation): Promise<void>;
+    observeContext(client: TransitionExecutionClient$2, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$2, operation: PhysicalOperation, context: ObservationContext, _phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(client: TransitionExecutionClient$2, operation: PhysicalOperation, guard: ApplyGuard, context: ObservationContext): Promise<{
+        passed: boolean;
+        observations: EvidenceObservation[];
+        recovery: readonly _dbsp_types.RecoveryArtefact[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$2, operation: PhysicalOperation, context: ObservationContext, duringGuards?: readonly ApplyGuard[]): Promise<{
+        kind: string;
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$2, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$2): Promise<void>;
+    rollback(client: TransitionExecutionClient$2): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$2, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type AttachLogicalIdentityPayload = {
+    readonly schema: string;
+    readonly table: string;
+    readonly column?: string;
+    readonly logicalId: string;
+    readonly carrierKind: 'postgresql-side-table';
+    readonly authenticated: false;
+};
+type TransitionExecutionClient$1 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAttachLogicalIdentityLockSql(payload: AttachLogicalIdentityPayload): string;
+declare function renderCreateLogicalIdentitySideTableSql(_schema: string): string;
+declare function renderCreateLogicalIdentityIndexesSql(_schema: string): readonly string[];
+declare function renderInsertLogicalIdentitySql(_schema: string): string;
+declare function beforeAfterFingerprints$1(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAttachLogicalIdentityOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$1;
+    checkout(target: unknown): Promise<TransitionExecutionClient$1>;
+    release(client: TransitionExecutionClient$1, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$1, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$1): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$1, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$1, operation: PhysicalOperation): Promise<void>;
+    observeContext(client: TransitionExecutionClient$1, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$1, operation: PhysicalOperation, context: ObservationContext, phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(): Promise<{
+        passed: boolean;
+        observations: never[];
+        recovery: never[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$1, operation: PhysicalOperation): Promise<{
+        kind: "completed";
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$1, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$1): Promise<void>;
+    rollback(client: TransitionExecutionClient$1): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$1, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type ManualSqlPayload = {
+    readonly statement: UnsafeNativeFragment;
+    readonly blastRadius: readonly ResourceAddress[];
+    readonly preconditions: readonly ExecutableAssertion[];
+    readonly postconditions: readonly ExecutableAssertion[];
+};
+type TransitionExecutionClient = {
+    readonly opaqueClient: unknown;
+};
+declare function normalizeManualSqlPayload(payload: ManualSqlPayload, context: ObservationContext): ManualSqlPayload;
+declare function beforeAfterFingerprints(operation: PhysicalOperation, _evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createManualSqlOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    operationKind: _dbsp_types.OperationKindRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints;
+    checkout(target: unknown): Promise<TransitionExecutionClient>;
+    release(client: TransitionExecutionClient, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient): Promise<void>;
+    setLockTimeout(_client: TransitionExecutionClient, _maxWaitMs: number): Promise<void>;
+    acquireLocks(): Promise<void>;
+    observeContext(client: TransitionExecutionClient, _operation: PhysicalOperation, proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(_client: TransitionExecutionClient, operation: PhysicalOperation, context: ObservationContext, phase: "before" | "after"): Promise<{
+        observations: never[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(): Promise<{
+        passed: boolean;
+        observations: never[];
+        recovery: never[];
+    }>;
+    executeOperation(client: TransitionExecutionClient, operation: PhysicalOperation, context: ObservationContext): Promise<{
+        kind: "completed";
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient): Promise<void>;
+    rollback(client: TransitionExecutionClient): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+interface SetNotNullMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly column: string;
+    readonly expectedColumnShape: SetNotNullColumnShapeExpectation;
+    readonly assumptions?: readonly Assumption[];
+}
+interface SetNotNullRuleOptions {
+    readonly naming?: NamingPlugin;
+}
+declare function createSetNotNullRule(options?: SetNotNullRuleOptions): TransitionRule<SetNotNullMatch>;
+
+interface EnumAddValueMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly type: string;
+    readonly label: string;
+    readonly after?: string;
+    readonly expectedBefore: readonly string[];
+    readonly expectedAfter: readonly string[];
+    readonly assumptions?: readonly Assumption[];
+}
+interface EnumAddValueRuleOptions {
+    readonly naming?: NamingPlugin;
+}
+declare function satisfiesPgEnumLabelVisibleCompositionFact(fact: TransitionCompositionFact, current: ModelIR, _context: ObservationContext): boolean;
+declare function createEnumAddValueRule(options?: EnumAddValueRuleOptions): TransitionRule<EnumAddValueMatch>;
+
+interface CreateUniqueIndexConcurrentlyMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly index: string;
+    readonly columns: readonly string[];
+    readonly assumptions?: readonly Assumption[];
+}
+
+type IdentityAdoptionAsserter = Exclude<TrustRoot, {
+    readonly kind: 'pack';
+}>;
+interface LogicalIdentityAdoptionMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly column?: string;
+    readonly logicalId: string;
+    readonly carrierKind: 'postgresql-side-table';
+    readonly authenticated: false;
+    readonly selectionBasis: string;
+}
+interface LogicalIdentityAdoptionRuleOptions {
+    readonly naming?: NamingPlugin;
+    readonly asserter?: IdentityAdoptionAsserter;
+    readonly selectionBasis?: string;
+}
+declare function createLogicalIdentityAdoptionRule(options?: LogicalIdentityAdoptionRuleOptions): TransitionRule<LogicalIdentityAdoptionMatch>;
+
+interface AddCheckMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly constraint: string;
+    readonly expression: string;
+    readonly requiresEnumLabels?: readonly RequiredEnumLabelIR[];
+    readonly assumptions?: readonly Assumption[];
+}
+
+interface PgTransitionPackOptions {
+    readonly dbCasing?: DbCasing;
+    readonly naming?: NamingPlugin;
+    readonly identityAdoptionAsserter?: IdentityAdoptionAsserter;
+    readonly identityAdoptionSelectionBasis?: string;
+}
+declare function createPgTransitionPack(options?: PgTransitionPackOptions): {
+    rules: (_dbsp_types.TransitionRule<AddCheckMatch> | _dbsp_types.TransitionRule<LogicalIdentityAdoptionMatch> | _dbsp_types.TransitionRule<CreateUniqueIndexConcurrentlyMatch> | _dbsp_types.TransitionRule<EnumAddValueMatch> | _dbsp_types.TransitionRule<SetNotNullMatch>)[];
+    operationSemantics: ({
+        artifact: _dbsp_types.SemanticArtifactRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        setLockTimeout(client: {
+            readonly opaqueClient: unknown;
+        }, maxWaitMs: number): Promise<void>;
+        acquireLocks(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _effects: _dbsp_types.OperationEffectAssessment, context: _dbsp_types.ObservationContext): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
+            passed: boolean;
+            observations: _dbsp_types.AdvisoryObservation[];
+            recovery: readonly _dbsp_types.RecoveryArtefact[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
+            kind: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        setLockTimeout(client: {
+            readonly opaqueClient: unknown;
+        }, maxWaitMs: number): Promise<void>;
+        acquireLocks(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
+            passed: boolean;
+            observations: _dbsp_types.EvidenceObservation[];
+            recovery: readonly _dbsp_types.RecoveryArtefact[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
+            kind: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        setLockTimeout(_client: {
+            readonly opaqueClient: unknown;
+        }, _maxWaitMs: number): Promise<void>;
+        acquireLocks(): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(_client: {
+            readonly opaqueClient: unknown;
+        }, _operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard): Promise<never>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[], executionTracker?: _dbsp_core.NonRollbackableExecutionTracker): Promise<{
+            kind: "partially-applied";
+            recovery: _dbsp_types.RecoveryArtefact[];
+            detail: string;
+        } | {
+            kind: string;
+            guard?: never;
+            recovery?: never;
+            nonRollbackableFootprint?: never;
+        } | {
+            kind: string;
+            guard: _dbsp_types.ApplyGuard;
+            recovery: never[];
+            nonRollbackableFootprint: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        rollback(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    })[];
+    issuer: _dbsp_types.ObservationIssuer;
+    executionCoordinator: ExecutionCoordinator;
+    transactionDomain: string;
+    equivalence: _dbsp_types.EquivalenceCapability;
+    capabilityDescriptors: readonly CapabilityDescriptor[];
+    comparatorNameNormalizer: {
+        normalizeCurrentIdentifier: (identifier: string) => string;
+    };
+    compositionFactKinds: string[];
+    satisfiesCompositionFact: typeof satisfiesPgEnumLabelVisibleCompositionFact;
+};
+
 /**
  * Identifier Validation for adapter-pgsql
  *
@@ -2342,4 +3260,4 @@ declare function sanitizeForDisplay(value: string): string;
  */
 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, 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 };
+export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, 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, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, type PgsqlBorrowedClientAdapterOptions, type PgsqlPoolAdapterOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, SET_NOT_NULL_RULE_ID, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, assertCreateIndexSupported, assertCreateIndexesSupported, 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, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgObservationIssuer, createPgTransitionPack, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, ensureMigrationsTable, ensureTransitionJournal, 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, normalizeManualSqlPayload, parse, parseExplainJson, parseMigrationFile, rawDistance, readPgObservationContext, readTransitionJournal, recordMigration, redactParams, removeMigrationRecord, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateDbspMetaSchemaSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderCreateTransitionJournalTableSql, renderCreateTransitionRunTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderSetNotNullLockSql, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };