@dbsp/adapter-pgsql 5.0.0 → 6.0.0

package/dist/outcome-protocol-Dw5DYhnA.d.ts

@@ -0,0 +1,2727 @@
+import * as _dbsp_types from '@dbsp/types';
+import { DialectCapabilities, IndexIR, ModelIR, DbCasing, NormalizedManagedStep, DeclarableResourceAddress, TableIR, CatalogueIdentity, SequenceIR, LedgerPayload, ResourceAddress, LedgerAddress, HierarchyIR, PhysicalNameInventory, Adapter, AdapterLogger, AdapterCapabilities, ConnectionAvailability, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, PinnedConnectionOptions, TransactionOptions, LedgerHome, DurableIntentRecord, TransitionRunAuthorization, TransitionRunJournal, ProvenPlanShape, LedgerReservationRow, LedgerIdentity, LedgerChainMember, LedgerMarkerState, DeclarationSet, ReinitializePreflightReport, OutcomeClaimPlan, DestructiveDecision, LedgerEventKind, OutcomeVacancy, OutcomeProtocolRefusal, ClaimBundleStatement, ControllerIdentity, AdmittedOutcomeClaim, ClaimToken, OutcomeIndeterminateRecoveryEvidence, OutcomeRecoveryEffect, OutcomeRecoveryClassification, ScopedApprovalSet, OutcomeRecoveryReadBack, OutcomeClaimAdmission } from '@dbsp/types';
+import { Pool, PoolClient } from 'pg';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, TransitionRunPersister, ValidatedManagedStepManifest } from '@dbsp/core';
+import { AdmittedDestructiveOutcomeClaim, DurablyLoadedRun } from '@dbsp/core/internal';
+
+/**
+ * Default primary key column name used as convention fallback
+ * when schema metadata doesn't provide an explicit PK.
+ *
+ * Consumers (handlers, compiler) must NOT use this directly —
+ * they use `requiredColumn()` to throw on missing data.
+ * Only convention mappers (extractors, introspection) should reference this.
+ */
+declare const DEFAULT_PK_COLUMN = "id";
+/**
+ * Derive a foreign key column name from a table name and the PK column it references.
+ *
+ * Convention: `${singularTableName}_${pkColumnName}`
+ * e.g. (authors, id) → author_id, (categories, id) → category_id
+ *
+ * Consumers should use `deriveFkColumnName` from CompilerContext or options
+ * for configurable behavior.
+ */
+type FkColumnDerivation = (tableName: string, pkColumnName: string) => string;
+declare const defaultFkDerivation: FkColumnDerivation;
+
+/**
+ * NamingPlugin - Identifier transformation between model and database naming conventions
+ *
+ * Inspired by Kysely's CamelCasePlugin architecture.
+ * The plugin transforms identifiers bidirectionally:
+ * - toDatabase: model name (camelCase) → database name (snake_case)
+ * - toModel: database name (snake_case) → model name (camelCase)
+ */
+/**
+ * Interface for naming convention transformation plugins
+ */
+interface NamingPlugin {
+    /**
+     * Transform a model identifier to database format
+     * Example: "createdAt" → "created_at"
+     */
+    toDatabase(identifier: string): string;
+    /**
+     * Transform a database identifier to model format
+     * Example: "created_at" → "createdAt"
+     */
+    toModel(identifier: string): string;
+}
+/**
+ * Identity plugin - no transformation
+ * Use this when model and database naming conventions match
+ */
+declare class IdentityNamingPlugin implements NamingPlugin {
+    toDatabase(identifier: string): string;
+    toModel(identifier: string): string;
+}
+/**
+ * CamelCase ↔ snake_case transformation plugin
+ *
+ * Follows the same logic as Kysely's CamelCasePlugin:
+ * - Handles consecutive uppercase letters (e.g., "parseJSON" → "parse_json")
+ * - Handles numbers (e.g., "field1Name" → "field1_name")
+ * - Preserves leading underscores
+ */
+declare class CamelCaseNamingPlugin implements NamingPlugin {
+    /**
+     * camelCase → snake_case
+     */
+    toDatabase(identifier: string): string;
+    /**
+     * snake_case → camelCase
+     */
+    toModel(identifier: string): string;
+}
+/**
+ * Singleton instances for convenience
+ */
+declare const identityNaming: IdentityNamingPlugin;
+declare const camelCaseNaming: CamelCaseNamingPlugin;
+/**
+ * Get a naming plugin by DbCasing (intuitive semantics).
+ * - `'snake_case'`: DB uses snake_case → CamelCaseNamingPlugin (transforms to camelCase)
+ * - `'camelCase'`: DB uses camelCase → IdentityNamingPlugin (no transform)
+ * - `'preserve'`: No transformation → IdentityNamingPlugin
+ */
+declare function getNamingPluginForDbCasing(casing: 'snake_case' | 'camelCase' | 'preserve'): NamingPlugin;
+
+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;
+    /** The in-process index value that owns a deparsed `where` predicate. */
+    readonly whereSource?: IndexIR | 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 class AutoIncrementTransitionUnsupportedError extends Error {
+    readonly table: string;
+    readonly column: string;
+    readonly direction: 'enable' | 'disable' | 'retype' | 'unknown';
+    constructor(table: string, column: string, direction: 'enable' | 'disable' | 'retype' | 'unknown');
+}
+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
+ *
+ * Generates SQL strings directly for better compatibility and control.
+ * Two-pass strategy handles circular FK dependencies.
+ *
+ * @module ddl/ddl-generator
+ */
+
+interface GenerateDDLOptions$1 {
+    /** Include DROP TABLE IF EXISTS statements before CREATE TABLE */
+    readonly includeDropStatements?: boolean;
+    /**
+     * Database schema name (e.g., 'public', 'tenant_123').
+     * Required when emitted DDL would otherwise mix non-default target-scoped
+     * custom types/enums with unqualified table SQL.
+     */
+    readonly schemaName?: string;
+    /**
+     * Automatically create indexes on foreign key columns.
+     * FK columns are frequently used in JOINs, so indexing is a best practice.
+     * @default true
+     */
+    readonly fkAutoIndex?: boolean;
+    /** Naming plugin for logical-model callers. Physical models omit this option. */
+    readonly naming?: NamingPlugin;
+    /** Dialect capabilities — unsupported index features throw during DDL generation */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/**
+ * Generate DDL statements from a ModelIR schema.
+ *
+ * Uses a two-pass approach to handle circular FK dependencies:
+ * 1. CREATE TABLE (without FK constraints)
+ * 2. ALTER TABLE ADD CONSTRAINT for foreign keys
+ * 3. CREATE INDEX (explicit + auto-generated for FKs)
+ *
+ * @param schema - The ModelIR schema to generate DDL from
+ * @param options - Optional configuration
+ * @returns Array of DDL statements in dependency order
+ */
+declare function generateDDL$1(schema: ModelIR, options?: GenerateDDLOptions$1): string[];
+declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, context?: IndexCapabilityContext, ifNotExists?: boolean): string;
+/**
+ * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
+ *
+ * Keep this as the single representability predicate for generated schema
+ * omission and destructive-drop classification: both sides must agree on the
+ * exact validation surface used by generateCreateIndex().
+ */
+declare function canGenerateCreateIndex(tableName: string, idx: IndexIR, schemaName?: string | undefined): boolean;
+
+/**
+ * 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' | 'readdress_table' | 'add_column' | 'drop_column' | 'alter_column_type' | 'alter_column_nullable' | 'alter_column_default' | 'alter_column_unique' | 'alter_column_auto_increment' | '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$1 {
+    /** Internal compatibility metadata; public physical-model comparison owns schema. */
+    readonly schema?: string;
+    /** Internal callers must already pass physical names; this value is ignored. */
+    dbCasing?: DbCasing;
+    /** Authored standalone-sequence names retained by the physical-model boundary. */
+    readonly declaredSequenceNames?: ReadonlyMap<string, string>;
+    /** 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 verbatim comparison for column defaults, 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, column defaults, and partial-index predicates before calling this function.
+     * Under that live mode, each side is canonicalised independently; rejected
+     * predicates refuse the migration and infrastructure fallback uses both raw
+     * models. This does not prove
+     * that the resulting migration is executable.
+     * 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[]);
+}
+type ReferencedKeyKind = 'unique_index' | 'primary_key' | 'column_unique';
+interface ReferencedKeyRemovalConflict {
+    readonly keyKind: ReferencedKeyKind;
+    readonly table: string;
+    readonly keyColumns: readonly string[];
+    readonly keyName?: string;
+    readonly referencingTable: string;
+    readonly foreignKeyColumns: readonly string[];
+}
+/**
+ * Refusal raised when executable UP SQL would remove a key a foreign key may
+ * depend on. Only foreign keys visible in the compared model are detected, so
+ * a single-schema comparison cannot see a foreign key whose source table is in
+ * another schema. A hand-built `SchemaDiff` without the comparison annotation
+ * is not covered.
+ */
+declare class ReferencedKeyRemovalError extends Error {
+    readonly conflicts: readonly ReferencedKeyRemovalConflict[];
+    constructor(conflicts: readonly ReferencedKeyRemovalConflict[]);
+}
+/**
+ * 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$1(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions$1): SchemaDiff;
+/** Collect comparison annotations from the changes an executable path selected. */
+declare function collectReferencedKeyRemovalConflicts(changes: readonly SchemaChange[]): readonly ReferencedKeyRemovalConflict[];
+
+type Address = DeclarableResourceAddress & {
+    readonly scope: 'schema' | 'database';
+};
+type GeneratedConstraintPostcondition = {
+    readonly type: 'p' | 'u';
+    readonly columns: readonly string[];
+    readonly deferrable: boolean;
+    readonly initiallyDeferred: boolean;
+    readonly enforced: boolean;
+} | {
+    readonly type: 'f';
+    readonly columns: readonly string[];
+    readonly references: {
+        readonly schema: string;
+        readonly table: string;
+        readonly columns: readonly string[];
+    };
+    readonly onDelete: GeneratedForeignKeyAction;
+    readonly onUpdate: GeneratedForeignKeyAction;
+    readonly deferrable: boolean;
+    readonly initiallyDeferred: boolean;
+    readonly enforced: boolean;
+    readonly notValid: boolean;
+} | {
+    readonly type: 'c';
+    /** The ModelIR CHECK expression, never a rendered constraint definition. */
+    readonly expression: string;
+    readonly notValid: boolean;
+};
+/** The semantic FK actions PostgreSQL can represent in pg_constraint. */
+type GeneratedForeignKeyAction = 'NO ACTION' | 'RESTRICT' | 'CASCADE' | 'SET NULL' | 'SET DEFAULT';
+type GeneratedIndexPostcondition = {
+    /** The identity is persisted separately from the rendered CREATE INDEX SQL. */
+    readonly schema: string;
+    readonly table: string;
+    readonly name: string;
+    /** PostgreSQL exposes an omitted method as btree; make that expectation explicit. */
+    readonly method: string;
+    readonly unique: boolean;
+    readonly valid: true;
+    readonly ready: true;
+    readonly live: true;
+    readonly columns: readonly string[];
+    readonly expressions?: readonly string[];
+    readonly include?: readonly string[];
+    readonly nullsNotDistinct: boolean;
+    readonly opclass?: Readonly<Record<string, string>>;
+    readonly with?: Readonly<Record<string, string>>;
+    readonly where?: string;
+};
+/** A canonical SQL fact, never an unversioned deparse string. */
+type CanonicalSqlFact = {
+    readonly canonicalFormVersion: 1;
+    readonly sql: string;
+};
+/**
+ * The default, identity, and expression facts are one discriminated state.
+ * In particular, an identity cannot also claim an authored/default sequence
+ * expression, and a missing default cannot carry an expression.
+ */
+type GeneratedColumnDefaultState = {
+    readonly defaultKind: 'none';
+    readonly hasDefault: false;
+    readonly identity: null;
+    readonly defaultExpression?: never;
+} | {
+    readonly defaultKind: 'authored';
+    readonly hasDefault: true;
+    readonly identity: null;
+    readonly defaultExpression: CanonicalSqlFact;
+} | {
+    readonly defaultKind: 'generated-sequence';
+    readonly hasDefault: true;
+    readonly identity: null;
+    readonly defaultExpression?: never;
+} | {
+    readonly defaultKind: 'identity';
+    readonly hasDefault: false;
+    readonly identity: 'always' | 'byDefault';
+    readonly defaultExpression?: never;
+};
+type GeneratedColumnDeclaration = {
+    readonly type?: string;
+    readonly nullable?: boolean;
+    /** null means no COLLATE clause was authored; it is not an effective default. */
+    readonly authoredCollation?: string | null;
+    readonly default?: GeneratedColumnDefaultState;
+};
+type GeneratedTableColumnDeclaration = GeneratedColumnDeclaration & {
+    /** A table-shape member name, not the table target binding. */
+    readonly name: string;
+};
+type GeneratedIndexDeclaration = Omit<GeneratedIndexPostcondition, 'schema' | 'table' | 'name' | 'expressions' | 'where'> & {
+    readonly expressions?: readonly CanonicalSqlFact[];
+    readonly where?: CanonicalSqlFact;
+};
+type GeneratedConstraintDeclaration = Extract<GeneratedConstraintPostcondition, {
+    readonly type: 'p' | 'u';
+}> | Extract<GeneratedConstraintPostcondition, {
+    readonly type: 'f';
+}>;
+/** Table names live only in TargetBinding; columns describe table structure. */
+type V3TableDeclaration = {
+    readonly kind: 'table';
+    readonly columns: readonly GeneratedTableColumnDeclaration[];
+};
+/** Column names live only in TargetBinding; this is the column's shape. */
+type V3ColumnDeclaration = {
+    readonly kind: 'column';
+    readonly column: GeneratedColumnDeclaration;
+};
+/** Constraint names live only in TargetBinding; this is a non-CHECK constraint fact. */
+type V3ConstraintDeclaration = {
+    readonly kind: 'constraint';
+    readonly constraint: GeneratedConstraintDeclaration;
+};
+/** CHECK names live only in TargetBinding; expression is canonical and versioned. */
+type V3CheckDeclaration = {
+    readonly kind: 'check';
+    readonly check: {
+        readonly expression: CanonicalSqlFact;
+        readonly notValid: boolean;
+    };
+};
+/** Index schema, table, and name live only in TargetBinding; options are structured facts. */
+type V3IndexDeclaration = {
+    readonly kind: 'index';
+    readonly index: GeneratedIndexDeclaration;
+};
+/** Enum names live only in TargetBinding; labels are the declaration. */
+type V3EnumDeclaration = {
+    readonly kind: 'enum';
+    readonly labels: readonly string[];
+};
+/** Sequence names live only in TargetBinding; options are the declaration. */
+type V3SequenceDeclaration = {
+    readonly kind: 'sequence';
+    readonly startValue?: string;
+    readonly incrementBy?: string;
+    readonly minValue?: string;
+    readonly maxValue?: string;
+    readonly cycle?: boolean;
+};
+/** Extension names live only in TargetBinding; requested version is the declaration. */
+type V3ExtensionDeclaration = {
+    readonly kind: 'extension';
+    readonly version?: string;
+};
+/** Address-free v3 declaration variants. */
+type GeneratedPostconditionDeclarationV3 = {
+    readonly canonicalFormVersion: 1;
+} & (V3TableDeclaration | V3ColumnDeclaration | V3ConstraintDeclaration | V3CheckDeclaration | V3IndexDeclaration | V3EnumDeclaration | V3SequenceDeclaration | V3ExtensionDeclaration | {
+    readonly kind: 'absent';
+});
+/**
+ * The separate binding selects the surrounding managed step's canonical
+ * address.  It is versioned independently so later verifiers can resolve it
+ * without teaching any declaration variant about physical addresses.
+ */
+type TargetBinding = {
+    readonly bindingVersion: 1;
+    readonly bindingKind: 'managed-step-address';
+};
+/** Version 3 carries an address-free declaration and a separately decoded binding. */
+type GeneratedPostconditionV3 = {
+    readonly postconditionVersion: 3;
+    /** v3 kind lives only in the address-free declaration, never beside the binding. */
+    readonly kind?: never;
+    readonly declaration: GeneratedPostconditionDeclarationV3;
+    readonly targetBinding: TargetBinding;
+};
+/** Only v3 is a decodable generated postcondition. Older values replan. */
+type GeneratedPostcondition = GeneratedPostconditionV3;
+/** The version tag is part of the digest domain, never an implicit convention. */
+declare function generatedPostconditionDigest(value: {
+    readonly postconditionVersion: number;
+}): string;
+declare function generatedPostconditionForChange(input: {
+    readonly change: SchemaChange;
+    readonly schema: string;
+}): _dbsp_types.LedgerPayload | undefined;
+/**
+ * The only change-kind boundary between diagnostic schema diffing and managed
+ * execution.  Keep it at manifest construction: diagnostic-only controls must
+ * never acquire an address, claim, reservation, or DDL bundle.
+ */
+declare function assertDeclarableChangeKind(kind: ChangeKind): asserts kind is Exclude<ChangeKind, 'enable_rls' | 'disable_rls' | 'create_policy' | 'drop_policy' | 'add_comment' | 'drop_comment' | 'alter_column_auto_increment'>;
+/**
+ * PostgreSQL's total ChangeKind-to-address producer.  The mapping is run at
+ * plan time, so no executable generator step can later fall through to a
+ * permissive "no managed address" branch.
+ */
+declare function createPgsqlGeneratedManagedStep(input: {
+    readonly change: SchemaChange;
+    readonly database: string;
+    readonly schema: string;
+    readonly stepKey: string;
+    readonly order: number;
+    readonly dependencyOrder?: readonly string[];
+    readonly statements: readonly string[];
+}): NormalizedManagedStep;
+/**
+ * The live differ is the shape comparator. Persist the exact authored table
+ * shape, rather than a boolean that could later be reinterpreted.
+ */
+declare function pgsqlDeclaredAdoptionDeclaration(table: TableIR): LedgerPayload;
+/**
+ * Create the persisted, token-gated declaration that admits an already-live
+ * table into the managed ledger.  It intentionally mirrors the historical
+ * generator lifecycle material so CLI plans retain their byte representation.
+ */
+declare function createPgsqlDeclaredAdoptionStep(input: {
+    readonly address: Address;
+    readonly table: TableIR;
+    readonly stepKey: string;
+    readonly order: number;
+    readonly catalogueIdentity: CatalogueIdentity;
+}): NormalizedManagedStep;
+declare function pgsqlDeclaredSequenceAdoptionDeclaration(sequence: SequenceIR): LedgerPayload;
+/** Creates the token-gated adoption claim for a physical standalone sequence. */
+declare function createPgsqlDeclaredSequenceAdoptionStep(input: {
+    readonly address: Address;
+    readonly sequence: SequenceIR;
+    readonly stepKey: string;
+    readonly order: number;
+    readonly catalogueIdentity: CatalogueIdentity;
+}): NormalizedManagedStep;
+
+type GeneratedPostconditionQuery = {
+    query(sql: string, params?: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+};
+declare const generatedPostconditionSessionBrand: unique symbol;
+/** An adapter-minted, exclusive PostgreSQL session for rollback-only proof. */
+type GeneratedPostconditionSession = GeneratedPostconditionQuery & {
+    readonly [generatedPostconditionSessionBrand]: true;
+};
+/** A retained session capability was used after its owning bracket ended. */
+declare class GeneratedPostconditionSessionDeactivatedError extends Error {
+    constructor();
+}
+/** A caller attempted to overlap rollback-only proofs on one capability. */
+declare class GeneratedPostconditionProofInFlightError extends Error {
+    constructor();
+}
+/** A session bracket completed while rollback-only proof work was still running. */
+declare class GeneratedPostconditionWorkInFlightError extends Error {
+    constructor();
+}
+/**
+ * Public verifier checkout bracket.  Scratch-backed proofs require the active
+ * role to hold database TEMP privilege; callers must preflight that capability
+ * before applying managed DDL whose postcondition needs scratch staging.
+ */
+declare function withGeneratedPostconditionSession<T>(executor: {
+    connect(): Promise<GeneratedPostconditionQuery & {
+        release(error?: unknown): void | Promise<void>;
+    }>;
+}, work: (session: GeneratedPostconditionSession) => Promise<T>, lockTimeoutMs?: number): Promise<T>;
+type ResolvableGeneratedPostconditionKind = 'table' | 'column' | 'constraint';
+type GeneratedPostconditionBindingKind = ResolvableGeneratedPostconditionKind | 'index' | 'enum' | 'sequence' | 'extension';
+type GeneratedPostconditionSchemaBindingKind = Exclude<GeneratedPostconditionBindingKind, 'extension'>;
+type GeneratedPostconditionTableChildKind = 'column' | 'index' | 'constraint';
+/** The canonical schema-scoped table parent of a managed table child. */
+type GeneratedPostconditionTableParent = {
+    readonly scope: 'schema';
+    readonly engine: string;
+    readonly database: string;
+    readonly schema: string;
+    readonly kind: 'table';
+    readonly name: string;
+    readonly parent?: never;
+    readonly catalogueIdentity?: never;
+    readonly qualifiedBy?: never;
+};
+type GeneratedPostconditionSchemaRootAddress<K extends Exclude<GeneratedPostconditionSchemaBindingKind, GeneratedPostconditionTableChildKind>> = Omit<ResourceAddress, 'engine' | 'schema' | 'parent' | 'kind'> & {
+    readonly engine: string;
+    readonly scope: 'schema';
+    readonly schema: string;
+    readonly parent?: never;
+    readonly kind: K;
+};
+type GeneratedPostconditionTableChildAddress<K extends GeneratedPostconditionTableChildKind> = Omit<ResourceAddress, 'engine' | 'schema' | 'parent' | 'kind'> & {
+    readonly engine: string;
+    readonly scope: 'schema';
+    readonly schema: string;
+    readonly parent: GeneratedPostconditionTableParent;
+    readonly kind: K;
+};
+type GeneratedPostconditionExtensionAddress = Omit<ResourceAddress, 'engine' | 'schema' | 'parent' | 'kind'> & {
+    readonly engine: string;
+    readonly scope: 'database';
+    readonly schema?: never;
+    readonly parent?: never;
+    readonly kind: 'extension';
+};
+/** The complete topology selected by a v3 managed-step binding. */
+type GeneratedPostconditionBindingAddress = GeneratedPostconditionSchemaRootAddress<'table' | 'enum' | 'sequence'> | GeneratedPostconditionTableChildAddress<GeneratedPostconditionTableChildKind> | GeneratedPostconditionExtensionAddress;
+declare class GeneratedPostconditionBindingResolutionError extends Error {
+    readonly sought: string;
+    readonly found: string;
+    constructor(input: {
+        readonly sought: string;
+        readonly found: string;
+    }, options?: ErrorOptions);
+}
+/**
+ * Narrows a ledger address into the complete topology that a v3 verifier can
+ * bind.  Ledger addresses are intentionally broader, so this boundary must
+ * reject malformed persisted input before it reaches any verifier dispatch.
+ */
+declare function toGeneratedPostconditionBindingAddress(address: LedgerAddress): GeneratedPostconditionBindingAddress;
+type IndexProjection = {
+    readonly schema: string;
+    readonly table: string;
+    readonly name: string;
+    readonly method: string;
+    readonly unique: boolean;
+    readonly valid: boolean;
+    readonly ready: boolean;
+    readonly live: boolean;
+    readonly nullsNotDistinct: boolean;
+    readonly primary: boolean;
+    readonly exclusion: boolean;
+    readonly immediate: boolean;
+    readonly constraintOwned: boolean;
+    readonly keyColumns: readonly (string | null)[];
+    readonly keyDefinitions: readonly string[];
+    readonly includeColumns: readonly string[];
+    readonly opclasses: readonly string[];
+    readonly keyOptions: readonly string[];
+    readonly reloptions: readonly string[];
+    readonly predicate: string | null;
+};
+type CheckProjection = {
+    readonly expression: string;
+    readonly validated: boolean;
+    readonly noInherit: boolean;
+    readonly enforced: boolean;
+    readonly isLocal: boolean;
+    readonly inheritanceCount: number;
+    readonly parentId: number;
+};
+type TableColumnProjection = {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    readonly default: string | undefined;
+    /** Ownership and canonical nextval shape read in the same catalogue snapshot. */
+    readonly generatedSequenceDefault: boolean;
+    readonly collation: string | null;
+    readonly identity: 'always' | 'byDefault' | null;
+};
+type TableProjection = {
+    readonly columns: readonly TableColumnProjection[];
+};
+type GeneratedColumnProjection = Omit<TableColumnProjection, 'name'>;
+declare class GeneratedPostconditionReplanRequiredError extends Error {
+    readonly code = "REPLAN_REQUIRED";
+    readonly diagnostic: Readonly<{
+        versionSeen: unknown;
+        stepIdentity: string | undefined;
+        structuralPath: string | undefined;
+    }>;
+    readonly structuralPath: string | undefined;
+    constructor(message: string, versionSeen?: unknown, stepIdentity?: string | undefined, options?: ErrorOptions, structuralPath?: string | undefined);
+}
+/**
+ * Decode exactly one postcondition interpretation per version: only v3 is
+ * accepted. v1/v2 and every other value are named REPLAN_REQUIRED outcomes.
+ */
+declare function decodeGeneratedPostcondition(value: unknown, stepIdentity?: string): GeneratedPostcondition;
+/**
+ * The persisted digest is bound to the versioned wire value before decoding.
+ * A digest minted for one version cannot authenticate another version body.
+ */
+declare function decodeGeneratedPostconditionPayload(payload: {
+    readonly value: unknown;
+    readonly digest: string;
+}, stepIdentity?: string): GeneratedPostcondition;
+/** Refuse structural lookalikes before any proof or catalogue read. */
+declare function assertGeneratedPostconditionSession(value: unknown): GeneratedPostconditionSession;
+type GeneratedPostconditionCatalogueIdentity = NonNullable<ResourceAddress['catalogueIdentity']>;
+/** Resolves the v3 table binding, then delegates its shared structural proof. */
+declare function verifyGeneratedTablePostcondition(input: {
+    readonly session: GeneratedPostconditionSession;
+    readonly postcondition: unknown;
+    readonly address: GeneratedPostconditionBindingAddress;
+}): Promise<{
+    readonly kind: 'table';
+    readonly projection: TableProjection;
+    readonly catalogueIdentity: GeneratedPostconditionCatalogueIdentity;
+}>;
+/** Resolves the v3 column binding, then delegates its shared structural proof. */
+declare function verifyGeneratedColumnPostcondition(input: {
+    readonly session: GeneratedPostconditionSession;
+    readonly postcondition: unknown;
+    readonly address: GeneratedPostconditionBindingAddress;
+}): Promise<{
+    readonly kind: 'column';
+    readonly projection: GeneratedColumnProjection;
+    readonly catalogueIdentity: GeneratedPostconditionCatalogueIdentity;
+}>;
+/** Resolves the v3 index binding, then delegates its shared structural proof. */
+declare function verifyGeneratedIndexPostcondition(input: {
+    readonly session: GeneratedPostconditionSession;
+    readonly postcondition: unknown;
+    readonly address: GeneratedPostconditionBindingAddress;
+}): Promise<{
+    readonly kind: 'index';
+    readonly projection: IndexProjection;
+    readonly catalogueIdentity: GeneratedPostconditionCatalogueIdentity;
+}>;
+/** Resolves the v3 CHECK binding, then delegates its shared structural proof. */
+declare function verifyGeneratedCheckPostcondition(input: {
+    readonly session: GeneratedPostconditionSession;
+    readonly postcondition: unknown;
+    readonly address: GeneratedPostconditionBindingAddress;
+}): Promise<{
+    readonly kind: 'constraint';
+    readonly projection: CheckProjection;
+    readonly catalogueIdentity: GeneratedPostconditionCatalogueIdentity;
+}>;
+/**
+ * Binds the deliberately non-structural v3 kinds under the same rollback-only
+ * proof bracket as structural verifiers.  The declaration kind is the binding
+ * expectation, so a sequence slot can never observe an enum declaration (or
+ * vice versa) merely because the address happens to resolve.
+ */
+declare function verifyGeneratedIdentityPostcondition(input: {
+    readonly session: GeneratedPostconditionSession;
+    readonly postcondition: unknown;
+    readonly address: GeneratedPostconditionBindingAddress;
+    readonly kind: 'constraint' | 'enum' | 'sequence' | 'extension';
+}): Promise<{
+    readonly kind: 'constraint' | 'enum' | 'sequence' | 'extension';
+    readonly identity: Readonly<{
+        readonly relationOid: string;
+        readonly objectOid?: string;
+    }>;
+    readonly catalogueIdentity: GeneratedPostconditionCatalogueIdentity;
+}>;
+
+/**
+ * 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
+ */
+
+/** The minimum every schema-level operation needs: which schema. */
+interface SchemaScopeOptions {
+    /** Schema name to operate on (default: 'public') */
+    readonly schema?: string;
+}
+/**
+ * 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.
+ */
+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 */
+/**
+ * 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[];
+}
+/**
+ * Introspect a database through a pool.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * So: hold a client, use `new PgsqlAdapter(client, { borrowedClient: true })`
+ * and call `.introspect()` on it.
+ */
+declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
+
+type PgPhysicalModelInput = {
+    readonly mode: 'logical';
+    readonly model: ModelIR;
+    readonly schema: string;
+    readonly dbCasing?: DbCasing;
+    readonly naming?: NamingPlugin;
+    readonly fkAutoIndex?: boolean;
+} | {
+    readonly mode: 'physical';
+    readonly model: ModelIR;
+    readonly schema: string;
+    readonly fkAutoIndex?: boolean;
+};
+type PgPhysicalNamespace = 'pg_class' | 'pg_type' | 'column' | 'constraint' | 'policy';
+interface PgPhysicalNameClaim {
+    readonly namespace: PgPhysicalNamespace;
+    readonly schema: string;
+    readonly table?: string;
+    readonly physicalName: string;
+    readonly logicalOrigin: string;
+}
+interface PgPhysicalNameCollision {
+    readonly namespace: PgPhysicalNamespace;
+    readonly schema: string;
+    readonly table?: string;
+    readonly physicalName: string;
+    readonly first: PgPhysicalNameClaim;
+    readonly second: PgPhysicalNameClaim;
+}
+declare class PgPhysicalNameCollisionError extends Error {
+    readonly collision: PgPhysicalNameCollision;
+    constructor(collision: PgPhysicalNameCollision);
+    get namespace(): PgPhysicalNamespace;
+    get schema(): string;
+    get table(): string | undefined;
+    get physicalName(): string;
+    get first(): PgPhysicalNameClaim;
+    get second(): PgPhysicalNameClaim;
+}
+/** Refusal raised before a physical model starts inspecting its input model. */
+declare class PgPhysicalModelInputError extends Error {
+    readonly reason: 'schema' | 'mode-options';
+    constructor(reason: 'schema' | 'mode-options');
+}
+interface PgPhysicalModel {
+    readonly mode: 'logical' | 'physical';
+    readonly schema: string;
+    readonly fkAutoIndex: boolean;
+    readonly model: ModelIR;
+    readonly inventory: PhysicalNameInventory;
+    readonly claims: readonly PgPhysicalNameClaim[];
+}
+/** Builds the sole PostgreSQL physical spelling of one model without rendering SQL. */
+declare function createPgPhysicalModel(input: PgPhysicalModelInput): PgPhysicalModel;
+
+type PgsqlTransactionTimeoutParameter = 'lock_timeout' | 'statement_timeout';
+
+/**
+ * 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
+ */
+
+declare const rollbackOnlyPgsqlScopeBrand: unique symbol;
+/** A scope minted by withScratchScope and guaranteed to roll back on success. */
+type RollbackOnlyPgsqlScope<DB = unknown> = PgsqlAdapter<DB> & {
+    readonly [rollbackOnlyPgsqlScopeBrand]: typeof rollbackOnlyPgsqlScopeBrand;
+};
+type PgAdvisoryLockKey = bigint | {
+    readonly classId: number;
+    readonly objId: number;
+};
+type PgAdvisoryLockResult<T> = {
+    readonly acquired: true;
+    readonly value: T;
+} | {
+    readonly acquired: false;
+};
+declare class PgsqlRawSqlTransactionControlError extends Error {
+    readonly dbspRawSqlTransactionControl = true;
+    constructor(cause: unknown);
+}
+declare class PgsqlTransactionAbortedCommitError extends Error {
+    readonly dbspTransactionAbortedCommit = true;
+    constructor(cause: unknown);
+}
+declare class PgsqlTransactionAbortedError extends Error {
+    readonly dbspTransactionAborted = true;
+    constructor(cause: unknown);
+}
+/**
+ * Raised when a pool-owned top-level transaction is aborted through
+ * `TransactionOptions.signal`. If the signal aborts while `pool.connect()` is
+ * still pending, dbsp honors it only after a client is acquired.
+ */
+declare class PgsqlTransactionAbortSignalError extends Error {
+    readonly dbspTransactionAbortSignal = true;
+    constructor();
+}
+declare class PgsqlPinnedConnectionAbortSignalError extends Error {
+    readonly dbspPinnedConnectionAbortSignal = true;
+    constructor();
+}
+declare class PgsqlTransactionOptionsError extends Error {
+    readonly dbspTransactionOptions = true;
+    constructor(message: string);
+}
+declare class PgsqlAdvisoryLockOptionsError extends Error {
+    readonly dbspAdvisoryLockOptions = true;
+    constructor(message: string);
+}
+/**
+ * Raised when a statement inside a dbsp-managed transaction fails with a SQLSTATE
+ * that matches a timeout the caller configured for that transaction: `55P03`
+ * (`lock_not_available`) when `lockTimeoutMs` was set, or `57014` (`query_canceled`)
+ * when `statementTimeoutMs` was set. The original PostgreSQL error is preserved as
+ * `cause`.
+ *
+ * Classification is by SQLSTATE only. PostgreSQL assigns these codes to the OUTCOME,
+ * not the cause: `55P03` is also raised by `FOR UPDATE NOWAIT`, and `57014` is also
+ * raised by an external cancel (e.g. `pg_cancel_backend`). There is no locale-stable
+ * structured field that separates the timeout from the other cause, so the message
+ * text is deliberately NOT parsed. dbsp never emits `NOWAIT` itself, so a `55P03`
+ * here is the configured `lock_timeout` unless the caller's own raw SQL used
+ * `NOWAIT`; a `57014` is the configured `statement_timeout` unless the backend was
+ * cancelled from outside. Inspect `cause` when that distinction matters.
+ */
+declare class PgsqlTransactionTimeoutError extends Error {
+    readonly timeout: PgsqlTransactionTimeoutParameter;
+    readonly dbspTransactionTimeout = true;
+    constructor(cause: unknown, timeout: PgsqlTransactionTimeoutParameter);
+}
+/**
+ * Raised when the single safe unnamed replay after a prepared-statement
+ * infrastructure failure also fails. `message` is always the safe constant
+ * `Prepared statement recovery replay failed.`; `cause` is the replay error;
+ * `infrastructureError` is the original infrastructure error; and
+ * `admissionFingerprint` identifies the admitted statement. DBSP-authored
+ * messages carry no parameter values; preserved upstream errors, including the
+ * standard Error `cause`, are unsanitized.
+ */
+declare class PgsqlPreparedStatementReplayError extends Error {
+    readonly admissionFingerprint: string;
+    readonly infrastructureError: unknown;
+    readonly dbspPreparedStatementReplay = true;
+    readonly originalInfrastructureError: unknown;
+    readonly originalError: unknown;
+    constructor(admissionFingerprint: string, infrastructureError: unknown, cause: unknown);
+}
+/**
+ * Options for PgsqlAdapter.
+ */
+interface PgsqlPreparedStatementsOptions {
+    /** Maximum distinct compiled statements admitted per executor (default: 500). */
+    readonly maxStatements?: number;
+}
+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;
+    /**
+     * Opt in to node-postgres named prepared statements for compiled queries with
+     * parameters. `true` uses the default statement cap; an object overrides it.
+     */
+    readonly preparedStatements?: boolean | PgsqlPreparedStatementsOptions;
+}
+interface PgsqlPoolAdapterOptionsBase extends PgsqlAdapterOptions {
+    readonly borrowedClient?: false;
+}
+type PgsqlPoolAdapterOptions = (PgsqlPoolAdapterOptionsBase & {
+    readonly replayInvalidatedPlans?: false | undefined;
+}) | (Omit<PgsqlPoolAdapterOptionsBase, 'preparedStatements'> & {
+    readonly preparedStatements: true | PgsqlPreparedStatementsOptions;
+    /**
+     * Enable one unnamed replay after `0A000`/`RevalidateCachedQuery` only when
+     * you assert that your statements do not invoke functions performing
+     * effectful work before nested prepared-statement operations. This requires
+     * `preparedStatements: true` (or a prepared-statements options object).
+     *
+     * Replay snapshots JSON-like values (finite numbers, strings, booleans,
+     * `null`, arrays, plain or null-prototype objects) and clean `Date`/`Buffer`
+     * instances. It excludes non-finite numbers, `undefined`, `bigint`, functions,
+     * proxies, cycles, sparse arrays, accessors, symbol-valued
+     * parameters, symbol keys on plain objects, exotic prototypes, custom built-ins,
+     * and values with their own node-postgres
+     * `toPostgres` behavior.
+     * Serialization-irrelevant symbol metadata on arrays and Buffers is ignored.
+     * The detached snapshot covers later mutations to the supplied value graph,
+     * not built-in prototypes, timezone state, or node-postgres serialization
+     * configuration; a process-global `toPostgres` or `toJSON` installed while
+     * the call is in flight is outside the guarantee. Each capture or replay copy
+     * is independently limited to 64 Ki visited values, 16 MiB of UTF-8 strings,
+     * and 16 MiB of Buffer data. An ineligible or over-budget value still receives
+     * the initial named submission, but disables transparent replay.
+     * These budgets bound copied nodes and payload bytes; enumerating a plain
+     * object's existing property table is proportional to the caller's own object.
+     *
+     * Replay needs the adapter-owned serialized physical client available from a
+     * pool; it is therefore not supported by borrowed or compile-only adapters.
+     */
+    readonly replayInvalidatedPlans: true;
+});
+interface PgsqlBorrowedClientAdapterOptions extends PgsqlAdapterOptions {
+    /** Replay is only available to a pool-owned pinned scope. */
+    readonly replayInvalidatedPlans?: never;
+    /** 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;
+}
+/** Options for a connectionless adapter, which cannot own replay serialization. */
+interface PgsqlCompileOnlyAdapterOptions extends PgsqlAdapterOptions {
+    readonly replayInvalidatedPlans?: never;
+}
+/**
+ * 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 adapterManagedPinnedConnection;
+    private readonly rollbackOnlyScope;
+    private readonly scopeToken;
+    private readonly scopeState;
+    private readonly schemaName;
+    private readonly _dbCasing;
+    private readonly naming;
+    private readonly model;
+    private readonly logger;
+    private readonly replayInvalidatedPlans;
+    private readonly preparedStatements;
+    private readonly preparedStatementRegistry;
+    private readonly _capabilities;
+    private readonly defaultPk;
+    private readonly deriveFk;
+    /**
+     * Create a new PgsqlAdapter.
+     *
+     * 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, options?: PgsqlPoolAdapterOptions);
+    constructor(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions);
+    constructor(pool?: undefined, options?: PgsqlCompileOnlyAdapterOptions);
+    /**
+     * Shared compilation dependencies — built lazily from adapter fields.
+     * Passed to compiler sub-modules instead of `this`.
+     */
+    /**
+     * Return a new PgsqlAdapterOptions that merges current config with overrides.
+     * Ensures that all configuration fields (logger, defaultPkColumnName,
+     * deriveFkColumnName, etc.) are propagated to scoped/transactional adapters.
+     */
+    private cloneOptions;
+    private buildCompileDeps;
+    private requireNqlCompileModel;
+    private assertNqlBindingNamesDisjointFromTables;
+    private compileNqlMutation;
+    private compileNqlBundleLeafEnvelope;
+    private compileNqlBundle;
+    /**
+     * Returns the pool/client executor, or refuses a connectionless adapter.
+     */
+    private requireConnection;
+    /** Adapter capabilities for feature detection */
+    get capabilities(): AdapterCapabilities;
+    /** Per-instance connection state, distinct from PostgreSQL capabilities. */
+    get connectionAvailability(): ConnectionAvailability;
+    /** Side-effect-free execution availability for core feature detection. */
+    executionAvailable(): boolean;
+    /** PostgreSQL dialect capabilities for planner strategy selection */
+    get dialectCapabilities(): DialectCapabilities;
+    /**
+     * DB column casing convention used by this adapter.
+     */
+    get dbCasing(): DbCasing;
+    /**
+     * Get the underlying pg Pool or borrowed PoolClient instance.
+     *
+     * Exposing raw access from a pool-owned dbsp-managed scope permanently taints that
+     * physical client: external callers can queue commands outside dbsp's statement
+     * lock, so replay is disabled and dbsp destroys the client at scope release.
+     * Expect pool churn; session state on that exposed connection does not survive the
+     * release. A borrowed client remains caller-owned: dbsp never releases it, and the
+     * caller decides its fate after raw exposure.
+     */
+    getPoolInstance(): Pool | PoolClient;
+    /**
+     * Compile a plan to executable SQL.
+     *
+     * When passed a direct `CompiledNqlQuery`, the adapter trusts that the bundle
+     * has already been semantically validated by the NQL compiler. This method
+     * still performs adapter-owned SQL safety checks for emitted binding names
+     * before CTE emission.
+     */
+    compile<T = unknown>(plan: PlanReport | CompiledNqlQuery, options?: CompileOptions): CompiledQuery<T>;
+    /**
+     * Compile a plan with includes, returning subquery include metadata (DX-033).
+     */
+    compileWithIncludes<T = unknown>(plan: PlanReport, options?: CompileOptions): CompileResultWithIncludes<T>;
+    /**
+     * Compile a subquery include query for given parent IDs (DX-033).
+     * Generates: SELECT * FROM targetTable WHERE foreignKey IN ($1, $2, ...)
+     *
+     * @param info - Subquery include metadata
+     * @param parentIds - Parent record IDs to fetch related records for
+     * @param options - Compile options
+     * @returns Compiled query for fetching related records
+     */
+    compileSubqueryInclude(info: SubqueryIncludeInfo, parentIds: readonly unknown[], options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a FROM-less SELECT expression to SQL.
+     *
+     * Produces: SELECT <expr>
+     * Example: SELECT nextval('my_seq')
+     *
+     * @param expr - ExpressionIntent to evaluate
+     * @returns Compiled SQL and parameters
+     */
+    compileSelectExpression<T = unknown>(expr: ExpressionIntent): CompiledQuery<T>;
+    /**
+     * Compile an insert intent to executable SQL.
+     *
+     * Strategy switch (per CompileOptions):
+     * - rows <= batchThreshold (default 50): VALUES ($1,$2),($3,$4),...
+     * - rows > batchThreshold OR batchThreshold === 0: SELECT unnest($1::type[]),...
+     */
+    compileInsert(intent: InsertIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an insert-from intent to executable SQL (NQL-ALIGN).
+     * INSERT INTO target (cols) SELECT cols FROM source WHERE ... LIMIT ... RETURNING ...
+     */
+    compileInsertFrom(intent: InsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an update intent to executable SQL.
+     */
+    compileUpdate(intent: UpdateIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a batch update intent to executable SQL using unnest FROM strategy (BATCH-001).
+     *
+     * Generates:
+     *   UPDATE "table" SET "update_col" = t."update_col" [, "scalar_col" = $N]
+     *   FROM unnest(CAST($1 AS type[]), CAST($2 AS type[])) AS t("match_col", "update_col")
+     *   WHERE "table"."match_col" = t."match_col"
+     *   [RETURNING ...]
+     */
+    compileBatchUpdate(intent: BatchUpdateIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a delete intent to executable SQL.
+     */
+    compileDelete(intent: DeleteIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an upsert intent to executable SQL (DX-026).
+     */
+    compileUpsert(intent: UpsertIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile an upsert-from intent to executable SQL (NQL-BIND).
+     * INSERT INTO target SELECT ... FROM source ON CONFLICT (cols) DO UPDATE SET ...
+     */
+    compileUpsertFrom(intent: UpsertFromIntent, options?: CompileOptions): CompiledQuery;
+    /**
+     * Compile a recursive CTE plan to executable SQL.
+     * Supports adjacency-list and edge-table traversal modes.
+     */
+    compileRecursive<T = unknown>(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
+    /**
+     * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
+     *
+     * Strategy: compile CTE nodes to SQL fragments, compile outer query
+     * independently (parameters starting at $1), then renumber outer params
+     * to start after CTE params and prepend WITH clause.
+     */
+    compileCteQuery<T = unknown>(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery<T>;
+    /**
+     * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
+     */
+    compileSetOperation<T = unknown>(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
+    private compileSetOperationWithBindings;
+    /**
+     * Create a dump for observability.
+     */
+    createDump(plan: PlanReport, query: CompiledQuery, meta?: DumpMeta): Dump;
+    /**
+     * Execute a query and return all results.
+     * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
+     */
+    execute<T>(query: CompiledQuery<T>): Promise<T[]>;
+    /**
+     * Execute a query and return rows plus PostgreSQL result metadata.
+     * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
+     */
+    executeWithMeta(query: CompiledQuery): Promise<{
+        readonly rows: readonly unknown[];
+        readonly rowCount: number;
+        readonly command?: string;
+    }>;
+    /**
+     * Transform result rows from database naming to model naming convention.
+     * For CamelCaseNamingPlugin: price_cents → priceCents
+     */
+    private transformResultRows;
+    /**
+     * Execute a query and return the first result or null.
+     */
+    executeOne<T>(query: CompiledQuery<T>): Promise<T | null>;
+    /**
+     * Execute a query and return the first result or throw.
+     */
+    executeOneOrThrow<T>(query: CompiledQuery<T>): Promise<T>;
+    /**
+     * Stream query results as an async iterable iterator.
+     * Uses PostgreSQL cursors for efficient streaming.
+     *
+     * Note: The cursor must be used within a transaction. If not already
+     * in a transaction, this method wraps the streaming in one.
+     *
+     * @param query - Compiled query to stream
+     * @param options - Stream options (chunkSize)
+     * @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.
+     *
+     * @param options - Optional introspection options (schema, include/exclude filters)
+     * @returns IntrospectedModelIR with tables, relations, and hierarchy metadata
+     *
+     * @example
+     * ```typescript
+     * const model = await adapter.introspect();
+     * const model = await adapter.introspect({ schema: 'tenant_1' });
+     * const model = await adapter.introspect({ exclude: ['_prisma*'] });
+     * ```
+     */
+    introspect(options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
+    /**
+     * Acquire an exclusive session-level PostgreSQL advisory lock for the callback.
+     *
+     * The lock, callback, and unlock run on one `withPinnedConnection()` adapter.
+     * dbsp performs one PostgreSQL acquire and one matching unlock per call. It
+     * does not track reentrant depth in v1; PostgreSQL's session-level stacking
+     * still applies when callers deliberately nest on the same pinned adapter.
+     */
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>): Promise<T>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options: {
+        readonly wait?: 'block';
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options: {
+        readonly wait: 'try';
+        readonly signal?: AbortSignal;
+    }): Promise<PgAdvisoryLockResult<T>>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options?: {
+        readonly wait?: 'block' | 'try';
+        readonly signal?: AbortSignal;
+    }): Promise<T | PgAdvisoryLockResult<T>>;
+    private unlockAdvisoryLock;
+    withPinnedConnection<T>(fn: (adapter: Adapter<DB>) => Promise<T>, options?: PinnedConnectionOptions): Promise<T>;
+    private pinnedConnectionReleaseReason;
+    private pinnedConnectionWithClient;
+    /**
+     * 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>, options?: TransactionOptions): 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 expression canonicalisation, where the caller
+     * needs PostgreSQL's rendering but must not keep the scratch objects. This
+     * scope has exactly one successful exit: rollback. In a caller transaction,
+     * only this outer savepoint is retained after rollback; nested work releases
+     * normally, so a large canonicalisation run cannot retain one subtransaction
+     * per expression.
+     * Rollback here is cleanup of dbsp-created work, not a sandbox for arbitrary
+     * session effects.
+     */
+    withScratchScope<T>(fn: (adapter: RollbackOnlyPgsqlScope<DB>) => Promise<T>): Promise<T>;
+    private createManagedClientAdapter;
+    private createPinnedConnectionAdapter;
+    private createChildTransactionObserver;
+    private observeChildTransaction;
+    private markChildTransactionObserved;
+    private refreshScopeChildrenFailure;
+    private transactionWithManagedClient;
+    private transactionWithManagedClientSavepointScope;
+    private applyTransactionTimeouts;
+    private captureAndApplySavepointTimeouts;
+    private restoreSavepointTimeouts;
+    private transactionWithClientTransaction;
+    private releaseClient;
+    private rollbackAndReleaseSavepoint;
+    private rollbackSavepoint;
+    private releaseSavepoint;
+    private rollbackTransactionIfOpen;
+    private classifyTransactionStateError;
+    private probeTransactionState;
+    private classifySavepointReleaseFailure;
+    private rollbackSavepointAfterReleaseFailure;
+    private enterTransactionScope;
+    private enterPinnedConnectionScope;
+    private enterSavepointScope;
+    private pushClientScope;
+    private currentClientScope;
+    private managedScopeEndedMessage;
+    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.
+     */
+    withSchema(schemaName: string): 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[]>;
+    /**
+     * Generate DDL statements from the PostgreSQL physical model.
+     *
+     * Uses PostgreSQL AST nodes and pgsql-deparser for consistent SQL generation.
+     * Names are already physical: they were mapped once when the model was built
+     * with `createPgPhysicalModel`, and this method maps none again.
+     *
+     * @param physical - The physical model to generate DDL from; its schema and
+     *   `fkAutoIndex` apply
+     * @param overrideOptions - Optional rendering overrides (e.g., includeDropStatements)
+     * @returns Array of DDL statements in dependency order
+     */
+    generateDDL(physical: PgPhysicalModel, overrideOptions?: GenerateDDLOptions): string[];
+    /**
+     * Execute a DDL statement directly (e.g. TRUNCATE, VACUUM, ALTER TABLE, CREATE INDEX).
+     *
+     * @throws Error if called on a compile-only adapter (no pool)
+     * @since DDL-TABLE-001
+     */
+    executeDDL(sql: string): Promise<void>;
+    /**
+     * 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 shouldProtectBorrowedClientTransaction;
+    /**
+     * An idle ReadyForQuery status says nothing about commands another owner has
+     * already queued on a PoolClient. Only a dbsp-created pinned scope both owns
+     * the checked-out physical client and holds its statement lock across the
+     * failed named execution and any unnamed replay.
+     */
+    private ownsSerializedClientForPreparedStatementReplay;
+    private executeQueryProtectingOpenTransaction;
+    private executeConnectionStatement;
+    private executeConnectionStatementUnlocked;
+    private executeConnectionStatementInSavepoint;
+    private issueConnectionQuery;
+    private assertNoMultiCommandRawCall;
+    private assertNoTransactionControlCommand;
+    private assertPrepareDidNotEndTransaction;
+    /**
+     * Resolve the explicit schema for a catalog read: an explicit argument, else
+     * the adapter's configured schema, else `undefined` (resolve in-query). NOT a
+     * hard-coded 'public' — an unresolved schema is handled by the SQL, which
+     * finds the table's schema search_path-aware, in the SAME session, so a
+     * non-public search_path and a pooled connection both stay correct.
+     */
+    private explicitSchema;
+    /**
+     * List all indexes on a table by querying pg_indexes.
+     *
+     * @param table - Table name
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
+     */
+    listIndexes(table: string, schema?: string, options?: {
+        namePattern?: string;
+    }): Promise<IndexInfo[]>;
+    /**
+     * Check whether an index with the given name exists on a table.
+     *
+     * @param name - Index name
+     * @param table - Table name
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
+     */
+    indexExists(name: string, table: string, schema?: string): Promise<boolean>;
+    /**
+     * Return the total storage size of a table in bytes (includes indexes and TOAST).
+     *
+     * The table name is a SQL identifier — it is double-quoted, not parameterized,
+     * because PostgreSQL does not allow parameterized table names in FROM clauses.
+     * With no known schema the table is left unqualified so ::regclass resolves it
+     * through search_path (the same table an unqualified reference would hit).
+     *
+     * @param table - Table name
+     * @param schema - Schema name (defaults to the search_path-resolved schema)
+     */
+    storageSize(table: string, schema?: string): Promise<number>;
+    /**
+     * Generate SQL for TRUNCATE TABLE.
+     * Implements TableDDLGeneratorAdapter.generateTruncate.
+     */
+    generateTruncate(table: string, schemaName: string, options?: TruncateOptions): string;
+    /**
+     * Generate SQL for VACUUM.
+     * Implements TableDDLGeneratorAdapter.generateVacuum.
+     */
+    generateVacuum(table: string, schemaName: string, options?: VacuumOptions): string;
+    /**
+     * Generate SQL for ALTER TABLE ... ALTER COLUMN.
+     * Implements TableDDLGeneratorAdapter.generateAlterColumn.
+     */
+    generateAlterColumn(table: string, schemaName: string, column: string, options: AlterColumnOptions): string;
+    /**
+     * Generate SQL for CREATE INDEX.
+     * Implements TableDDLGeneratorAdapter.generateCreateIndex.
+     */
+    generateCreateIndex(table: string, schemaName: string, options: CreateIndexOptions): string;
+    /**
+     * Generate SQL for DROP INDEX.
+     * Implements TableDDLGeneratorAdapter.generateDropIndex.
+     */
+    generateDropIndex(name: string, schemaName: string, options?: DropIndexOptions): string;
+    /**
+     * Validate an identifier (table name, column name, schema name).
+     */
+    validateIdentifier(value: string, type: string): void;
+}
+/**
+ * Create a PgsqlAdapter from a pg Pool instance.
+ *
+ * @param pool - pg Pool instance
+ * @param options - Optional configuration
+ * @returns A new PgsqlAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { createPgsqlAdapter } from '@dbsp/adapter-pgsql';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const adapter = createPgsqlAdapter(pool);
+ *
+ * // With naming convention
+ * const adapter = createPgsqlAdapter(pool, { dbCasing: 'snake_case' });
+ * ```
+ */
+declare function createPgsqlAdapter<DB = unknown>(pool: Pool, options?: PgsqlPoolAdapterOptions): PgsqlAdapter<DB>;
+declare function createPgsqlAdapter<DB = unknown>(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions): PgsqlAdapter<DB>;
+/**
+ * Creates a connectionless PgsqlAdapter for SQL generation without a database connection.
+ *
+ * All compilation methods (compile, compileInsert, etc.), createDump(), and generateDDL()
+ * work normally. The adapter has the full PgsqlAdapter surface; database operations refuse
+ * at runtime until it is constructed with a connection via createPgsqlAdapter(pool).
+ *
+ * @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?: PgsqlCompileOnlyAdapterOptions): PgsqlAdapter<DB>;
+
+interface CheckConstraintCanonicalizationWarning {
+    readonly table: string;
+    readonly kind: 'check_constraint';
+    readonly name: string;
+    readonly constraint: string;
+    readonly message: string;
+    readonly cause: unknown;
+}
+interface ColumnDefaultCanonicalizationWarning {
+    readonly table: string;
+    readonly kind: 'column_default';
+    readonly name: string;
+    readonly message: string;
+    readonly cause: unknown;
+    readonly outcome?: 'unavailable' | 'rejected' | 'refused';
+    /** Whether this warning represents a raw fallback or absent counterpart. */
+    readonly comparison: 'raw' | 'unpaired';
+    /** Present when the default could not be paired with the opposite model side. */
+    readonly side?: 'desired' | 'database';
+}
+interface IndexPredicateCanonicalizationWarning {
+    readonly table: string;
+    readonly kind: 'index_predicate';
+    readonly name: string;
+    readonly message: string;
+    readonly cause: unknown;
+    readonly outcome: 'unavailable' | 'rejected' | 'refused';
+    /** Predicate fallback always compares both complete models raw. */
+    readonly comparison: 'raw';
+    readonly side?: 'desired' | 'database';
+}
+type ExpressionCanonicalizationWarning = CheckConstraintCanonicalizationWarning | ColumnDefaultCanonicalizationWarning | IndexPredicateCanonicalizationWarning;
+interface CanonicalizeCheckConstraintsOptions {
+    /** Database schema that owns the target tables and target-scoped enum types. */
+    readonly schemaName?: string;
+    /** 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;
+    /** Skip CHECK scratch work when the caller's dialect does not support CHECK DDL. */
+    readonly canonicalizeCheckConstraints?: boolean;
+    /** Capabilities used to generate the migration this scope is staging for. */
+    readonly dialectCapabilities?: DialectCapabilities;
+}
+/** The comparison result for one CHECK owned by an application assertion. */
+type OwnedCheckState = 'healthy' | 'absent' | 'unrenderable' | 'definition-mismatch' | 'unvalidated';
+declare class CheckConstraintCanonicalizationError extends Error {
+    readonly table: string;
+    readonly constraints: readonly string[];
+    readonly cause: unknown;
+    constructor(table: string, constraints: readonly string[], cause: unknown);
+}
+declare class ColumnDefaultCanonicalizationError extends Error {
+    readonly table: string;
+    readonly column: string;
+    readonly cause: unknown;
+    constructor(table: string, column: string, cause: unknown);
+}
+/**
+ * Canonicalise PostgreSQL CHECK constraint expressions in a desired model.
+ */
+declare function canonicalizeCheckConstraints(adapter: RollbackOnlyPgsqlScope, desired: ModelIR, dbModel: ModelIR, options?: CanonicalizeCheckConstraintsOptions): Promise<ModelIR>;
+
+interface ComparePgsqlDatabaseSchemaOptions$1 extends CompareSchemataOptions$1, SchemaScopeOptions {
+    /**
+     * Whether to canonicalise PostgreSQL CHECK constraint expressions, column defaults, and predicates on column-keyed
+     * partial indexes before comparing. Defaults to `true`. Expression-keyed
+     * partial-index predicates are reported as unavailable. Set to `false` only for compatibility with
+     * legacy raw-string live diffs.
+     *
+     * Live canonicalisation creates temporary scratch tables inside an adapter
+     * scratch scope whose successful cleanup is rollback. The database role needs
+     * permission to create temporary tables and use the scratch column types. If
+     * PostgreSQL refuses that scratch DDL, non-strict mode warns and falls back to
+     * best-effort raw string comparison for the affected expression surfaces.
+     */
+    readonly canonicalizeExpressions?: boolean;
+    /**
+     * Receives live expression canonicalisation warnings. Defaults to the core logger.
+     */
+    readonly onWarning?: (message: string) => void;
+    /** Receives the identity-bearing canonicalisation warning before its string form. */
+    readonly onExpressionCanonicalizationWarning?: (warning: ExpressionCanonicalizationWarning) => void;
+    /**
+     * Diff that the caller just applied before this live re-diff. Used only when
+     * expression surfaces are compared by raw text to fail loudly if the exact same
+     * expression-surface drift appears again after re-introspection.
+     */
+    readonly previouslyAppliedDiff?: SchemaDiff;
+    /** Internal physical-to-authored sequence provenance for legacy-name refusal. */
+    readonly declaredSequenceNames?: ReadonlyMap<string, string>;
+}
+/**
+ * Compare the declared shape of an adopted table against its live PostgreSQL
+ * counterpart. The supplied model is deliberately declaration-scoped: the whole
+ * schema is introspected, so an adopted table's foreign keys to any table are
+ * seen, and the comparison then keeps only the declared physical tables (with
+ * the relations between them), so drift on other tables is not reported.
+ */
+interface ComparePgsqlDeclaredAdoptionSchemaInput {
+    readonly executor: PgsqlAdoptionComparisonExecutor;
+    readonly model: ModelIR;
+    readonly schema: string;
+    readonly dbCasing: DbCasing;
+    /**
+     * Already-physicalized naming authority for `model`. Callers that own a
+     * snapshot pass it here so comparison never re-applies logical naming.
+     */
+    readonly physical?: PgPhysicalModel;
+    /** Physical [table, index] JSON keys whose drop drift is unmanaged. */
+    readonly externalIndexMask?: ReadonlySet<string>;
+    /** Physical [table, surface] JSON keys maintained by application assertions. */
+    readonly ownershipMask?: PgsqlDeclaredAdoptionOwnershipMask;
+    /** Internal physical-to-authored sequence provenance for legacy-name refusal. */
+    readonly declaredSequenceNames?: ReadonlyMap<string, string>;
+}
+/** Internal converge-only declaration mask; public database comparison is unchanged. */
+interface PgsqlDeclaredAdoptionOwnershipMask {
+    readonly checks: ReadonlySet<string>;
+    readonly columnTypes: ReadonlySet<string>;
+    readonly indexes: ReadonlySet<string>;
+}
+/** Minimal pool surface retained so callers can keep their executor opaque. */
+interface PgsqlAdoptionComparisonExecutor {
+    query(sql: string, parameters?: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+}
+/** Builds the declaration-scoped model used by every adoption shape check. */
+declare function modelForDeclaredAdoption(table: TableIR): ModelIR;
+/**
+ * PostgreSQL-aware comparison used to admit a declared table adoption. A
+ * claimed session remains pinned by constructing a borrowed, transaction-aware
+ * adapter from that exact executor.
+ */
+declare function comparePgsqlDeclaredAdoptionSchema(input: ComparePgsqlDeclaredAdoptionSchemaInput): Promise<SchemaDiff>;
+type NonConvergentSchemaDiffSurface = {
+    readonly kind: 'check_constraint';
+    readonly table: string;
+    readonly constraint: string;
+} | {
+    readonly kind: 'column_default';
+    readonly table: string;
+    readonly column: string;
+};
+declare class NonConvergentSchemaDiffError extends Error {
+    readonly surface: NonConvergentSchemaDiffSurface;
+    readonly desiredExpressionHash: string;
+    readonly databaseExpressionHash: string;
+    constructor(surface: NonConvergentSchemaDiffSurface, desiredExpressionHash: string, databaseExpressionHash: 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[]);
+}
+/** A raw partial-index predicate and added enum values cannot share one migration. */
+declare class PartialIndexPredicateNewEnumValueError extends Error {
+    readonly addedEnumValues: readonly AddedEnumValue[];
+    constructor(addedEnumValues: readonly AddedEnumValue[]);
+}
+/** #454: Predicate canonicalization is not implemented for indexes with expression keys. */
+declare class ExpressionKeyedIndexPredicateCanonicalizationUnsupportedError extends Error {
+    readonly predicates: readonly {
+        readonly side: 'desired' | 'database';
+        readonly table: string;
+        readonly index: string;
+    }[];
+    constructor(predicates: readonly {
+        readonly side: 'desired' | 'database';
+        readonly table: string;
+        readonly index: string;
+    }[]);
+}
+/**
+ * A raw partial-index predicate cannot be proven to converge after PostgreSQL
+ * deparses it, so emitting its CREATE statement is unsafe.
+ */
+declare class RawIndexPredicateFallbackError extends Error {
+    constructor(cause?: unknown);
+}
+declare class IndexPredicateCanonicalizationError extends Error {
+    readonly rejectedPredicates: readonly {
+        readonly side: 'desired' | 'database';
+        readonly table: string;
+        readonly index: string;
+        readonly reason?: unknown;
+    }[];
+    /**
+     * Enum values added by this migration are diagnostic candidates only. They
+     * are collected from the schema diff, never matched to a rejected index.
+     */
+    readonly addedEnumValues: readonly AddedEnumValue[];
+    constructor(rejectedPredicates: readonly {
+        readonly side: 'desired' | 'database';
+        readonly table: string;
+        readonly index: string;
+        readonly reason?: unknown;
+    }[], 
+    /**
+     * Enum values added by this migration are diagnostic candidates only. They
+     * are collected from the schema diff, never matched to a rejected index.
+     */
+    addedEnumValues?: readonly AddedEnumValue[]);
+}
+/**
+ * Live PostgreSQL schema diff: introspect, canonicalise desired CHECK
+ * constraint expressions, column defaults, and predicates on column-keyed
+ * partial indexes 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.
+ *
+ * Index expressions are intentionally not canonicalised here; partial-index
+ * predicates on expression-keyed indexes are reported as unavailable and are
+ * therefore rejected by strict mode. They need their own key-shape substrate.
+ */
+declare function comparePgsqlDatabaseSchema$1(adapter: PgsqlAdapter, desired: ModelIR, options?: ComparePgsqlDatabaseSchemaOptions$1): Promise<SchemaDiff>;
+declare function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff: SchemaDiff, currentDiff: SchemaDiff, rawExpressionSurfaces?: 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$1 {
+    /**
+     * 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;
+    /**
+     * Declared model whose FK-index coverage controls automatic index emission.
+     * This lets callers mask generated DDL surfaces without changing the
+     * declaration-level decision to emit an automatic FK index.
+     */
+    readonly fkAutoIndexCoverage?: ModelIR;
+    /** 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$1(diff: SchemaDiff, options?: MigrationSQLOptions$1): readonly string[];
+/**
+ * Generate ordered DOWN SQL statements from a SchemaDiff.
+ *
+ * Reverses the topological order used in UP migrations:
+ * phases run in descending order (18, 17, ..., 0).
+ *
+ * Irreversible drops with missing or unmanaged metadata produce SQL WARNING
+ * comments instead of reconstructing the dropped object.
+ */
+declare function generateDownSQL$1(diff: SchemaDiff, options?: MigrationSQLOptions$1): readonly string[];
+
+/** Public physical-model DDL facade.  The rendering engines remain ModelIR-only. */
+
+interface GenerateDDLOptions extends Omit<GenerateDDLOptions$1, 'schemaName' | 'naming' | 'fkAutoIndex'> {
+}
+interface CompareSchemataOptions extends Omit<CompareSchemataOptions$1, 'schema' | 'dbCasing' | 'declaredSequenceNames'> {
+}
+interface ComparePgsqlDatabaseSchemaOptions extends Omit<ComparePgsqlDatabaseSchemaOptions$1, 'schema' | 'dbCasing' | 'declaredSequenceNames'> {
+}
+interface MigrationSQLOptions extends Omit<MigrationSQLOptions$1, 'schemaName' | 'fkAutoIndex' | 'fkAutoIndexCoverage'> {
+}
+interface PgSchemaDiff extends SchemaDiff {
+    readonly physical: Pick<PgPhysicalModel, 'schema' | 'fkAutoIndex'>;
+}
+declare function generateDDL(physical: PgPhysicalModel, options?: GenerateDDLOptions): string[];
+declare function compareSchemata(desired: PgPhysicalModel, database: PgPhysicalModel, options?: CompareSchemataOptions): PgSchemaDiff;
+declare function comparePgsqlDatabaseSchema(adapter: PgsqlAdapter, desired: PgPhysicalModel, options?: ComparePgsqlDatabaseSchemaOptions): Promise<PgSchemaDiff>;
+declare function generateMigrationSQL(diff: PgSchemaDiff, options?: MigrationSQLOptions): readonly string[];
+declare function generateDownSQL(diff: PgSchemaDiff, options?: MigrationSQLOptions): readonly string[];
+
+/** The intentionally narrow query facade passed to application callbacks. */
+interface PgApplicationStepTx {
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: readonly unknown[]): Promise<{
+        readonly rows: readonly Row[];
+    }>;
+}
+interface PgConvergeApplicationStepBase {
+    readonly id: string;
+    readonly digest: string;
+    readonly scope?: 'schema';
+    readonly phase: 'before-generated-ddl' | 'after-generated-ddl';
+    readonly lockTimeoutMs?: number;
+    readonly statementTimeoutMs?: number;
+}
+interface PgConvergeOnceStep extends PgConvergeApplicationStepBase {
+    readonly kind: 'once';
+    readonly apply: (tx: PgApplicationStepTx) => Promise<void> | void;
+}
+interface PgConvergeAssertOwnership {
+    readonly checks?: readonly {
+        readonly table: string;
+        readonly name: string;
+    }[];
+    readonly columnTypes?: readonly {
+        readonly table: string;
+        readonly column: string;
+    }[];
+    readonly indexes?: readonly {
+        readonly table: string;
+        readonly name: string;
+    }[];
+}
+type PgOwnedCheckState = OwnedCheckState;
+interface PgApplicationStepOwnedState {
+    readonly checks: readonly {
+        readonly table: string;
+        readonly name: string;
+        readonly physicalTable: string;
+        readonly physicalName: string;
+        readonly state: PgOwnedCheckState;
+    }[];
+}
+interface PgConvergeAssertStep extends PgConvergeApplicationStepBase {
+    readonly kind: 'assert';
+    /** Declaration surfaces maintained by this assertion rather than converge. */
+    readonly owns?: PgConvergeAssertOwnership;
+    readonly inspect: (tx: PgApplicationStepTx, owned: PgApplicationStepOwnedState) => Promise<'healthy' | 'unhealthy'> | 'healthy' | 'unhealthy';
+    readonly apply: (tx: PgApplicationStepTx, owned: PgApplicationStepOwnedState) => Promise<void> | void;
+}
+type PgConvergeApplicationStep = PgConvergeOnceStep | PgConvergeAssertStep;
+
+type PgConvergeRefusal = 'invalid-options' | 'unsupported-change' | 'unmanaged-object' | 'unmanaged-parent' | 'concurrent-drift' | 'ledger-absent' | 'incompatible-ledger' | 'unsupported-server' | 'busy' | 'recovery-required' | 'database-read-only' | 'execution-refused' | 'adoption-refused' | 'application-step-changed' | 'application-step-failed' | 'initialization-refused';
+interface PgConvergeInitializationFailure {
+    readonly home: LedgerHome;
+    readonly code: string;
+    readonly step: string;
+    readonly detail: string;
+}
+type PgConvergeRefusalChange = Pick<SchemaChange, 'kind' | 'table' | 'column' | 'details'> & {
+    /**
+     * Present for create_index and drop_index when the index has a name: always
+     * for a live index and for a logical-mode physical model, which names every
+     * index; a physical-mode snapshot passes its own names through as given.
+     */
+    readonly index?: string;
+};
+/**
+ * Unsupported-change, ledger and ownership refusals occur before converge commits
+ * managed DDL. An execution refusal may follow a rolled-back transactional DDL
+ * attempt, and comparison may use rollback-only scratch DDL.
+ */
+declare class PgConvergeRefusalError extends Error {
+    readonly refusal: PgConvergeRefusal;
+    readonly changes: readonly PgConvergeRefusalChange[];
+    readonly detail?: string | undefined;
+    readonly runIds?: readonly string[] | undefined;
+    readonly executionIds?: readonly string[] | undefined;
+    readonly busyRunIds?: readonly string[] | undefined;
+    readonly initialization?: PgConvergeInitializationFailure | undefined;
+    constructor(refusal: PgConvergeRefusal, changes: readonly PgConvergeRefusalChange[], detail?: string | undefined, runIds?: readonly string[] | undefined, executionIds?: readonly string[] | undefined, busyRunIds?: readonly string[] | undefined, initialization?: PgConvergeInitializationFailure | undefined, options?: ErrorOptions);
+}
+type PgConvergeResult = {
+    readonly kind: 'no-drift';
+    readonly applied: readonly string[];
+} | {
+    readonly kind: 'applied';
+    readonly applied: readonly string[];
+} | {
+    readonly kind: 'partially-applied';
+    readonly completedStepKeys: readonly string[];
+    readonly notStartedStepKeys: readonly string[];
+    readonly detail: string;
+} | {
+    readonly kind: 'transport-ambiguous';
+    readonly detail: string;
+};
+type PgConvergePlannedStep = {
+    readonly stepKey: string;
+    readonly order: number;
+    readonly dependencyOrder: readonly string[];
+    readonly address: NonNullable<NormalizedManagedStep['address']>;
+    readonly kind: SchemaChange['kind'];
+    readonly table: string;
+    readonly column?: string;
+    readonly details: string;
+} | {
+    readonly stepKey: string;
+    readonly order: number;
+    readonly dependencyOrder: readonly string[];
+    readonly address: NonNullable<NormalizedManagedStep['address']>;
+    readonly kind: 'adopt_table' | 'adopt_sequence';
+} | {
+    readonly kind: 'application-step';
+    readonly id: string;
+    readonly step: 'once';
+    readonly inspected?: never;
+    readonly stepKey?: never;
+    readonly order?: never;
+    readonly dependencyOrder?: never;
+    readonly address?: never;
+} | {
+    readonly kind: 'application-step';
+    readonly id: string;
+    readonly step: 'assert';
+    readonly inspected: boolean;
+    readonly stepKey?: never;
+    readonly order?: never;
+    readonly dependencyOrder?: never;
+    readonly address?: never;
+};
+type PgConvergeCheckResult = {
+    readonly kind: 'no-drift';
+} | {
+    readonly kind: 'would-apply';
+    readonly planDigest: string;
+    readonly steps: readonly PgConvergePlannedStep[];
+};
+interface ConvergePgBaseOptions {
+    readonly schema?: string;
+    readonly dbCasing?: DbCasing;
+    /** Internal physical-model rendering choice; public callers cannot override it. */
+    readonly fkAutoIndex?: boolean;
+    /** Internal physical-to-authored sequence provenance for legacy-name refusal. */
+    readonly declaredSequenceNames?: ReadonlyMap<string, string>;
+    /**
+     * In apply mode, create a ledger for an absent schema ledger. `pristine`
+     * refuses declared live tables or standalone sequences; `adopt-existing`
+     * also adopts matching declared relations on every converge call. The schema
+     * itself must already exist. Defaults to `never`.
+     */
+    readonly initialize?: 'never' | 'pristine' | 'adopt-existing';
+    /**
+     * Exact physical PostgreSQL index names that converge must leave alone on
+     * declared model tables. Each table name uses the model's naming, while the
+     * index name is used verbatim. Entries are validated before connecting: they
+     * must be distinct, name declared tables, and must not equal the name of an
+     * index listed in any declared table's `indexes`. Converge never drops a
+     * live index named here. It does not check these names against the other
+     * relations the model creates (tables, sequences, primary-key or UNIQUE
+     * constraint indexes); PostgreSQL rejects such a collision when the step
+     * runs, and converge reports it as that step's failure.
+     */
+    readonly externalIndexes?: readonly {
+        readonly table: string;
+        readonly name: string;
+    }[];
+    /**
+     * Transactional application-owned schema work. Recorded runs append
+     * `application-step:<id>` to `applied`, after generated change kinds.
+     * The transaction facade rejects leading transaction-control keywords; it is
+     * a correctness guard, not a security boundary for code in this process.
+     */
+    readonly steps?: readonly PgConvergeApplicationStep[];
+}
+interface ConvergePgOptions extends ConvergePgBaseOptions {
+    readonly mode?: 'apply';
+}
+interface ConvergePgCheckOptions extends ConvergePgBaseOptions {
+    readonly mode: 'check';
+}
+/**
+ * Converges only startup-safe PostgreSQL additions: it creates tables and
+ * sequences, adds nullable columns without defaults and NOT NULL columns with
+ * boolean, finite-number, or non-function-like string literal defaults of a
+ * a PostgreSQL built-in base type or an enum to managed tables, and creates
+ * indexes, CHECK constraints, and foreign keys when their table parents are
+ * created by this same run (for foreign keys, both tables).
+ * Other defaulted original database types are refused.
+ *
+ * Adding a column still takes an ACCESS EXCLUSIVE lock on its table, bounded by
+ * the executor's five-second lock_timeout and held through read-back and the
+ * ledger terminal. A no-rewrite default is therefore not non-blocking.
+ *
+ * Converge mutates only declared additions whose target and existing parent pass
+ * managed admission. It compares the declared tables, sequences, and enums'
+ * structural shape; it does not audit the provenance of an exact-matching child
+ * already present on a managed table.
+ * An assert may own declared CHECKs, column types, and named indexes; those
+ * surfaces are excluded from comparison and generated DDL. Its read-only
+ * `inspect` receives canonical owned-CHECK state, while its callback is
+ * responsible for maintaining them. `externalIndexes` accepts exact physical
+ * index names on logical model tables;
+ * entries are validated before the ledger lock or any query, and converge
+ * never drops a matching live index. A name that collides with another
+ * relation the model creates fails when that step runs.
+ * Before comparison, converge refuses while its target ledger home has a live
+ * reservation: wait for a run that is still executing, reconcile a run whose
+ * lock is free with reconcilePgTransitionRun or `dbsp reconcile --db
+ * <database> <run-id>`, have the ledger owner resolve an unmapped reservation
+ * and the journal owner one whose journal attribution cannot be read, then call
+ * converge again.
+ * Application steps run on the converge session: session-level effects such as
+ * `SET` without `LOCAL`, `SET ROLE`, `LISTEN`, `PREPARE`, temporary tables and
+ * session advisory locks are not part of a step and can affect the rest of the
+ * call. Steps should use `SET LOCAL`.
+ * A declared table with `adopt: true` is taken into management when it exists,
+ * the ledger projects its address as unknown (the only state an adoption claim
+ * opens from), and it matches the declaration exactly after `externalIndexes`
+ * and application ownership masking. A mismatch found while planning refuses
+ * `adoption-refused` before anything is written. A table that changes while
+ * its adoption runs is refused under its claim and the ledger records that
+ * refused adoption; tables adopted earlier in the same call stay adopted.
+ * Tables a run creates and every change on those tables commit together or not
+ * at all. A sequence created by the same run commits on its own and can remain
+ * after a failure. After a transport-ambiguous outcome, the next call observes
+ * whichever state PostgreSQL holds. Converge runs are not journaled. Check mode
+ * returns a point-in-time plan without executing it; it is not a guarantee that
+ * a later apply will succeed, because other sessions can change the database
+ * and execution-time ledger physical-shape integrity, claim-time adoption
+ * re-verification, vacancy, and lock-timeout checks are not reproduced.
+ * `initialize` defaults to `never`. `pristine` creates an absent ledger only
+ * when declared tables and standalone sequences are absent, while
+ * `adopt-existing` creates an absent ledger and adopts matching declared
+ * relations on every call. The target schema must already exist. Application
+ * steps run with `search_path` set to the target schema, `pg_temp`, then the
+ * connection's entries, so `current_schema()` is the target. Lookup goes through
+ * `pg_catalog` first unless those entries name it explicitly, then the target,
+ * `pg_temp` and those entries.
+ */
+declare function convergePg(pool: Pool, model: ModelIR, options?: ConvergePgOptions): Promise<PgConvergeResult>;
+declare function convergePg(pool: Pool, model: ModelIR, options: ConvergePgCheckOptions): Promise<PgConvergeCheckResult>;
+
+type QueryResultLike = {
+    readonly rows: readonly Record<string, unknown>[];
+};
+type TransitionJournalQueryable = {
+    query(sql: string, params?: readonly unknown[]): Promise<QueryResultLike>;
+};
+/** A copied plan row is not authority for a differently named run. */
+declare class TransitionRunIdentityMismatchError extends Error {
+    constructor();
+}
+declare function renderCreateDbspMetaSchemaSql(): string;
+declare function renderCreateTransitionRunTableSql(exclusive?: boolean): string;
+declare function renderCreateTransitionJournalTableSql(exclusive?: boolean): string;
+declare function renderCreateTransitionRunPlanTableSql(exclusive?: boolean): string;
+declare function renderCreateTransitionAuthorizationTableSql(exclusive?: boolean): string;
+declare function ensureTransitionJournal(executor: TransitionJournalQueryable): Promise<void>;
+declare function createPgTransitionRunPersister(executor: TransitionJournalQueryable): TransitionRunPersister;
+declare function appendIntentJournal(executor: TransitionJournalQueryable, record: DurableIntentRecord): Promise<void>;
+/** Append-only run approval, intentionally separate from step attempts. */
+declare function appendTransitionAuthorization(executor: TransitionJournalQueryable, record: TransitionRunAuthorization): Promise<void>;
+declare function readTransitionJournal(executor: TransitionJournalQueryable, runId: string, options?: {
+    readonly ensure?: boolean;
+}): Promise<TransitionRunJournal & {
+    readonly plan: ProvenPlanShape;
+}>;
+
+interface PgCatalogueIdentityQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+}
+/**
+ * Re-read the PostgreSQL catalogue identity for one managed address. The
+ * adapter deliberately returns absence as undefined; callers decide whether an
+ * absent object is legal for the lifecycle state they are admitting.
+ */
+declare function readPgCatalogueIdentity(executor: PgCatalogueIdentityQueryable, address: ResourceAddress): Promise<ResourceAddress | undefined>;
+
+declare const PG_LEDGER_SHAPE_VERSION = 1;
+declare const ledgerShapeAllowanceBrand: unique symbol;
+/**
+ * An in-process allowance for one non-ledger trigger observed immediately
+ * after trusted harness setup. Its contents are deliberately not structural:
+ * only the internal factory can register a value in the WeakSet below.
+ */
+interface PgLedgerShapeAllowance {
+    readonly [ledgerShapeAllowanceBrand]: 'dbsp-ledger-shape-allowance';
+}
+type PgLedgerPhysicalShapeOutcome = {
+    readonly kind: 'verified';
+} | {
+    readonly kind: 'shape-wrong';
+    readonly artefact: string;
+} | {
+    readonly kind: 'unverifiable';
+    readonly cause: string;
+} | {
+    readonly kind: 'unsupported-major';
+    readonly major: number | undefined;
+} | {
+    readonly kind: 'validator-abi-failure';
+    readonly sqlstate: string;
+};
+/**
+ * Read-only admission of an existing ledger.  A fixture is deliberately a
+ * prerequisite: deparse text is not portable across PostgreSQL majors.
+ */
+declare function classifyPgLedgerPhysicalShape(executor: TransitionJournalQueryable, target: PgLedgerTarget, allowance?: PgLedgerShapeAllowance): Promise<PgLedgerPhysicalShapeOutcome>;
+/**
+ * Throwing compatibility façade. Existing mutating callers intentionally keep
+ * their historical contract; outcome-aware consumers use `classify…`.
+ */
+declare function validatePgLedgerPhysicalShape(executor: TransitionJournalQueryable, target: PgLedgerTarget, allowance?: PgLedgerShapeAllowance): Promise<void>;
+/**
+ * Mint a one-request allowance for one exact live trigger. This is exported
+ * only from the adapter's `/internal` surface: consumers cannot forge the
+ * WeakMap registration or serialize it into an ordinary recovery request.
+ */
+declare function createPgLedgerShapeAllowance(executor: TransitionJournalQueryable, target: PgLedgerTarget, triggerName: string): Promise<PgLedgerShapeAllowance>;
+declare class PgLedgerStorageUnsupportedError extends Error {
+    constructor(observed: unknown);
+}
+declare const pgOrderedLedgerLocksBrand: unique symbol;
+/** Proof returned only after this transaction acquired every home in order. */
+interface PgOrderedLedgerLocks {
+    readonly homes: readonly PgLedgerTarget[];
+    readonly [pgOrderedLedgerLocksBrand]: 'dbsp-pg-ordered-ledger-locks';
+}
+type PgLedgerLockResult = {
+    readonly kind: 'acquired';
+    readonly proof: PgOrderedLedgerLocks;
+} | {
+    readonly kind: 'busy';
+    readonly ledger: LedgerHome;
+} | {
+    readonly kind: 'refused';
+    readonly ledger: LedgerHome;
+    readonly error: unknown;
+};
+type PgLedgerTarget = LedgerHome;
+/** Read only reservations explicitly linked to one durable execution/run. */
+declare function readPgLedgerReservationsForExecution(executor: TransitionJournalQueryable, target: PgLedgerTarget, executionId: string): Promise<readonly LedgerReservationRow[]>;
+/**
+ * A re-address pair can cross ledger homes. Discover every existing reservation
+ * table before reading the pair so recovery cannot accidentally treat one side
+ * of a cross-schema closure as the entire operation.
+ */
+type PgLedgerReservationCandidateOutcome = {
+    readonly target: PgLedgerTarget;
+    readonly kind: 'verified';
+} | {
+    readonly target: PgLedgerTarget;
+    readonly kind: 'not-ledger-shape';
+} | {
+    readonly target: PgLedgerTarget;
+    readonly kind: 'unverifiable';
+    readonly cause: string;
+};
+type PgLedgerReservationsForPair = readonly LedgerReservationRow[] & {
+    readonly candidates: readonly PgLedgerReservationCandidateOutcome[];
+};
+declare function readPgLedgerReservationsForPair(executor: TransitionJournalQueryable, pairId: string): Promise<PgLedgerReservationsForPair>;
+type LedgerWriteMember = Omit<LedgerChainMember, 'controller' | 'recordedAt'>;
+declare function renderCreateLedgerEventTableSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerTerminalMemberIndexSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerReservationTableSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerIdentityTableSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerMarkerTableSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerImmutabilityFunctionSql(target: PgLedgerTarget): string;
+declare function renderCreateLedgerImmutabilityTriggerSql(target: PgLedgerTarget): string;
+/** Proves the PG 15 requirement before emitting a NULLS NOT DISTINCT table. */
+declare function ensurePgLedgerStorageVersion(executor: TransitionJournalQueryable): Promise<void>;
+declare function ensurePgLedger(executor: TransitionJournalQueryable, target: PgLedgerTarget, options?: {
+    readonly writeMarker?: boolean;
+}): Promise<void>;
+declare function ensureDbspMetaLedger(executor: TransitionJournalQueryable, options?: {
+    readonly writeMarker?: boolean;
+}): Promise<void>;
+/** Records lineage once; a mismatching identity is an admission concern of unit 5. */
+declare function recordPgLedgerIdentity(executor: TransitionJournalQueryable, target: PgLedgerTarget, identity: LedgerIdentity): Promise<void>;
+declare function appendPgLedgerProgress(executor: TransitionJournalQueryable, target: PgLedgerTarget, member: LedgerWriteMember): Promise<void>;
+/**
+ * Appends the root claim and every reservation in one PostgreSQL statement.
+ * Callers can include this statement in a larger DDL transaction, but cannot
+ * accidentally split this claim's append from its durable reservation rows.
+ */
+declare function appendPgLedgerClaim(executor: TransitionJournalQueryable, target: PgLedgerTarget, member: LedgerWriteMember, reservations: readonly LedgerReservationRow[], reservationRootClaimId?: string): Promise<void>;
+/**
+ * Appends an entire destructive closure as one ledger group.  The caller owns
+ * the surrounding locked transaction; consequently a failed member insert
+ * rolls back the root, every member and every reservation together.
+ */
+declare function appendPgLedgerClaimGroup(executor: TransitionJournalQueryable, root: LedgerWriteMember, members: readonly LedgerWriteMember[], reservations: readonly LedgerReservationRow[]): Promise<void>;
+/** Resolves every closure terminal in the caller's one locked transaction. */
+declare function appendPgLedgerResolutionGroup(executor: TransitionJournalQueryable, rootClaimId: string, members: readonly LedgerWriteMember[], reservations: readonly Pick<LedgerReservationRow, 'address'>[]): Promise<void>;
+/**
+ * Appends a terminal member and releases the reservations owned by this
+ * append atomically. A group-owned contained member has an intentionally
+ * empty closure because its group's root append already released it.
+ */
+declare function appendPgLedgerResolution(executor: TransitionJournalQueryable, target: PgLedgerTarget, member: LedgerWriteMember, rootClaimId: string, reservations: readonly Pick<LedgerReservationRow, 'address'>[]): Promise<void>;
+/**
+ * `released` has no claim spelling in the closed event grammar. It is the
+ * deliberate atomic managed-to-unknown transition, so it must not invent an
+ * empty reservation closure merely to reuse ordinary claim resolution.
+ */
+declare function appendPgLedgerRelease(executor: TransitionJournalQueryable, target: PgLedgerTarget, member: LedgerWriteMember): Promise<void>;
+/**
+ * Transaction-scoped, non-waiting locks for one effects closure. The ordering
+ * is dbsp_meta first and then schema name, so opposing closures cannot deadlock.
+ */
+declare function acquirePgLedgerLocks(executor: TransitionJournalQueryable, homes: readonly LedgerHome[]): Promise<PgLedgerLockResult>;
+
+type ReinitializePreflightCheckpoint = 'archive' | 'create' | 'grants' | 'journal-create' | 'marker' | 'output';
+/** Test-only callers can observe real engine progress without changing production flow. */
+type ReinitializePreflightObserver = (checkpoint: ReinitializePreflightCheckpoint, ledger?: LedgerHome) => Promise<void>;
+interface PgReinitializePreflightClient extends TransitionJournalQueryable {
+    release?(error?: unknown): void;
+}
+interface PgReinitializePreflightPool {
+    connect(): Promise<PgReinitializePreflightClient>;
+}
+interface PgReinitializePreflightOptions {
+    readonly pool: PgReinitializePreflightPool;
+    /** Schema names only. `dbsp_meta` is always added as the database ledger. */
+    readonly schemas: readonly string[];
+    readonly declarations: DeclarationSet;
+    readonly writeAdoptionFile: (report: ReinitializePreflightReport) => Promise<void>;
+    readonly observer?: ReinitializePreflightObserver;
+}
+/**
+ * Read exactly one ledger shape marker without creating or repairing anything.
+ * Ordinary command surfaces use this to refuse a non-current mutating scope;
+ * inspect deliberately reports the returned value instead.
+ */
+declare function readPgLedgerMarker(executor: TransitionJournalQueryable, home: LedgerHome): Promise<LedgerMarkerState>;
+/**
+ * Ordinary mutating commands consume this read-only admission result.  It
+ * intentionally delegates equality to the preflight's recorded-vs-live
+ * comparison, keeping that pair as the only ledger lineage comparison.
+ */
+type PgLedgerScopeCurrency = {
+    readonly kind: 'absent';
+    readonly marker: LedgerMarkerState;
+} | {
+    readonly kind: 'current';
+    readonly marker: LedgerMarkerState;
+} | {
+    readonly kind: 'not-current';
+    readonly marker: LedgerMarkerState;
+    readonly reason: 'marker' | 'lineage';
+};
+declare function readPgLedgerScopeCurrency(executor: TransitionJournalQueryable, home: LedgerHome): Promise<PgLedgerScopeCurrency>;
+/**
+ * Pair recovery reads only homes already selected by the durable run.  A
+ * same-named user table in another schema is never discovery evidence for a
+ * pair; callers must first establish the finite candidate homes from reviewed
+ * material and then each home is admitted here.
+ */
+declare function readVerifiedPgLedgerReservationsForPair(executor: TransitionJournalQueryable, pairId: string, homes: readonly LedgerHome[]): Promise<readonly _dbsp_types.LedgerReservationRow[]>;
+/**
+ * Runs the separately privileged reinitialize-preflight. It never invokes a
+ * ledger append primitive: the only durable writes are additive structure,
+ * archived structure, identity, grants, marker, and the caller-owned output.
+ */
+declare function runPgReinitializePreflight(options: PgReinitializePreflightOptions): Promise<ReinitializePreflightReport>;
+
+declare const pgLockedRunBrand: unique symbol;
+/**
+ * A run identity that was loaded while the caller owns its run lock.  This is
+ * deliberately not a structural `{ runId, planDigest }`: callers cannot bind
+ * the digest check to two independently supplied strings.
+ */
+interface PgLockedRun {
+    readonly runId: string;
+    readonly planDigest: string;
+    readonly [pgLockedRunBrand]: 'dbsp-pg-locked-journal-run';
+}
+/**
+ * Adapter-only bridge from the journal-load/run-lock boundary.  Keep this
+ * beside the admitted facade; ordinary callers receive a `PgLockedRun`, never
+ * manufacture one from string fields.
+ */
+declare function lockPgJournalRun(run: DurablyLoadedRun): PgLockedRun;
+/** A COMMIT write may have reached PostgreSQL even when its acknowledgement did not. */
+declare class PgCommitAcknowledgementAmbiguousError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Test-only observation points on the admitted path.  Production callers do
+ * not supply an observer, so the helper is inert: it performs no IPC, I/O, or
+ * scheduling work in an ordinary run.
+ */
+type PgOutcomeCheckpoint = 'post-lock-integrity-before-append' | 'commit-acknowledged' | 'ddl-completed-before-read-back';
+type PgOutcomeCheckpointObserver = (checkpoint: PgOutcomeCheckpoint) => Promise<void> | void;
+interface PgOutcomeClaimRequest {
+    readonly plan: OutcomeClaimPlan;
+    readonly reservations: readonly LedgerReservationRow[];
+    readonly lockTimeoutMs?: number;
+    /** Destructive authority is evaluated under these same ledger locks. */
+    readonly destructiveDecision?: (executor: TransitionJournalQueryable, plan: OutcomeClaimPlan) => Promise<DestructiveDecision>;
+    /** Optional E2E observer; absent in all production command paths. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+}
+/** One root claim plus its token-free destructive-closure members. */
+interface PgOutcomeClaimGroupRequest extends PgOutcomeClaimRequest {
+    readonly members: readonly Omit<PgOutcomeClaimRequest, 'destructiveDecision'>[];
+}
+interface PgOutcomeClaimGroupAdmission {
+    readonly root: OutcomeClaimAdmission;
+    readonly members: readonly OutcomeClaimAdmission[];
+}
+interface PgOutcomeClaimGroupResolution {
+    readonly rootClaimId: string;
+    readonly members: readonly {
+        readonly target: PgLedgerTarget;
+        readonly member: Omit<LedgerChainMember, 'controller' | 'recordedAt'>;
+    }[];
+    readonly reservations: readonly Pick<LedgerReservationRow, 'address'>[];
+    readonly lockTimeoutMs?: number;
+    /** Durable run witness carried from destructive admission to its terminal. */
+    readonly runtimeIntegrityRun?: PgLockedRun;
+    /** Optional E2E observer for this terminal-appending transaction. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+}
+interface PgOutcomeResolution {
+    readonly eventId: string;
+    readonly eventKind: Exclude<LedgerEventKind, 'intent' | 'retire-intent' | 'readdress-intent' | 'adopt-intent' | 'executing'>;
+    readonly observed?: LedgerChainMember['observed'];
+    /** Required by the ledger writer when this resolution is `refused`. */
+    readonly refusal?: LedgerChainMember['refusal'];
+}
+interface PgOutcomeExecutionRequest {
+    readonly token: ClaimToken;
+    readonly claim: AdmittedOutcomeClaim;
+    readonly statements: readonly ClaimBundleStatement[];
+}
+/**
+ * The first admitted-operation shape. Later waves add single and paired
+ * operation variants without reopening the facade's authority boundary.
+ */
+interface PgSingleAdmittedOperation {
+    readonly kind: 'single-outcome';
+    readonly request: PgOutcomeTransactionalRequest | PgOutcomeNonTransactionalRequest;
+}
+/**
+ * The three generated payload roles are intentionally disjoint at the type
+ * boundary. Their runtime serialization remains the ledger's `{ value,
+ * digest }` pair; the discriminant prevents a generic identity observation
+ * from being wired into a declaration or a structural-proof slot.
+ */
+type GeneratedDeclarationPayload = LedgerPayload & {
+    readonly payloadKind: 'generated-declaration';
+};
+type GeneratedIdentityObservation = LedgerPayload & {
+    readonly payloadKind: 'generated-identity-observation';
+};
+type GeneratedStructuralObservation = LedgerPayload & {
+    readonly payloadKind: 'generated-structural-observation';
+};
+/**
+ * Readdress keeps its catalogue closure discovery in readdress.ts, while this
+ * facade owns the only claim/permit/DDL/terminal path for the resulting pair.
+ */
+interface PgPairedReaddressOperation {
+    readonly kind: 'paired-readdress';
+    readonly request: {
+        readonly pairId: string;
+        readonly executionId: string;
+        readonly members: readonly {
+            readonly source: LedgerAddress;
+            readonly target: LedgerAddress;
+            readonly sourceClaimId: string;
+            readonly targetClaimId: string;
+            readonly sourceDeclared?: LedgerPayload;
+            readonly targetDeclared: GeneratedDeclarationPayload;
+            readonly targetObserved: GeneratedIdentityObservation;
+            /**
+             * Optional structural proof for a typed table declaration. The paired
+             * protocol invokes it after DDL on its pinned transaction session, so
+             * the observed ledger fact is the catalogue projection it just read.
+             */
+            readonly postDdlReadBack?: (executor: GeneratedPostconditionSession) => Promise<GeneratedStructuralObservation>;
+            /** Verifies a physical relationship that identity alone cannot prove. */
+            readonly postDdlVerify?: (executor: TransitionJournalQueryable) => Promise<void>;
+        }[];
+        readonly reservations: readonly LedgerReservationRow[];
+        readonly statements: readonly ClaimBundleStatement[];
+        /** Digest-covered root material for this paired request; it is never empty. */
+        readonly manifestPlan: OutcomeClaimPlan;
+        /** Re-read closure, source controller/identity and target vacancy under lock. */
+        readonly verifyLiveAdmission: (executor: TransitionJournalQueryable, currentController: ControllerIdentity) => Promise<OutcomeProtocolRefusal | readonly {
+            readonly source: LedgerAddress;
+            readonly target: LedgerAddress;
+            readonly catalogueIdentity: NonNullable<NonNullable<Awaited<ReturnType<typeof readPgCatalogueIdentity>>>['catalogueIdentity']>;
+        }[]>;
+        readonly lockTimeoutMs?: number;
+        /** Optional E2E observer; absent in normal execution. */
+        readonly observer?: PgOutcomeCheckpointObserver;
+    };
+}
+interface PgDestructiveAdmittedOperation {
+    readonly kind: 'destructive-outcome';
+    readonly request: PgOutcomeClaimGroupRequest;
+    readonly readBackAndResolve: (executor: TransitionJournalQueryable, claim: AdmittedDestructiveOutcomeClaim) => Promise<PgOutcomeClaimGroupResolution>;
+}
+type PgAdmittedOperation = PgSingleAdmittedOperation | PgPairedReaddressOperation | PgDestructiveAdmittedOperation;
+type PgAdmittedOperationResult = PgOutcomeResult | PgDestructiveOutcomeResult | {
+    readonly kind: 'executed-paired-readdress';
+    readonly pairId: string;
+} | {
+    readonly kind: 'outcome-transport-ambiguous';
+    readonly reason: string;
+} | {
+    readonly kind: 'outcome-recovery-required';
+    readonly claimId: string;
+    readonly reason: string;
+};
+type PgDestructiveOutcomeResult = {
+    readonly kind: 'executed-destructive-outcome';
+}
+/**
+ * SQL was admitted and may have run, but its operation-owned read-back could
+ * not establish a terminal fact.  Keep the durable claim open for reconcile;
+ * in particular, never turn this post-executing state into `refused`.
+ */
+ | {
+    readonly kind: 'outcome-protocol-pending';
+    readonly reason: string;
+} | OutcomeProtocolRefusal | {
+    readonly kind: 'outcome-transport-ambiguous';
+    readonly reason: string;
+} | {
+    readonly kind: 'outcome-recovery-required';
+    readonly claimId: string;
+    readonly reason: string;
+};
+/**
+ * Internal compatibility bridge. Callers must bring the durable run and scoped
+ * approvals that the façade consumes; this bridge never invents either.
+ */
+declare function executePgDestructiveOutcome(executor: TransitionJournalQueryable, input: {
+    readonly run: PgLockedRun;
+    readonly approval: ScopedApprovalSet;
+    readonly request: PgOutcomeClaimGroupRequest;
+    readonly readBackAndResolve: (executor: TransitionJournalQueryable, claim: AdmittedDestructiveOutcomeClaim) => Promise<PgOutcomeClaimGroupResolution>;
+}): Promise<PgDestructiveOutcomeResult>;
+/** Keeps terminal appends and reservation release behind the managed facade. */
+declare function resolvePgDestructiveOutcome(executor: TransitionJournalQueryable, request: PgOutcomeClaimGroupResolution): Promise<undefined | OutcomeProtocolRefusal>;
+interface PgOutcomeTransactionalRequest extends PgOutcomeClaimRequest {
+    readonly resolution: PgOutcomeResolution;
+    /** Core has already opened the segment transaction; never nest BEGIN. */
+    readonly transactionOpen?: boolean;
+    /**
+     * Operation-owned terminal read-back; generic catalogue identity is not
+     * evidence. It receives the admitted session so transactional DDL is read
+     * before its terminal ledger fact commits.
+     */
+    readonly readBack?: (executor: GeneratedPostconditionSession) => Promise<LedgerPayload>;
+    /** Required for creations; the reader runs after the claim and before SQL. */
+    readonly vacancy?: (executor: TransitionJournalQueryable, plan: OutcomeClaimPlan) => Promise<OutcomeVacancy>;
+    /** Re-check operation-specific live facts after the claim/reservation opens. */
+    readonly verifyLiveAdmission?: (executor: TransitionJournalQueryable, plan: OutcomeClaimPlan) => Promise<OutcomeProtocolRefusal | undefined>;
+    /** Record the post-DDL catalogue identity on a present terminal member. */
+    readonly recordCatalogueIdentity?: boolean;
+}
+interface PgOutcomeNonTransactionalRequest extends PgOutcomeTransactionalRequest {
+    readonly executingEventId: string;
+    /** Observable acknowledgement point after executing has committed, before SQL. */
+    readonly onExecutingCommitted?: () => Promise<void> | void;
+}
+/** Builds the canonical read-back payload once catalogue presence is proven. */
+type PgOutcomeReadBackFactory = (executor: GeneratedPostconditionSession, address: LedgerAddress, catalogueIdentity: NonNullable<Awaited<ReturnType<typeof readPgCatalogueIdentity>>>['catalogueIdentity']) => Promise<LedgerPayload>;
+/**
+ * A postcondition read owned by the operation itself.  Catalogue identity is
+ * still retained when present for the ledger, but effect classification comes
+ * from the operation's value-level observation rather than object presence.
+ */
+type PgOutcomeOperationReadBackFactory = (executor: TransitionJournalQueryable, address: LedgerAddress, catalogueIdentity: NonNullable<Awaited<ReturnType<typeof readPgCatalogueIdentity>>>['catalogueIdentity'] | undefined) => Promise<{
+    readonly observed: LedgerPayload;
+    readonly effect: OutcomeRecoveryEffect;
+}>;
+interface PgOutcomeRecoveryRequest {
+    readonly address: LedgerAddress;
+    readonly reservations: readonly Pick<LedgerReservationRow, 'address'>[];
+    readonly resolutionEventId: string;
+    readonly acceptedExternalDdlExclusion: boolean;
+    /** Durable claim-bound evidence re-matched by reconcile under the run lock. */
+    readonly indeterminateEvidence?: OutcomeIndeterminateRecoveryEvidence;
+    readonly resolveIndeterminate?: boolean;
+    readonly readBack: PgOutcomeReadBackFactory;
+    readonly operationReadBack?: PgOutcomeOperationReadBackFactory;
+    readonly lockTimeoutMs?: number;
+    /** Internal-only, in-memory allowance for one harness-installed trigger. */
+    readonly ledgerShapeAllowance?: PgLedgerShapeAllowance;
+    /** Optional E2E observer for recovery's committing transaction. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+}
+type PgOutcomeResolutionAppendResult = {
+    readonly kind: 'appended-outcome-resolution';
+} | {
+    readonly kind: 'already-appended-outcome-resolution';
+} | {
+    readonly kind: 'malformed-outcome-resolution';
+    readonly reason: string;
+};
+type PgOutcomeRecoveryResult = Exclude<OutcomeRecoveryClassification, {
+    readonly kind: 'outcome-recovery-append';
+}> | {
+    readonly kind: 'outcome-recovery-appended';
+    readonly classification: Extract<OutcomeRecoveryClassification, {
+        readonly kind: 'outcome-recovery-append';
+    }>;
+    readonly append: Exclude<PgOutcomeResolutionAppendResult, {
+        readonly kind: 'malformed-outcome-resolution';
+    }>;
+} | {
+    readonly kind: 'outcome-transport-ambiguous';
+    readonly reason: string;
+} | OutcomeProtocolRefusal;
+type PgOutcomeResult = {
+    readonly kind: 'executed-outcome-claim';
+    readonly claim: AdmittedOutcomeClaim;
+} | OutcomeProtocolRefusal | {
+    readonly kind: 'outcome-transport-ambiguous';
+    readonly reason: string;
+} | {
+    readonly kind: 'outcome-recovery-required';
+    readonly claimId: string;
+    readonly reason: string;
+};
+type PgPairedReaddressRecoveryDecision = {
+    readonly kind: 'refused';
+    readonly reason: string;
+} | {
+    readonly kind: 'pending';
+    readonly reason: string;
+} | {
+    readonly kind: 'indeterminate';
+    readonly reason: string;
+} | {
+    readonly kind: 'outcome-transport-ambiguous';
+    readonly reason: string;
+};
+/**
+ * Recovery owns its reservation set: it re-reads every durable pair row,
+ * checks currency under the same locks, and appends only under a minted paired
+ * permit. A caller's selected rows are evidence to compare, never authority.
+ */
+declare function recoverPgAdmittedReaddressPair(executor: TransitionJournalQueryable, request: {
+    readonly pairId: string;
+    readonly executionId: string;
+    readonly reservations: readonly LedgerReservationRow[];
+    readonly assess: (executor: TransitionJournalQueryable, reservations: readonly LedgerReservationRow[]) => Promise<PgPairedReaddressRecoveryDecision>;
+    readonly observer?: PgOutcomeCheckpointObserver;
+}): Promise<PgPairedReaddressRecoveryDecision>;
+type RuntimeIntegritySeams = {
+    readonly validateShape: typeof validatePgLedgerPhysicalShape;
+    readonly readCurrency: typeof readPgLedgerScopeCurrency;
+};
+/**
+ * The façade's runtime gate: validate the physical ledger and its marker /
+ * lineage currency on the same pinned execution session before it admits DDL.
+ * Callers must still take the ledger locks before claiming; this check avoids a
+ * preflight-only trust decision without widening the ledger DDL grammar.
+ */
+declare function validatePgLedgerRuntimeIntegrity(executor: TransitionJournalQueryable, homes: readonly PgLedgerTarget[], run?: PgLockedRun, seams?: RuntimeIntegritySeams): Promise<OutcomeProtocolRefusal | undefined>;
+/**
+ * Appends a resolution once, or treats an already-written equal payload as a
+ * successful retry. A different child cannot be written by PostgreSQL's
+ * one-child constraint and is reported as a fail-closed malformed outcome.
+ */
+declare function appendPgOutcomeResolution(executor: TransitionJournalQueryable, target: PgLedgerTarget, member: Omit<LedgerChainMember, 'controller' | 'recordedAt'>, rootClaimId: string, reservations: readonly Pick<LedgerReservationRow, 'address'>[]): Promise<PgOutcomeResolutionAppendResult>;
+/**
+ * Standalone PostgreSQL catalogue read-back. This intentionally does not
+ * issue LOCK TABLE: callers may supply a Pool, and protocol atomicity belongs
+ * to the transaction-bound recovery and observed-resolution paths.
+ */
+declare function readPgOutcomeRecoveryReadBack(executor: TransitionJournalQueryable, address: LedgerAddress, readBack: PgOutcomeReadBackFactory, operationReadBack?: PgOutcomeOperationReadBackFactory, lockTimeoutMs?: number): Promise<OutcomeRecoveryReadBack>;
+/** Opens a claim on one connection when supplied a PostgreSQL pool. */
+declare function openPgOutcomeClaim(executor: TransitionJournalQueryable, request: PgOutcomeClaimRequest, run?: PgLockedRun): Promise<OutcomeClaimAdmission>;
+/**
+ * Opens a root and all closure claims under globally ordered ledger locks in
+ * one transaction.  No child is ever durable before its root group commits.
+ */
+declare function openPgOutcomeClaimGroup(executor: TransitionJournalQueryable, request: PgOutcomeClaimGroupRequest, run?: PgLockedRun): Promise<PgOutcomeClaimGroupAdmission>;
+/** Resolves every member terminal atomically under the same ordered locks. */
+declare function resolvePgOutcomeClaimGroup(executor: TransitionJournalQueryable, request: PgOutcomeClaimGroupResolution): Promise<undefined | OutcomeProtocolRefusal>;
+/**
+ * The public PostgreSQL admitted-execution boundary. It is intentionally not
+ * used by legacy paths yet: later dispatches bind their persisted runs and
+ * operation shapes here without changing this authority surface.
+ */
+declare function executePgAdmittedOperation(session: TransitionJournalQueryable, input: {
+    readonly run: PgLockedRun;
+    readonly operation: PgAdmittedOperation;
+    readonly approval: ScopedApprovalSet;
+    /** Branded proof that the operation came from the normalized manifest. */
+    readonly manifest?: ValidatedManagedStepManifest;
+    /** Recomputed from the durable plan while the caller owns its run lock. */
+    readonly recomputedPlanDigest?: string;
+}): Promise<PgAdmittedOperationResult>;
+/**
+ * Reads an address's chain and live catalogue in one locked transaction before
+ * appending the core classifier's instruction. It never calls the DDL sink.
+ */
+declare function recoverPgOutcomeClaim(executor: TransitionJournalQueryable, request: PgOutcomeRecoveryRequest): Promise<PgOutcomeRecoveryResult>;
+
+export { type PgAdvisoryLockResult as $, type AddedEnumValue as A, GeneratedPostconditionReplanRequiredError as B, type ChangeKind as C, DEFAULT_PK_COLUMN as D, ExpressionCanonicalizationUnavailableError as E, type FkColumnDerivation as F, type GeneratedPostconditionSession as G, GeneratedPostconditionSessionDeactivatedError as H, GeneratedPostconditionWorkInFlightError as I, IdentityNamingPlugin as J, type IndexCapabilityContext as K, IndexFeatureUnsupportedError as L, IndexPredicateCanonicalizationError as M, type NamingPlugin as N, type IndexRenderSpec as O, type PgLockedRun as P, type IntrospectedModelIR as Q, type IntrospectionOptions as R, type MigrationSQLOptions as S, type TransitionJournalQueryable as T, NonConvergentSchemaDiffError as U, type NonConvergentSchemaDiffSurface as V, PG_LEDGER_SHAPE_VERSION as W, PartialIndexPredicateNewEnumValueError as X, type PgAdmittedOperation as Y, type PgAdmittedOperationResult as Z, type PgAdvisoryLockKey as _, type PgOutcomeCheckpointObserver as a, assertCreateIndexesSupported as a$, type PgApplicationStepOwnedState as a0, type PgApplicationStepTx as a1, type PgCatalogueIdentityQueryable as a2, type PgConvergeApplicationStep as a3, type PgConvergeAssertStep as a4, type PgConvergeInitializationFailure as a5, type PgConvergeOnceStep as a6, type PgConvergePlannedStep as a7, type PgConvergeRefusal as a8, type PgConvergeRefusalChange as a9, type PgsqlAdapterOptions as aA, PgsqlAdvisoryLockOptionsError as aB, type PgsqlBorrowedClientAdapterOptions as aC, type PgsqlCompileOnlyAdapterOptions as aD, PgsqlPinnedConnectionAbortSignalError as aE, type PgsqlPoolAdapterOptions as aF, PgsqlPreparedStatementReplayError as aG, type PgsqlPreparedStatementsOptions as aH, PgsqlRawSqlTransactionControlError as aI, PgsqlTransactionAbortSignalError as aJ, PgsqlTransactionAbortedCommitError as aK, PgsqlTransactionAbortedError as aL, PgsqlTransactionOptionsError as aM, PgsqlTransactionTimeoutError as aN, RawIndexPredicateFallbackError as aO, type ReferencedKeyKind as aP, type ReferencedKeyRemovalConflict as aQ, ReferencedKeyRemovalError as aR, type RollbackOnlyPgsqlScope as aS, type SchemaChange as aT, type SchemaDiff as aU, type SchemaScopeOptions as aV, TransitionRunIdentityMismatchError as aW, acquirePgLedgerLocks as aX, appendIntentJournal as aY, appendTransitionAuthorization as aZ, assertCreateIndexSupported as a_, PgConvergeRefusalError as aa, type PgLedgerLockResult as ab, PgLedgerStorageUnsupportedError as ac, type PgLedgerTarget as ad, type PgOutcomeCheckpoint as ae, type PgOutcomeClaimRequest as af, type PgOutcomeExecutionRequest as ag, type PgOutcomeNonTransactionalRequest as ah, type PgOutcomeReadBackFactory as ai, type PgOutcomeRecoveryRequest as aj, type PgOutcomeRecoveryResult as ak, type PgOutcomeResolution as al, type PgOutcomeResolutionAppendResult as am, type PgOutcomeResult as an, type PgOutcomeTransactionalRequest as ao, type PgOwnedCheckState as ap, type PgPhysicalModelInput as aq, PgPhysicalModelInputError as ar, type PgPhysicalNameClaim as as, type PgPhysicalNameCollision as at, PgPhysicalNameCollisionError as au, type PgPhysicalNamespace as av, type PgReinitializePreflightOptions as aw, type PgReinitializePreflightPool as ax, type PgSchemaDiff as ay, PgsqlAdapter as az, type ConvergePgOptions as b, type ComparePgsqlDeclaredAdoptionSchemaInput as b$, assertDeclarableChangeKind as b0, assertGeneratedPostconditionSession as b1, assertNoRepeatedExpressionSurfaceDrift as b2, camelCaseNaming as b3, canGenerateCreateIndex as b4, canonicalizeCheckConstraints as b5, comparePgsqlDatabaseSchema as b6, compareSchemata as b7, createPgPhysicalModel as b8, createPgTransitionRunPersister as b9, recordPgLedgerIdentity as bA, renderCreateDbspMetaSchemaSql as bB, renderCreateIndex as bC, renderCreateLedgerEventTableSql as bD, renderCreateLedgerIdentityTableSql as bE, renderCreateLedgerImmutabilityFunctionSql as bF, renderCreateLedgerImmutabilityTriggerSql as bG, renderCreateLedgerMarkerTableSql as bH, renderCreateLedgerReservationTableSql as bI, renderCreateLedgerTerminalMemberIndexSql as bJ, renderCreateTransitionAuthorizationTableSql as bK, renderCreateTransitionJournalTableSql as bL, renderCreateTransitionRunPlanTableSql as bM, renderCreateTransitionRunTableSql as bN, runPgReinitializePreflight as bO, toGeneratedPostconditionBindingAddress as bP, validatePgLedgerRuntimeIntegrity as bQ, verifyGeneratedCheckPostcondition as bR, verifyGeneratedColumnPostcondition as bS, verifyGeneratedIdentityPostcondition as bT, verifyGeneratedIndexPostcondition as bU, verifyGeneratedTablePostcondition as bV, withGeneratedPostconditionSession as bW, type PgOrderedLedgerLocks as bX, type PgLedgerShapeAllowance as bY, type PgLedgerPhysicalShapeOutcome as bZ, type ComparePgsqlDatabaseSchemaOptions$1 as b_, createPgsqlAdapter as ba, createPgsqlCompileOnlyAdapter as bb, createPgsqlGeneratedManagedStep as bc, decodeGeneratedPostcondition as bd, decodeGeneratedPostconditionPayload as be, defaultFkDerivation as bf, ensureDbspMetaLedger as bg, ensurePgLedger as bh, ensurePgLedgerStorageVersion as bi, ensureTransitionJournal as bj, executePgAdmittedOperation as bk, generateCreateIndex as bl, generateDDL as bm, generateDownSQL as bn, generateMigrationSQL as bo, generatedPostconditionDigest as bp, generatedPostconditionForChange as bq, getNamingPluginForDbCasing as br, identityNaming as bs, introspect as bt, readPgCatalogueIdentity as bu, readPgLedgerMarker as bv, readPgLedgerReservationsForExecution as bw, readPgLedgerScopeCurrency as bx, readPgOutcomeRecoveryReadBack as by, readVerifiedPgLedgerReservationsForPair as bz, type PgPhysicalModel as c, type CompareSchemataOptions$1 as c0, type ConvergePgBaseOptions as c1, type ConvergePgCheckOptions as c2, type GenerateDDLOptions$1 as c3, type MigrationSQLOptions$1 as c4, PgCommitAcknowledgementAmbiguousError as c5, type PgsqlAdoptionComparisonExecutor as c6, appendPgLedgerClaim as c7, appendPgLedgerClaimGroup as c8, appendPgLedgerProgress as c9, resolvePgDestructiveOutcome as cA, resolvePgOutcomeClaimGroup as cB, appendPgLedgerRelease as ca, appendPgLedgerResolution as cb, appendPgLedgerResolutionGroup as cc, appendPgOutcomeResolution as cd, classifyPgLedgerPhysicalShape as ce, collectReferencedKeyRemovalConflicts as cf, comparePgsqlDatabaseSchema$1 as cg, comparePgsqlDeclaredAdoptionSchema as ch, compareSchemata$1 as ci, convergePg as cj, createPgLedgerShapeAllowance as ck, createPgsqlDeclaredAdoptionStep as cl, createPgsqlDeclaredSequenceAdoptionStep as cm, executePgDestructiveOutcome as cn, generateDDL$1 as co, generateDownSQL$1 as cp, generateMigrationSQL$1 as cq, lockPgJournalRun as cr, modelForDeclaredAdoption as cs, openPgOutcomeClaim as ct, openPgOutcomeClaimGroup as cu, pgsqlDeclaredAdoptionDeclaration as cv, pgsqlDeclaredSequenceAdoptionDeclaration as cw, readPgLedgerReservationsForPair as cx, recoverPgAdmittedReaddressPair as cy, recoverPgOutcomeClaim as cz, type PgConvergeResult as d, type PgConvergeCheckResult as e, type PgLedgerScopeCurrency as f, AutoIncrementTransitionUnsupportedError as g, CamelCaseNamingPlugin as h, type CanonicalizeCheckConstraintsOptions as i, CheckConstraintCanonicalizationError as j, type CheckConstraintCanonicalizationWarning as k, CheckConstraintNewEnumValueError as l, ColumnDefaultCanonicalizationError as m, type ColumnDefaultCanonicalizationWarning as n, type ComparePgsqlDatabaseSchemaOptions as o, type CompareSchemataOptions as p, type DetectedHierarchy as q, readTransitionJournal as r, type DiffSummary as s, type ExpressionCanonicalizationWarning as t, ExpressionKeyedIndexPredicateCanonicalizationUnsupportedError as u, type GenerateDDLOptions as v, type GeneratedPostcondition as w, type GeneratedPostconditionBindingAddress as x, GeneratedPostconditionBindingResolutionError as y, GeneratedPostconditionProofInFlightError as z };