@prisma/orm-framework 8.0.0-rc.1-dev.41 → 8.0.0-rc.1-dev.43

package/dist/{runtime-Cne6hBaG.d.mts → runtime-Cuxw8obj.d.mts}

@@ -1,5 +1,5 @@
 import { U as PlanMeta } from "./domain-envelope-D6Wn9AmZ-BqZKTT9U.mjs";
-import { r as CodecCallContext } from "./codec-types-720XoDZ0-Br-QaYK3.mjs";
+import { r as CodecCallContext } from "./codec-types-D6VRj2RE-BLElXc-O.mjs";
 //#region ../../../1-framework/1-core/framework-components/dist/runtime.d.mts
 //#region src/annotations.d.ts
 /**
@@ -302,23 +302,22 @@ interface RuntimeLog {
   debug?(event: unknown): void;
 }
 /**
- * Per-execute context threaded through every middleware phase
- * (`beforeExecute`, `onRow`, `afterExecute`). Allocated once per
- * `runtime.execute()` call and shared by reference across all
- * middleware in the chain.
- *
- * - `signal` carries the per-query `AbortSignal` -- the same
- *   reference that `runtime.execute(plan, { signal })` was invoked
- *   with, and the same reference threaded into the per-call
- *   `CodecCallContext` (ADR 207). Middleware that wraps a
- *   network-backed SDK forwards `ctx.signal` into that SDK to
- *   propagate caller cancellation; pure-CPU middleware ignores it.
- *
- * Symmetric plumbing across all middleware phases (rather than only
- * `beforeExecute`) is a deliberate choice: a middleware that wraps a
- * downstream observability hook or post-processor in `afterExecute` /
- * `onRow` needs the same cancellation reach as its `beforeExecute`
- * counterpart.
+ * Per-operation context threaded through every middleware phase
+ * (`beforeQuery`, `interceptQuery`, `onRow`, `afterQuery` for queries, and
+ * `beforeExecute`, `interceptExecute`, `afterExecute` for executes). Allocated
+ * once per runtime operation and shared by reference across all middleware in
+ * the chain.
+ *
+ * - `signal` carries the per-operation `AbortSignal` -- the same reference
+ *   passed to the runtime call and the same reference threaded into the
+ *   per-call `CodecCallContext` (ADR 207). Middleware that wraps a
+ *   network-backed SDK forwards `ctx.signal` into that SDK to propagate caller
+ *   cancellation; pure-CPU middleware ignores it.
+ *
+ * Symmetric plumbing across all middleware phases is a deliberate choice: a
+ * middleware that wraps a downstream observability hook or post-processor in
+ * `afterQuery` / `afterExecute`, `interceptQuery` / `interceptExecute`, or
+ * `onRow` needs the same cancellation reach as its before hook.
  */
 interface RuntimeMiddlewareContext {
   readonly contract: unknown;
@@ -344,21 +343,22 @@ interface RuntimeMiddlewareContext {
    */
   contentHash(exec: ExecutionPlan): Promise<string>;
   /**
-   * Per-execute cancellation signal threaded through every middleware
-   * phase. Middleware that wraps async work or downstream cancellable
-   * primitives should observe this and abort early when the consumer
-   * cancels.
+   * Per-operation cancellation signal threaded through every selected
+   * middleware phase. Middleware that wraps async work or downstream
+   * cancellable primitives should observe this and abort early when the
+   * consumer cancels.
    */
   readonly signal?: AbortSignal;
   /**
-   * Identifies the queryable scope this execution is running under.
+   * Identifies the queryable scope this operation is running under.
    *
-   * - `'runtime'` — top-level `runtime.execute(plan)`. The default scope
-   *   used by the standard read/write paths.
-   * - `'connection'` — `connection.execute(plan)` after
-   *   `runtime.connection()` checked out a connection from the pool.
-   * - `'transaction'` — `transaction.execute(plan)` inside an explicit
-   *   transaction, or a query routed through `withTransaction`.
+   * - `'runtime'` — top-level `runtime.query(plan)` or `runtime.execute(plan)`.
+   *   The default scope used by the standard read/write paths.
+   * - `'connection'` — `connection.query(plan)` or `connection.execute(plan)`
+   *   after `runtime.connection()` checked out a connection from the pool.
+   * - `'transaction'` — `transaction.query(plan)` or
+   *   `transaction.execute(plan)` inside an explicit transaction, or an
+   *   operation routed through `withTransaction`.
    *
    * Middleware that should only act at the top level read this field to
    * bypass non-runtime scopes. The cache middleware uses it to skip
@@ -372,28 +372,28 @@ interface RuntimeMiddlewareContext {
    */
   readonly scope: 'runtime' | 'connection' | 'transaction';
   /**
-   * Identity for one `execute()` call. The runtime mints a fresh value via
-   * `crypto.randomUUID()` when it constructs the per-execute context, and
-   * the same context reference is threaded through every middleware phase
-   * (`beforeExecute`, `intercept`, `onRow`, `afterExecute`). Every hook in
-   * one execute call therefore observes the same `planExecutionId`; two
-   * executions of the same plan observe distinct values. Use this to
-   * correlate observations across the lifecycle of a single execute call
+   * Identity for one `query()` or `execute()` call. The runtime mints a fresh
+   * value via `crypto.randomUUID()` when it constructs the per-operation
+   * context, then threads that context through every hook in the selected
+   * query or execute lifecycle. Every hook in one call therefore observes
+   * the same `planExecutionId`; two calls for the same plan observe distinct
+   * values. Use this to correlate observations across a single operation
    * (tracing, timing, audit). See ADR 220.
    */
   readonly planExecutionId: string;
 }
-interface AfterExecuteResult {
-  readonly rowCount: number;
+interface AfterResultBase {
   readonly latencyMs: number;
-  readonly completed: boolean;
   /**
-   * Indicates where the rows observed during this execution came from.
+   * Indicates which execution path was selected.
    *
-   * - `'driver'` — the default. Rows came from the underlying driver via
-   *   `runDriver` / `runWithMiddleware`'s normal path.
-   * - `'middleware'` — a `RuntimeMiddleware.intercept` hook short-circuited
-   *   execution and supplied the rows directly. The driver was not invoked.
+   * - `'driver'` — the default. The result came from the underlying driver via
+   *   `runDriver` / `runQueryWithMiddleware` or
+   *   `runExecuteWithMiddleware`'s normal path.
+   * - `'middleware'` — a `RuntimeMiddleware.interceptQuery` or
+   *   `RuntimeMiddleware.interceptExecute` hook selected the middleware
+   *   interception path. This includes both supplying the result directly and
+   *   completing with an interceptor error; the driver was not invoked.
    *
    * Observers (telemetry, lints, budgets) that need to distinguish between
    * driver-served and middleware-served executions read this field.
@@ -401,37 +401,30 @@ interface AfterExecuteResult {
    */
   readonly source: 'driver' | 'middleware';
 }
-/**
- * Result of a successful `RuntimeMiddleware.intercept` hook.
- *
- * Carries the rows that the middleware wishes to return in place of
- * invoking the driver. The runtime iterates `rows` in order and yields
- * each row to the consumer; `beforeExecute`, `runDriver`, and `onRow` are
- * all skipped on the hit path. `afterExecute` still fires with
- * `source: 'middleware'`.
- *
- * `rows` accepts both `Iterable` (arrays, sync generators) and
- * `AsyncIterable` (async generators). `for await` natively handles both
- * via `Symbol.asyncIterator` / `Symbol.iterator` fallback, so the
- * orchestrator does not need to branch on the variant. Cached arrays in
- * the cache middleware are the common case; streaming variants support
- * future use cases like mock layers replaying recordings.
- *
- * Row shape is `Record<string, unknown>` — the same untyped shape
- * `onRow` receives. The SQL runtime decodes intercepted rows through its
- * normal codec pass, so interceptors cache and return raw (undecoded)
- * rows.
- */
-interface InterceptResult {
+interface AfterQueryResult extends AfterResultBase {
+  readonly rowCount: number;
+  readonly completed: boolean;
+}
+type AfterExecuteResult = AfterResultBase & ({
+  readonly stats: RuntimeStatementStats;
+  readonly completed: true;
+} | {
+  readonly completed: false;
+});
+interface QueryInterceptResult {
   readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
 }
+interface ExecuteInterceptResult {
+  readonly stats: RuntimeStatementStats;
+}
 /**
  * Marker interface for family-specific param-ref mutators threaded into
- * `beforeExecute` as the third argument. The framework treats the mutator
- * opaquely — it allocates and forwards the family's mutator instance so
- * `runWithMiddleware` can stay family-agnostic. SQL extends this with
- * `SqlParamRefMutator` (over `ParamRef`); Mongo extends with
- * `MongoParamRefMutator` (over `MongoParamRef`).
+ * `beforeQuery` or `beforeExecute` as the third argument. The framework treats
+ * the mutator opaquely — it allocates and forwards the family's mutator
+ * instance so the operation-specific middleware runners can stay
+ * family-agnostic. SQL extends this with `SqlParamRefMutator` (over
+ * `ParamRef`); Mongo extends this with `MongoParamRefMutator` (over
+ * `MongoParamRef`).
  *
  * Extension authors target the family-specific mutator type, not this
  * marker.
@@ -449,66 +442,124 @@ type ParamRefMutator = {
  * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.
  *
  * `TMutator` is the family-specific {@link ParamRefMutator} the runtime
- * threads into `beforeExecute(plan, ctx, params)` as a third argument.
- * Existing `(plan)` / `(plan, ctx)` middleware bodies continue to compile
- * — TypeScript permits assigning a function with fewer parameters to a
- * function-typed slot that declares more. The third arg is additive.
+ * threads into `beforeQuery(plan, ctx, params)` or
+ * `beforeExecute(plan, ctx, params)` as a third argument. Existing
+ * `(plan)` / `(plan, ctx)` middleware bodies continue to compile — TypeScript
+ * permits assigning a function with fewer parameters to a function-typed slot
+ * that declares more. The third arg is additive.
  */
 interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan, TMutator extends ParamRefMutator = ParamRefMutator> {
   readonly name: string;
   readonly familyId?: string;
   readonly targetId?: string;
   /**
-   * Optional short-circuit hook. Runs inside `runWithMiddleware`, after
-   * the orchestrator receives the lowered plan and before any
-   * `beforeExecute` hook fires. Middleware run in registration order; the
-   * first to return a non-`undefined` `InterceptResult` wins, and
-   * subsequent middleware's `intercept` does not fire.
+   * Fires after the family runtime has produced a draft execution plan from
+   * the AST, but before the family encodes parameter values to driver wire
+   * format. Mutations applied via the family-specific `params` mutator are
+   * visible to the subsequent encode step.
+   *
+   * Lifecycle position (SQL example):
+   *   `runBeforeCompile → lowerSqlPlan → beforeQuery → encodeParams → interceptQuery → driver query`.
+   *
+   * The `params` argument is a family-specific {@link ParamRefMutator}
+   * scoped to the value slots of `ParamRef` nodes in the plan's AST.
+   * Middleware that doesn't need to mutate params can ignore the argument;
+   * existing `(plan)` / `(plan, ctx)` bodies stay compatible.
+   *
+   * `ctx.signal` carries the per-operation `AbortSignal`; middleware that
+   * wraps a network SDK forwards it. Cooperative cancellation surfaces a
+   * `RUNTIME.ABORTED { phase: 'beforeQuery' }` envelope promptly even when the
+   * body ignores the signal.
+   *
+   * Intercept ordering: `interceptQuery` runs *after* this hook; an
+   * interceptor that short-circuits the driver path still observes the
+   * post-`beforeQuery`, fully-encoded plan. The trade-off is that any
+   * `beforeQuery` SDK round-trips happen even when a downstream interceptor
+   * would have skipped the driver entirely.
+   */
+  beforeQuery?(plan: TPlan, ctx: RuntimeMiddlewareContext, params?: TMutator): void | Promise<void>;
+  /**
+   * Optional short-circuit hook for query executions. Runs inside
+   * `runQueryWithMiddleware`, after the orchestrator receives the lowered plan
+   * and after the `beforeQuery` hook fires. Middleware run in registration
+   * order; the first to return a non-`undefined` `QueryInterceptResult` wins,
+   * and subsequent middleware's `interceptQuery` does not fire.
    *
-   * On a hit, `beforeExecute`, `runDriver`, and `onRow` are all skipped.
-   * `afterExecute` still fires with `source: 'middleware'`.
+   * On a hit, `beforeQuery` has already fired; `runDriver` and `onRow` are
+   * skipped. `afterQuery` still fires with `source: 'middleware'`.
    *
-   * Returning `undefined` (or omitting the hook entirely) signals
-   * passthrough — execution proceeds through the normal driver path.
+   * Returning `undefined` (or omitting the hook entirely) signals passthrough
+   * — execution proceeds through the normal driver path.
    *
-   * Errors thrown inside `intercept` are rethrown by `runWithMiddleware`
-   * as the original `Error` — no envelope is guaranteed at this layer.
-   * Before rethrowing, `afterExecute` fires with `completed: false` and
-   * `source: 'middleware'`. Errors thrown by `afterExecute` during the
-   * error path remain swallowed (existing semantics, unchanged).
+   * Errors thrown inside `interceptQuery` are rethrown by
+   * `runQueryWithMiddleware` as the original `Error` — no envelope is
+   * guaranteed at this layer. Before rethrowing, `afterQuery` fires with
+   * `completed: false` and `source: 'middleware'`. Errors thrown by
+   * `afterQuery` during the error path remain swallowed (existing semantics,
+   * unchanged).
    *
-   * Used by middleware that need to short-circuit execution and supply
+   * Used by middleware that need to short-circuit query execution and supply
    * rows directly: caching, mocks, rate limiting, circuit breaking.
+   *
+   * `rows` accepts both `Iterable` (arrays, sync generators) and `AsyncIterable`
+   * (async generators). `for await` natively handles both via
+   * `Symbol.asyncIterator` / `Symbol.iterator` fallback, so the orchestrator
+   * does not need to branch on the variant. Cached arrays in the cache
+   * middleware are the common case; streaming variants support future use
+   * cases like mock layers replaying recordings.
+   *
+   * Row shape is `Record<string, unknown>` — the same untyped shape `onRow`
+   * receives. The SQL runtime decodes intercepted rows through its normal
+   * codec pass, so interceptors cache and return raw (undecoded) rows.
    */
-  intercept?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<InterceptResult | undefined>;
+  interceptQuery?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<QueryInterceptResult | undefined>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  afterQuery?(plan: TPlan, result: AfterQueryResult, ctx: RuntimeMiddlewareContext): Promise<void>;
   /**
-   * Fires after the family runtime has produced a draft execution
-   * plan from the AST, but before the family encodes parameter values
-   * to driver wire format. Mutations applied via the
-   * family-specific `params` mutator are visible to the subsequent
-   * encode step.
+   * Fires after the family runtime has produced a draft execution plan from
+   * the AST, but before the family encodes parameter values to driver wire
+   * format. Mutations applied via the family-specific `params` mutator are
+   * visible to the subsequent encode step.
    *
    * Lifecycle position (SQL example):
-   *   `runBeforeCompile → lowerSqlPlan → beforeExecute → encodeParams → intercept → driver`.
+   *   `runBeforeCompile → lowerSqlPlan → beforeExecute → encodeParams → interceptExecute → driver execute`.
    *
    * The `params` argument is a family-specific {@link ParamRefMutator}
    * scoped to the value slots of `ParamRef` nodes in the plan's AST.
-   * Middleware that doesn't need to mutate params can ignore the
-   * argument; existing `(plan)` / `(plan, ctx)` bodies stay compatible.
+   * Middleware that doesn't need to mutate params can ignore the argument;
+   * existing `(plan)` / `(plan, ctx)` bodies stay compatible.
    *
-   * `ctx.signal` carries the per-query `AbortSignal`; middleware that
-   * wraps a network SDK forwards it. Cooperative cancellation
-   * surfaces a `RUNTIME.ABORTED { phase: 'beforeExecute' }` envelope
-   * promptly even when the body ignores the signal.
+   * `ctx.signal` carries the per-operation `AbortSignal`; middleware that
+   * wraps a network SDK forwards it. Cooperative cancellation surfaces a
+   * `RUNTIME.ABORTED { phase: 'beforeExecute' }` envelope promptly even when
+   * the body ignores the signal.
    *
-   * Intercept ordering: `intercept` runs *after* this hook; an
-   * interceptor that short-circuits the driver path still observes
-   * the post-`beforeExecute`, fully-encoded plan. The trade-off is
-   * that any `beforeExecute` SDK round-trips happen even when a
-   * downstream interceptor would have skipped the driver entirely.
+   * Intercept ordering: `interceptExecute` runs *after* this hook; an
+   * interceptor that short-circuits the driver path still observes the
+   * post-`beforeExecute`, fully-encoded plan. The trade-off is that any
+   * `beforeExecute` SDK round-trips happen even when a downstream interceptor
+   * would have skipped the driver entirely.
    */
   beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext, params?: TMutator): void | Promise<void>;
-  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  /**
+   * Optional short-circuit hook for execute operations. Middleware run in
+   * registration order; the first to return a non-`undefined`
+   * `ExecuteInterceptResult` wins, and subsequent middleware's
+   * `interceptExecute` does not fire.
+   *
+   * On a hit, `beforeExecute` has already fired; only the driver execute is
+   * skipped. The statistics supplied in `stats` are returned eagerly; there is
+   * no row stream and `onRow` is not fired. `afterExecute` still fires with
+   * `source: 'middleware'`.
+   *
+   * Returning `undefined` (or omitting the hook entirely) signals passthrough
+   * — execution proceeds through the normal driver path. Errors thrown inside
+   * `interceptExecute` are rethrown by `runExecuteWithMiddleware` as the
+   * original `Error`. Before rethrowing, `afterExecute` fires with
+   * `completed: false`; errors thrown by `afterExecute` during the error path
+   * remain swallowed.
+   */
+  interceptExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<ExecuteInterceptResult | undefined>;
   afterExecute?(plan: TPlan, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
 }
 /**
@@ -537,47 +588,100 @@ type CrossFamilyMiddleware<TPlan extends QueryPlan = QueryPlan> = RuntimeMiddlew
   readonly targetId?: undefined;
 };
 /**
- * Optional per-`execute` options accepted by every family runtime.
+ * Optional per-operation options accepted by every family runtime.
  *
- * `signal` is the per-query cancellation signal. The runtime threads the
- * signal through to every codec call for the query and uses it to short-
- * circuit the row stream with `RUNTIME.ABORTED` when the caller aborts.
- * Omitting the option (or passing `undefined`) preserves today's behavior
- * bit-for-bit.
+ * `signal` is the per-operation cancellation signal. The runtime threads it
+ * through middleware and codec calls; query row streams stop with
+ * `RUNTIME.ABORTED` when the caller aborts. Omitting the option (or passing
+ * `undefined`) preserves today's behavior bit-for-bit.
  */
 interface RuntimeExecuteOptions {
   readonly signal?: AbortSignal;
   readonly scope?: 'runtime' | 'connection' | 'transaction';
 }
 /**
- * Cross-family SPI for any runtime that can execute plans and be shut down.
+ * Cross-family SPI for any runtime that can query or execute plans and be shut down.
  * Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,
  * Mongo structurally (due to its phantom Row parameter using a unique symbol).
  *
- * The `_row` intersection on `execute` connects the `Row` type parameter to the
+ * The `_row` intersection on `query` connects the `Row` type parameter to the
  * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
  */
+interface RuntimeStatementStats {
+  readonly affectedRows: number;
+}
 interface RuntimeExecutor<TPlan extends QueryPlan> {
-  execute<Row>(plan: TPlan & {
+  query<Row>(plan: TPlan & {
     readonly _row?: Row;
   }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
+  execute(plan: TPlan, options?: RuntimeExecuteOptions): Promise<RuntimeStatementStats>;
   close(): Promise<void>;
 }
 declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, runtimeFamilyId: string, runtimeTargetId: string): void;
 //#endregion
 //#region src/execution/before-execute-chain.d.ts
+/**
+ * Runs every middleware's `beforeQuery` hook in registration order,
+ * threading through the (optional) family-specific `paramsMutator`.
+ *
+ * Why this lives outside {@link runQueryWithMiddleware}: middleware that
+ * mutates parameter values (e.g. cipherstash's bulk-encrypt SDK
+ * round-trip) must run *before* the family runtime encodes those
+ * parameters to driver wire format. Family runtimes call
+ * `runBeforeQueryChain` between the AST → plan lowering step and
+ * the parameter encode step; the encode then observes the mutator's
+ * `currentParams()` view. `runQueryWithMiddleware` retains the rest of
+ * the query lifecycle (`interceptQuery`, driver/row source loop, `onRow`,
+ * `afterQuery`) but no longer fires `beforeQuery` itself.
+ *
+ * Lifecycle within this helper:
+ *
+ *  1. For each middleware in registration order, if `beforeQuery`
+ *     is implemented:
+ *     - `checkAborted(ctx, 'beforeQuery')` short-circuits if the
+ *       caller already aborted at entry.
+ *     - The hook is invoked with `(plan, ctx, paramsMutator)`. A
+ *       middleware body that ignores the mutator stays compatible —
+ *       JavaScript allows extra positional arguments.
+ *     - If the hook returns a Promise, it is raced against
+ *       `ctx.signal` via {@link raceAgainstAbort} so cooperative
+ *       cancellation surfaces a `RUNTIME.ABORTED { phase:
+ *       'beforeQuery' }` envelope even when the body itself
+ *       ignores the signal.
+ *
+ * Error propagation: any error thrown by a `beforeQuery` body
+ * (or surfaced by the abort race) propagates out of this helper
+ * unchanged. Family runtime entry points await this helper before invoking
+ * `runQueryWithMiddleware`, so a rejection prevents the runner and its
+ * `afterQuery` hook from running.
+ *
+ * Relationship to {@link runQueryWithMiddleware}: the framework's
+ * `RuntimeCore.query` template calls this helper between
+ * `lower(plan)` and `runQueryWithMiddleware(...)`. Family runtimes that
+ * override query preparation (e.g. SQL, which inlines lower + encode for
+ * direct mutator threading) call this helper themselves at the
+ * equivalent point — between the family's AST → draft-plan
+ * lowering and the parameter-encode step.
+ *
+ * Intercept ordering: this helper fires unconditionally before
+ * `runQueryWithMiddleware`. `interceptQuery` (inside
+ * `runQueryWithMiddleware`) therefore observes the post-`beforeQuery`
+ * plan — mutator mutations are visible in the params interceptors see.
+ * The trade-off is documented on `RuntimeMiddleware.interceptQuery`.
+ */
+declare function runBeforeQueryChain<TExec extends ExecutionPlan, TMutator extends ParamRefMutator = ParamRefMutator>(plan: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec, TMutator>>, ctx: RuntimeMiddlewareContext, paramsMutator?: TMutator): Promise<void>;
 /**
  * Runs every middleware's `beforeExecute` hook in registration order,
  * threading through the (optional) family-specific `paramsMutator`.
  *
- * Why this lives outside {@link runWithMiddleware}: middleware that
+ * Why this lives outside {@link runExecuteWithMiddleware}: middleware that
  * mutates parameter values (e.g. cipherstash's bulk-encrypt SDK
  * round-trip) must run *before* the family runtime encodes those
  * parameters to driver wire format. Family runtimes call
  * `runBeforeExecuteChain` between the AST → plan lowering step and
  * the parameter encode step; the encode then observes the mutator's
- * `currentParams()` view. `runWithMiddleware` retains the rest of
- * the lifecycle (`intercept`, driver/row source loop, `onRow`,
+ * `currentParams()` view. `runExecuteWithMiddleware` retains the rest of
+ * the execute lifecycle (`interceptExecute`, driver statistics execution,
  * `afterExecute`) but no longer fires `beforeExecute` itself.
  *
  * Lifecycle within this helper:
@@ -597,23 +701,23 @@ declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, run
  *
  * Error propagation: any error thrown by a `beforeExecute` body
  * (or surfaced by the abort race) propagates out of this helper
- * unchanged. The family runtime is responsible for converting it
- * into the appropriate `afterExecute(completed: false)` notification
- * once `runWithMiddleware` runs.
+ * unchanged. Family runtime entry points await this helper before invoking
+ * `runExecuteWithMiddleware`, so a rejection prevents the runner and its
+ * `afterExecute` hook from running.
  *
- * Relationship to {@link runWithMiddleware}: the framework's
+ * Relationship to {@link runExecuteWithMiddleware}: the framework's
  * `RuntimeCore.execute` template calls this helper between
- * `lower(plan)` and `runWithMiddleware(...)`. Family runtimes that
- * override `execute` (e.g. SQL, which inlines lower + encode for
+ * `lower(plan)` and `runExecuteWithMiddleware(...)`. Family runtimes that
+ * override execute (e.g. SQL, which inlines lower + encode for
  * direct mutator threading) call this helper themselves at the
  * equivalent point — between the family's AST → draft-plan
  * lowering and the parameter-encode step.
  *
  * Intercept ordering: this helper fires unconditionally before
- * `runWithMiddleware`. `intercept` (inside `runWithMiddleware`)
- * therefore observes the post-`beforeExecute` plan — mutator
- * mutations are visible in the params interceptors see. The
- * trade-off is documented on `RuntimeMiddleware.intercept`.
+ * `runExecuteWithMiddleware`. `interceptExecute` (inside
+ * `runExecuteWithMiddleware`) therefore observes the post-`beforeExecute`
+ * plan — mutator mutations are visible in the params interceptors see.
+ * The trade-off is documented on `RuntimeMiddleware.interceptExecute`.
  */
 declare function runBeforeExecuteChain<TExec extends ExecutionPlan, TMutator extends ParamRefMutator = ParamRefMutator>(plan: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec, TMutator>>, ctx: RuntimeMiddlewareContext, paramsMutator?: TMutator): Promise<void>;
 //#endregion
@@ -644,17 +748,18 @@ declare function runtimeError(code: string, message: string, details?: Record<st
  * - `'decode'` — abort fired during `decodeRow` / `decodeField`.
  * - `'stream'` — abort fired between rows or before any codec call
  *   (already-aborted at entry).
- * - `'beforeExecute'` / `'afterExecute'` / `'onRow'` — abort fired
- *   on entry to or during the corresponding middleware phase
+ * - `'beforeQuery'` / `'beforeExecute'` / `'afterQuery'` /
+ *   `'afterExecute'` / `'onRow'` — abort fired on entry to or during
+ *   the corresponding middleware phase
  *   (cooperative cancellation per the param-transform seam).
  */
 declare const RUNTIME_ABORTED: "RUNTIME.ABORTED";
 /** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
-type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream' | 'beforeExecute' | 'afterExecute' | 'onRow';
+type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream' | 'beforeQuery' | 'beforeExecute' | 'afterQuery' | 'afterExecute' | 'onRow';
 /**
  * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
  * abort was observed — codec call sites (`encode` / `decode` / `stream`)
- * or middleware seams (`beforeExecute` / `afterExecute` / `onRow`), as
+ * or operation-specific middleware seams, as
  * enumerated on {@link RuntimeAbortedPhase}. Cause carries
  * `signal.reason` verbatim from the platform — native abort produces a
  * `DOMException`, explicit `controller.abort(reason)` produces whatever
@@ -710,49 +815,84 @@ declare function raceAgainstAbort<T>(work: Promise<T>, signal: AbortSignal | und
 //#endregion
 //#region src/execution/run-with-middleware.d.ts
 /**
- * Drives a single execution of `runDriver()` through the middleware
- * lifecycle's intercept + row-source + termination phases.
+ * Drives a single query execution of `runDriver()` through the middleware
+ * lifecycle's `interceptQuery` + row-source + termination phases.
  *
  * Lifecycle, in order:
- *  1. For each middleware in registration order: `intercept(exec, ctx)`. The
- *     first non-`undefined` result wins; subsequent middleware's `intercept`
- *     does not fire. On a hit, the runtime emits a `middleware.intercept`
- *     debug event naming the winning middleware, switches the row source to
- *     the intercepted rows, and proceeds with `source: 'middleware'`. On
- *     all-passthrough (every `intercept` returns `undefined` or is omitted),
- *     `source: 'driver'` is used and the row source is `runDriver()`.
+ *  1. For each middleware in registration order: `interceptQuery(exec, ctx)`.
+ *     The first non-`undefined` result wins; subsequent middleware's
+ *     `interceptQuery` does not fire. On a hit, the runtime emits a
+ *     `middleware.interceptQuery` debug event naming the winning middleware,
+ *     switches the row source to the intercepted rows, and proceeds with
+ *     `source: 'middleware'`. On all-passthrough (every `interceptQuery`
+ *     returns `undefined` or is omitted), `source: 'driver'` is used and the
+ *     row source is `runDriver()`.
  *  2. Iterate the row source. On the driver path, for each row, for each
  *     middleware in registration order: `onRow(row, exec, ctx)`; then yield
  *     the row. On the intercepted hit path, `onRow` is skipped — intercepted
  *     rows did not originate from a driver row stream — but rows are still
  *     yielded to the consumer in order.
  *  3. On successful completion: for each middleware in registration order:
- *     `afterExecute(exec, { rowCount, latencyMs, completed: true, source },
+ *     `afterQuery(exec, { rowCount, latencyMs, completed: true, source },
  *     ctx)`.
  *  4. On any error thrown during steps 1–2: for each middleware in
- *     registration order: `afterExecute(exec, { rowCount, latencyMs,
- *     completed: false, source }, ctx)`. Errors thrown by `afterExecute`
+ *     registration order: `afterQuery(exec, { rowCount, latencyMs,
+ *     completed: false, source }, ctx)`. Errors thrown by `afterQuery`
  *     during the error path are swallowed so they do not mask the original
  *     error. The original error is then rethrown.
  *
- * `beforeExecute` is **not** fired here — see
- * {@link runBeforeExecuteChain} in `before-execute-chain.ts`. Family
- * runtimes call that helper between the AST → plan lowering step and
- * the parameter encode step so middleware that mutates ParamRef
- * values (e.g. cipherstash bulk-encrypt) can have its mutations
- * visible to encode. `runWithMiddleware` operates on the fully-
- * encoded plan; interceptors therefore observe a fully-mutated,
+ * `beforeQuery` is **not** fired here — see
+ * {@link runBeforeQueryChain} in `before-execute-chain.ts`. Family runtimes
+ * call that helper between the AST → plan lowering step and the parameter
+ * encode step so middleware that mutates ParamRef values can have its
+ * mutations visible to encode. `runQueryWithMiddleware` operates on the
+ * fully-encoded plan; interceptors therefore observe a fully-mutated,
  * encoded plan.
  *
- * The `source` field on `AfterExecuteResult` lets observers (telemetry,
- * lints, budgets) distinguish driver-served from middleware-served
- * executions without needing their own out-of-band signal.
+ * The `source` field on `AfterQueryResult` lets observers (telemetry, lints,
+ * budgets) distinguish driver-served from middleware-served executions
+ * without needing their own out-of-band signal.
  *
  * This helper is the single canonical implementation of the
- * intercept-and-row-source loop; family runtimes should not
- * reimplement it.
+ * intercept-and-row-source loop; family runtimes should not reimplement it.
+ */
+declare function runQueryWithMiddleware<TExec extends ExecutionPlan, Row>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => AsyncIterable<Row>): AsyncIterableResult<Row>;
+/**
+ * Drives a single execute operation through the middleware
+ * `interceptExecute` + statistics + termination phases.
+ *
+ * Lifecycle, in order:
+ *  1. For each middleware in registration order: `interceptExecute(exec, ctx)`.
+ *     The first non-`undefined` result wins; subsequent middleware's
+ *     `interceptExecute` does not fire. On a hit, the runtime emits a
+ *     `middleware.interceptExecute` debug event naming the winning middleware,
+ *     uses the returned `stats`, and proceeds with `source: 'middleware'`.
+ *     On all-passthrough (every `interceptExecute` returns `undefined` or is
+ *     omitted), `source: 'driver'` is used and `runDriver()` supplies the
+ *     statistics.
+ *  2. Execute operations return eager statistics. There is no row stream and
+ *     `onRow` does not fire.
+ *  3. On successful completion: for each middleware in registration order:
+ *     `afterExecute(exec, { stats, latencyMs, completed: true, source }, ctx)`.
+ *  4. On any error thrown during steps 1–2: for each middleware in
+ *     registration order: `afterExecute(exec, { latencyMs, completed: false,
+ *     source }, ctx)`. Errors thrown by `afterExecute` during the error path
+ *     are swallowed so they do not mask the original error. The original
+ *     error is then rethrown.
+ *
+ * `beforeExecute` is **not** fired here — see
+ * {@link runBeforeExecuteChain} in `before-execute-chain.ts`. Family runtimes
+ * call that helper between the AST → plan lowering step and the parameter
+ * encode step so middleware that mutates ParamRef values can have its
+ * mutations visible to encode. `runExecuteWithMiddleware` operates on the
+ * fully-encoded plan; interceptors therefore observe a fully-mutated,
+ * encoded plan.
+ *
+ * The `source` field on `AfterExecuteResult` lets observers (telemetry, lints,
+ * budgets) distinguish driver-served from middleware-served executions
+ * without needing their own out-of-band signal.
  */
-declare function runWithMiddleware<TExec extends ExecutionPlan, Row>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => AsyncIterable<Row>): AsyncIterableResult<Row>;
+declare function runExecuteWithMiddleware<TExec extends ExecutionPlan>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => Promise<RuntimeStatementStats>): Promise<RuntimeStatementStats>;
 //#endregion
 //#region src/execution/runtime-core.d.ts
 /**
@@ -769,34 +909,30 @@ interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan
 /**
  * Family-agnostic abstract runtime base.
  *
- * Defines the entire `execute(plan)` template in one place:
+ * Defines the shared operation-specific middleware lifecycles:
  *
  * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides
- *    this to run its `beforeCompile` middleware-hook chain.
+ *    this to run its shared `beforeCompile` middleware-hook chain.
  * 2. `lower(plan)` — abstract. Each family produces its `*ExecutionPlan`
  *    (SQL via `lowerSqlPlan`, Mongo via `adapter.lower`).
- * 3. `runBeforeExecuteChain(exec, this.middleware, this.ctx)` — concrete;
- *    runs every middleware's `beforeExecute` hook after lowering but
- *    before the row source is opened. Family runtimes that need a
- *    params mutator visible to a downstream encode step (SQL) override
- *    `execute` and call this helper themselves at the equivalent
- *    pre-encode point.
- * 4. `runWithMiddleware(exec, this.middleware, this.ctx,
- *    () => runDriver(exec))` — concrete; runs the intercept chain,
- *    drives the row source, fires `onRow` / `afterExecute`. Does
- *    **not** fire `beforeExecute` — see step 3.
- *
- * Concrete subclasses must implement `lower`, `runDriver`, and `close`.
+ * 3. Queries run `beforeQuery`; statements run `beforeExecute`. Both chains
+ *    run after lowering and before their matching driver terminal. Family
+ *    runtimes that expose a params mutator to downstream encoding override
+ *    the operation and call the matching helper at the pre-encode point.
+ * 4. The matching runner processes `interceptQuery` or `interceptExecute`
+ *    before invoking the driver. Queries then fire `onRow` and `afterQuery`;
+ *    statements fire `afterExecute`.
+ *
+ * Concrete subclasses must implement `lower`, `runDriver`, `runExecute`, and
+ * `close`.
  *
  * The class is generic over:
  * - `TPlan` — the family's pre-lowering plan type.
  * - `TExec` — the family's post-lowering (executable) plan type.
  * - `TMiddleware` — the family's middleware type. Constrained to
- *   `RuntimeMiddleware<TExec>` because `runWithMiddleware` invokes the
- *   `beforeExecute` / `onRow` / `afterExecute` hooks with the lowered
- *   `TExec`. (The spec/plan wording "RuntimeMiddleware<TPlan>" is
- *   tightened to `<TExec>` here so the helper call typechecks; the
- *   intent is unchanged — middleware sees the post-lowering plan.)
+ *   `RuntimeMiddleware<TExec>` because the operation-specific runners invoke
+ *   hooks with the lowered `TExec`. Middleware therefore sees the
+ *   post-lowering plan.
  */
 declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends ExecutionPlan, TMiddleware extends RuntimeMiddleware<TExec>> implements RuntimeExecutor<TPlan> {
   protected readonly middleware: ReadonlyArray<TMiddleware>;
@@ -813,11 +949,10 @@ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends Execut
    * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo
    * produces `{ command, ... }`.
    *
-   * `ctx` carries per-query cancellation (and any future fields on
-   * `CodecCallContext`); concrete subclasses forward it to the
-   * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,
-   * Mongo's `resolveValue` in m3). The runtime allocates one ctx per
-   * `execute()` call and threads the same reference everywhere; the
+   * `ctx` carries per-operation cancellation (and any future fields on
+   * `CodecCallContext`); concrete subclasses forward it to the encode-side
+   * codec dispatch site. The runtime allocates one ctx per operation call
+   * and threads the same reference everywhere; the
    * `signal` field inside may be `undefined`, but the ctx object itself
    * is always present.
    */
@@ -826,17 +961,19 @@ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends Execut
    * Drive the underlying transport for a lowered `TExec`. Yields raw rows
    * directly from the driver as `Record<string, unknown>`; codec decoding
    * (if any) is the subclass's responsibility, applied by wrapping
-   * `execute()` rather than living inside this hook.
+   * `query()` rather than living inside this hook.
    *
-   * The `Row` type parameter on `execute()` is satisfied by the caller via
+   * The `Row` type parameter on `query()` is satisfied by the caller via
    * the plan's phantom `_row`; the runtime treats rows as opaque records
    * here and trusts the caller's row typing.
    */
   protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;
+  protected abstract runExecute(exec: TExec): Promise<RuntimeStatementStats>;
   abstract close(): Promise<void>;
-  execute<Row>(plan: TPlan & {
+  query<Row>(plan: TPlan & {
     readonly _row?: Row;
   }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
+  execute(plan: TPlan, options?: RuntimeExecuteOptions): Promise<RuntimeStatementStats>;
 }
 //#endregion
 //#region src/meta-builder.d.ts
@@ -897,5 +1034,5 @@ interface LaneMetaBuilder<K extends OperationKind> extends MetaBuilder<K> {
  */
 declare function createMetaBuilder<K extends OperationKind>(kind: K, terminalName: string): LaneMetaBuilder<K>;
 //#endregion
-export { defineAnnotation as A, RuntimeMiddleware as C, checkAborted as D, assertAnnotationsApplicable as E, runtimeAborted as F, runtimeError as I, raceAgainstAbort as M, runBeforeExecuteChain as N, checkMiddlewareCompatibility as O, runWithMiddleware as P, RuntimeLog as S, ValidAnnotations as T, RuntimeCore as _, CrossFamilyMiddleware as a, RuntimeExecuteOptions as b, InterceptResult as c, OperationKind as d, ParamRefMutator as f, RuntimeAbortedPhase as g, ResultType as h, AsyncIterableResult as i, isRuntimeError as j, createMetaBuilder as k, LaneMetaBuilder as l, RUNTIME_ABORTED as m, AnnotationHandle as n, DefineAnnotationOptions as o, QueryPlan as p, AnnotationValue as r, ExecutionPlan as s, AfterExecuteResult as t, MetaBuilder as u, RuntimeCoreOptions as v, RuntimeMiddlewareContext as w, RuntimeExecutor as x, RuntimeErrorEnvelope as y };
-//# sourceMappingURL=runtime-Cne6hBaG.d.mts.map
+export { checkAborted as A, runtimeAborted as B, RuntimeExecutor as C, RuntimeStatementStats as D, RuntimeMiddlewareContext as E, raceAgainstAbort as F, runBeforeExecuteChain as I, runBeforeQueryChain as L, createMetaBuilder as M, defineAnnotation as N, ValidAnnotations as O, isRuntimeError as P, runExecuteWithMiddleware as R, RuntimeExecuteOptions as S, RuntimeMiddleware as T, runtimeError as V, ResultType as _, AsyncIterableResult as a, RuntimeCoreOptions as b, ExecuteInterceptResult as c, MetaBuilder as d, OperationKind as f, RUNTIME_ABORTED as g, QueryPlan as h, AnnotationValue as i, checkMiddlewareCompatibility as j, assertAnnotationsApplicable as k, ExecutionPlan as l, QueryInterceptResult as m, AfterQueryResult as n, CrossFamilyMiddleware as o, ParamRefMutator as p, AnnotationHandle as r, DefineAnnotationOptions as s, AfterExecuteResult as t, LaneMetaBuilder as u, RuntimeAbortedPhase as v, RuntimeLog as w, RuntimeErrorEnvelope as x, RuntimeCore as y, runQueryWithMiddleware as z };
+//# sourceMappingURL=runtime-Cuxw8obj.d.mts.map