@dbsp/adapter-pgsql 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1 } from '@dbsp/core';
+import * as _dbsp_core from '@dbsp/core';
+import { IndexInfo, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, ExpressionRef, ModelIR as ModelIR$1, ExecutionCoordinator, CapabilityDescriptor } from '@dbsp/core';
 export { normalizeSQL } from '@dbsp/core';
 import * as _dbsp_types from '@dbsp/types';
-import { DialectCapabilities, ModelIR, ColumnListInput, ParamIntent, JsonAggOrderByEntry, IndexIR, HierarchyIR, Adapter, DbCasing, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, CompileOnlyAdapter, ColumnIR, MutationReturningItem, WhereIntent, QueryIntent } from '@dbsp/types';
+import { DialectCapabilities, ModelIR, ColumnListInput, ParamIntent, JsonAggOrderByEntry, IndexIR, HierarchyIR, Adapter, DbCasing, AdapterLogger, AdapterCapabilities, PlanReport, CompiledNqlQuery, CompileOptions, CompiledQuery, CompileResultWithIncludes, SubqueryIncludeInfo, ExpressionIntent, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, RecursivePlanReport, CteQueryIntent, SetOperationIntent, DumpMeta, Dump, AdapterStreamOptions, 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 * as _pgsql_types from '@pgsql/types';
 import { Node, OnConflictClause, ParamRef } from '@pgsql/types';
 import { Pool, PoolClient } from 'pg';
@@ -727,6 +728,39 @@ declare class PlanCompiler {
  */
 declare function compilePlan(plan: SimplifiedPlanReport, options?: CompilerOptions): CompiledResult;
 
+type IndexRenderKey = {
+    readonly column?: string | undefined;
+    readonly expression?: string | undefined;
+    readonly opclass?: string | undefined;
+};
+type IndexRenderSpec = {
+    readonly name: string;
+    readonly table: string;
+    readonly schema?: string | undefined;
+    readonly unique: boolean;
+    readonly method?: string | undefined;
+    readonly keys: readonly IndexRenderKey[];
+    readonly include?: readonly string[] | undefined;
+    readonly nullsNotDistinct?: boolean | undefined;
+    readonly with?: Readonly<Record<string, unknown>> | undefined;
+    readonly where?: string | undefined;
+    readonly concurrently?: boolean | undefined;
+    readonly ifNotExists?: boolean | undefined;
+};
+type IndexCapabilityContext = {
+    readonly caps: DialectCapabilities;
+    readonly targetVersion?: string | undefined;
+};
+type IndexFeature = 'INCLUDE' | 'PARTIAL INDEX' | 'EXPRESSION INDEX' | 'INDEX METHOD' | 'OPCLASS' | 'NULLS NOT DISTINCT';
+declare class IndexFeatureUnsupportedError extends Error {
+    readonly indexName: string;
+    readonly unsupportedFeatures: readonly IndexFeature[];
+    constructor(indexName: string, unsupportedFeatures: readonly IndexFeature[], message: string);
+}
+declare function assertCreateIndexSupported(spec: IndexRenderSpec, ctx?: IndexCapabilityContext): void;
+declare function assertCreateIndexesSupported(specs: readonly IndexRenderSpec[], ctx?: IndexCapabilityContext): void;
+declare function renderCreateIndex(spec: IndexRenderSpec, ctx?: IndexCapabilityContext): string;
+
 /**
  * DDL Generator - Generates PostgreSQL DDL statements from ModelIR
  *
@@ -753,7 +787,7 @@ interface GenerateDDLOptions {
     readonly fkAutoIndex?: boolean;
     /** Naming plugin for identifier transformation */
     readonly naming?: NamingPlugin;
-    /** Dialect capabilities — DDL passes for unsupported features will be skipped */
+    /** Dialect capabilities — unsupported index features throw during DDL generation */
     readonly dialectCapabilities?: DialectCapabilities;
 }
 /**
@@ -769,7 +803,7 @@ interface GenerateDDLOptions {
  * @returns Array of DDL statements in dependency order
  */
 declare function generateDDL(schema: ModelIR, options?: GenerateDDLOptions): string[];
-declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin): string;
+declare function generateCreateIndex(tableName: string, idx: IndexIR, schemaName: string | undefined, naming: NamingPlugin, context?: IndexCapabilityContext): string;
 /**
  * Returns whether the PostgreSQL DDL generator can emit this IndexIR.
  *
@@ -843,6 +877,8 @@ interface IntrospectedModelIR extends ModelIR {
  */
 declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
 
+type PgsqlTransactionTimeoutParameter = 'lock_timeout' | 'statement_timeout';
+
 /**
  * PgsqlAdapter - Implements the Adapter interface for PostgreSQL using native pg driver.
  *
@@ -852,6 +888,16 @@ declare function introspect(pool: Pool, options?: IntrospectionOptions): Promise
  * @module pgsql-adapter
  */
 
+type PgAdvisoryLockKey = bigint | {
+    readonly classId: number;
+    readonly objId: number;
+};
+type PgAdvisoryLockResult<T> = {
+    readonly acquired: true;
+    readonly value: T;
+} | {
+    readonly acquired: false;
+};
 declare class PgsqlRawSqlTransactionControlError extends Error {
     readonly dbspRawSqlTransactionControl = true;
     constructor(cause: unknown);
@@ -864,6 +910,48 @@ declare class PgsqlTransactionAbortedError extends Error {
     readonly dbspTransactionAborted = true;
     constructor(cause: unknown);
 }
+/**
+ * Raised when a pool-owned top-level transaction is aborted through
+ * `TransactionOptions.signal`. If the signal aborts while `pool.connect()` is
+ * still pending, dbsp honors it only after a client is acquired.
+ */
+declare class PgsqlTransactionAbortSignalError extends Error {
+    readonly dbspTransactionAbortSignal = true;
+    constructor();
+}
+declare class PgsqlPinnedConnectionAbortSignalError extends Error {
+    readonly dbspPinnedConnectionAbortSignal = true;
+    constructor();
+}
+declare class PgsqlTransactionOptionsError extends Error {
+    readonly dbspTransactionOptions = true;
+    constructor(message: string);
+}
+declare class PgsqlAdvisoryLockOptionsError extends Error {
+    readonly dbspAdvisoryLockOptions = true;
+    constructor(message: string);
+}
+/**
+ * Raised when a statement inside a dbsp-managed transaction fails with a SQLSTATE
+ * that matches a timeout the caller configured for that transaction: `55P03`
+ * (`lock_not_available`) when `lockTimeoutMs` was set, or `57014` (`query_canceled`)
+ * when `statementTimeoutMs` was set. The original PostgreSQL error is preserved as
+ * `cause`.
+ *
+ * Classification is by SQLSTATE only. PostgreSQL assigns these codes to the OUTCOME,
+ * not the cause: `55P03` is also raised by `FOR UPDATE NOWAIT`, and `57014` is also
+ * raised by an external cancel (e.g. `pg_cancel_backend`). There is no locale-stable
+ * structured field that separates the timeout from the other cause, so the message
+ * text is deliberately NOT parsed. dbsp never emits `NOWAIT` itself, so a `55P03`
+ * here is the configured `lock_timeout` unless the caller's own raw SQL used
+ * `NOWAIT`; a `57014` is the configured `statement_timeout` unless the backend was
+ * cancelled from outside. Inspect `cause` when that distinction matters.
+ */
+declare class PgsqlTransactionTimeoutError extends Error {
+    readonly timeout: PgsqlTransactionTimeoutParameter;
+    readonly dbspTransactionTimeout = true;
+    constructor(cause: unknown, timeout: PgsqlTransactionTimeoutParameter);
+}
 /**
  * Options for PgsqlAdapter.
  */
@@ -940,6 +1028,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private readonly borrowedClient;
     private readonly managedTransactions;
     private readonly adapterManagedTransaction;
+    private readonly adapterManagedPinnedConnection;
     private readonly scopeToken;
     private readonly scopeState;
     private readonly schemaName;
@@ -980,7 +1069,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private requireNqlCompileModel;
     private assertNqlBindingNamesDisjointFromTables;
     private compileNqlMutation;
-    private compileNqlBundleLeaf;
+    private compileNqlBundleLeafEnvelope;
     private compileNqlBundle;
     /**
      * Returns the pool/client executor, or throws if in compile-only mode.
@@ -1030,7 +1119,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * @param expr - ExpressionIntent to evaluate
      * @returns Compiled SQL and parameters
      */
-    compileSelectExpression(expr: ExpressionIntent): CompiledQuery;
+    compileSelectExpression<T = unknown>(expr: ExpressionIntent): CompiledQuery<T>;
     /**
      * Compile an insert intent to executable SQL.
      *
@@ -1075,7 +1164,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Compile a recursive CTE plan to executable SQL.
      * Supports adjacency-list and edge-table traversal modes.
      */
-    compileRecursive(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    compileRecursive<T = unknown>(report: RecursivePlanReport, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
     /**
      * Compile a CTE query backed by unnest() arrays (BATCH-001 Block 5).
      *
@@ -1083,11 +1172,11 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * independently (parameters starting at $1), then renumber outer params
      * to start after CTE params and prepend WITH clause.
      */
-    compileCteQuery(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery;
+    compileCteQuery<T = unknown>(intent: CteQueryIntent, options?: CompileOptions): CompiledQuery<T>;
     /**
      * Compile a set operation (UNION / INTERSECT / EXCEPT) to SQL.
      */
-    compileSetOperation(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery;
+    compileSetOperation<T = unknown>(intent: SetOperationIntent, model: ModelIR, options?: CompileOptions): CompiledQuery<T>;
     private compileSetOperationWithBindings;
     /**
      * Create a dump for observability.
@@ -1098,6 +1187,15 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
      */
     execute<T>(query: CompiledQuery<T>): Promise<T[]>;
+    /**
+     * Execute a query and return rows plus PostgreSQL result metadata.
+     * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
+     */
+    executeWithMeta<T = unknown>(query: CompiledQuery<T>): Promise<{
+        readonly rows: T[];
+        readonly rowCount: number;
+        readonly command?: string;
+    }>;
     /**
      * Transform result rows from database naming to model naming convention.
      * For CamelCaseNamingPlugin: price_cents → priceCents
@@ -1123,6 +1221,9 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * @returns AsyncIterableIterator that yields rows one by one
      */
     stream<T>(query: CompiledQuery<T>, options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+    /** Stream raw SQL directly using the same cursor machinery as stream(). */
+    streamRaw<T = unknown>(sql: string, parameters?: readonly unknown[], options?: AdapterStreamOptions): AsyncIterableIterator<T>;
+    private streamCursor;
     /**
      * Internal: Stream with an existing client using cursors.
      */
@@ -1144,6 +1245,31 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * ```
      */
     introspect(options?: IntrospectionOptions): Promise<IntrospectedModelIR>;
+    /**
+     * Acquire an exclusive session-level PostgreSQL advisory lock for the callback.
+     *
+     * The lock, callback, and unlock run on one `withPinnedConnection()` adapter.
+     * dbsp performs one PostgreSQL acquire and one matching unlock per call. It
+     * does not track reentrant depth in v1; PostgreSQL's session-level stacking
+     * still applies when callers deliberately nest on the same pinned adapter.
+     */
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>): Promise<T>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options: {
+        readonly wait?: 'block';
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options: {
+        readonly wait: 'try';
+        readonly signal?: AbortSignal;
+    }): Promise<PgAdvisoryLockResult<T>>;
+    withAdvisoryLock<T>(key: PgAdvisoryLockKey, fn: (locked: Adapter<DB>) => Promise<T>, options?: {
+        readonly wait?: 'block' | 'try';
+        readonly signal?: AbortSignal;
+    }): Promise<T | PgAdvisoryLockResult<T>>;
+    private unlockAdvisoryLock;
+    withPinnedConnection<T>(fn: (adapter: Adapter<DB>) => Promise<T>, options?: PinnedConnectionOptions): Promise<T>;
+    private pinnedConnectionReleaseReason;
+    private pinnedConnectionWithClient;
     /**
      * Execute a callback within a database transaction.
      *
@@ -1173,7 +1299,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * and hand dbsp a `borrowedClient` **without** `managedTransactions`. dbsp will then
      * contain its own statements inside *your* transaction instead of the other way round.
      */
-    transaction<T>(fn: (adapter: Adapter<DB>) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (adapter: Adapter<DB>) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
      * Execute scratch PostgreSQL work in a scope that always rolls back on success.
      *
@@ -1185,12 +1311,16 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     withScratchScope<T>(fn: (adapter: PgsqlAdapter<DB>) => Promise<T>): Promise<T>;
     private createManagedClientAdapter;
+    private createPinnedConnectionAdapter;
     private createChildTransactionObserver;
     private observeChildTransaction;
     private markChildTransactionObserved;
     private refreshScopeChildrenFailure;
     private transactionWithManagedClient;
     private transactionWithManagedClientSavepointScope;
+    private applyTransactionTimeouts;
+    private captureAndApplySavepointTimeouts;
+    private restoreSavepointTimeouts;
     private transactionWithClientTransaction;
     private releaseClient;
     private rollbackAndReleaseSavepoint;
@@ -1202,9 +1332,11 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private classifySavepointReleaseFailure;
     private rollbackSavepointAfterReleaseFailure;
     private enterTransactionScope;
+    private enterPinnedConnectionScope;
     private enterSavepointScope;
     private pushClientScope;
     private currentClientScope;
+    private managedScopeEndedMessage;
     private assertCanUseClient;
     private assertUsableScopeAncestors;
     private findClientScope;
@@ -1269,6 +1401,7 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      */
     get inTransaction(): boolean;
     private adapterManagedScopeIsLive;
+    private shouldProtectBorrowedClientTransaction;
     private executeQueryProtectingOpenTransaction;
     private executeConnectionStatement;
     private executeConnectionStatementUnlocked;
@@ -1318,27 +1451,27 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
      * Generate SQL for TRUNCATE TABLE.
      * Implements TableDDLGeneratorAdapter.generateTruncate.
      */
-    generateTruncate(table: string, schema?: string, options?: TruncateOptions): string;
+    generateTruncate(table: string, schemaName: string, options?: TruncateOptions): string;
     /**
      * Generate SQL for VACUUM.
      * Implements TableDDLGeneratorAdapter.generateVacuum.
      */
-    generateVacuum(table: string, schema?: string, options?: VacuumOptions): string;
+    generateVacuum(table: string, schemaName: string, options?: VacuumOptions): string;
     /**
      * Generate SQL for ALTER TABLE ... ALTER COLUMN.
      * Implements TableDDLGeneratorAdapter.generateAlterColumn.
      */
-    generateAlterColumn(table: string, column: string, options: AlterColumnOptions, schema?: string): string;
+    generateAlterColumn(table: string, schemaName: string, column: string, options: AlterColumnOptions): string;
     /**
      * Generate SQL for CREATE INDEX.
      * Implements TableDDLGeneratorAdapter.generateCreateIndex.
      */
-    generateCreateIndex(table: string, options: CreateIndexOptions, schema?: string): string;
+    generateCreateIndex(table: string, schemaName: string, options: CreateIndexOptions): string;
     /**
      * Generate SQL for DROP INDEX.
      * Implements TableDDLGeneratorAdapter.generateDropIndex.
      */
-    generateDropIndex(name: string, options?: DropIndexOptions): string;
+    generateDropIndex(name: string, schemaName: string, options?: DropIndexOptions): string;
     /**
      * Validate an identifier (table name, column name, schema name).
      */
@@ -1562,7 +1695,7 @@ interface MigrationSQLOptions {
     readonly includeDestructive?: boolean;
     /** Automatically create indexes on FK columns for new tables (default: true) */
     readonly fkAutoIndex?: boolean;
-    /** Dialect capabilities — migration SQL for unsupported features will be filtered */
+    /** Dialect capabilities — unsupported index features throw during migration SQL generation */
     readonly dialectCapabilities?: DialectCapabilities;
 }
 /**
@@ -1657,9 +1790,12 @@ interface MigrationRecord {
     readonly destructive: boolean;
 }
 /**
- * Execute a callback under an advisory lock using a dedicated client.
+ * Execute a callback under the migration advisory lock using a pinned client.
  * The lock is held for the duration of the callback.
- * The client is released (and lock freed) after the callback completes.
+ *
+ * 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>;
 /**
@@ -2341,6 +2477,8 @@ declare function collectAndValidateParamRefs(node: unknown): {
     allValid: boolean;
 };
 
+declare function derivePostgresqlCapabilitiesForVersion(version: string): DialectCapabilities;
+
 /**
  * Redact sensitive values in a query dump's `params` array before logging.
  *
@@ -2371,6 +2509,28 @@ declare const DEFAULT_REDACTION_PATTERNS: ReadonlyArray<RegExp>;
  */
 declare function redactParams(params: readonly unknown[], config: RedactionConfig): readonly unknown[];
 
+declare const projectionEnvelopeBrand: unique symbol;
+type ProjectionEnvelope<T = unknown> = {
+    readonly [projectionEnvelopeBrand]: true;
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+    readonly ast?: Node;
+    readonly projection: ProjectionState;
+    readonly hydrationPlan?: PlanReport;
+    readonly __resultType?: T;
+};
+type ProjectionState = {
+    readonly kind: 'known';
+    readonly outputs: ReadonlyMap<string, OutputProjection>;
+} | {
+    readonly kind: 'dropped';
+    readonly reason: ProjectionDropReason;
+    readonly hadConvertibleSource: boolean;
+};
+type OutputProjection = OutputDescriptor;
+
+type ProjectionDropReason = 'set-operation-positional-merge' | 'raw-recursive-cte-positional-merge' | 'unknown-raw-sql' | 'unsupported-source';
+
 /**
  * Set operation compiler (UNION / INTERSECT / EXCEPT)
  *
@@ -2379,37 +2539,33 @@ declare function redactParams(params: readonly unknown[], config: RedactionConfi
  */
 
 /**
- * Compiled SQL with positional parameters.
+ * Compiled set-operation SQL with positional parameters.
  */
-interface SetOperationResult {
-    readonly sql: string;
-    readonly parameters: readonly unknown[];
-}
+type SetOperationResult<T = unknown> = CompiledQuery<T>;
 /**
- * Function that compiles a single QueryIntent leaf to SQL + parameters.
+ * Function that compiles a single QueryIntent leaf to a projection envelope, or
+ * a compiled query that can be bridged into one.
  * Provided by the caller to decouple from adapter internals.
  */
-type LeafCompileFn = (query: QueryIntent) => {
-    sql: string;
-    parameters: readonly unknown[];
-};
+type LeafCompileResult = ProjectionEnvelope | CompiledQuery;
+type LeafCompileFn = (query: QueryIntent) => LeafCompileResult;
 /**
  * Recursively compile a SetOperationIntent to SQL with merged parameters.
  *
- * Each leaf QueryIntent is compiled via `compileFn`. When merging left and
- * right branches, the right side's `$N` placeholders are renumbered so they
- * don't collide with the left side's parameters.
+ * Each leaf QueryIntent is compiled via `compileFn` to a projection envelope.
+ * When merging left and right branches, the right side's `$N` placeholders are
+ * renumbered so they don't collide with the left side's parameters. The final
+ * set operation drops positional projection provenance through the envelope so
+ * `finalizeEnvelope` owns the set-operation `js` fail-loud behavior.
  *
  * @param intent - The set operation intent (recursive tree)
- * @param compileFn - Compiles a single QueryIntent to SQL + params
+ * @param compileFn - Compiles a single QueryIntent to an envelope-compatible result
  * @returns Combined SQL string and merged parameter array
  *
  * @example
  * ```typescript
- * const result = compileSetOperation(setOpIntent, (query) => {
- *   const planReport = plan(query, model, { dialectCapabilities });
- *   return adapter.compile(planReport, { model });
- * });
+ * const compileFn = createLeafCompileFn(adapter, model, plan);
+ * const result = compileSetOperation(setOpIntent, compileFn);
  * console.log(result.sql);        // (SELECT ...) UNION (SELECT ...)
  * console.log(result.parameters);  // [...leftParams, ...rightParams]
  * ```
@@ -2428,10 +2584,7 @@ declare function compileSetOperation(intent: SetOperationIntent, compileFn: Leaf
 declare function createLeafCompileFn(adapter: {
     compile(plan: PlanReport, options: CompileOptions & {
         model: ModelIR$1;
-    }): {
-        sql: string;
-        parameters: readonly unknown[];
-    };
+    }): CompiledQuery;
     dialectCapabilities: DialectCapabilities;
 }, model: ModelIR$1, planFn: (intent: QueryIntent, model: ModelIR$1, options: {
     dialectCapabilities: DialectCapabilities;
@@ -2593,6 +2746,550 @@ declare function buildStreamingStatements(query: Node, config?: StreamConfig): {
     close: Node;
 };
 
+declare const PG_OPERATION_PACK_ARTIFACT: SemanticArtifactRef;
+declare const PG_RULE_PACK_ARTIFACT: SemanticArtifactRef;
+declare const PG_INTROSPECTION_ARTIFACT: SemanticArtifactRef;
+declare const ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND: OperationKindRef;
+declare const ALTER_TYPE_ADD_VALUE_OPERATION_KIND: OperationKindRef;
+declare const ATTACH_LOGICAL_IDENTITY_OPERATION_KIND: OperationKindRef;
+declare const MANUAL_SQL_OPERATION_KIND: OperationKindRef;
+declare const SET_NOT_NULL_RULE_ID = "postgresql.column.set-not-null";
+declare const ADD_CHECK_RULE_ID = "postgresql.table.add-check";
+declare const ENUM_ADD_VALUE_RULE_ID = "postgresql.enum.add-value";
+declare const LOGICAL_IDENTITY_ADOPTION_RULE_ID = "postgresql.logical-identity.adopt";
+declare const DBSP_META_SCHEMA = "dbsp_meta";
+declare const DBSP_TRANSITION_RUN_TABLE = "dbsp_transition_run";
+declare const DBSP_TRANSITION_JOURNAL_TABLE = "dbsp_transition_journal";
+declare const DBSP_LOGICAL_IDENTITY_TABLE = "dbsp_logical_identity";
+declare const COLUMN_EXISTS_OBSERVATION = "postgresql.column.exists";
+declare const ENUM_TYPE_EXISTS_OBSERVATION = "postgresql.enum-type.exists";
+declare const ENUM_LABEL_VISIBLE_OBSERVATION = "postgresql.enum-label.visible";
+declare const ALTER_AUTHORITY_OBSERVATION = "postgresql.table.alter-authority";
+declare const ENGINE_VERSION_OBSERVATION = "postgresql.engine.version-supported";
+declare const LOGICAL_IDENTITY_CARRIER_OBSERVATION = "postgresql.logical-identity.carrier-state";
+declare const NO_NULLS_GUARD = "NO_NULLS";
+
+type QueryResultLike = {
+    readonly rows: readonly Record<string, unknown>[];
+};
+type TransitionJournalQueryable = {
+    query(sql: string, params?: readonly unknown[]): Promise<QueryResultLike>;
+};
+declare function renderCreateDbspMetaSchemaSql(): string;
+declare function renderCreateTransitionRunTableSql(): string;
+declare function renderCreateTransitionJournalTableSql(): string;
+declare function ensureTransitionJournal(executor: TransitionJournalQueryable): Promise<void>;
+declare function readTransitionJournal(executor: TransitionJournalQueryable, runId: string): Promise<TransitionRunJournal>;
+
+type ObservationTarget = {
+    readonly table: string;
+    readonly column?: string;
+    readonly constraint?: string;
+    readonly index?: string;
+    readonly schema?: string;
+};
+type EnumObservationTarget = {
+    readonly type: string;
+    readonly label?: string;
+    readonly schema?: string;
+};
+declare function createPgObservationIssuer(): ObservationIssuer;
+declare function readPgObservationContext(target: unknown, schema?: string, observationTarget?: ObservationTarget | EnumObservationTarget): Promise<ObservationContext>;
+
+interface SetNotNullColumnShapeExpectation {
+    readonly kind: 'postgresql.set-not-null.column-shape.v1';
+    readonly name: string;
+    readonly nullability: {
+        readonly from: true;
+        readonly to: boolean;
+    };
+    readonly type: TypeRef;
+    readonly default: ExpressionValue | null;
+    readonly collation: CollationRef;
+    readonly identity: 'always' | 'byDefault' | null;
+    readonly generated: string | null;
+    readonly autoIncrement: boolean;
+    readonly unique: boolean;
+    readonly uniqueConstraintName: string | null;
+    readonly logicalIdentity?: LogicalIdentity | null;
+    readonly comment: string | null;
+    readonly target?: ColumnDefaultAttestationTarget;
+}
+interface ColumnDefaultAttestationTarget {
+    readonly database?: string;
+    readonly schema?: string;
+    readonly table: string;
+    readonly column: string;
+}
+
+type AlterColumnSetNotNullPayload = {
+    readonly table: string;
+    readonly column: string;
+    readonly schema?: string;
+    readonly expectedColumnShape?: SetNotNullColumnShapeExpectation;
+};
+type TransitionExecutionClient$3 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAlterColumnSetNotNullSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function renderSetNotNullLockSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function renderNoNullsCheckSql(payload: AlterColumnSetNotNullPayload, context: ObservationContext): string;
+declare function beforeAfterFingerprints$3(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAlterColumnSetNotNullOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$3;
+    checkout(target: unknown): Promise<TransitionExecutionClient$3>;
+    release(client: TransitionExecutionClient$3, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$3, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$3): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$3, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$3, operation: PhysicalOperation, _effects: OperationEffectAssessment, context: ObservationContext): Promise<void>;
+    observeContext(client: TransitionExecutionClient$3, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$3, operation: PhysicalOperation, context: ObservationContext, _phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(client: TransitionExecutionClient$3, operation: PhysicalOperation, guard: ApplyGuard, context: ObservationContext): Promise<{
+        passed: boolean;
+        observations: AdvisoryObservation[];
+        recovery: readonly _dbsp_types.RecoveryArtefact[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$3, operation: PhysicalOperation, context: ObservationContext, duringGuards?: readonly ApplyGuard[]): Promise<{
+        kind: string;
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$3, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$3): Promise<void>;
+    rollback(client: TransitionExecutionClient$3): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$3, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type AlterTypeAddValuePayload = {
+    readonly schema: string;
+    readonly type: string;
+    readonly label: string;
+    readonly after?: string;
+    readonly expectedBefore: readonly string[];
+    readonly expectedAfter: readonly string[];
+};
+type TransitionExecutionClient$2 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAlterTypeAddValueSql(payload: AlterTypeAddValuePayload, context: ObservationContext): string;
+declare function beforeAfterFingerprints$2(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAlterTypeAddValueOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    operationKind: _dbsp_types.OperationKindRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$2;
+    checkout(target: unknown): Promise<TransitionExecutionClient$2>;
+    release(client: TransitionExecutionClient$2, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$2, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$2): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$2, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$2, operation: PhysicalOperation): Promise<void>;
+    observeContext(client: TransitionExecutionClient$2, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$2, operation: PhysicalOperation, context: ObservationContext, _phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(client: TransitionExecutionClient$2, operation: PhysicalOperation, guard: ApplyGuard, context: ObservationContext): Promise<{
+        passed: boolean;
+        observations: EvidenceObservation[];
+        recovery: readonly _dbsp_types.RecoveryArtefact[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$2, operation: PhysicalOperation, context: ObservationContext, duringGuards?: readonly ApplyGuard[]): Promise<{
+        kind: string;
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$2, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$2): Promise<void>;
+    rollback(client: TransitionExecutionClient$2): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$2, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type AttachLogicalIdentityPayload = {
+    readonly schema: string;
+    readonly table: string;
+    readonly column?: string;
+    readonly logicalId: string;
+    readonly carrierKind: 'postgresql-side-table';
+    readonly authenticated: false;
+};
+type TransitionExecutionClient$1 = {
+    readonly opaqueClient: unknown;
+};
+declare function renderAttachLogicalIdentityLockSql(payload: AttachLogicalIdentityPayload): string;
+declare function renderCreateLogicalIdentitySideTableSql(_schema: string): string;
+declare function renderCreateLogicalIdentityIndexesSql(_schema: string): readonly string[];
+declare function renderInsertLogicalIdentitySql(_schema: string): string;
+declare function beforeAfterFingerprints$1(operation: PhysicalOperation, evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createAttachLogicalIdentityOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints$1;
+    checkout(target: unknown): Promise<TransitionExecutionClient$1>;
+    release(client: TransitionExecutionClient$1, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient$1, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient$1): Promise<void>;
+    setLockTimeout(client: TransitionExecutionClient$1, maxWaitMs: number): Promise<void>;
+    acquireLocks(client: TransitionExecutionClient$1, operation: PhysicalOperation): Promise<void>;
+    observeContext(client: TransitionExecutionClient$1, operation: PhysicalOperation, _proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(client: TransitionExecutionClient$1, operation: PhysicalOperation, context: ObservationContext, phase: "before" | "after", issuer: ObservationIssuer): Promise<{
+        observations: IssuedObservation[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(): Promise<{
+        passed: boolean;
+        observations: never[];
+        recovery: never[];
+    }>;
+    executeOperation(client: TransitionExecutionClient$1, operation: PhysicalOperation): Promise<{
+        kind: "completed";
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient$1, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient$1): Promise<void>;
+    rollback(client: TransitionExecutionClient$1): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient$1, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+type ManualSqlPayload = {
+    readonly statement: UnsafeNativeFragment;
+    readonly blastRadius: readonly ResourceAddress[];
+    readonly preconditions: readonly ExecutableAssertion[];
+    readonly postconditions: readonly ExecutableAssertion[];
+};
+type TransitionExecutionClient = {
+    readonly opaqueClient: unknown;
+};
+declare function normalizeManualSqlPayload(payload: ManualSqlPayload, context: ObservationContext): ManualSqlPayload;
+declare function beforeAfterFingerprints(operation: PhysicalOperation, _evidence: readonly EvidenceObservation[], context: ObservationContext): {
+    expectedBefore: FingerprintManifest;
+    expectedAfter: FingerprintManifest;
+};
+declare function createManualSqlOperationRuntime(): {
+    artifact: _dbsp_types.SemanticArtifactRef;
+    operationKind: _dbsp_types.OperationKindRef;
+    supportsOperation(operation: PhysicalOperation): boolean;
+    effectsOf(operation: PhysicalOperation, context: ObservationContext): OperationEffectAssessment;
+    buildFingerprints: typeof beforeAfterFingerprints;
+    checkout(target: unknown): Promise<TransitionExecutionClient>;
+    release(client: TransitionExecutionClient, error?: unknown): void;
+    writeIntentJournal(client: TransitionExecutionClient, record: DurableIntentRecord): Promise<void>;
+    begin(client: TransitionExecutionClient): Promise<void>;
+    setLockTimeout(_client: TransitionExecutionClient, _maxWaitMs: number): Promise<void>;
+    acquireLocks(): Promise<void>;
+    observeContext(client: TransitionExecutionClient, _operation: PhysicalOperation, proofContext: ObservationContext): Promise<ObservationContext>;
+    observeOperation(_client: TransitionExecutionClient, operation: PhysicalOperation, context: ObservationContext, phase: "before" | "after"): Promise<{
+        observations: never[];
+        fingerprint: FingerprintManifest;
+    }>;
+    checkGuard(): Promise<{
+        passed: boolean;
+        observations: never[];
+        recovery: never[];
+    }>;
+    executeOperation(client: TransitionExecutionClient, operation: PhysicalOperation, context: ObservationContext): Promise<{
+        kind: "completed";
+    }>;
+    writeCompletionJournal(client: TransitionExecutionClient, operation: PhysicalOperation, record: TransactionalCompletionRecord): Promise<void>;
+    commit(client: TransitionExecutionClient): Promise<void>;
+    rollback(client: TransitionExecutionClient): Promise<void>;
+    writeObservedJournal(client: TransitionExecutionClient, journal: StepJournal): Promise<void>;
+    isLockTimeout(error: unknown): boolean;
+};
+
+interface SetNotNullMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly column: string;
+    readonly expectedColumnShape: SetNotNullColumnShapeExpectation;
+    readonly assumptions?: readonly Assumption[];
+}
+interface SetNotNullRuleOptions {
+    readonly naming?: NamingPlugin;
+}
+declare function createSetNotNullRule(options?: SetNotNullRuleOptions): TransitionRule<SetNotNullMatch>;
+
+interface EnumAddValueMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly type: string;
+    readonly label: string;
+    readonly after?: string;
+    readonly expectedBefore: readonly string[];
+    readonly expectedAfter: readonly string[];
+    readonly assumptions?: readonly Assumption[];
+}
+interface EnumAddValueRuleOptions {
+    readonly naming?: NamingPlugin;
+}
+declare function satisfiesPgEnumLabelVisibleCompositionFact(fact: TransitionCompositionFact, current: ModelIR, _context: ObservationContext): boolean;
+declare function createEnumAddValueRule(options?: EnumAddValueRuleOptions): TransitionRule<EnumAddValueMatch>;
+
+interface CreateUniqueIndexConcurrentlyMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly index: string;
+    readonly columns: readonly string[];
+    readonly assumptions?: readonly Assumption[];
+}
+
+type IdentityAdoptionAsserter = Exclude<TrustRoot, {
+    readonly kind: 'pack';
+}>;
+interface LogicalIdentityAdoptionMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly column?: string;
+    readonly logicalId: string;
+    readonly carrierKind: 'postgresql-side-table';
+    readonly authenticated: false;
+    readonly selectionBasis: string;
+}
+interface LogicalIdentityAdoptionRuleOptions {
+    readonly naming?: NamingPlugin;
+    readonly asserter?: IdentityAdoptionAsserter;
+    readonly selectionBasis?: string;
+}
+declare function createLogicalIdentityAdoptionRule(options?: LogicalIdentityAdoptionRuleOptions): TransitionRule<LogicalIdentityAdoptionMatch>;
+
+interface AddCheckMatch {
+    readonly schema?: string;
+    readonly database?: string;
+    readonly table: string;
+    readonly constraint: string;
+    readonly expression: string;
+    readonly requiresEnumLabels?: readonly RequiredEnumLabelIR[];
+    readonly assumptions?: readonly Assumption[];
+}
+
+interface PgTransitionPackOptions {
+    readonly dbCasing?: DbCasing;
+    readonly naming?: NamingPlugin;
+    readonly identityAdoptionAsserter?: IdentityAdoptionAsserter;
+    readonly identityAdoptionSelectionBasis?: string;
+}
+declare function createPgTransitionPack(options?: PgTransitionPackOptions): {
+    rules: (_dbsp_types.TransitionRule<AddCheckMatch> | _dbsp_types.TransitionRule<LogicalIdentityAdoptionMatch> | _dbsp_types.TransitionRule<CreateUniqueIndexConcurrentlyMatch> | _dbsp_types.TransitionRule<EnumAddValueMatch> | _dbsp_types.TransitionRule<SetNotNullMatch>)[];
+    operationSemantics: ({
+        artifact: _dbsp_types.SemanticArtifactRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        setLockTimeout(client: {
+            readonly opaqueClient: unknown;
+        }, maxWaitMs: number): Promise<void>;
+        acquireLocks(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _effects: _dbsp_types.OperationEffectAssessment, context: _dbsp_types.ObservationContext): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
+            passed: boolean;
+            observations: _dbsp_types.AdvisoryObservation[];
+            recovery: readonly _dbsp_types.RecoveryArtefact[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
+            kind: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        setLockTimeout(client: {
+            readonly opaqueClient: unknown;
+        }, maxWaitMs: number): Promise<void>;
+        acquireLocks(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, _phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard, context: _dbsp_types.ObservationContext): Promise<{
+            passed: boolean;
+            observations: _dbsp_types.EvidenceObservation[];
+            recovery: readonly _dbsp_types.RecoveryArtefact[];
+        }>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[]): Promise<{
+            kind: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        rollback(client: {
+            readonly opaqueClient: unknown;
+        }): Promise<void>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    } | {
+        artifact: _dbsp_types.SemanticArtifactRef;
+        operationKind: _dbsp_types.OperationKindRef;
+        supportsOperation(operation: _dbsp_types.PhysicalOperation): boolean;
+        effectsOf(operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext): _dbsp_types.OperationEffectAssessment;
+        buildFingerprints: (operation: _dbsp_types.PhysicalOperation, evidence: readonly _dbsp_types.EvidenceObservation[], context: _dbsp_types.ObservationContext) => {
+            expectedBefore: _dbsp_types.FingerprintManifest;
+            expectedAfter: _dbsp_types.FingerprintManifest;
+        };
+        checkout(target: unknown): Promise<{
+            readonly opaqueClient: unknown;
+        }>;
+        release(client: {
+            readonly opaqueClient: unknown;
+        }, error?: unknown): void;
+        writeIntentJournal(client: {
+            readonly opaqueClient: unknown;
+        }, record: _dbsp_types.DurableIntentRecord): Promise<void>;
+        begin(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        setLockTimeout(_client: {
+            readonly opaqueClient: unknown;
+        }, _maxWaitMs: number): Promise<void>;
+        acquireLocks(): Promise<void>;
+        observeContext(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, _proofContext: _dbsp_types.ObservationContext): Promise<_dbsp_types.ObservationContext>;
+        observeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, phase: "before" | "after", issuer: _dbsp_types.ObservationIssuer): Promise<{
+            observations: _dbsp_types.IssuedObservation[];
+            fingerprint: _dbsp_types.FingerprintManifest;
+        }>;
+        checkGuard(_client: {
+            readonly opaqueClient: unknown;
+        }, _operation: _dbsp_types.PhysicalOperation, guard: _dbsp_types.ApplyGuard): Promise<never>;
+        executeOperation(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, context: _dbsp_types.ObservationContext, duringGuards?: readonly _dbsp_types.ApplyGuard[], executionTracker?: _dbsp_core.NonRollbackableExecutionTracker): Promise<{
+            kind: "partially-applied";
+            recovery: _dbsp_types.RecoveryArtefact[];
+            detail: string;
+        } | {
+            kind: string;
+            guard?: never;
+            recovery?: never;
+            nonRollbackableFootprint?: never;
+        } | {
+            kind: string;
+            guard: _dbsp_types.ApplyGuard;
+            recovery: never[];
+            nonRollbackableFootprint: string;
+        }>;
+        writeCompletionJournal(client: {
+            readonly opaqueClient: unknown;
+        }, operation: _dbsp_types.PhysicalOperation, record: _dbsp_types.TransactionalCompletionRecord): Promise<void>;
+        commit(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        rollback(_client: {
+            readonly opaqueClient: unknown;
+        }): Promise<never>;
+        writeObservedJournal(client: {
+            readonly opaqueClient: unknown;
+        }, journal: _dbsp_types.StepJournal): Promise<void>;
+        isLockTimeout(error: unknown): boolean;
+    })[];
+    issuer: _dbsp_types.ObservationIssuer;
+    executionCoordinator: ExecutionCoordinator;
+    transactionDomain: string;
+    equivalence: _dbsp_types.EquivalenceCapability;
+    capabilityDescriptors: readonly CapabilityDescriptor[];
+    comparatorNameNormalizer: {
+        normalizeCurrentIdentifier: (identifier: string) => string;
+    };
+    compositionFactKinds: string[];
+    satisfiesCompositionFact: typeof satisfiesPgEnumLabelVisibleCompositionFact;
+};
+
 /**
  * Identifier Validation for adapter-pgsql
  *
@@ -2662,4 +3359,4 @@ declare function sanitizeForDisplay(value: string): string;
  */
 declare function validateSqlExpression(sql: string, context: string): void;
 
-export { type AddedEnumValue, type BatchValuesJoinDecision, 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, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, type LeafCompileFn, type MigrationRecord, type MigrationSQLOptions, type NamingPlugin, NonConvergentSchemaDiffError, type ParamRefValidationResult, type ParsedMigrationFile, PgsqlAdapter, type PgsqlAdapterOptions, type PgsqlBorrowedClientAdapterOptions, type PgsqlPoolAdapterOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, 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, createAnyExpr, createEqualityExpr, createLeafCompileFn, createParamRef, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createTypeCastParamRef, defaultFkDerivation, ensureMigrationsTable, excludedRef, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, parse, parseExplainJson, parseMigrationFile, rawDistance, recordMigration, redactParams, removeMigrationRecord, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };
+export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, type ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type 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 };