@dbsp/adapter-pgsql 3.5.1 → 5.0.0

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import * as _dbsp_core from '@dbsp/core';
-import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, TransitionRunPersister, ExecutionCoordinator, CapabilityDescriptor } from '@dbsp/core';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, ValidatedManagedStepManifest, ExecutionCoordinator, CapabilityDescriptor } from '@dbsp/core';
 export { normalizeSQL } from '@dbsp/core';
 import * as _dbsp_types from '@dbsp/types';
-import { DialectCapabilities, ModelIR, ColumnListInput, ParamIntent, JsonAggOrderByEntry, IndexIR, HierarchyIR, Adapter, DbCasing, 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, ColumnIR, MutationReturningItem, WhereIntent, OutputDescriptor, QueryIntent, OperationKindRef, SemanticArtifactRef, ProvenPlanShape, PostgreSqlObservationTargetIdentity, ExecutionContract, TransitionSessionClient, TransitionRunJournal, TransitionLessor, ObservationIssuer, ObservationRequest, ObservationContext, EvidenceObservation, TypeRef, ExpressionValue, CollationRef, LogicalIdentity, PhysicalOperation, OperationEffectAssessment, FingerprintManifest, DurableIntentRecord, IssuedObservation, ApplyGuard, AdvisoryObservation, TransactionalCompletionRecord, StepJournal, UnsafeNativeFragment, ResourceAddress, ExecutableAssertion, Assumption, TransitionRule, TransitionCompositionFact, TrustRoot, RequiredEnumLabelIR } from '@dbsp/types';
+import { DialectCapabilities, ModelIR, ColumnListInput, ParamIntent, JsonAggOrderByEntry, IndexIR, HierarchyIR, Adapter, DbCasing, 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, ColumnIR, MutationReturningItem, WhereIntent, OutputDescriptor, QueryIntent, LedgerHome, LedgerAddress, LedgerPayload, ScopedApprovalSet, NormalizedManagedStep, LedgerChainMember, OperationKindRef, SemanticArtifactRef, ProvenPlanShape, PostgreSqlObservationTargetIdentity, ExecutionContract, TransitionSessionClient, TransitionLessor, ExclusiveTransitionTarget, ObservationIssuer, ObservationRequest, ObservationContext, EvidenceObservation, TypeRef, ExpressionValue, CollationRef, LogicalIdentity, PhysicalOperation, OperationEffectAssessment, FingerprintManifest, DurableIntentRecord, IssuedObservation, ApplyGuard, AdvisoryObservation, TransactionalCompletionRecord, StepJournal, UnsafeNativeFragment, ResourceAddress, ExecutableAssertion, Assumption, TransitionRule, TransitionCompositionFact, TrustRoot, RequiredEnumLabelIR, TableReaddressDeclaration, LedgerReservationRow, LedgerRefusal, ContainmentClosureDestructiveOutcome, LedgerClaimKind } from '@dbsp/types';
 import * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
+import { C as ChangeKind, a as CompareSchemataOptions, S as SchemaDiff, T as TransitionJournalQueryable, P as PgLockedRun, b as PgOutcomeCheckpointObserver } from './outcome-protocol-CACJDzli.js';
+export { D as DiffSummary, E as ExpressionCanonicalizationUnavailableError, G as GeneratedPostcondition, c as GeneratedPostconditionBindingAddress, d as GeneratedPostconditionBindingResolutionError, e as GeneratedPostconditionProofInFlightError, f as GeneratedPostconditionReplanRequiredError, g as GeneratedPostconditionSession, h as GeneratedPostconditionSessionDeactivatedError, i as GeneratedPostconditionWorkInFlightError, j as PG_LEDGER_SHAPE_VERSION, k as PgAdmittedOperation, l as PgAdmittedOperationResult, m as PgCatalogueIdentityQueryable, n as PgLedgerLockResult, o as PgLedgerScopeCurrency, p as PgLedgerStorageUnsupportedError, q as PgLedgerTarget, r as PgOutcomeCheckpoint, s as PgOutcomeClaimRequest, t as PgOutcomeExecutionRequest, u as PgOutcomeNonTransactionalRequest, v as PgOutcomeReadBackFactory, w as PgOutcomeRecoveryRequest, x as PgOutcomeRecoveryResult, y as PgOutcomeResolution, z as PgOutcomeResolutionAppendResult, A as PgOutcomeResult, B as PgOutcomeTransactionalRequest, F as PgReinitializePreflightOptions, H as PgReinitializePreflightPool, I as SchemaChange, J as TransitionRunIdentityMismatchError, K as acquirePgLedgerLocks, L as appendIntentJournal, M as appendTransitionAuthorization, N as assertDeclarableChangeKind, O as assertGeneratedPostconditionSession, Q as compareSchemata, R as createPgTransitionRunPersister, U as createPgsqlGeneratedManagedStep, V as decodeGeneratedPostcondition, W as decodeGeneratedPostconditionPayload, X as ensureDbspMetaLedger, Y as ensurePgLedger, Z as ensurePgLedgerStorageVersion, _ as ensureTransitionJournal, $ as executePgAdmittedOperation, a0 as generatedPostconditionDigest, a1 as generatedPostconditionForChange, a2 as readPgCatalogueIdentity, a3 as readPgLedgerMarker, a4 as readPgLedgerReservationsForExecution, a5 as readPgLedgerScopeCurrency, a6 as readPgOutcomeRecoveryReadBack, a7 as readTransitionJournal, a8 as readVerifiedPgLedgerReservationsForPair, a9 as recordPgLedgerIdentity, aa as renderCreateDbspMetaSchemaSql, ab as renderCreateLedgerEventTableSql, ac as renderCreateLedgerIdentityTableSql, ad as renderCreateLedgerImmutabilityFunctionSql, ae as renderCreateLedgerImmutabilityTriggerSql, af as renderCreateLedgerMarkerTableSql, ag as renderCreateLedgerReservationTableSql, ah as renderCreateLedgerTerminalMemberIndexSql, ai as renderCreateTransitionAuthorizationTableSql, aj as renderCreateTransitionJournalTableSql, ak as renderCreateTransitionRunPlanTableSql, al as renderCreateTransitionRunTableSql, am as runPgReinitializePreflight, an as toGeneratedPostconditionBindingAddress, ao as validatePgLedgerRuntimeIntegrity, ap as verifyGeneratedCheckPostcondition, aq as verifyGeneratedColumnPostcondition, ar as verifyGeneratedIdentityPostcondition, as as verifyGeneratedIndexPostcondition, at as verifyGeneratedTablePostcondition, au as withGeneratedPostconditionSession } from './outcome-protocol-CACJDzli.js';
 import { Pool, PoolClient } from 'pg';
+import '@dbsp/core/internal';
 
 /**
  * Default primary key column name used as convention fallback
@@ -290,6 +293,8 @@ interface WhereHandler {
 }
 /**
  * Dispatcher for recursive WHERE compilation.
+ * The same function object may be passed to every level of a recursive compilation, so it is an opaque callback.
+ * Handlers must not use its identity to distinguish frames or carry frame-local state.
  */
 type WhereDispatcher = (decision: Decision, ctx: CompilerContext, state: CompilerState) => Node;
 /**
@@ -728,6 +733,8 @@ declare class PlanCompiler {
  */
 declare function compilePlan(plan: SimplifiedPlanReport, options?: CompilerOptions): CompiledResult;
 
+declare function dbTypesEqual(a: string, b: string): boolean;
+
 type IndexRenderKey = {
     readonly column?: string | undefined;
     readonly expression?: string | undefined;
@@ -744,6 +751,8 @@ type IndexRenderSpec = {
     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;
 };
@@ -803,7 +812,7 @@ interface GenerateDDLOptions {
  * @returns Array of DDL statements in dependency order
  */
 declare function generateDDL(schema: ModelIR, options?: GenerateDDLOptions): string[];
-declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin, context?: IndexCapabilityContext): string;
+declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin, context?: IndexCapabilityContext, ifNotExists?: boolean): string;
 /**
  * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
  *
@@ -813,6 +822,25 @@ declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName
  */
 declare function canGenerateCreateIndex(tableName: string, idx: IndexIR, schemaName?: string | undefined, naming?: NamingPlugin): boolean;
 
+/** EFF-04's closed generated-mutation result domain. */
+type GeneratedMutationClassification = 'non-destructive' | 'removal' | 'data-destructive'
+/** A table rename is executed only by the paired re-address protocol. */
+ | 'paired-readdress';
+/**
+ * Total, fail-closed classifier for generator mutations. `string` is deliberate:
+ * a newly-added ChangeKind cannot silently become safe before this table names it.
+ */
+declare function classifyGeneratedMutation(kind: ChangeKind | string, change?: {
+    readonly destructive?: boolean;
+}): GeneratedMutationClassification;
+declare function isGeneratedMutationDestructive(kind: ChangeKind | string, change?: {
+    readonly destructive?: boolean;
+}): boolean;
+/** All removal statements remain generator-only; no transition operation maps one. */
+declare function refusesRecordedPlanRemoval(kind: ChangeKind | string, change?: {
+    readonly destructive?: boolean;
+}): boolean;
+
 /**
  * PostgreSQL Schema Introspection (ADAPTER-006)
  *
@@ -957,6 +985,23 @@ declare class PgsqlTransactionTimeoutError extends Error {
     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.
  */
@@ -988,10 +1033,45 @@ interface PgsqlAdapterOptions {
      */
     readonly preparedStatements?: boolean | PgsqlPreparedStatementsOptions;
 }
-interface PgsqlPoolAdapterOptions extends PgsqlAdapterOptions {
+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;
     /**
@@ -1021,6 +1101,10 @@ interface PgsqlBorrowedClientAdapterOptions extends PgsqlAdapterOptions {
      */
     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.
  *
@@ -1051,6 +1135,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private readonly naming;
     private readonly model;
     private readonly logger;
+    private readonly replayInvalidatedPlans;
     private readonly preparedStatements;
     private readonly preparedStatementRegistry;
     private readonly _capabilities;
@@ -1068,10 +1153,9 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      *   or nothing at all for compile-only mode
      * @param options - configuration; declares connection ownership
      */
-    constructor(pool?: Pool | undefined, options?: PgsqlPoolAdapterOptions);
     constructor(pool: Pool, options?: PgsqlPoolAdapterOptions);
     constructor(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions);
-    constructor(pool: undefined, options?: PgsqlAdapterOptions);
+    constructor(pool?: undefined, options?: PgsqlCompileOnlyAdapterOptions);
     /**
      * Shared compilation dependencies — built lazily from adapter fields.
      * Passed to compiler sub-modules instead of `this`.
@@ -1096,6 +1180,8 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     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;
     /**
@@ -1104,6 +1190,13 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     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;
     /**
@@ -1210,8 +1303,8 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Execute a query and return rows plus PostgreSQL result metadata.
      * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
      */
-    executeWithMeta<T = unknown>(query: CompiledQuery<T>): Promise<{
-        readonly rows: T[];
+    executeWithMeta(query: CompiledQuery): Promise<{
+        readonly rows: readonly unknown[];
         readonly rowCount: number;
         readonly command?: string;
     }>;
@@ -1425,6 +1518,13 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     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;
@@ -1539,7 +1639,7 @@ declare function createPgsqlAdapter<DB = unknown>(client: PoolClient, options: P
  * console.log(dump.sql);
  * ```
  */
-declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): PgsqlAdapter<DB>;
+declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlCompileOnlyAdapterOptions): PgsqlAdapter<DB>;
 
 interface CheckConstraintCanonicalizationWarning {
     readonly table: string;
@@ -1561,7 +1661,18 @@ interface ColumnDefaultCanonicalizationWarning {
     /** Present when the default could not be paired with the opposite model side. */
     readonly side?: 'desired' | 'database';
 }
-type ExpressionCanonicalizationWarning = CheckConstraintCanonicalizationWarning | ColumnDefaultCanonicalizationWarning;
+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;
@@ -1573,6 +1684,8 @@ interface CanonicalizeCheckConstraintsOptions {
     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;
 }
 declare class CheckConstraintCanonicalizationError extends Error {
     readonly table: string;
@@ -1591,108 +1704,11 @@ declare class ColumnDefaultCanonicalizationError extends Error {
  */
 declare function canonicalizeCheckConstraints(adapter: RollbackOnlyPgsqlScope, desired: ModelIR, dbModel: ModelIR, options?: CanonicalizeCheckConstraintsOptions): Promise<ModelIR>;
 
-/**
- * Schema Comparison Engine (DDL-PROV Block 1)
- *
- * Compares two ModelIRs (schema definition vs database state)
- * and produces a structured diff of changes needed.
- *
- * @module schema-diff
- */
-
-type ChangeKind = 'create_table' | 'drop_table' | 'add_column' | 'drop_column' | 'alter_column_type' | 'alter_column_nullable' | 'alter_column_default' | 'alter_column_unique' | 'add_primary_key' | 'drop_primary_key' | 'add_foreign_key' | 'drop_foreign_key' | 'alter_foreign_key' | 'validate_constraint' | 'create_index' | 'drop_index' | 'add_check_constraint' | 'drop_check_constraint' | 'create_enum' | 'alter_enum_add_value' | 'drop_enum' | 'alter_column_collation' | 'alter_column_identity' | 'add_comment' | 'drop_comment' | 'create_extension' | 'drop_extension' | 'create_sequence' | 'alter_sequence' | 'drop_sequence' | 'enable_rls' | 'disable_rls' | 'create_policy' | 'drop_policy';
-interface SchemaChange {
-    readonly kind: ChangeKind;
-    readonly table: string;
-    readonly column?: string;
-    readonly destructive: boolean;
-    readonly details: string;
-    /** Additional metadata for SQL generation */
-    readonly meta?: Readonly<Record<string, unknown>>;
-}
-interface DiffSummary {
-    readonly tables: {
-        readonly added: number;
-        readonly dropped: number;
-    };
-    readonly columns: {
-        readonly added: number;
-        readonly dropped: number;
-        readonly altered: number;
-    };
-    readonly indexes: {
-        readonly added: number;
-        readonly dropped: number;
-    };
-    readonly constraints: {
-        readonly added: number;
-        readonly dropped: number;
-        readonly altered: number;
-    };
-}
-interface SchemaDiff {
-    readonly changes: readonly SchemaChange[];
-    readonly hasDestructive: boolean;
-    readonly summary: DiffSummary;
-}
-interface CompareSchemataOptions {
-    /**
-     * Database naming convention.
-     * When set, schema model names (camelCase) are converted to DB format
-     * (e.g. snake_case) before comparison with the introspected model.
-     */
-    dbCasing?: DbCasing;
-    /** Dialect capabilities — comparisons for unsupported features will be skipped */
-    readonly dialectCapabilities?: DialectCapabilities;
-    /**
-     * When `true`, extensions present in the live DB but absent from the model
-     * schema are silently ignored — no `drop_extension` change is emitted for them.
-     * Only extensions explicitly declared in the model are managed (created if missing).
-     *
-     * Use this when the database image pre-installs extensions that the application
-     * schema does not own (e.g. pgvector, pg_search bundled in a custom Postgres image).
-     * Default: `false` (full-sync behaviour — unmanaged DB extensions produce a
-     * `drop_extension` entry).
-     */
-    readonly ignoreUnmanagedExtensions?: boolean;
-    /**
-     * Strict compile-only mode for callers that require convergence guarantees.
-     *
-     * `compareSchemata()` is intentionally pure and cannot ask PostgreSQL to
-     * canonicalise raw-SQL expression surfaces. By default it keeps the historic
-     * best-effort 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 and column defaults before calling this function.
-     * Under that live mode, every default surface considered under this option is
-     * either canonicalised as a pair or explicitly refused. This does not prove
-     * that the resulting migration is executable.
-     * Partial-index predicates and index expressions are not canonicalised by the
-     * live helper and are rejected there when this strict flag is set.
-     */
-    readonly requireExpressionCanonicalization?: boolean;
-}
-declare class ExpressionCanonicalizationUnavailableError extends Error {
-    readonly surfaces: readonly string[];
-    constructor(surfaces: readonly string[]);
-}
-/**
- * Compare two ModelIRs and produce a structured diff.
- *
- * @param schema - The desired schema (from definition)
- * @param db - The current database state (from introspection)
- * @param options - Optional comparison settings (e.g. dbCasing)
- * @returns SchemaDiff with all changes needed to bring DB in sync with schema
- */
-declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: CompareSchemataOptions): SchemaDiff;
-
 interface ComparePgsqlDatabaseSchemaOptions extends CompareSchemataOptions, SchemaScopeOptions {
     /**
-     * Whether to canonicalise PostgreSQL CHECK constraint expressions and column defaults before
-     * comparing. Defaults to `true`. Set to `false` only for compatibility with
+     * 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
@@ -1710,7 +1726,7 @@ interface ComparePgsqlDatabaseSchemaOptions extends CompareSchemataOptions, Sche
     readonly onExpressionCanonicalizationWarning?: (warning: ExpressionCanonicalizationWarning) => void;
     /**
      * Diff that the caller just applied before this live re-diff. Used only when
-     * CHECK expressions or column defaults are compared by raw text to fail loudly if the exact same
+     * 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;
@@ -1739,12 +1755,61 @@ declare class CheckConstraintNewEnumValueError extends Error {
     readonly table: string;
     readonly constraint: string;
     readonly addedEnumValues: readonly AddedEnumValue[];
-    readonly surfaceKind: 'CHECK constraint' | 'column default';
-    constructor(table: string, constraint: string, addedEnumValues: readonly AddedEnumValue[], surfaceKind?: 'CHECK constraint' | 'column default');
+    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 and column defaults through PostgreSQL, then call the pure synchronous
+ * 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
@@ -1754,9 +1819,9 @@ declare class CheckConstraintNewEnumValueError extends Error {
  * that cannot run. Apply the enum addition by itself first, then add or update
  * the CHECK constraint in a later migration.
  *
- * Partial-index predicates and index expressions are intentionally not
- * canonicalised here; non-strict diffs compare them by raw string, and strict
- * diffs reject them.
+ * 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(adapter: PgsqlAdapter, desired: ModelIR, options?: ComparePgsqlDatabaseSchemaOptions): Promise<SchemaDiff>;
 declare function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff: SchemaDiff, currentDiff: SchemaDiff, rawExpressionSurfaces?: ReadonlySet<string>): void;
@@ -1816,101 +1881,6 @@ declare function generateMigrationSQL(diff: SchemaDiff, options?: MigrationSQLOp
  */
 declare function generateDownSQL(diff: SchemaDiff, options?: MigrationSQLOptions): readonly string[];
 
-/**
- * Migration File Format v2 — UP + DOWN sections.
- *
- * File format:
- *   -- dbsp:destructive: true|false
- *   <UP statements>;
- *   -- DOWN
- *   <DOWN statements>;
- *
- * The separator `-- DOWN` must be on its own line (SC-25).
- *
- * @module ddl/migration-file
- */
-
-/**
- * Result of parsing a migration file's UP/DOWN sections.
- */
-interface ParsedMigrationFile {
-    readonly upStatements: readonly string[];
-    readonly downStatements: readonly string[];
-    readonly hasDown: boolean;
-    readonly destructive?: boolean | undefined;
-}
-/**
- * Generate a migration file content with UP and DOWN sections.
- */
-declare function generateMigrationFile(diff: SchemaDiff, options?: MigrationSQLOptions & {
-    name?: string;
-}): string;
-/**
- * Parse a migration file into UP and DOWN sections.
- * Separator: `^\s*-- DOWN\s*$` (strict regex, own line only — SC-25)
- */
-declare function parseMigrationFile(content: string): ParsedMigrationFile;
-/**
- * Check if SQL statements contain destructive operations.
- * Destructive: DROP TABLE, DROP COLUMN, lossy ALTER COLUMN TYPE
- */
-declare function isDestructiveDown(downStatements: readonly string[]): boolean;
-
-/**
- * Migration Tracker — `_dbsp_migrations` table CRUD.
- *
- * Manages the tracking table that records which migrations
- * have been applied to a database.
- */
-
-interface MigrationRecord {
-    /** Migration filename (e.g., "0001_create_users.sql") */
-    readonly name: string;
-    /** SHA-256 checksum of the migration file content */
-    readonly checksum: string;
-    /** When the migration was applied */
-    readonly appliedAt: Date;
-    /** Schema version at time of this migration */
-    readonly schemaVersion: number;
-    /** Whether this migration contains destructive changes */
-    readonly destructive: boolean;
-}
-/**
- * Execute a callback under the migration advisory lock using a pinned client.
- * The lock is held for the duration of the callback.
- *
- * Intentional latent-bug fix: session-level advisory locks are not freed by
- * returning a PoolClient to pg's pool. If unlock fails, PgsqlAdapter destroys the
- * session instead of returning a possibly lock-holding connection to the pool.
- */
-declare function withMigrationLock<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
-/**
- * Ensure the migrations tracking table exists.
- * Auto-migrates existing tables that lack `schema_version`/`destructive` columns,
- * and backfills `schema_version` by `applied_at` order for rows still at 0.
- */
-declare function ensureMigrationsTable(pool: Pool): Promise<void>;
-/**
- * Get all applied migrations, ordered by name.
- */
-declare function getAppliedMigrations(pool: Pool): Promise<readonly MigrationRecord[]>;
-/**
- * Record a migration as applied.
- */
-declare function recordMigration(pool: Pool, name: string, checksum: string, schemaVersion: number, destructive: boolean): Promise<void>;
-/**
- * Check if a specific migration has been applied.
- */
-declare function isMigrationApplied(pool: Pool, name: string): Promise<boolean>;
-/**
- * Get the next schema version number (max + 1, or 1 if no migrations).
- */
-declare function getNextSchemaVersion(pool: Pool): Promise<number>;
-/**
- * Remove a migration record (for rollback).
- */
-declare function removeMigrationRecord(pool: Pool, name: string): Promise<void>;
-
 /**
  * Type Mapping - Maps ModelIR ColumnType to PostgreSQL data types
  *
@@ -2779,6 +2749,91 @@ declare function buildStreamingStatements(query: Node, config?: StreamConfig): {
     close: Node;
 };
 
+type PgAdoptionResult = {
+    readonly outcome: 'completed';
+} | {
+    readonly outcome: 'no-op';
+} | {
+    readonly outcome: 'adoption-refused';
+    readonly detail: string;
+} | {
+    readonly outcome: 'execution-failed';
+    readonly detail: string;
+} | {
+    readonly outcome: 'recovery-required';
+    readonly claimId: string;
+    readonly detail: string;
+} | {
+    readonly outcome: 'transport-ambiguous';
+    readonly detail: string;
+};
+type PgAdoptionPreflightResult = {
+    readonly outcome: 'ready';
+} | {
+    readonly outcome: 'no-op';
+} | {
+    readonly outcome: 'adoption-refused';
+    readonly detail: string;
+} | {
+    readonly outcome: 'execution-failed';
+    readonly detail: string;
+};
+interface PgDeclaredAdoptionInput {
+    readonly executor: TransitionJournalQueryable;
+    readonly home: LedgerHome;
+    readonly address: LedgerAddress;
+    readonly declaration: LedgerPayload;
+    /** Identity observed while the digest-covered adoption plan was reviewed. */
+    readonly expectedCatalogueIdentity: NonNullable<LedgerAddress['catalogueIdentity']>;
+    readonly shapeMatches: (executor: TransitionJournalQueryable) => Promise<boolean>;
+}
+interface PgPersistedDeclaredAdoptionInput extends PgDeclaredAdoptionInput {
+    /** Locked durable identity and its full reviewed manifest from apply. */
+    readonly run: PgLockedRun;
+    readonly manifest: ValidatedManagedStepManifest;
+    readonly recomputedPlanDigest: string;
+    readonly approval: ScopedApprovalSet;
+    /** Attempt namespace journaled before this lifecycle can open a claim. */
+    readonly executionId: string;
+    /** Exact digest-covered step; adoption never constructs a standalone plan. */
+    readonly step: NormalizedManagedStep;
+    /** Test-only admitted-path observation; absent from normal callers. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+}
+/**
+ * Inspect a declared adoption without opening its adopt-intent claim.
+ *
+ * The generator executes this pass for every declared adoption before it opens
+ * any claim for ordinary schema work.  A changed shape or physical identity is
+ * therefore reported as the actionable adoption refusal, rather than being
+ * hidden behind an unrelated destructive-authority refusal.
+ */
+declare function preflightPgDeclaredAdoption(input: PgDeclaredAdoptionInput): Promise<PgAdoptionPreflightResult>;
+/**
+ * The caller supplies the already-established live shape comparison. This
+ * adapter owns the identity read and the only append path, so a matching shape
+ * can never be turned into an adoption without a live catalogue identity.
+ */
+declare function executePgDeclaredAdoption(input: PgPersistedDeclaredAdoptionInput): Promise<PgAdoptionResult>;
+
+interface PgLedgerAddressChain {
+    readonly ledger: LedgerHome;
+    readonly address: LedgerAddress;
+    /** Every member is returned so the core projector can diagnose malformed chains. */
+    readonly events: readonly LedgerChainMember[];
+    /** Undefined means there is no unique terminal member; it is never inferred by row order. */
+    readonly terminalMember?: LedgerChainMember;
+}
+/** Finds a terminal by predecessor topology only; callers must not use row position. */
+declare function findPgLedgerTerminalMember(events: readonly LedgerChainMember[]): LedgerChainMember | undefined;
+/**
+ * Reads one address without imposing an insertion order. The resulting full
+ * chain feeds the core projection, which owns all lifecycle interpretation.
+ */
+declare function readPgLedgerAddressChain(executor: TransitionJournalQueryable, ledger: LedgerHome, address: LedgerAddress): Promise<PgLedgerAddressChain>;
+/** Read the durable PostgreSQL role identity for the selected terminal event. */
+declare function readPgLedgerControllerOid(executor: TransitionJournalQueryable, ledger: LedgerHome, address: LedgerAddress, eventId: string): Promise<string>;
+
 declare const PG_OPERATION_PACK_ARTIFACT: SemanticArtifactRef;
 declare const PG_RULE_PACK_ARTIFACT: SemanticArtifactRef;
 declare const PG_INTROSPECTION_ARTIFACT: SemanticArtifactRef;
@@ -2794,6 +2849,11 @@ declare const DBSP_META_SCHEMA = "dbsp_meta";
 declare const DBSP_TRANSITION_RUN_TABLE = "dbsp_transition_run";
 declare const DBSP_TRANSITION_RUN_PLAN_TABLE = "dbsp_transition_run_plan";
 declare const DBSP_TRANSITION_JOURNAL_TABLE = "dbsp_transition_journal";
+declare const DBSP_TRANSITION_AUTHORIZATION_TABLE = "dbsp_transition_authorization";
+declare const DBSP_LEDGER_EVENT_TABLE = "dbsp_ledger_event";
+declare const DBSP_LEDGER_RESERVATION_TABLE = "dbsp_ledger_reservation";
+declare const DBSP_LEDGER_IDENTITY_TABLE = "dbsp_ledger_identity";
+declare const DBSP_LEDGER_MARKER_TABLE = "dbsp_ledger_marker";
 declare const DBSP_LOGICAL_IDENTITY_TABLE = "dbsp_logical_identity";
 declare const COLUMN_EXISTS_OBSERVATION = "postgresql.column.exists";
 declare const ENUM_TYPE_EXISTS_OBSERVATION = "postgresql.enum-type.exists";
@@ -2803,6 +2863,33 @@ declare const ENGINE_VERSION_OBSERVATION = "postgresql.engine.version-supported"
 declare const LOGICAL_IDENTITY_CARRIER_OBSERVATION = "postgresql.logical-identity.carrier-state";
 declare const NO_NULLS_GUARD = "NO_NULLS";
 
+/** The stable command outcome for a PostgreSQL target that cannot accept writes. */
+declare const DATABASE_READ_ONLY_OUTCOME: "database-read-only";
+declare class PgDatabaseReadOnlyError extends Error {
+    readonly code: "database-read-only";
+    constructor(detail: string);
+}
+declare function isPgDatabaseReadOnlyError(error: unknown): error is PgDatabaseReadOnlyError;
+type PgDatabaseWritability = {
+    readonly kind: 'writable';
+} | {
+    readonly kind: typeof DATABASE_READ_ONLY_OUTCOME;
+    readonly detail: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly detail: string;
+};
+/**
+ * One PostgreSQL writability classification for every managed mutation.  Both
+ * a physical standby and a session made read-only by default reach the same
+ * outcome; an unreadable response is deliberately not treated as writable.
+ */
+declare function classifyPgDatabaseWritability(executor: TransitionJournalQueryable): Promise<PgDatabaseWritability>;
+/** Fail closed without replacing a PostgreSQL query failure's own words. */
+declare function assertPgDatabaseWritable(executor: TransitionJournalQueryable): Promise<void>;
+/** Preserve PostgreSQL's own failure words while normalizing SQLSTATE 25006. */
+declare function classifyPgWrite<T>(write: () => Promise<T>): Promise<T>;
+
 /**
  * A proven operation may still be ineligible for a durable execution contract
  * when its reviewed requirements cannot be derived.  The CLI renders this as a
@@ -2827,7 +2914,7 @@ declare function readPgExecutionTargetFromClient(target: TransitionSessionClient
     readonly sessionProvenance: Readonly<Record<'search_path' | 'client_encoding' | 'TimeZone', string>>;
 }>;
 /** Build the versioned canonical document once, while the plan is minted. */
-declare function createPgExecutionContract(plan: ProvenPlanShape, identity: PostgreSqlObservationTargetIdentity, _sessionProvenance: Readonly<Record<'search_path' | 'client_encoding' | 'TimeZone', string>>): ExecutionContract;
+declare function createPgExecutionContract(plan: ProvenPlanShape, identity: PostgreSqlObservationTargetIdentity, sessionProvenance: Readonly<Record<'search_path' | 'client_encoding' | 'TimeZone', string>>): ExecutionContract;
 /** Evaluate the stored document on the leased executor, before it renders SQL. */
 declare function evaluatePgExecutionContract(target: TransitionSessionClient, contract: ExecutionContract): Promise<{
     readonly ok: true;
@@ -2836,23 +2923,39 @@ declare function evaluatePgExecutionContract(target: TransitionSessionClient, co
     readonly clause: string;
     readonly detail: string;
 }>;
-
-type QueryResultLike = {
-    readonly rows: readonly Record<string, unknown>[];
-};
-type TransitionJournalQueryable = {
-    query(sql: string, params?: readonly unknown[]): Promise<QueryResultLike>;
-};
-declare function renderCreateDbspMetaSchemaSql(): string;
-declare function renderCreateTransitionRunTableSql(): string;
-declare function renderCreateTransitionJournalTableSql(): string;
-declare function renderCreateTransitionRunPlanTableSql(): string;
-declare function ensureTransitionJournal(executor: TransitionJournalQueryable): Promise<void>;
-declare function createPgTransitionRunPersister(executor: TransitionJournalQueryable): TransitionRunPersister;
-declare function readTransitionJournal(executor: TransitionJournalQueryable, runId: string): Promise<TransitionRunJournal & {
-    readonly plan: ProvenPlanShape;
+/**
+ * The durable preflight boundary.  This intentionally receives a core-minted
+ * leased session, so SET/SHOW and the context used by the renderer are on the
+ * exact connection that subsequently records intent and executes DDL.
+ */
+declare function preparePgExecutionSession(target: TransitionSessionClient, contract: ExecutionContract, plan: ProvenPlanShape): Promise<{
+    readonly ok: true;
+    readonly context: _dbsp_types.ObservationContext;
+} | {
+    readonly ok: false;
+    readonly kind: 'refused' | 'failed' | 'read-only';
+    readonly detail: string;
+}>;
+/**
+ * Recovery admission is intentionally narrower than apply preflight: it proves
+ * only that recovery is reading the planned cluster, database and namespaces.
+ * Target state may have changed, and revoked DDL authority is irrelevant to
+ * classification.
+ */
+declare function preparePgRecoveryAdmission(target: TransitionSessionClient, contract: ExecutionContract): Promise<{
+    readonly ok: true;
+    readonly context: _dbsp_types.ObservationContext;
+} | {
+    readonly ok: false;
+    readonly detail: string;
 }>;
 
+type PgTransitionRunLockResult<T> = {
+    readonly kind: 'acquired';
+    readonly value: T;
+} | {
+    readonly kind: 'busy';
+};
 type PgTransitionClientLease = {
     readonly client: PoolClient;
     query(sql: string, params?: unknown): Promise<{
@@ -2880,8 +2983,33 @@ type PgTransitionClientLease = {
  * worth spending that.
  */
 declare function createPgTransitionLessor(pool: Pool): TransitionLessor;
-/** Acquire a UTF-8-configured PostgreSQL client for direct planning paths. */
+/**
+ * Acquire a configured PostgreSQL transition client.
+ *
+ * Callers that use the native adapter must pass this checked-out client with
+ * `borrowedClient: true` and return it through `release()` when finished.
+ */
 declare function acquirePgTransitionClient(pool: Pool): Promise<PgTransitionClientLease>;
+/**
+ * Hold a session advisory lock on the same checked-out session used for every
+ * transition segment.  `pg_try_advisory_lock` makes contention an explicit
+ * `busy` result rather than a hidden queue; releasing the client also releases
+ * the lock if an unlock attempt itself fails.
+ */
+declare function withPgTransitionRunLock<T>(pool: Pool, runId: string, callback: (target: ExclusiveTransitionTarget) => Promise<T>): Promise<PgTransitionRunLockResult<T>>;
+
+type Queryable$2 = {
+    query(sql: string, params?: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+};
+/**
+ * Check every existing managed ledger before ordinary apply reaches the
+ * execution-contract comparison. A restored plan's physical-target clause is
+ * necessarily different too, but the ledger's fresh-ledger path is the
+ * actionable refusal and must win that ordering.
+ */
+declare function validatePgManagedLedgerCurrency(executor: Queryable$2, plan: ProvenPlanShape): Promise<string | undefined>;
 
 type ObservationTarget = {
     readonly table: string;
@@ -2897,8 +3025,20 @@ type EnumObservationTarget = {
 };
 /** Acquire one lease, issue the observation, then release that lease. */
 declare function executePgObservationFromLessor(lessor: TransitionLessor, request: ObservationRequest, context: ObservationContext): Promise<EvidenceObservation>;
+/**
+ * Read context through a caller-owned lease.
+ *
+ * A lease rather than anything with `query()`, for the reason given on
+ * {@link executePgObservationFromClient}: this reads the server version,
+ * database, role and `search_path` in sequence, and a pool would answer each
+ * from a different connection.
+ *
+ * Internal: the supported entry point is
+ * {@link readPgObservationContextFromLessor}.
+ */
+declare function readPgObservationContextFromClient(target: TransitionSessionClient, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget, expectedTargetIdentity?: ObservationContext['postgresqlTargetIdentity']): Promise<ObservationContext>;
 /** Acquire one lease, read context, then release that lease. */
-declare function readPgObservationContextFromLessor(lessor: TransitionLessor, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget, expectedTargetIdentity?: ObservationContext['postgresqlTargetIdentity']): Promise<ObservationContext>;
+declare function readPgObservationContextFromLessor(lessor: TransitionLessor | ExclusiveTransitionTarget, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget, expectedTargetIdentity?: ObservationContext['postgresqlTargetIdentity']): Promise<ObservationContext>;
 declare function createPgObservationIssuer(): ObservationIssuer;
 
 interface SetNotNullColumnShapeExpectation {
@@ -3084,6 +3224,19 @@ declare function createAttachLogicalIdentityOperationRuntime(): {
     isLockTimeout(error: unknown): boolean;
 };
 
+type QueryResultLike = {
+    readonly rows: readonly Record<string, unknown>[];
+};
+type Queryable$1 = {
+    query(sql: string, params?: readonly unknown[]): Promise<QueryResultLike>;
+};
+/**
+ * Recovery has no authority to turn an interrupted concurrent build into an
+ * outcome unless its postcondition is established. An invalid retained target
+ * is deliberately reported in the operation's own admission words.
+ */
+declare function assertCreateUniqueIndexConcurrentlyRecoveryNotInvalid(executor: Queryable$1, operation: PhysicalOperation): Promise<void>;
+
 type ManualSqlPayload = {
     readonly statement: UnsafeNativeFragment;
     readonly blastRadius: readonly ResourceAddress[];
@@ -3522,6 +3675,201 @@ declare function createPgTransitionPack(options?: PgTransitionPackOptions): {
     satisfiesCompositionFact: typeof satisfiesPgEnumLabelVisibleCompositionFact;
 };
 
+type ReaddressRecoveryAnswer = {
+    readonly kind: 'refused-pair';
+} | {
+    readonly kind: 'pending-pair';
+} | {
+    readonly kind: 'indeterminate-pair';
+};
+type PgReaddressPairRecoveryResult = {
+    readonly kind: 'readdress-recovery-refused-pair';
+    readonly pairId: string;
+} | {
+    readonly kind: 'readdress-recovery-pending-pair';
+    readonly pairId: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'readdress-recovery-indeterminate-pair';
+    readonly pairId: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'readdress-recovery-transport-ambiguous-pair';
+    readonly pairId: string;
+    readonly reason: string;
+};
+/**
+ * The pair recovery decision is deliberately tiny and exhaustive: it never
+ * completes a DDL operation.  A readable shape other than the original,
+ * complete source closure is outside interference.
+ */
+declare function classifyPgReaddressRecovery(input: {
+    readonly unreadable: boolean;
+    readonly completeSourceClosure: boolean;
+}): ReaddressRecoveryAnswer;
+type PgReaddressResult = {
+    readonly outcome: 'completed';
+    readonly pairId: string;
+} | {
+    readonly outcome: 'no-op';
+} | {
+    readonly outcome: 'readdress-unsupported';
+    readonly detail: string;
+} | {
+    readonly outcome: 'readdress-refused';
+    readonly detail: string;
+} | {
+    readonly outcome: 'recovery-required';
+    readonly claimId: string;
+    readonly detail: string;
+} | {
+    readonly outcome: 'transport-ambiguous';
+    readonly detail: string;
+};
+interface PgPersistedReaddressInput {
+    readonly executor: TransitionJournalQueryable;
+    /** The durable-run witness is locked by apply before this lifecycle starts. */
+    readonly run: PgLockedRun;
+    readonly manifest: ValidatedManagedStepManifest;
+    readonly recomputedPlanDigest: string;
+    readonly approval: ScopedApprovalSet;
+    /** Attempt namespace journaled before this lifecycle can open a claim. */
+    readonly executionId: string;
+    /** Exact digest-covered normalized step; this is the only operation source. */
+    readonly step: NormalizedManagedStep;
+    readonly database: string;
+    readonly targetSchema: string;
+    /** Test-only admitted-path observation; absent from normal callers. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+}
+/**
+ * The immutable DDL material attributed to one paired table re-address.
+ * Recovery fixtures use this same construction when they open a real
+ * readdress-intent through outcome admission.
+ */
+declare function renderPgTableReaddressStatements(source: LedgerAddress, target: LedgerAddress): readonly string[];
+declare function classifyPgReaddressSupport(request: {
+    readonly database: string;
+    readonly targetSchema?: string;
+    readonly executionId?: string;
+    readonly declaration: TableReaddressDeclaration;
+}): PgReaddressResult | undefined;
+/**
+ * Reconciles one interrupted re-address as one closure. Every live read is
+ * complete before an append is considered, and the only closing outcome is a
+ * verified refusal of the untouched source closure. Neither path issues DDL.
+ */
+declare function recoverPgReaddressPair(executor: TransitionJournalQueryable, input: {
+    readonly pairId: string;
+    readonly executionId: string;
+    readonly reservations: readonly LedgerReservationRow[];
+}): Promise<PgReaddressPairRecoveryResult>;
+/**
+ * Execute the ADR 0006 pair from one exact, persisted normalized step.
+ *
+ * This deliberately has no direct-request form: the durable run, validated
+ * manifest, digest and reviewed lifecycle material all arrive together from
+ * the apply lock boundary.
+ */
+declare function executePgPersistedTableReaddress(input: PgPersistedReaddressInput): Promise<PgReaddressResult>;
+
+type PgReleaseResult = {
+    readonly outcome: 'released';
+} | {
+    /** A managed mutation must name a non-writable target before any release read. */
+    readonly outcome: 'database-read-only';
+    readonly detail: string;
+    readonly address: LedgerAddress;
+} | {
+    /** Transport/query/read-only failure; never mislabel it malformed chain. */
+    readonly outcome: 'release-unavailable';
+    readonly detail: string;
+    readonly address: LedgerAddress;
+} | {
+    readonly outcome: 'release-refused';
+    readonly detail: string;
+    readonly address: LedgerAddress;
+    readonly refusal: LedgerRefusal;
+};
+declare function releasePgManagedAddress(input: {
+    readonly executor: TransitionJournalQueryable;
+    readonly home: LedgerHome;
+    readonly address: LedgerAddress;
+}): Promise<PgReleaseResult>;
+
+type Queryable = {
+    query(sql: string, params?: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+};
+interface PgRemovalEffectAddress {
+    readonly address: LedgerAddress;
+    /** Physical pg_depend identity retained for the reviewed closure digest. */
+    readonly physicalIdentity?: {
+        readonly classId?: string;
+        readonly objectId?: string;
+        readonly objectSubId?: string;
+        readonly parentClassId?: string;
+        readonly parentObjectId?: string;
+        readonly parentObjectSubId?: string;
+        readonly dependencyType?: string;
+    };
+    /** Extension members are accounted by their adopted extension parent only. */
+    readonly extensionMember?: boolean;
+    /**
+     * An `i` dependency to an artifact owned by the referenced relation (row
+     * type, its array type, toast relation, index, or constraint). It remains
+     * cascade evidence, but is accounted by that relation rather than requiring
+     * a separate ledger ownership lookup.
+     */
+    readonly internalOwned?: boolean;
+}
+type PgRemovalEffectsClosure = {
+    readonly kind: 'all-contained-or-managed';
+    readonly root: LedgerAddress;
+    readonly effects: readonly PgRemovalEffectAddress[];
+    readonly managedDependents: readonly LedgerAddress[];
+    /** Exact, canonical cascade set admitted under the ledger locks. */
+    readonly closureDigest: string;
+} | {
+    readonly kind: 'reaches-unmanaged';
+    readonly root: LedgerAddress;
+    readonly effects: readonly PgRemovalEffectAddress[];
+    readonly unmanaged: LedgerAddress;
+} | {
+    readonly kind: 'undecidable';
+    readonly reason: string;
+};
+/**
+ * Classifies a fully enumerated cascade. Non-declarable dependent kinds refuse
+ * before SQL; adopted-extension members are the sole parent-accounted carveout.
+ */
+declare function classifyRemovalEffectsClosure(input: {
+    readonly root: LedgerAddress;
+    readonly effects: readonly PgRemovalEffectAddress[];
+    readonly isManaged: (address: LedgerAddress) => boolean;
+}): PgRemovalEffectsClosure;
+/** Map closure results directly into the core authority's closed vocabulary. */
+declare function containmentAuthorityOutcome(closure: PgRemovalEffectsClosure): ContainmentClosureDestructiveOutcome;
+declare function reservationsForRemovalClosure(input: {
+    readonly closure: Extract<PgRemovalEffectsClosure, {
+        readonly kind: 'all-contained-or-managed';
+    }>;
+    readonly executionId: string;
+    readonly rootClaimId: string;
+    readonly claimKind?: LedgerClaimKind;
+    readonly homeLedger: LedgerHome;
+}): readonly LedgerReservationRow[];
+/**
+ * Enumerates PostgreSQL's dependency cascade before any destructive DDL. The
+ * caller supplies ledger ownership; an unreadable catalogue is never evidence.
+ */
+declare function readPgRemovalEffectsClosure(input: {
+    readonly executor: Queryable;
+    readonly root: LedgerAddress;
+    readonly isManaged: (address: LedgerAddress) => Promise<boolean>;
+}): Promise<PgRemovalEffectsClosure>;
+
 /**
  * Identifier Validation for adapter-pgsql
  *
@@ -3596,4 +3944,4 @@ declare function escapeDiagnosticText(value: string): string;
  */
 declare function validateSqlExpression(sql: string, context: string): void;
 
-export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, type ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, ColumnDefaultCanonicalizationError, type ColumnDefaultCanonicalizationWarning, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_PLAN_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionCanonicalizationWarning, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, type NonConvergentSchemaDiffSurface, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type PgAdvisoryLockKey, type PgAdvisoryLockResult, PgExecutionContractDerivationError, type PgTransitionClientLease, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, PgsqlAdvisoryLockOptionsError, type PgsqlBorrowedClientAdapterOptions, PgsqlPinnedConnectionAbortSignalError, type PgsqlPoolAdapterOptions, type PgsqlPreparedStatementsOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortSignalError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PgsqlTransactionOptionsError, PgsqlTransactionTimeoutError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type RollbackOnlyPgsqlScope, SET_NOT_NULL_RULE_ID, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquirePgTransitionClient, assertCreateIndexSupported, assertCreateIndexesSupported, assertNoRepeatedExpressionSurfaceDrift, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgExecutionContract, createPgObservationIssuer, createPgTransitionLessor, createPgTransitionPack, createPgTransitionRunPersister, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, ensureMigrationsTable, ensureTransitionJournal, escapeDiagnosticText, evaluatePgExecutionContract, excludedRef, executePgObservationFromLessor, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, normalizeManualSqlPayload, parse, parseExplainJson, parseMigrationFile, pgTargetIdentityMismatch, rawDistance, readPgExecutionTargetFromClient, readPgObservationContextFromLessor, readTransitionJournal, recordMigration, redactParams, removeMigrationRecord, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateDbspMetaSchemaSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderCreateTransitionJournalTableSql, renderCreateTransitionRunPlanTableSql, renderCreateTransitionRunTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderSetNotNullLockSql, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };
+export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, ColumnDefaultCanonicalizationError, type ColumnDefaultCanonicalizationWarning, type ComparePgsqlDatabaseSchemaOptions, CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DATABASE_READ_ONLY_OUTCOME, DBSP_LEDGER_EVENT_TABLE, DBSP_LEDGER_IDENTITY_TABLE, DBSP_LEDGER_MARKER_TABLE, DBSP_LEDGER_RESERVATION_TABLE, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_AUTHORIZATION_TABLE, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_PLAN_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, type ExpressionCanonicalizationWarning, type ExpressionHandler, ExpressionKeyedIndexPredicateCanonicalizationUnsupportedError, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type GeneratedMutationClassification, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, IndexPredicateCanonicalizationError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, type NonConvergentSchemaDiffSurface, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, PartialIndexPredicateNewEnumValueError, type PgAdoptionPreflightResult, type PgAdoptionResult, type PgAdvisoryLockKey, type PgAdvisoryLockResult, PgDatabaseReadOnlyError, type PgDatabaseWritability, type PgDeclaredAdoptionInput, PgExecutionContractDerivationError, type PgLedgerAddressChain, PgLockedRun, PgOutcomeCheckpointObserver, type PgPersistedDeclaredAdoptionInput, type PgPersistedReaddressInput, type PgReaddressPairRecoveryResult, type PgReleaseResult, type PgRemovalEffectAddress, type PgRemovalEffectsClosure, type PgTransitionClientLease, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, PgsqlAdvisoryLockOptionsError, type PgsqlBorrowedClientAdapterOptions, type PgsqlCompileOnlyAdapterOptions, PgsqlPinnedConnectionAbortSignalError, type PgsqlPoolAdapterOptions, PgsqlPreparedStatementReplayError, type PgsqlPreparedStatementsOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortSignalError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PgsqlTransactionOptionsError, PgsqlTransactionTimeoutError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, RawIndexPredicateFallbackError, type RedactionConfig, type RedactionPattern, type RollbackOnlyPgsqlScope, SET_NOT_NULL_RULE_ID, SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquirePgTransitionClient, assertCreateIndexSupported, assertCreateIndexesSupported, assertCreateUniqueIndexConcurrentlyRecoveryNotInvalid, assertNoRepeatedExpressionSurfaceDrift, assertPgDatabaseWritable, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, classifyGeneratedMutation, classifyPgDatabaseWritability, classifyPgReaddressRecovery, classifyPgReaddressSupport, classifyPgWrite, classifyRemovalEffectsClosure, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, containmentAuthorityOutcome, cosineDistance, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgExecutionContract, createPgObservationIssuer, createPgTransitionLessor, createPgTransitionPack, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, dbTypesEqual, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, escapeDiagnosticText, evaluatePgExecutionContract, excludedRef, executePgDeclaredAdoption, executePgObservationFromLessor, executePgPersistedTableReaddress, findPgLedgerTerminalMember, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationSQL, generateSeries, getNamingPluginForDbCasing, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isGeneratedMutationDestructive, isJoinDecision, isPgDatabaseReadOnlyError, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, normalizeManualSqlPayload, parse, parseExplainJson, pgTargetIdentityMismatch, preflightPgDeclaredAdoption, preparePgExecutionSession, preparePgRecoveryAdmission, rawDistance, readPgExecutionTargetFromClient, readPgLedgerAddressChain, readPgLedgerControllerOid, readPgObservationContextFromClient, readPgObservationContextFromLessor, readPgRemovalEffectsClosure, recoverPgReaddressPair, redactParams, refusesRecordedPlanRemoval, releasePgManagedAddress, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderPgTableReaddressStatements, renderSetNotNullLockSql, reservationsForRemovalClosure, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validatePgManagedLedgerCurrency, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withPgTransitionRunLock };