@dbsp/adapter-pgsql 3.2.2 → 3.4.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as _dbsp_core from '@dbsp/core';
-import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, ExecutionCoordinator, CapabilityDescriptor } from '@dbsp/core';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, TransitionRunPersister, 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, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, PinnedConnectionOptions, TransactionOptions, CompileOnlyAdapter, ColumnIR, MutationReturningItem, WhereIntent, OutputDescriptor, QueryIntent, OperationKindRef, SemanticArtifactRef, TransitionRunJournal, ObservationIssuer, ObservationContext, TypeRef, ExpressionValue, CollationRef, LogicalIdentity, PhysicalOperation, OperationEffectAssessment, EvidenceObservation, FingerprintManifest, DurableIntentRecord, IssuedObservation, ApplyGuard, AdvisoryObservation, TransactionalCompletionRecord, StepJournal, UnsafeNativeFragment, ResourceAddress, ExecutableAssertion, Assumption, TransitionRule, TransitionCompositionFact, TrustRoot, RequiredEnumLabelIR } from '@dbsp/types';
+import { 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 * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
 import { Pool, PoolClient } from 'pg';
@@ -888,6 +888,11 @@ type PgsqlTransactionTimeoutParameter = 'lock_timeout' | 'statement_timeout';
  * @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;
@@ -1029,6 +1034,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private readonly managedTransactions;
     private readonly adapterManagedTransaction;
     private readonly adapterManagedPinnedConnection;
+    private readonly rollbackOnlyScope;
     private readonly scopeToken;
     private readonly scopeState;
     private readonly schemaName;
@@ -1072,11 +1078,13 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private compileNqlBundleLeafEnvelope;
     private compileNqlBundle;
     /**
-     * Returns the pool/client executor, or throws if in compile-only mode.
+     * 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;
     /** PostgreSQL dialect capabilities for planner strategy selection */
     get dialectCapabilities(): DialectCapabilities;
     /**
@@ -1304,12 +1312,16 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Execute scratch PostgreSQL work in a scope that always rolls back on success.
      *
      * This is intentionally PostgreSQL-adapter-specific. It is used for catalog
-     * shaped scratch DDL such as CHECK expression canonicalisation, where the
-     * caller needs PostgreSQL's rendering but must not keep the scratch objects.
+     * 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: PgsqlAdapter<DB>) => Promise<T>): Promise<T>;
+    withScratchScope<T>(fn: (adapter: RollbackOnlyPgsqlScope<DB>) => Promise<T>): Promise<T>;
     private createManagedClientAdapter;
     private createPinnedConnectionAdapter;
     private createChildTransactionObserver;
@@ -1499,10 +1511,11 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
 declare function createPgsqlAdapter<DB = unknown>(pool: Pool, options?: PgsqlPoolAdapterOptions): PgsqlAdapter<DB>;
 declare function createPgsqlAdapter<DB = unknown>(client: PoolClient, options: PgsqlBorrowedClientAdapterOptions): PgsqlAdapter<DB>;
 /**
- * Creates a compile-only PgsqlAdapter for SQL generation without a database connection.
+ * Creates a connectionless PgsqlAdapter for SQL generation without a database connection.
  *
  * All compilation methods (compile, compileInsert, etc.), createDump(), and generateDDL()
- * work normally. Execution methods (execute, stream, transaction, etc.) throw an error.
+ * 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
@@ -1515,7 +1528,57 @@ declare function createPgsqlAdapter<DB = unknown>(client: PoolClient, options: P
  * console.log(dump.sql);
  * ```
  */
-declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): CompileOnlyAdapter;
+declare function createPgsqlCompileOnlyAdapter<DB = unknown>(options?: PgsqlAdapterOptions): 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';
+}
+type ExpressionCanonicalizationWarning = CheckConstraintCanonicalizationWarning | ColumnDefaultCanonicalizationWarning;
+interface CanonicalizeCheckConstraintsOptions {
+    /** Database schema that owns the target tables and target-scoped enum types. */
+    readonly schemaName?: string;
+    /** Naming convention used when matching desired table names to DB table names. */
+    readonly dbCasing?: DbCasing;
+    /** Called when PostgreSQL CHECK canonicalisation fails and raw comparison is used. */
+    readonly onWarning?: (warning: CheckConstraintCanonicalizationWarning) => void;
+    /** Throw instead of falling back to raw comparison when canonicalisation fails. */
+    readonly requireCanonicalization?: boolean;
+    /** Skip CHECK scratch work when the caller's dialect does not support CHECK DDL. */
+    readonly canonicalizeCheckConstraints?: boolean;
+}
+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>;
 
 /**
  * Schema Comparison Engine (DDL-PROV Block 1)
@@ -1586,13 +1649,16 @@ interface CompareSchemataOptions {
      *
      * `compareSchemata()` is intentionally pure and cannot ask PostgreSQL to
      * canonicalise raw-SQL expression surfaces. By default it keeps the historic
-     * best-effort raw string comparison for CHECK expressions, partial-index
-     * predicates, and index expressions. Set this flag to throw when either model
+     * 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 before calling this function.
+     * 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.
      */
@@ -1614,36 +1680,44 @@ declare function compareSchemata(schema: ModelIR, db: ModelIR, options?: Compare
 
 interface ComparePgsqlDatabaseSchemaOptions extends CompareSchemataOptions, SchemaScopeOptions {
     /**
-     * Whether to canonicalise PostgreSQL CHECK constraint expressions before
+     * Whether to canonicalise PostgreSQL CHECK constraint expressions and column defaults before
      * comparing. Defaults to `true`. Set to `false` only for compatibility with
      * legacy raw-string live diffs.
      *
-     * Live canonicalisation creates temporary scratch tables and missing desired
-     * enum types inside an adapter scratch scope whose successful cleanup is
-     * rollback. The database role needs permission to create temporary tables,
-     * and enum-dependent checks may need permission to create the pending enum
-     * type. If PostgreSQL refuses that scratch DDL, non-strict mode warns and
-     * falls back to best-effort raw string comparison for the affected CHECK
-     * constraints.
+     * 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 CHECK canonicalisation warnings. Defaults to console.warn.
+     * Receives live expression canonicalisation warnings. Defaults to console.warn.
      */
     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
-     * CHECK expressions are compared by raw text to fail loudly if the exact same
+     * CHECK expressions or column defaults are compared by raw text to fail loudly if the exact same
      * expression-surface drift appears again after re-introspection.
      */
     readonly previouslyAppliedDiff?: SchemaDiff;
 }
-declare class NonConvergentSchemaDiffError extends Error {
+type NonConvergentSchemaDiffSurface = {
+    readonly kind: 'check_constraint';
     readonly table: string;
     readonly constraint: string;
-    readonly desiredExpression: string;
-    readonly databaseExpression: string;
-    constructor(table: string, constraint: string, desiredExpression: string, databaseExpression: 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 {
@@ -1654,11 +1728,12 @@ declare class CheckConstraintNewEnumValueError extends Error {
     readonly table: string;
     readonly constraint: string;
     readonly addedEnumValues: readonly AddedEnumValue[];
-    constructor(table: string, constraint: string, addedEnumValues: readonly AddedEnumValue[]);
+    readonly surfaceKind: 'CHECK constraint' | 'column default';
+    constructor(table: string, constraint: string, addedEnumValues: readonly AddedEnumValue[], surfaceKind?: 'CHECK constraint' | 'column default');
 }
 /**
  * Live PostgreSQL schema diff: introspect, canonicalise desired CHECK
- * constraint expressions through PostgreSQL, then call the pure synchronous
+ * constraint expressions and column defaults through PostgreSQL, then call the pure synchronous
  * schema comparator.
  *
  * If CHECK canonicalisation falls back while the same diff adds a plausibly
@@ -1673,7 +1748,7 @@ declare class CheckConstraintNewEnumValueError extends Error {
  * diffs reject them.
  */
 declare function comparePgsqlDatabaseSchema(adapter: PgsqlAdapter, desired: ModelIR, options?: ComparePgsqlDatabaseSchemaOptions): Promise<SchemaDiff>;
-declare function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff: SchemaDiff, currentDiff: SchemaDiff, rawCheckExpressionSurfaces?: ReadonlySet<string>): void;
+declare function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff: SchemaDiff, currentDiff: SchemaDiff, rawExpressionSurfaces?: ReadonlySet<string>): void;
 
 /**
  * Migration SQL Generator (DDL-PROV Block 1)
@@ -1965,59 +2040,6 @@ declare function getRowEstimates(plans: ExplainPlan[]): {
     actual: number;
 };
 
-interface CheckConstraintCanonicalizationWarning {
-    readonly table: string;
-    readonly constraint: string;
-    readonly message: string;
-    readonly cause: unknown;
-}
-interface CanonicalizeCheckConstraintsOptions {
-    /** Database schema that owns the target tables and target-scoped enum types. */
-    readonly schemaName?: string;
-    /** Naming convention used when matching desired table names to DB table names. */
-    readonly dbCasing?: DbCasing;
-    /** Called when PostgreSQL CHECK canonicalisation fails and raw comparison is used. */
-    readonly onWarning?: (warning: CheckConstraintCanonicalizationWarning) => void;
-    /** Throw instead of falling back to raw comparison when canonicalisation fails. */
-    readonly requireCanonicalization?: boolean;
-}
-type PgsqlCanonicalizationScope = Pick<Adapter, 'executeRaw' | 'transaction'>;
-declare class CheckConstraintCanonicalizationError extends Error {
-    readonly table: string;
-    readonly constraints: readonly string[];
-    readonly cause: unknown;
-    constructor(table: string, constraints: readonly string[], cause: unknown);
-}
-/**
- * Canonicalise PostgreSQL CHECK constraint expressions in a desired model.
- *
- * CHECK constraints are canonicalised by creating a transaction-local temp table
- * with the desired table's column definitions (borrowing live database type
- * detail for existing columns when the desired model omits it), adding the
- * authored CHECK constraints to that temp table, and reading PostgreSQL's
- * `pg_get_constraintdef()` rendering. The caller must provide a rollback-only
- * scratch scope; that rollback is cleanup for dbsp-created scratch objects, not
- * a sandbox for arbitrary session effects.
- * Missing desired enum types are also created inside that scratch scope before
- * scratch tables.
- * Scratch columns include only names and types; defaults, identity, uniqueness,
- * nullability, and other table-shape clauses are deliberately omitted.
- *
- * The returned expression is the full `CHECK (...)` clause. Bare authored
- * predicates are accepted and become full CHECK clauses.
- *
- * PostgreSQL does not allow an enum value added by `ALTER TYPE ... ADD VALUE`
- * to be used in the same transaction that added it. Because dbsp currently
- * emits and applies each migration in one transaction, the live diff layer
- * deliberately refuses CHECK constraints that fall back while the same diff adds
- * a plausibly referenced enum value. Splitting that into multiple transaction
- * phases is a separate migration-runner feature.
- *
- * This does not canonicalise partial-index predicates or index expressions, so
- * those surfaces may still compare by raw text in non-strict diffs.
- */
-declare function canonicalizeCheckConstraints(adapter: PgsqlCanonicalizationScope, desired: ModelIR, dbModel: ModelIR, options?: CanonicalizeCheckConstraintsOptions): Promise<ModelIR>;
-
 /**
  * ParadeDB Extension Wrappers
  *
@@ -2759,6 +2781,7 @@ declare const ENUM_ADD_VALUE_RULE_ID = "postgresql.enum.add-value";
 declare const LOGICAL_IDENTITY_ADOPTION_RULE_ID = "postgresql.logical-identity.adopt";
 declare const DBSP_META_SCHEMA = "dbsp_meta";
 declare const DBSP_TRANSITION_RUN_TABLE = "dbsp_transition_run";
+declare const DBSP_TRANSITION_RUN_PLAN_TABLE = "dbsp_transition_run_plan";
 declare const DBSP_TRANSITION_JOURNAL_TABLE = "dbsp_transition_journal";
 declare const DBSP_LOGICAL_IDENTITY_TABLE = "dbsp_logical_identity";
 declare const COLUMN_EXISTS_OBSERVATION = "postgresql.column.exists";
@@ -2769,6 +2792,40 @@ 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";
 
+/**
+ * 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
+ * blocked assessment rather than treating it as an operational failure.
+ */
+declare class PgExecutionContractDerivationError extends Error {
+    readonly operationRef: string;
+    readonly operationName: string;
+    constructor(operationRef: string, operationName: string, detail: string);
+}
+/**
+ * Compare namespace identities by name, rather than the incidental order in
+ * which PostgreSQL or a persisted JSON document happened to return them.
+ */
+declare function pgTargetIdentityMismatch(expected: PostgreSqlObservationTargetIdentity, observed: PostgreSqlObservationTargetIdentity): string | undefined;
+/**
+ * Name resolution is only used to locate the namespace OID.  The resulting
+ * contract never treats the name itself as identity.
+ */
+declare function readPgExecutionTargetFromClient(target: TransitionSessionClient, namespaceNames: readonly string[]): Promise<{
+    readonly identity: PostgreSqlObservationTargetIdentity;
+    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;
+/** Evaluate the stored document on the leased executor, before it renders SQL. */
+declare function evaluatePgExecutionContract(target: TransitionSessionClient, contract: ExecutionContract): Promise<{
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly clause: string;
+    readonly detail: string;
+}>;
+
 type QueryResultLike = {
     readonly rows: readonly Record<string, unknown>[];
 };
@@ -2778,8 +2835,42 @@ type TransitionJournalQueryable = {
 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 readTransitionJournal(executor: TransitionJournalQueryable, runId: string): Promise<TransitionRunJournal>;
+declare function createPgTransitionRunPersister(executor: TransitionJournalQueryable): TransitionRunPersister;
+declare function readTransitionJournal(executor: TransitionJournalQueryable, runId: string): Promise<TransitionRunJournal & {
+    readonly plan: ProvenPlanShape;
+}>;
+
+type PgTransitionClientLease = {
+    readonly client: PoolClient;
+    query(sql: string, params?: unknown): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+    release(error?: unknown): void;
+};
+/**
+ * Declare a pg Pool as a source of transition leases.
+ *
+ * The typed Pool argument and this explicit factory call are the declaration.
+ * Neither check below infers ownership; each rejects a declaration that
+ * contradicts itself.
+ *
+ * A pg Pool and a pg Client are structurally identical — both expose connect(),
+ * query() and end(), and neither exposes release() — so the argument cannot be
+ * classified on sight. What connect() returns can be: a Pool leases a
+ * PoolClient, which carries release(); a Client resolves to itself, which does
+ * not. The lease is therefore checked at the first acquisition, which costs one
+ * connection to learn and is why the constructor cannot report it.
+ *
+ * This deliberately avoids `instanceof Client`, which would be sound but
+ * requires importing pg at runtime. Nothing else in this package does, so the
+ * compiler and the SQL renderer work without a driver, and one guard is not
+ * worth spending that.
+ */
+declare function createPgTransitionLessor(pool: Pool): TransitionLessor;
+/** Acquire a UTF-8-configured PostgreSQL client for direct planning paths. */
+declare function acquirePgTransitionClient(pool: Pool): Promise<PgTransitionClientLease>;
 
 type ObservationTarget = {
     readonly table: string;
@@ -2793,8 +2884,11 @@ type EnumObservationTarget = {
     readonly label?: string;
     readonly schema?: string;
 };
+/** Acquire one lease, issue the observation, then release that lease. */
+declare function executePgObservationFromLessor(lessor: TransitionLessor, request: ObservationRequest, context: ObservationContext): Promise<EvidenceObservation>;
+/** 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 createPgObservationIssuer(): ObservationIssuer;
-declare function readPgObservationContext(target: unknown, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget): Promise<ObservationContext>;
 
 interface SetNotNullColumnShapeExpectation {
     readonly kind: 'postgresql.set-not-null.column-shape.v1';
@@ -2829,7 +2923,7 @@ type AlterColumnSetNotNullPayload = {
     readonly expectedColumnShape?: SetNotNullColumnShapeExpectation;
 };
 type TransitionExecutionClient$3 = {
-    readonly opaqueClient: unknown;
+    readonly opaqueClient: TransitionSessionClient;
 };
 declare function renderAlterColumnSetNotNullSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
 declare function renderSetNotNullLockSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
@@ -2840,11 +2934,14 @@ declare function beforeAfterFingerprints$3(operation: PhysicalOperation, evidenc
 };
 declare function createAlterColumnSetNotNullOperationRuntime(): {
     artifact: _dbsp_types.SemanticArtifactRef;
+    operationKind: _dbsp_types.OperationKindRef;
+    executionContractEligibility: {
+        readonly eligible: true;
+    };
     supportsOperation(operation: PhysicalOperation): boolean;
+    renderPlanSql(operation: PhysicalOperation, context: ObservationContext): string;
     effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
     buildFingerprints: typeof beforeAfterFingerprints$3;
-    checkout(target: unknown): Promise<TransitionExecutionClient$3>;
-    release(client: TransitionExecutionClient$3, error?: unknown): void;
     writeIntentJournal(client: TransitionExecutionClient$3, record: DurableIntentRecord): Promise<void>;
     begin(client: TransitionExecutionClient$3): Promise<void>;
     setLockTimeout(client: TransitionExecutionClient$3, maxWaitMs: number): Promise<void>;
@@ -2878,7 +2975,7 @@ type AlterTypeAddValuePayload = {
     readonly expectedAfter: readonly string[];
 };
 type TransitionExecutionClient$2 = {
-    readonly opaqueClient: unknown;
+    readonly opaqueClient: TransitionSessionClient;
 };
 declare function renderAlterTypeAddValueSql(payload: AlterTypeAddValuePayload, context: ObservationContext): string;
 declare function beforeAfterFingerprints$2(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
@@ -2888,11 +2985,17 @@ declare function beforeAfterFingerprints$2(operation: PhysicalOperation, evidenc
 declare function createAlterTypeAddValueOperationRuntime(): {
     artifact: _dbsp_types.SemanticArtifactRef;
     operationKind: _dbsp_types.OperationKindRef;
+    executionContractEligibility: {
+        readonly eligible: true;
+    };
+    rendererSessionRequirements: readonly [{
+        readonly setting: "standard_conforming_strings";
+        readonly value: "on";
+    }];
     supportsOperation(operation: PhysicalOperation): boolean;
+    renderPlanSql(operation: PhysicalOperation, context: ObservationContext): string;
     effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
     buildFingerprints: typeof beforeAfterFingerprints$2;
-    checkout(target: unknown): Promise<TransitionExecutionClient$2>;
-    release(client: TransitionExecutionClient$2, error?: unknown): void;
     writeIntentJournal(client: TransitionExecutionClient$2, record: DurableIntentRecord): Promise<void>;
     begin(client: TransitionExecutionClient$2): Promise<void>;
     setLockTimeout(client: TransitionExecutionClient$2, maxWaitMs: number): Promise<void>;
@@ -2926,7 +3029,7 @@ type AttachLogicalIdentityPayload = {
     readonly authenticated: false;
 };
 type TransitionExecutionClient$1 = {
-    readonly opaqueClient: unknown;
+    readonly opaqueClient: TransitionSessionClient;
 };
 declare function renderAttachLogicalIdentityLockSql(payload: AttachLogicalIdentityPayload): string;
 declare function renderCreateLogicalIdentitySideTableSql(_schema: string): string;
@@ -2938,11 +3041,14 @@ declare function beforeAfterFingerprints$1(operation: PhysicalOperation, evidenc
 };
 declare function createAttachLogicalIdentityOperationRuntime(): {
     artifact: _dbsp_types.SemanticArtifactRef;
+    executionContractEligibility: {
+        readonly eligible: false;
+        readonly detail: "PostgreSQL AttachLogicalIdentity has no derivable execution requirements yet";
+    };
     supportsOperation(operation: PhysicalOperation): boolean;
+    renderPlanSql(operation: PhysicalOperation): string;
     effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
     buildFingerprints: typeof beforeAfterFingerprints$1;
-    checkout(target: unknown): Promise<TransitionExecutionClient$1>;
-    release(client: TransitionExecutionClient$1, error?: unknown): void;
     writeIntentJournal(client: TransitionExecutionClient$1, record: DurableIntentRecord): Promise<void>;
     begin(client: TransitionExecutionClient$1): Promise<void>;
     setLockTimeout(client: TransitionExecutionClient$1, maxWaitMs: number): Promise<void>;
@@ -2974,7 +3080,7 @@ type ManualSqlPayload = {
     readonly postconditions: readonly ExecutableAssertion[];
 };
 type TransitionExecutionClient = {
-    readonly opaqueClient: unknown;
+    readonly opaqueClient: TransitionSessionClient;
 };
 declare function normalizeManualSqlPayload(payload: ManualSqlPayload, context: ObservationContext): ManualSqlPayload;
 declare function beforeAfterFingerprints(operation: PhysicalOperation, _evidence: readonly EvidenceObservation[], context: ObservationContext): {
@@ -2984,11 +3090,14 @@ declare function beforeAfterFingerprints(operation: PhysicalOperation, _evidence
 declare function createManualSqlOperationRuntime(): {
     artifact: _dbsp_types.SemanticArtifactRef;
     operationKind: _dbsp_types.OperationKindRef;
+    executionContractEligibility: {
+        readonly eligible: false;
+        readonly detail: "PostgreSQL ManualSql has no derivable execution requirements because its statement has no declared schema target";
+    };
     supportsOperation(operation: PhysicalOperation): boolean;
+    renderPlanSql(operation: PhysicalOperation, context: ObservationContext): string;
     effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
     buildFingerprints: typeof beforeAfterFingerprints;
-    checkout(target: unknown): Promise<TransitionExecutionClient>;
-    release(client: TransitionExecutionClient, error?: unknown): void;
     writeIntentJournal(client: TransitionExecutionClient, record: DurableIntentRecord): Promise<void>;
     begin(client: TransitionExecutionClient): Promise<void>;
     setLockTimeout(_client: TransitionExecutionClient, _maxWaitMs: number): Promise<void>;
@@ -3091,164 +3200,220 @@ declare function createPgTransitionPack(options?: PgTransitionPackOptions): {
     rules: (_dbsp_types.TransitionRule<AddCheckMatch> | _dbsp_types.TransitionRule<LogicalIdentityAdoptionMatch> | _dbsp_types.TransitionRule<CreateUniqueIndexConcurrentlyMatch> | _dbsp_types.TransitionRule<EnumAddValueMatch> | _dbsp_types.TransitionRule<SetNotNullMatch>)[];
     operationSemantics: ({
         artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        executionContractEligibility: {
+            readonly eligible: true;
+        };
         supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        renderPlanSql(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): string;
         effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
         buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
             expectedBefore: _dbsp_types.FingerprintManifest;
             expectedAfter: _dbsp_types.FingerprintManifest;
         };
-        checkout(target: unknown): Promise<{
-            readonly opaqueClient: unknown;
-        }>;
-        release(client: {
-            readonly opaqueClient: unknown;
-        }, error?: unknown): void;
         writeIntentJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
         begin(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         setLockTimeout(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, maxWaitMs: number): Promise<void>;
         acquireLocks(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, _effects: _dbsp_types.OperationEffectAssessment, context: _dbsp_types.ObservationContext): Promise<void>;
         observeContext(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
         observeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
             observations: _dbsp_types.IssuedObservation[];
             fingerprint: _dbsp_types.FingerprintManifest;
         }>;
         checkGuard(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
             passed: boolean;
             observations: _dbsp_types.AdvisoryObservation[];
             recovery: readonly _dbsp_types.RecoveryArtefact[];
         }>;
         executeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
             kind: string;
         }>;
         writeCompletionJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
         commit(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         rollback(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         writeObservedJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, journal: _dbsp_types.StepJournal): Promise<void>;
         isLockTimeout(error: unknown): boolean;
     } | {
         artifact: _dbsp_types.SemanticArtifactRef;
         operationKind: _dbsp_types.OperationKindRef;
+        executionContractEligibility: {
+            readonly eligible: true;
+        };
+        rendererSessionRequirements: readonly [{
+            readonly setting: "standard_conforming_strings";
+            readonly value: "on";
+        }];
         supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        renderPlanSql(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): string;
         effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
         buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
             expectedBefore: _dbsp_types.FingerprintManifest;
             expectedAfter: _dbsp_types.FingerprintManifest;
         };
-        checkout(target: unknown): Promise<{
-            readonly opaqueClient: unknown;
-        }>;
-        release(client: {
-            readonly opaqueClient: unknown;
-        }, error?: unknown): void;
         writeIntentJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
         begin(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         setLockTimeout(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, maxWaitMs: number): Promise<void>;
         acquireLocks(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation): Promise<void>;
         observeContext(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
         observeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
             observations: _dbsp_types.IssuedObservation[];
             fingerprint: _dbsp_types.FingerprintManifest;
         }>;
         checkGuard(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
             passed: boolean;
             observations: _dbsp_types.EvidenceObservation[];
             recovery: readonly _dbsp_types.RecoveryArtefact[];
         }>;
         executeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
             kind: string;
         }>;
         writeCompletionJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
         commit(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         rollback(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<void>;
         writeObservedJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, journal: _dbsp_types.StepJournal): Promise<void>;
         isLockTimeout(error: unknown): boolean;
     } | {
         artifact: _dbsp_types.SemanticArtifactRef;
-        operationKind: _dbsp_types.OperationKindRef;
+        executionContractEligibility: {
+            readonly eligible: false;
+            readonly detail: "PostgreSQL AttachLogicalIdentity has no derivable execution requirements yet";
+        };
         supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        renderPlanSql(operation: _dbsp_types.PhysicalOperation): string;
         effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
         buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
             expectedBefore: _dbsp_types.FingerprintManifest;
             expectedAfter: _dbsp_types.FingerprintManifest;
         };
-        checkout(target: unknown): Promise<{
-            readonly opaqueClient: unknown;
+        writeIntentJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        setLockTimeout(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, maxWaitMs: number): Promise<void>;
+        acquireLocks(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(): Promise<{
+            passed: boolean;
+            observations: never[];
+            recovery: never[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation): Promise<{
+            kind: "completed";
         }>;
-        release(client: {
-            readonly opaqueClient: unknown;
-        }, error?: unknown): void;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        executionContractEligibility: {
+            readonly eligible: true;
+        };
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        renderPlanSql(operation: _dbsp_types.PhysicalOperation): string;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
         writeIntentJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
         begin(_client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<never>;
         setLockTimeout(_client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, _maxWaitMs: number): Promise<void>;
         acquireLocks(): Promise<void>;
         observeContext(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
         observeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
             observations: _dbsp_types.IssuedObservation[];
             fingerprint: _dbsp_types.FingerprintManifest;
         }>;
         checkGuard(_client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, _operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard): Promise<never>;
         executeOperation(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[], executionTracker?: _dbsp_core.NonRollbackableExecutionTracker): Promise<{
             kind: "partially-applied";
             recovery: _dbsp_types.RecoveryArtefact[];
@@ -3265,16 +3430,72 @@ declare function createPgTransitionPack(options?: PgTransitionPackOptions): {
             nonRollbackableFootprint: string;
         }>;
         writeCompletionJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
         commit(_client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<never>;
         rollback(_client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }): Promise<never>;
         writeObservedJournal(client: {
-            readonly opaqueClient: unknown;
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        executionContractEligibility: {
+            readonly eligible: false;
+            readonly detail: "PostgreSQL ManualSql has no derivable execution requirements because its statement has no declared schema target";
+        };
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        renderPlanSql(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): string;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, _evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        writeIntentJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        setLockTimeout(_client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, _maxWaitMs: number): Promise<void>;
+        acquireLocks(): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, _operation: _dbsp_types.PhysicalOperation, proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(_client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, phase: "before" | "after"): Promise<{
+            observations: never[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(): Promise<{
+            passed: boolean;
+            observations: never[];
+            recovery: never[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): Promise<{
+            kind: "completed";
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: _dbsp_types.TransitionSessionClient;
         }, journal: _dbsp_types.StepJournal): Promise<void>;
         isLockTimeout(error: unknown): boolean;
     })[];
@@ -3348,6 +3569,11 @@ declare function validateIdentifiers(identifiers: Record<string, 'table' | 'colu
  * NOT for use in SQL - use validateIdentifier + AST helpers for that.
  */
 declare function sanitizeForDisplay(value: string): string;
+/**
+ * Preserve hostile diagnostic text as one printable line without losing which
+ * control character was supplied. This is for diagnostics only, never SQL.
+ */
+declare function escapeDiagnosticText(value: string): string;
 /**
  * Validate a raw SQL expression used in DDL contexts (defaults, policy USING/CHECK).
  * Rejects injection vectors: semicolons, line-comment markers, block-comment markers.
@@ -3359,4 +3585,4 @@ declare function sanitizeForDisplay(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, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type PgAdvisoryLockKey, type PgAdvisoryLockResult, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, PgsqlAdvisoryLockOptionsError, type PgsqlBorrowedClientAdapterOptions, PgsqlPinnedConnectionAbortSignalError, type PgsqlPoolAdapterOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortSignalError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PgsqlTransactionOptionsError, PgsqlTransactionTimeoutError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, SET_NOT_NULL_RULE_ID, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, assertCreateIndexSupported, assertCreateIndexesSupported, assertNoRepeatedExpressionSurfaceDrift, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgObservationIssuer, createPgTransitionPack, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, ensureMigrationsTable, ensureTransitionJournal, excludedRef, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, normalizeManualSqlPayload, parse, parseExplainJson, parseMigrationFile, rawDistance, readPgObservationContext, readTransitionJournal, recordMigration, redactParams, removeMigrationRecord, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateDbspMetaSchemaSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderCreateTransitionJournalTableSql, renderCreateTransitionRunTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderSetNotNullLockSql, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };
+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, 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 };