@dbsp/core 3.1.0 → 3.3.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _dbsp_types from '@dbsp/types';
-import { PseudoColumnMetadata, RecursiveMetadata, RelationIR, RelationKind, AdapterCapabilities, Adapter, BaseAdapter, DDLGeneratingAdapter, ExecutingAdapter, IntrospectingAdapter, RawSqlAdapter, StreamingAdapter, TransactionalAdapter, ColumnType, ColumnJsReadType as ColumnJsReadType$1, WhereIntent, OnDeleteAction, ModelIR, DbCasing, QueryIntent, PlanOptions, PlanReport, RecursiveIntent, RecursivePlanOptions, RecursivePlanReport, ObservationContext, TransitionConnectionPool, IssuedObservation, RecoveryArtefact, FingerprintManifest, OperationSemantics, OperationKindRef, PhysicalOperation, EvidenceObservation, DurableIntentRecord, OperationEffectAssessment, ObservationIssuer, ApplyGuard, OperationExecutionOutcome, TransactionalCompletionRecord, StepJournal, TransitionRule, EquivalenceCapability, CapabilityDescriptor, TransitionCompositionFact, RuleRef, SemanticArtifactRef, CheckConstraintIR, Comparator, EnumIR, ObservationRequest, EvidenceView, AdvisoryObservationId, AssumptionId, ClaimId, EvidenceId, SemanticArtifactId, IndexIR, ResourceAddress, ResourceSelector, ApplyPolicy, ApplyResult, TransitionCandidate, TransitionFragmentComposition, PlanAssessment, CompareOutcome, TransitionFragment, ProofClaim, Assumption, ProvenPlanShape, ApplicableAssessment, TransitionRunJournal, InapplicableAssessment, TableIR, SequenceIR, AmbiguityCheckResult, DialectCapabilities, DDLFeature, DDLFeatureVersionRange, SelectIntent, IncludeIntent, AggregateIntent, OrderByIntent, SortDirection, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, Dump, SetOperationIntent, LockStrength, LockWaitPolicy, DumpMeta, JoinIntent, UnnestCteIntent, CteQueryIntent, CompileOptions, CompiledQuery, MutationIntent as MutationIntent$1, DumpSequenceStep, UpsertConflictTarget, UpsertConflictAction, RawCteIntent, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, IndexInfo, ExpressionIntent, ComparisonOperator, WhereSubqueryIntent, SubqueryRefIntent, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereRelationFilterIntent, RecursiveExistsOptions, WhereExistsIntent, WhereInIntent, WhereNullIntent, WhereLikeIntent, WhereNotIntent, WhereNotExistsIntent, WhereOrIntent, WhereRawExistsIntent, WhereRawNotExistsIntent, WhereExpressionIntent, AggOrderByArg, RelationType as RelationType$1, Cardinality, FeatureWarning, UnsupportedFeatureBehavior, FeatureBehaviorConfig, RangeValue, WhereRangeIntent, SubqueryIncludeInfo } from '@dbsp/types';
-export { Adapter, AdapterCapabilities, AdapterLogger, AdapterStreamOptions, AdjacencyTraversal, AggregateExpressionIntent, AggregateFunction, AggregateIntent, AggregateWindowFunction, AliasIncludedColumnsMode, AlterColumnOptions, AmbiguityCheckResult, ApplicableAssessment, ApplicableEvaluation, ApplyPolicy, ArrayOperator, Assumption, BaseAdapter, CTEDefinition, CapabilityDescriptor, Cardinality, CaseExpressionIntent, CoalesceExpressionIntent, ColumnAliasIntent, ColumnExpressionIntent, ColumnIR, ColumnJsReadType, ColumnType, CommonColumnType, Comparator, CompareOutcome, ComparisonExpressionIntent, ComparisonOperator, CompileOnlyAdapter, CompileOptions, CompileResultWithIncludes, CompiledQuery, CompilingAdapter, CreateIndexOptions, CustomTraversal, DDLGeneratingAdapter, DbCasing, DecisionType, DeleteIntent, DialectCapabilities, DialectName, DropIndexOptions, DuckDBColumnType, Dump, DumpMeta, DurableIntentRecord, EdgeTableTraversal, EmitJoinClause, ExecutingAdapter, ExpressionIntent, FilterStrategy, FingerprintManifest, ForeignKeyIR, InapplicableAssessment, IncludeIntent, IncludeStrategy, IndexColumnDef, IndexIR, IndexInfo, IndexMethod, InsertFromIntent, InsertIntent, IntrospectingAdapter, IsTypeSupported, JoinDefault, JoinIntent, LiteralExpressionIntent, LogicalIdentity, LogicalIdentityCarrier, LogicalOperator, MSSQLColumnType, ModelIR, MutationIntent, MySQLColumnType, NullOperator, NullsPosition, ObservationContext, ObservationIssuer, ObservationRequest, OffsetWindowFunction, OnDeleteAction, OperationEffectAssessment, OperationSemantics, Optionality, OrderByIntent, PartitionIR, PhysicalOperation, PlanDecision, PlanOptions, PlanReport, PlanWarning, PlanWarningCode, PostgresColumnType, PostgresOnlyColumnType, ProvenApplyGuard, ProvenGuardProtocol, ProvenPlanShape, ProvenPlanStep, PseudoColumnExpressionIntent, PseudoColumnMetadata, PseudoColumnTraversal, QueryIntent, RangeOperator, RangeValue, RankingWindowFunction, RawExpressionIntent, RawSqlAdapter, RecognitionResult, RecursiveAdvancedOptions, RecursiveDedupe, RecursiveDirection, RecursiveEmitOptions, RecursiveExistsOptions, RecursiveIntent, RecursiveMetadata, RecursiveNodeIdExpr, RecursivePlanOptions, RecursivePlanReport, RecursiveTrackOptions, RecursiveTraversal, RelationColumnIntent, RelationIR, RelationKind, RelationOperator, RelationType, RequiredEnumLabelIR, ResolvedIncludeStrategy, ResourceAddress, RuleEvaluation, RuleSupport, SQLiteColumnType, SelectAggregateIntent, SelectAllIntent, SelectFieldsIntent, SelectIntent, SelectWithExpressionsIntent, SerializedProvenPlan, SortDirection, StepJournal, StreamingAdapter, StringOperator, SubqueryIncludeInfo, SubqueryRefIntent, SupportedColumnTypes, TableIR, TransactionalAdapter, TransactionalCompletionRecord, TransitionCandidate, TransitionConnectionPool, TransitionQueryClient, TransitionRule, TransitionRunMetadata, TruncateOptions, UpdateIntent, UpsertConflictAction, UpsertConflictTarget, UpsertFromIntent, UpsertIntent, VacuumOptions, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereExistsIntent, WhereInIntent, WhereIntent, WhereLikeIntent, WhereNotExistsIntent, WhereNotIntent, WhereNullIntent, WhereOrIntent, WhereRangeIntent, WhereRelationFilterIntent, WhereSubqueryIntent, WindowFunction, WindowIntent, WindowOrderBy, getNodeIdAlias, isAdjacencyTraversal, isAggregateWindowFunction, isCoalesceExpression, isColumnAliasExpression, isCustomTraversal, isDeleteIntent, isEdgeTableTraversal, isInsertIntent, isMutationIntent, isRankingWindowFunction, isRawExpression, isRecursiveIntent, isRelationColumnExpression, isSelectAggregate, isSelectAll, isSelectFields, isSelectWithExpressions, isSubqueryRef, isUpdateIntent, isUpsertIntent, isWhereAnd, isWhereAny, isWhereComparison, isWhereExists, isWhereIn, isWhereLike, isWhereLogical, isWhereNot, isWhereNotExists, isWhereNull, isWhereOr, isWhereRange, isWhereRelationBased, isWhereRelationFilter, isWhereSubquery, isWindowIntent } from '@dbsp/types';
+import { PseudoColumnMetadata, RecursiveMetadata, RelationIR, RelationKind, AdapterCapabilities, Adapter, BaseAdapter, DDLGeneratingAdapter, ExecutingAdapter, IntrospectingAdapter, RawSqlAdapter, StreamingAdapter, TransactionalAdapter, ColumnType, ColumnJsReadType as ColumnJsReadType$1, WhereIntent, OnDeleteAction, ModelIR, DbCasing, QueryIntent, PlanOptions, PlanReport, RecursiveIntent, RecursivePlanOptions, RecursivePlanReport, ObservationContext, TransitionSessionClient, IssuedObservation, RecoveryArtefact, FingerprintManifest, OperationSemantics, OperationKindRef, PhysicalOperation, EvidenceObservation, DurableIntentRecord, OperationEffectAssessment, ObservationIssuer, ApplyGuard, OperationExecutionOutcome, TransactionalCompletionRecord, StepJournal, TransitionRule, EquivalenceCapability, CapabilityDescriptor, TransitionCompositionFact, RuleRef, SemanticArtifactRef, CheckConstraintIR, Comparator, EnumIR, ObservationRequest, EvidenceView, AdvisoryObservationId, AssumptionId, ClaimId, EvidenceId, SemanticArtifactId, IndexIR, ResourceAddress, ResourceSelector, TransitionLessor, ApplyPolicy, ApplyResult, TransitionCandidate, TransitionFragmentComposition, PlanAssessment, CompareOutcome, TransitionQueryClient, TransitionFragment, ProofClaim, Assumption, ProvenPlanShape, ApplicableAssessment, TransitionRunJournal, InapplicableAssessment, TableIR, SequenceIR, AmbiguityCheckResult, DialectCapabilities, DDLFeature, DDLFeatureVersionRange, SelectIntent, IncludeIntent, AggregateIntent, OrderByIntent, SortDirection, InsertIntent, InsertFromIntent, UpdateIntent, BatchUpdateIntent, DeleteIntent, UpsertIntent, UpsertFromIntent, TransactionBeginOptions, Dump, SetOperationIntent, LockStrength, LockWaitPolicy, DumpMeta, JoinIntent, UnnestCteIntent, CteQueryIntent, CompileOptions, CompiledQuery, MutationIntent as MutationIntent$1, DumpSequenceStep, UpsertConflictTarget, UpsertConflictAction, RawCteIntent, TruncateOptions, VacuumOptions, AlterColumnOptions, CreateIndexOptions, DropIndexOptions, IndexInfo, TransactionOptions, PinnedConnectionOptions, ExpressionIntent, ComparisonOperator, WhereSubqueryIntent, SubqueryRefIntent, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereRelationFilterIntent, RecursiveExistsOptions, WhereExistsIntent, WhereInIntent, WhereNullIntent, WhereLikeIntent, WhereNotIntent, WhereNotExistsIntent, WhereOrIntent, WhereRawExistsIntent, WhereRawNotExistsIntent, WhereExpressionIntent, AggOrderByArg, RelationType as RelationType$1, Cardinality, FeatureWarning, UnsupportedFeatureBehavior, FeatureBehaviorConfig, RangeValue, WhereRangeIntent, SubqueryIncludeInfo } from '@dbsp/types';
+export { Adapter, AdapterCapabilities, AdapterLogger, AdapterStreamOptions, AdjacencyTraversal, AggregateExpressionIntent, AggregateFunction, AggregateIntent, AggregateWindowFunction, AliasIncludedColumnsMode, AlterColumnOptions, AmbiguityCheckResult, ApplicableAssessment, ApplicableEvaluation, ApplyPolicy, ArrayOperator, Assumption, BaseAdapter, CTEDefinition, CapabilityDescriptor, Cardinality, CaseExpressionIntent, CoalesceExpressionIntent, ColumnAliasIntent, ColumnExpressionIntent, ColumnIR, ColumnJsReadType, ColumnType, CommonColumnType, Comparator, CompareOutcome, ComparisonExpressionIntent, ComparisonOperator, CompileOnlyAdapter, CompileOptions, CompileResultWithIncludes, CompiledQuery, CompilingAdapter, CreateIndexOptions, CustomTraversal, DDLGeneratingAdapter, DbCasing, DecisionType, DeleteIntent, DialectCapabilities, DialectName, DropIndexOptions, DuckDBColumnType, Dump, DumpMeta, DurableIntentRecord, EdgeTableTraversal, EmitJoinClause, ExecutingAdapter, ExpressionIntent, FilterStrategy, FingerprintManifest, ForeignKeyIR, InapplicableAssessment, IncludeIntent, IncludeStrategy, IndexColumnDef, IndexIR, IndexInfo, IndexMethod, InsertFromIntent, InsertIntent, IntrospectingAdapter, IsTypeSupported, JoinDefault, JoinIntent, LiteralExpressionIntent, LogicalIdentity, LogicalIdentityCarrier, LogicalOperator, MSSQLColumnType, ModelIR, MutationIntent, MySQLColumnType, NullOperator, NullsPosition, ObservationContext, ObservationIssuer, ObservationRequest, OffsetWindowFunction, OnDeleteAction, OperationEffectAssessment, OperationSemantics, Optionality, OrderByIntent, PartitionIR, PhysicalOperation, PlanDecision, PlanOptions, PlanReport, PlanWarning, PlanWarningCode, PostgresColumnType, PostgresOnlyColumnType, ProvenApplyGuard, ProvenGuardProtocol, ProvenPlanShape, ProvenPlanStep, PseudoColumnExpressionIntent, PseudoColumnMetadata, PseudoColumnTraversal, QueryIntent, RangeOperator, RangeValue, RankingWindowFunction, RawExpressionIntent, RawSqlAdapter, RecognitionResult, RecursiveAdvancedOptions, RecursiveDedupe, RecursiveDirection, RecursiveEmitOptions, RecursiveExistsOptions, RecursiveIntent, RecursiveMetadata, RecursiveNodeIdExpr, RecursivePlanOptions, RecursivePlanReport, RecursiveTrackOptions, RecursiveTraversal, RelationColumnIntent, RelationIR, RelationKind, RelationOperator, RelationType, RequiredEnumLabelIR, ResolvedIncludeStrategy, ResourceAddress, RuleEvaluation, RuleSupport, SQLiteColumnType, SelectAggregateIntent, SelectAllIntent, SelectFieldsIntent, SelectIntent, SelectWithExpressionsIntent, SerializedProvenPlan, SortDirection, StepJournal, StreamingAdapter, StringOperator, SubqueryIncludeInfo, SubqueryRefIntent, SupportedColumnTypes, TableIR, TransactionOptions, TransactionalAdapter, TransactionalCompletionRecord, TransitionCandidate, TransitionLessor, TransitionQueryClient, TransitionRule, TransitionRunMetadata, TransitionSessionClient, TruncateOptions, UpdateIntent, UpsertConflictAction, UpsertConflictTarget, UpsertFromIntent, UpsertIntent, VacuumOptions, WhereAndIntent, WhereAnyIntent, WhereComparisonIntent, WhereExistsIntent, WhereInIntent, WhereIntent, WhereLikeIntent, WhereNotExistsIntent, WhereNotIntent, WhereNullIntent, WhereOrIntent, WhereRangeIntent, WhereRelationFilterIntent, WhereSubqueryIntent, WindowFunction, WindowIntent, WindowOrderBy, getNodeIdAlias, isAdjacencyTraversal, isAggregateWindowFunction, isCoalesceExpression, isColumnAliasExpression, isCustomTraversal, isDeleteIntent, isEdgeTableTraversal, isInsertIntent, isMutationIntent, isRankingWindowFunction, isRawExpression, isRecursiveIntent, isRelationColumnExpression, isSelectAggregate, isSelectAll, isSelectFields, isSelectWithExpressions, isSubqueryRef, isUpdateIntent, isUpsertIntent, isWhereAnd, isWhereAny, isWhereComparison, isWhereExists, isWhereIn, isWhereLike, isWhereLogical, isWhereNot, isWhereNotExists, isWhereNull, isWhereOr, isWhereRange, isWhereRelationBased, isWhereRelationFilter, isWhereSubquery, isWindowIntent } from '@dbsp/types';
 import { NqlCompilerOptions } from '@dbsp/nql';
 
 /**
@@ -1439,15 +1439,13 @@ interface GuardExecutionResult {
     readonly recovery: readonly RecoveryArtefact[];
 }
 interface TransitionExecutionClient {
-    readonly opaqueClient: unknown;
+    readonly opaqueClient: TransitionSessionClient;
 }
 interface NonRollbackableExecutionTracker {
     markNonRollbackableOperationExecuted(): void;
 }
 interface ExecutionCoordinator {
     readonly transactionDomain: string;
-    checkout(target: TransitionConnectionPool): Promise<TransitionExecutionClient>;
-    release(client: TransitionExecutionClient, error?: unknown): Promise<void> | void;
     begin(client: TransitionExecutionClient): Promise<void>;
     setLockTimeout(client: TransitionExecutionClient, maxWaitMs: number): Promise<void>;
     commit(client: TransitionExecutionClient): Promise<void>;
@@ -1459,8 +1457,6 @@ interface TransactionCoordinatorBinding {
     readonly transactionDomain: string;
 }
 interface OperationRuntime extends RegisteredOperationSemantics {
-    checkout(target: TransitionConnectionPool): Promise<TransitionExecutionClient>;
-    release(client: TransitionExecutionClient, error?: unknown): Promise<void> | void;
     writeIntentJournal(client: TransitionExecutionClient, record: DurableIntentRecord): Promise<void>;
     begin(client: TransitionExecutionClient): Promise<void>;
     setLockTimeout(client: TransitionExecutionClient, maxWaitMs: number): Promise<void>;
@@ -1623,7 +1619,7 @@ interface StagedTransitionInput {
     readonly desired: ModelIR;
     readonly loadCurrent: () => Promise<ModelIR>;
     readonly readContext: () => Promise<ObservationContext>;
-    readonly target: TransitionConnectionPool;
+    readonly target: TransitionLessor;
     readonly policy: ApplyPolicy;
     readonly maxIterations?: number;
 }
@@ -1661,6 +1657,48 @@ declare function chooseReadyCandidate(preflight: Extract<StagedCompositionPrefli
 }>): StagedCompositionCandidate;
 declare function projectCompareToSingleCandidate(compare: TransitionCompare, entry: StagedCompositionCandidate): TransitionCompare;
 
+declare const TRANSITION_LESSOR_REJECTION = "transition target must be a core-minted lessor";
+/** A core-owned lease: packs receive its session, while core retains release. */
+type TransitionLease = {
+    readonly session: TransitionSessionClient;
+    readonly release: (failure?: TransitionLeaseFailure) => Promise<void>;
+};
+/**
+ * Cross the engine's acquisition boundary.
+ *
+ * A lessor brand is a declaration, not a security boundary, so every
+ * acquisition is checked here even when a caller forged that declaration.
+ */
+declare function acquireTransitionLease(target: TransitionLessor): Promise<TransitionLease>;
+/**
+ * Mint a declared source of transition leases.
+ *
+ * This declares a source of leases; it does not inspect individual
+ * acquisitions. Every acquisition crosses `acquireTransitionLease`, the
+ * runtime boundary that validates and captures it exactly once.
+ *
+ * The wrapper is allocated and frozen by core. Its non-writable,
+ * non-configurable `Symbol.for('dbsp.transition.lessor')` brand carries this
+ * protocol version, so independently installed incompatible core versions do
+ * not accept one another's lessors. The global symbol is intentionally not a
+ * security boundary: code already running in this realm can forge it. This
+ * protects callers from passing the wrong connection object by accident.
+ */
+declare function createTransitionLessor(acquire: () => Promise<TransitionQueryClient>): TransitionLessor;
+/**
+ * Recognize a core-minted transition lessor. The shape check only rejects a
+ * contradictory declaration (a branded object without acquire()); the brand
+ * and protocol version are the declaration.
+ */
+declare function isTransitionLessor(value: unknown): value is TransitionLessor;
+/**
+ * Carries the error that ended a lease's use. Its presence — not the value it
+ * holds — is what says the lease is being returned after a failure.
+ */
+type TransitionLeaseFailure = {
+    readonly error: unknown;
+};
+
 type TransitionRelationalValidationInput = {
     readonly kind: 'fragment';
     readonly fragment: TransitionFragment;
@@ -1712,20 +1750,20 @@ type ProveOutcome = {
 };
 interface Prover {
     readonly artifact: SemanticArtifactRef;
-    prove(compare: CompareOutcome, target: TransitionConnectionPool, context: ObservationContext): Promise<ProveOutcome>;
+    prove(compare: CompareOutcome, target: TransitionLessor, context: ObservationContext): Promise<ProveOutcome>;
 }
 interface Applier {
     readonly artifact: SemanticArtifactRef;
     apply(proven: {
         readonly plan: InProcessProvenPlan;
         readonly assessment: ApplicableAssessment;
-    }, policy: ApplyPolicy, target: TransitionConnectionPool): Promise<ApplyResult>;
-    resume(runId: string, loadCurrent: TransitionResumeJournalLoader, readContext: TransitionResumeContextReader, policy: ApplyPolicy, target: TransitionConnectionPool): Promise<ApplyResult>;
+    }, policy: ApplyPolicy, target: TransitionLessor): Promise<ApplyResult>;
+    resume(runId: string, loadCurrent: TransitionResumeJournalLoader, readContext: TransitionResumeContextReader, policy: ApplyPolicy, target: TransitionLessor): Promise<ApplyResult>;
 }
 type TransitionResumeJournalLoader = (runId: string) => Promise<TransitionRunJournal & {
     readonly plan: ProvenPlanShape;
 }>;
-type TransitionResumeContextReader = (target: TransitionConnectionPool, run: TransitionRunJournal['run']) => Promise<ObservationContext>;
+type TransitionResumeContextReader = (target: TransitionLessor, run: TransitionRunJournal['run']) => Promise<ObservationContext>;
 
 /**
  * @module model-impl
@@ -2426,7 +2464,7 @@ interface QueryBuilderContext {
  * Options for streaming query execution.
  * Options for configuring streaming behavior.
  */
-interface StreamOptions {
+interface StreamOptions extends TransactionBeginOptions {
     /**
      * Number of rows to fetch per batch from the database.
      * Only affects PostgreSQL with pg-cursor configured.
@@ -2438,6 +2476,8 @@ interface StreamOptions {
      * Receives the query dump for observability/logging.
      */
     readonly onStart?: (dump: Dump) => void;
+    /** AbortSignal is intentionally unsupported by stream-owned transactions. */
+    readonly signal?: never;
 }
 /**
  * Options for offset-based pagination.
@@ -3851,6 +3891,7 @@ declare abstract class MutationBuilderBase<T, TIntent extends InsertIntent | Upd
     protected requireAdapter(operation: string): Adapter;
     dump(extraOptions?: CompileOptions): MutationDump;
     execute(): Promise<T>;
+    affectedRows(): Promise<number>;
     private prepareMutationExecution;
 }
 /**
@@ -4475,6 +4516,13 @@ interface SelectExpressionResult {
      */
     execute<T = Record<string, unknown>>(): Promise<T[]>;
 }
+interface RawReadOptions {
+    /**
+     * Map of output-key -> JS read type, applied to bigint columns read via raw SQL.
+     * The caller declares provenance explicitly; dbsp does not infer it for arbitrary SQL.
+     */
+    readonly bigintReads?: Readonly<Record<string, ColumnJsReadType$1>>;
+}
 interface OrmInstance<DB = Record<string, unknown>> {
     /**
      * Type-safe table references for query building.
@@ -4624,6 +4672,26 @@ interface OrmInstance<DB = Record<string, unknown>> {
      * The strict mode setting for this ORM instance.
      */
     readonly strictMode: boolean;
+    /**
+     * Whether the connection backing this ORM instance is inside a transaction.
+     *
+     * Reflects the backing adapter's real transaction state: `true` inside a
+     * {@link OrmInstance.transaction} callback, and also `true` for a top-level
+     * instance built on an adapter that is ALREADY inside a caller-owned
+     * transaction (e.g. a borrowed pg client mid-`BEGIN`); `false` otherwise.
+     *
+     * Callers use this to enforce a top-level precondition: an operation whose
+     * effects a caller's outer rollback must not silently undo — DDL that cannot
+     * be nested, or a process-level cache that would go stale if the surrounding
+     * transaction rolls back — can fail closed when the connection is already in a
+     * transaction instead of assuming it owns the top-level transaction.
+     *
+     * Optional for backward compatibility: instances produced by `createOrm`
+     * always populate it, but a pre-existing hand-built `OrmInstance` double may
+     * omit it (reads as `undefined`), so a fail-closed caller should treat a
+     * non-`true` value it cannot confirm accordingly.
+     */
+    readonly inTransaction?: boolean;
     /**
      * Create a schema-scoped ORM instance.
      * All queries from the returned instance will include the schema prefix.
@@ -4731,7 +4799,17 @@ interface OrmInstance<DB = Record<string, unknown>> {
      * });
      * ```
      */
-    transaction<T>(fn: (tx: OrmInstance<DB>) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (tx: OrmInstance<DB>) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Execute a callback with all ORM work pinned to one physical database
+     * connection for the callback lifetime, without opening a transaction.
+     *
+     * @typeParam T - The return type of the callback
+     * @param fn - Async callback that receives a connection-pinned ORM instance
+     * @param options - Optional pinned connection controls
+     * @returns Promise resolving to the callback's return value
+     */
+    withPinnedConnection<T>(fn: (pinned: OrmInstance<DB>) => Promise<T>, options?: PinnedConnectionOptions): Promise<T>;
     /**
      * NQL template tag for writing queries in Natural Query Language.
      *
@@ -4755,9 +4833,10 @@ interface OrmInstance<DB = Record<string, unknown>> {
      * @typeParam T - Expected result type (defaults to unknown)
      * @param sql - Raw SQL string with parameter placeholders
      * @param parameters - Parameter values for placeholders
+     * @param options - Explicit raw read coercion options
      * @returns Promise resolving to array of results
      */
-    raw<T = unknown>(sql: string, parameters?: readonly unknown[]): Promise<T[]>;
+    raw<T = unknown>(sql: string, parameters?: readonly unknown[], options?: RawReadOptions): Promise<T[]>;
     /**
      * Create a CTE (Common Table Expression) backed by unnest() arrays.
      *
@@ -8016,4 +8095,4 @@ declare const assertIntentHasOrderBy: (result: AssertionQueryResult, expected: b
  */
 declare function runAssertions(blocks: AssertionBlock[], results: AssertionQueryResult[], queries: string[], hasDb?: boolean): AssertionSummary;
 
-export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Applier, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type CheckDelta, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, type EmitWarningOptions, type EnumAddDelta, ErrorCode, type ErrorHookContext, Errors, type EstablishedProofClaim, type ExecutionCoordinator, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GetSchemaFromDbOptions, type GuardExecutionResult, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type InProcessProvenPlan, type IncludeOptions, type IncludeOptionsWithRecursive, type IndexDelta, type IndexSetEntry, type InferColumn, type InferColumnNonNull, type InferColumnType, type InferColumnTypes, type InferDB, type InferRefColumn, type InferRow, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType as NewSchemaColumnType, type NonRollbackableExecutionTracker, NotFoundError, type NqlBuilder, type NqlRawFragment, type NqlTag, type OnErrorHook, type OperationFingerprints, type OperationObservation, type OperationRuntime, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, POSTGRESQL_CAPABILITIES, PackRegistry, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type ProveOutcome, type Prover, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RegisteredOperationSemantics, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationPathIncludeNode, type RelationPathUsage, type RelationRef, type RelationShorthand, type RelationTupleDef, ResultHydrator, type RulePrecedenceFact, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaColumnType, type SchemaConstraints, type SchemaDefinition, SchemaValidationError as SchemaError, type SchemaExtras, type SchemaIndexOptions, type SchemaIndexValidationInput, type SchemaOptions, type SchemaTableOptions, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StagedCompositionCandidate, type StagedCompositionPreflight, type StagedCompositionPreflightInput, type StagedTransitionInput, type StagedTransitionOrchestrator, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TransactionCoordinatorBinding, type TransitionExecutionClient, type TransitionPack, type TransitionRelationalValidationInput, type TransitionRelationalValidationResult, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type WarningCategory, type WhereFilter, WindowBuilder, advisoryObservationId, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, assumptionId, batchValues, capitalize, caseWhen, cast, checkDelta, chooseReadyCandidate, claimId, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, countDistinctRelationPathsByName, createApplier, createComparator, createDialectCapabilities, createEvidenceView, createHookManager, createNqlTag, createOrm, createPackRegistry, createProver, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, createStagedTransitionOrchestrator, decapitalize, defaultIndexName, defaultLogger, defineModel, denseRank, deriveRelationPathFromIntentPath, distinct, emitWarning, enumAddDelta, eq, every, evidenceId, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, indexDelta, inferForeignKey, isAliasedColumn, isAllColumns, isBatchValuesRef, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isKnownDialect, isNotNull, isNull, isOperationRuntime, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizedIndex, not, notExists, nqlRaw, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, preflightStagedComposition, projectCompareToSingleCandidate, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveEnumSchemaForComparison, resolveQueryIndex, resourceIsWithin, resourceScopeCovers, rowNumber, runAssertions, schema, schemaToModelIR, selectorMatchesResource, semanticArtifactId, serverVersionNum, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateSchemaIndexOptions, validateTransitionRelationalInvariants, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };
+export { ASSERTION_TYPES, AdapterRequiredError, type AdjacencyOptions, type AfterMutationHook, type AfterQueryHook, type AggregateOptions, type AliasedColumn, type AliasedExprColumn, type AllColumns, AmbiguousPlanError, AmbiguousRelationError, type Applier, type Assertion, type AssertionBlock, type AssertionOutcome, type AssertionQueryResult, type AssertionSummary, type AssertionType, BRAND, type BatchValuesOptions, type BatchValuesRef, type BeforeMutationHook, type BeforeQueryHook, type BrandKey, COLUMN_META, type CardinalityShorthand, CaseBuilder, type CaseValue, type CheckDelta, type ColumnDef, type ColumnMetaKey, ColumnNotFoundError, type ColumnRef, type ColumnSpec, CteBuilder, type CteDump, CteQueryBuilder, type CursorPaginateOptions, type CursorPaginatedResult, DEFAULT_FEATURE_CHECKERS, DUCKDB_CAPABILITIES, type DefaultFilters, type DefineModelOptions, DeleteBuilder, type DistinctField, type DumpMetaInput, type EdgeTableOptions, type EmitWarningOptions, type EnumAddDelta, ErrorCode, type ErrorHookContext, Errors, type EstablishedProofClaim, type ExecutionCoordinator, ExecutionError, type ExprInput, ExpressionRef, type ExpressionSpec, type FeatureChecker, type FeatureUsage, type FilterOperators, type FilterValue, type FullTextSearchField, type FullTextSearchOptions, type GetSchemaFromDbOptions, type GuardExecutionResult, type HierarchyOptions, type HookErrorHandler, type HookManager, type HookPriority, type HydrateOptions, IRREGULAR_PLURALS, type InProcessProvenPlan, type IncludeOptions, type IncludeOptionsWithRecursive, type IndexDelta, type IndexSetEntry, type InferColumn, type InferColumnNonNull, type InferColumnType, type InferColumnTypes, type InferDB, type InferRefColumn, type InferRow, type InferSchemaDB, type InferTableRow, type InferTables, type InferredRangeValue, InsertBuilder, IntentBuilder, type IntentBuilderState, type IntentSummary, InvalidOperationError, InvalidRelationDefinitionError, type JoinOptions, type JsonValue, type LightweightRelationsDef, type ListHierarchyOptions, type ListIndexOptions, type Logger, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, ModelIRImpl, type MutationDump, type MutationHookContext, type MutationOperation, NamingConventionMismatchError, type NegotiationResult, type NestedInclude, type SchemaColumnType as NewSchemaColumnType, type NonRollbackableExecutionTracker, NotFoundError, type NqlBuilder, type NqlRawFragment, type NqlTag, type OnErrorHook, type OperationFingerprints, type OperationObservation, type OperationRuntime, type OrderByInput, type OrderByRecord, type OrderBySpec, type OrmInstance, type OrmOf, type OrmOptions, type OrmOptionsWithAdapter, type OrmOptionsWithModel, POSTGRESQL_CAPABILITIES, PackRegistry, type PaginateOptions, type PaginatedResult, type ParseError, type ParseResult, type ParsedRelationDef, type ParsedRelationKey, type PathOptions, type PrioritizedHook, type ProveOutcome, type Prover, type QueryAssertionResult, type QueryBuilder, type QueryHookContext, type QueryResultType, RELATION_META, type RangeType, RawCteQueryBuilder, type RecursiveDump, type RecursiveIncludeConfig, type RecursiveOptions, RecursiveShapeMismatchError, type RefDefinition, type RefOptions, type RegisteredOperationSemantics, type RelationHints, type RelationKey, type RelationMetaKey, RelationNotFoundError, type RelationObjectDef, type RelationPathIncludeNode, type RelationPathUsage, type RelationRef, type RelationShorthand, type RelationTupleDef, ResultHydrator, type RulePrecedenceFact, SQLITE_CAPABILITIES, SQL_RAW_MARKER, type Schema, type SchemaColumnType, type SchemaConstraints, type SchemaDefinition, SchemaValidationError as SchemaError, type SchemaExtras, type SchemaIndexOptions, type SchemaIndexValidationInput, type SchemaOptions, type SchemaTableOptions, SchemaValidationError, type SelectField, type SelfRefRoles, type SetOperationBuilder, type SimplifiedOrmOptions, type SqlRawExpression, type StagedCompositionCandidate, type StagedCompositionPreflight, type StagedCompositionPreflightInput, type StagedTransitionInput, type StagedTransitionOrchestrator, type StreamOptions, SubqueryBuilder, SubqueryExpression, TABLE_META, TRANSITION_LESSOR_REJECTION, type TableAssertionData, type TableDDL, type TableDef, type TableIndexes, type TableMetaKey, TableNotFoundError, type TableRef, type TransactionCoordinatorBinding, type TransitionExecutionClient, type TransitionLeaseFailure, type TransitionPack, type TransitionRelationalValidationInput, type TransitionRelationalValidationResult, type TraversalDirection, UnhandledTypeInDialect, UnknownDialectError, UnsafeOperationError, UnsupportedCapabilityError, UnsupportedFeatureError, UnsupportedStrategyError, UpdateBuilder, UpsertBuilder, type WarningCategory, type WhereFilter, WindowBuilder, acquireTransitionLease, advisoryObservationId, aggOrderBy, and, any, array, arrayAgg, assertCapability, assertContains, assertDbColumnExists, assertDbOutput, assertDbRowsEquals, assertDbRowsMax, assertDbRowsMin, assertDbValueEquals, assertEquals, assertIntentHasGroupBy, assertIntentHasOrderBy, assertIntentHasWhere, assertIntentTable, assertIntentType, assertIntentWith, assertMatches, assertParamsEquals, assertParamsLength, assertParamsType, assertParamsValue, assertSQLColumn, assertSQLEquals, assertSQLJoin, assertSQLTable, assertSuccess, assertTypeSupported, assumptionId, batchValues, capitalize, caseWhen, cast, checkDelta, chooseReadyCandidate, claimId, coalesce, col, composeAfterMutationHooks, composeAfterQueryHooks, composeBeforeMutationHooks, composeBeforeQueryHooks, composeOnErrorHooks, countDistinctRelationPathsByName, createApplier, createComparator, createDialectCapabilities, createEvidenceView, createHookManager, createNqlTag, createOrm, createPackRegistry, createProver, createPseudoColumnMetadata, createRawCteBuilder, createRecursiveMetadata, createStagedTransitionOrchestrator, createTransitionLessor, decapitalize, defaultIndexName, defaultLogger, defineModel, denseRank, deriveRelationPathFromIntentPath, distinct, emitWarning, enumAddDelta, eq, every, evidenceId, exists, ref as exprRef, extendDialect, extractPseudoColumnKeywords, findClosestMatch, fn, fullTextSearch, getAvailableDialects, getDialectCapabilities, getLogger, getRelationKind, getSchemaFromDb, gt, gte, inArray, inSubquery, indexDelta, inferForeignKey, isAliasedColumn, isAllColumns, isBatchValuesRef, isCardinalityShorthand, isColumnRef, isDistinctField, isDistinctFrom, isExpressionSpec, isKnownDialect, isNotNull, isNull, isOperationRuntime, isOverallSuccess, isRecursiveIncludeOptions, isRecursiveRelation, isRef, isRelationObjectDef, isRelationRef, isRelationTupleDef, isSelfReferential, isSqlRaw, isSubqueryExpression, isTableRef, isTransitionLessor, isWhereIntent, lag, lead, like, literal, lt, lte, namedArg, negotiateFeatures, neq, none, normalizeSQL, normalizedIndex, not, notExists, nqlRaw, objectToWhereIntent, op, or, outerRef, param, parseAssertionFile, parseRelationDef, parseRelationKey, pipeAfterMutationHooks, pipeAfterQueryHooks, pipeBeforeMutationHooks, pipeBeforeQueryHooks, pipeOnErrorHooks, plan, planRecursive, pluralize, preflightStagedComposition, projectCompareToSingleCandidate, rangeContainedBy, rangeContains, rangeOverlaps, rank, raw, rawExists, rawNotExists, ref$1 as ref, registerDialect, relationColumn, requiresDatabase, resetLogger, resolveEnumSchemaForComparison, resolveQueryIndex, resourceIsWithin, resourceScopeCovers, rowNumber, runAssertions, schema, schemaToModelIR, selectorMatchesResource, semanticArtifactId, serverVersionNum, setLogger, silentLogger, singularize, some, sortByPriority, sql, star, stringAgg, subquery, supportsDDLGeneration, supportsExecution, supportsIntrospection, supportsRawSql, supportsStreaming, supportsTransactions, textScore, unary, validateAssertionBlocks, validateRecursiveInclude, validateRecursiveShape, validateSchemaIndexOptions, validateTransitionRelationalInvariants, validateTypeName, wAvg, wCount, wMax, wMin, wSum, withPriority };