@dbsp/core 3.1.0 → 3.2.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, 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, 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, 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 { NqlCompilerOptions } from '@dbsp/nql';
 
 /**
@@ -2426,7 +2426,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 +2438,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 +3853,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 +4478,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 +4634,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 +4761,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 +4795,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.
      *

package/dist/index.js

@@ -11788,7 +11788,7 @@ function createStagedTransitionOrchestrator(registry) {
 
 // src/adapter.ts
 function supportsExecution(adapter) {
-  return "execute" in adapter && "executeOne" in adapter && typeof adapter.execute === "function";
+  return typeof adapter.execute === "function" && typeof adapter.executeOne === "function" && typeof adapter.executeOneOrThrow === "function";
 }
 function supportsStreaming(adapter) {
   return adapter.capabilities?.supportsStreaming === true && "stream" in adapter && typeof adapter.stream === "function";
@@ -14325,6 +14325,10 @@ function compileMutationIntent(adapter, intent, options) {
   );
 }
 async function runMutationWithHooks(opts) {
+  const execution = await runMutationWithHooksMeta(opts);
+  return execution.result;
+}
+async function runMutationWithHooksMeta(opts) {
   if (!opts.hookStore || !hasHooks(opts.hookStore)) {
     const prepared = opts.prepare(opts.intent);
     return prepared.execute();
@@ -14358,25 +14362,30 @@ async function runMutationWithHooksInner(opts, store) {
     }
     const prepared = opts.prepare(intent);
     const duration = Date.now() - startTime;
-    const result = await prepared.execute();
+    const execution = await prepared.execute();
+    let result = execution.result;
     if (store.afterMutation.length > 0) {
       const afterCtx = Object.freeze({
         ...ctx,
         sql: prepared.sql,
         parameters: prepared.parameters,
-        duration
+        duration,
+        ...execution.affectedRows !== void 0 ? { affectedRows: execution.affectedRows } : {}
       });
       const transformed = await runAfterMutationHooks(
         store.afterMutation,
         afterCtx,
-        [...prepared.getAfterMutationResult?.(result) ?? []],
+        [...prepared.getAfterMutationResult?.(execution.result) ?? []],
         opts.onHookError
       );
       if (prepared.returnAfterMutationResult) {
-        return prepared.mapAfterMutationResult?.(result, transformed) ?? transformed;
+        result = prepared.mapAfterMutationResult?.(result, transformed) ?? transformed;
       }
     }
-    return result;
+    return {
+      result,
+      ...execution.affectedRows !== void 0 ? { affectedRows: execution.affectedRows } : {}
+    };
   } catch (error) {
     if (store.onError.length > 0) {
       const errorCtx = {
@@ -14502,6 +14511,34 @@ var MutationBuilderBase = class {
       prepare: (preparedIntent) => this.prepareMutationExecution(adapter, preparedIntent)
     });
   }
+  async affectedRows() {
+    const adapter = this.requireAdapter(this.operationName);
+    const intent = this.buildIntent();
+    if (typeof adapter.executeWithMeta !== "function") {
+      throw new ExecutionError({
+        operation: `${this.operationName}.affectedRows`,
+        reason: "this adapter does not support affectedRows(); it does not implement executeWithMeta",
+        fix: "Use an adapter that implements executeWithMeta, or call execute() when row count metadata is not required."
+      });
+    }
+    const execution = await runMutationWithHooksMeta({
+      table: this.table,
+      intent,
+      hookStore: this.hookStore,
+      onHookError: this.onHookError,
+      schemaName: this.schemaName,
+      inTransaction: this.inTransaction,
+      prepare: (preparedIntent) => this.prepareMutationExecution(adapter, preparedIntent)
+    });
+    if (execution.affectedRows === void 0) {
+      throw new ExecutionError({
+        operation: `${this.operationName}.affectedRows`,
+        reason: "this adapter does not support affectedRows(); it did not return executeWithMeta metadata",
+        fix: "Use an adapter that implements executeWithMeta and returns rowCount metadata."
+      });
+    }
+    return execution.affectedRows;
+  }
   prepareMutationExecution(adapter, intent) {
     const compileOptions = {
       model: this.model,
@@ -14512,7 +14549,19 @@ var MutationBuilderBase = class {
       return {
         sql: compiled.sql,
         parameters: compiled.parameters,
-        execute: () => adapter.execute(compiled),
+        execute: async () => {
+          if (typeof adapter.executeWithMeta === "function") {
+            const result2 = await adapter.executeWithMeta(compiled);
+            return {
+              result: result2.rows,
+              affectedRows: result2.rowCount
+            };
+          }
+          const result = await adapter.execute(compiled);
+          return {
+            result
+          };
+        },
         getAfterMutationResult: (result) => result,
         returnAfterMutationResult: true
       };
@@ -14521,8 +14570,17 @@ var MutationBuilderBase = class {
       sql: compiled.sql,
       parameters: compiled.parameters,
       execute: async () => {
+        if (typeof adapter.executeWithMeta === "function") {
+          const result = await adapter.executeWithMeta(compiled);
+          return {
+            result: void 0,
+            affectedRows: result.rowCount
+          };
+        }
         await adapter.execute(compiled);
-        return void 0;
+        return {
+          result: void 0
+        };
       },
       getAfterMutationResult: () => []
     };
@@ -16355,12 +16413,27 @@ var NqlBuilderImpl = class {
           sql: compiled.sql,
           parameters: compiled.parameters,
           execute: async () => {
+            if (typeof adapter.executeWithMeta === "function") {
+              const metadata = await adapter.executeWithMeta(compiled);
+              const hookRows2 = metadata.rows;
+              const rawRows2 = snapshotMutationRows(hookRows2);
+              return {
+                result: {
+                  rawRows: rawRows2,
+                  hookRows: hookRows2,
+                  transformedRows: hookRows2
+                },
+                affectedRows: metadata.rowCount
+              };
+            }
             const hookRows = await adapter.execute(compiled);
             const rawRows = snapshotMutationRows(hookRows);
             return {
-              rawRows,
-              hookRows,
-              transformedRows: hookRows
+              result: {
+                rawRows,
+                hookRows,
+                transformedRows: hookRows
+              }
             };
           },
           getAfterMutationResult: (result) => hasReturning ? result.hookRows : [],
@@ -16704,6 +16777,11 @@ function extractPseudoColumnKeywords(model) {
   };
 }
 
+// src/dx/orm-instance.ts
+import {
+  convertBigintJsReadValue as convertBigintJsReadValue2
+} from "@dbsp/types";
+
 // src/dx/hierarchy-helpers.ts
 function extractRecursiveField(result, field) {
   if (result == null) return [];
@@ -17600,9 +17678,35 @@ function createUnsupportedStreamingError() {
     fix: "Use an adapter configuration that supports streaming."
   });
 }
+function hasStreamTransactionBeginOptions(options) {
+  return options != null && (options.isolationLevel !== void 0 || options.readOnly !== void 0 || options.lockTimeoutMs !== void 0 || options.statementTimeoutMs !== void 0);
+}
+function hasRuntimeStreamSignalOption(options) {
+  return typeof options === "object" && options !== null && "signal" in options;
+}
+function createAdapterStreamOptions(options) {
+  if (options === void 0 || options.chunkSize === void 0 && !hasStreamTransactionBeginOptions(options)) {
+    return void 0;
+  }
+  return {
+    ...options.chunkSize !== void 0 && { chunkSize: options.chunkSize },
+    ...options.isolationLevel !== void 0 && {
+      isolationLevel: options.isolationLevel
+    },
+    ...options.readOnly !== void 0 && { readOnly: options.readOnly },
+    ...options.lockTimeoutMs !== void 0 && {
+      lockTimeoutMs: options.lockTimeoutMs
+    },
+    ...options.statementTimeoutMs !== void 0 && {
+      statementTimeoutMs: options.statementTimeoutMs
+    }
+  };
+}
 function stream(builder, options) {
   const adapter = builder.getConfiguredAdapter();
-  const adapterOptions = options?.chunkSize !== void 0 ? { chunkSize: options.chunkSize } : void 0;
+  const hasBeginOptions = hasStreamTransactionBeginOptions(options);
+  const hasSignalOption = hasRuntimeStreamSignalOption(options);
+  const adapterOptions = createAdapterStreamOptions(options);
   const hookStore = builder.ctx.hookStore;
   const onHookError = builder.ctx.onHookError;
   const table = builder.from;
@@ -17622,6 +17726,16 @@ function stream(builder, options) {
       if (!supportsStreaming(adapter)) {
         throw createUnsupportedStreamingError();
       }
+      if (hasSignalOption) {
+        throw new Error(
+          "stream() does not support signal; AbortSignal is only supported by transaction()."
+        );
+      }
+      if (hasBeginOptions && adapter.capabilities.supportsTransactionOptions !== true) {
+        throw new Error(
+          "This adapter does not support stream transaction options (isolationLevel/readOnly/lockTimeoutMs/statementTimeoutMs); it does not declare supportsTransactionOptions."
+        );
+      }
       if (!hooksFired) {
         hooksFired = true;
         if (hookStore && hasHooks(hookStore)) {
@@ -19175,8 +19289,21 @@ function createRawCteBuilder(cteName, options, adapter, schemaName, model) {
 function quoteIdent(name) {
   return `"${name.replace(/"/g, '""')}"`;
 }
+var DEFAULT_DDL_SCHEMA_NAME = "public";
+function resolveDDLSchemaName(schemaName) {
+  const resolved = schemaName ?? DEFAULT_DDL_SCHEMA_NAME;
+  validateIdentifier(resolved, "schema");
+  return resolved;
+}
+function sanitizeDropIndexOptions(options) {
+  if (options === void 0 || !("schema" in options)) {
+    return options;
+  }
+  const { schema: _schema, ...rest } = options;
+  return Object.keys(rest).length > 0 ? rest : void 0;
+}
 function buildQualifiedTable(tableName, schemaName) {
-  return schemaName ? `${quoteIdent(schemaName)}.${quoteIdent(tableName)}` : quoteIdent(tableName);
+  return `${quoteIdent(schemaName)}.${quoteIdent(tableName)}`;
 }
 function generateTruncateSQL(tableName, schemaName, options) {
   const parts = [`TRUNCATE ${buildQualifiedTable(tableName, schemaName)}`];
@@ -19198,6 +19325,33 @@ function createUnsupportedTransactionError() {
     fix: "Use an adapter that implements transaction() and withSchema(), and declare adapter.capabilities.supportsTransactions: true."
   });
 }
+function createUnsupportedPinnedConnectionError() {
+  return new ExecutionError({
+    operation: "withPinnedConnection()",
+    reason: "The adapter does not declare capabilities.supportsPinnedConnections: true and implement withPinnedConnection() for this ORM instance.",
+    fix: "Use an adapter that implements withPinnedConnection(), and declare adapter.capabilities.supportsPinnedConnections: true."
+  });
+}
+function hasTransactionOptions(options) {
+  return options != null && (options.isolationLevel !== void 0 || options.readOnly !== void 0 || options.lockTimeoutMs !== void 0 || options.statementTimeoutMs !== void 0 || options.signal !== void 0);
+}
+function supportsPinnedConnections(adapter) {
+  return adapter.capabilities.supportsPinnedConnections === true && typeof adapter.withPinnedConnection === "function";
+}
+function applyBigintReads(row, bigintReads) {
+  if (row === null || typeof row !== "object") return row;
+  const rowRecord = row;
+  const converted = { ...rowRecord };
+  for (const [outputKey, js] of Object.entries(bigintReads)) {
+    if (!(outputKey in rowRecord)) continue;
+    converted[outputKey] = convertBigintJsReadValue2(rowRecord[outputKey], js, {
+      table: "(raw)",
+      column: outputKey,
+      outputKey
+    });
+  }
+  return converted;
+}
 function adapterTransactionState(adapter, operation, statement) {
   const inTransaction = adapter.inTransaction;
   if (typeof inTransaction !== "boolean") {
@@ -19216,8 +19370,8 @@ function assertOutsideTransaction(adapter, operation, statement) {
     );
   }
 }
-function generateAlterColumnSQL(tableName, column, schemaName, options) {
-  const tbl = buildQualifiedTable(tableName, schemaName);
+function generateAlterColumnSQL(tableName, schemaName, column, options) {
+  const tbl = buildQualifiedTable(tableName, resolveDDLSchemaName(schemaName));
   const col2 = quoteIdent(column);
   const clauses = [];
   if (options.type !== void 0) {
@@ -19249,8 +19403,7 @@ function generateDropIndexSQL(name, schemaName, options) {
   const parts = ["DROP INDEX"];
   if (options?.concurrently) parts.push("CONCURRENTLY");
   if (options?.ifExists) parts.push("IF EXISTS");
-  const sc = options?.schema ?? schemaName;
-  parts.push(sc ? `${quoteIdent(sc)}.${quoteIdent(name)}` : quoteIdent(name));
+  parts.push(`${quoteIdent(schemaName)}.${quoteIdent(name)}`);
   if (options?.cascade) parts.push("CASCADE");
   return parts.join(" ");
 }
@@ -19261,7 +19414,8 @@ function buildIndexAPI(tableName, schemaName, adapter, requireAdapter2) {
       if (opts.concurrently) {
         assertOutsideTransaction(a, "createIndex", "CREATE INDEX CONCURRENTLY");
       }
-      const sql2 = a.generateCreateIndex(tableName, opts, schemaName);
+      const ddlSchemaName = resolveDDLSchemaName(schemaName);
+      const sql2 = a.generateCreateIndex(tableName, ddlSchemaName, opts);
       await a.executeDDL?.(sql2);
     },
     async drop(name, options) {
@@ -19269,8 +19423,9 @@ function buildIndexAPI(tableName, schemaName, adapter, requireAdapter2) {
       if (options?.concurrently) {
         assertOutsideTransaction(a, "dropIndex", "DROP INDEX CONCURRENTLY");
       }
-      const scopedOptions = schemaName ? { ...options, schema: options?.schema ?? schemaName } : options;
-      const sql2 = a.generateDropIndex ? a.generateDropIndex(name, scopedOptions) : generateDropIndexSQL(name, schemaName, options);
+      const ddlSchemaName = resolveDDLSchemaName(schemaName);
+      const sanitizedOptions = sanitizeDropIndexOptions(options);
+      const sql2 = a.generateDropIndex ? a.generateDropIndex(name, ddlSchemaName, sanitizedOptions) : generateDropIndexSQL(name, ddlSchemaName, sanitizedOptions);
       await a.executeDDL?.(sql2);
     },
     async list(options) {
@@ -19318,20 +19473,23 @@ function buildTableDDL(tableName, schemaName, adapter) {
   return {
     async truncate(options) {
       const a = requireAdapter2();
-      const sql2 = a.generateTruncate ? a.generateTruncate(tableName, schemaName, options) : generateTruncateSQL(tableName, schemaName, options);
+      const ddlSchemaName = resolveDDLSchemaName(schemaName);
+      const sql2 = a.generateTruncate ? a.generateTruncate(tableName, ddlSchemaName, options) : generateTruncateSQL(tableName, ddlSchemaName, options);
       await a.executeDDL?.(sql2);
     },
     async vacuum(options) {
       const a = requireAdapter2();
       assertOutsideTransaction(a, "vacuum", "VACUUM");
-      const sql2 = a.generateVacuum ? a.generateVacuum(tableName, schemaName, options) : generateVacuumSQL(tableName, schemaName, options);
+      const ddlSchemaName = resolveDDLSchemaName(schemaName);
+      const sql2 = a.generateVacuum ? a.generateVacuum(tableName, ddlSchemaName, options) : generateVacuumSQL(tableName, ddlSchemaName, options);
       await a.executeDDL?.(sql2);
     },
     async alterColumn(column, options) {
       validateIdentifier(tableName, "table");
       validateIdentifier(column, "column");
       const a = requireAdapter2();
-      const sql2 = a.generateAlterColumn ? a.generateAlterColumn(tableName, column, options, schemaName) : generateAlterColumnSQL(tableName, column, schemaName, options);
+      const ddlSchemaName = resolveDDLSchemaName(schemaName);
+      const sql2 = a.generateAlterColumn ? a.generateAlterColumn(tableName, ddlSchemaName, column, options) : generateAlterColumnSQL(tableName, ddlSchemaName, column, options);
       await a.executeDDL?.(sql2);
     },
     indexes: buildIndexAPI(tableName, schemaName, adapter, requireAdapter2),
@@ -19410,6 +19568,18 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
   );
   return {
     strictMode,
+    // Reflect the REAL transaction state of the backing adapter so callers can
+    // enforce a top-level precondition. This is authoritative even when the ORM
+    // was handed an adapter ALREADY inside a caller-owned transaction (e.g. a
+    // borrowed pg client mid-BEGIN): the adapter tracks the connection's actual
+    // state, which dbsp's construction-time nesting flag alone cannot see. Falls
+    // back to that flag only when no adapter exposes the state (e.g. a compile-only
+    // ORM). withSchema/transaction() re-derive it from their own (scoped/tx)
+    // adapter, so every instance reports the state of the connection it uses.
+    get inTransaction() {
+      const adapterState = adapter?.inTransaction;
+      return typeof adapterState === "boolean" ? adapterState : inTransaction ?? false;
+    },
     nql,
     tables: tablesDDLProxy,
     // biome-ignore lint/suspicious/noExplicitAny: polymorphic constraint — TTable is inferred by callers; TableRef generics are statically erased in this implementation signature
@@ -19662,7 +19832,7 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
     // as awaited, by core, before the caller ever touched it. So the adapter's
     // promise is passed through untouched. The guards still reject rather than
     // throwing synchronously, because that is what callers already rely on.
-    transaction(fn2) {
+    transaction(fn2, options) {
       if (!adapter) {
         return Promise.reject(
           new Error(
@@ -19673,6 +19843,13 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
       if (!supportsTransactions(adapter)) {
         return Promise.reject(createUnsupportedTransactionError());
       }
+      if (hasTransactionOptions(options) && adapter.capabilities.supportsTransactionOptions !== true) {
+        return Promise.reject(
+          new Error(
+            "This adapter does not support transaction options (isolationLevel/readOnly/lockTimeoutMs/statementTimeoutMs/signal); it does not declare supportsTransactionOptions."
+          )
+        );
+      }
       try {
         return adapter.transaction(async (txAdapter) => {
           const txOrm = createOrmInstance(
@@ -19692,7 +19869,41 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
             tablesProxy
           );
           return fn2(txOrm);
-        });
+        }, options);
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    withPinnedConnection(fn2, options) {
+      if (!adapter) {
+        return Promise.reject(
+          new Error(
+            "withPinnedConnection() requires an adapter. Pass an adapter when creating the ORM."
+          )
+        );
+      }
+      if (!supportsPinnedConnections(adapter)) {
+        return Promise.reject(createUnsupportedPinnedConnectionError());
+      }
+      try {
+        return adapter.withPinnedConnection(async (pinnedAdapter) => {
+          const pinnedOrm = createOrmInstance(
+            model,
+            strictMode,
+            relationHints,
+            pinnedAdapter,
+            schemaName,
+            dialectCapabilities,
+            schemaDefinition,
+            globalPlanOptions,
+            defaultFilters,
+            hookStore,
+            onHookError,
+            pinnedAdapter.inTransaction,
+            tablesProxy
+          );
+          return fn2(pinnedOrm);
+        }, options);
       } catch (error) {
         return Promise.reject(error);
       }
@@ -19725,13 +19936,18 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
      *
      * @see {@link https://owasp.org/www-community/attacks/SQL_Injection | OWASP SQL Injection}
      */
-    async raw(sqlString, parameters = []) {
+    async raw(sqlString, parameters = [], options) {
       if (!adapter) {
         throw new Error(
           "raw() requires an adapter. Pass an adapter when creating the ORM."
         );
       }
-      return adapter.executeRaw(sqlString, parameters);
+      const rows = await adapter.executeRaw(sqlString, parameters);
+      const bigintReads = options?.bigintReads;
+      if (!bigintReads || Object.keys(bigintReads).length === 0) {
+        return rows;
+      }
+      return rows.map((row) => applyBigintReads(row, bigintReads));
     },
     batchValues(data, columns, types, opts) {
       return batchValues(data, columns, types, opts);
@@ -19788,19 +20004,16 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
           );
         }
         validateIdentifier(name, "index");
-        const sc = options?.schema ?? schemaName;
-        if (sc) {
-          validateIdentifier(sc, "schema");
-        }
-        const scopedOptions = sc ? { ...options, schema: sc } : options;
-        const sql2 = adapter.generateDropIndex ? adapter.generateDropIndex(name, scopedOptions) : (() => {
+        const ddlSchemaName = resolveDDLSchemaName(schemaName);
+        const sanitizedOptions = sanitizeDropIndexOptions(options);
+        const sql2 = adapter.generateDropIndex ? adapter.generateDropIndex(name, ddlSchemaName, sanitizedOptions) : (() => {
           const parts = ["DROP INDEX"];
-          if (options?.concurrently) parts.push("CONCURRENTLY");
-          if (options?.ifExists) parts.push("IF EXISTS");
+          if (sanitizedOptions?.concurrently) parts.push("CONCURRENTLY");
+          if (sanitizedOptions?.ifExists) parts.push("IF EXISTS");
           parts.push(
-            sc ? `"${sc.replace(/"/g, '""')}"."${name.replace(/"/g, '""')}"` : `"${name.replace(/"/g, '""')}"`
+            `"${ddlSchemaName.replace(/"/g, '""')}"."${name.replace(/"/g, '""')}"`
           );
-          if (options?.cascade) parts.push("CASCADE");
+          if (sanitizedOptions?.cascade) parts.push("CASCADE");
           return parts.join(" ");
         })();
         await adapter.executeDDL(sql2);