@prisma/orm-framework 0.16.0

package/dist/runtime--RZXG1zP.d.mts

@@ -0,0 +1,901 @@
+import { U as PlanMeta } from "./domain-envelope-D6Wn9AmZ-BqZKTT9U.mjs";
+import { r as CodecCallContext } from "./codec-types-XJO6eC9U-B_K2q0zm.mjs";
+//#region ../../../1-framework/1-core/framework-components/dist/runtime.d.mts
+//#region src/annotations.d.ts
+/**
+ * The kinds of operations an annotation may apply to.
+ *
+ * - `'read'` — `SELECT` / `find` / `first` / `all` / `count` / aggregates.
+ * - `'write'` — `INSERT` / `UPDATE` / `DELETE` / `create` / `update` / `delete` / `upsert`.
+ *
+ * Annotations declare which kinds they apply to via `defineAnnotation`'s
+ * `applicableTo` option; lane terminals enforce the constraint at both the
+ * type level (via `ValidAnnotations`) and at runtime (via
+ * `assertAnnotationsApplicable`).
+ *
+ * Finer-grained kinds (`'select' | 'insert' | 'update' | 'delete' | 'upsert'`)
+ * are deliberately deferred. The binary covers the common case (the cache
+ * middleware applies to reads; an audit annotation would apply to writes;
+ * tracing/OTel applies to both). When a real annotation surfaces that needs
+ * a finer split, the union widens and existing handles remain typecheckable.
+ */
+type OperationKind = 'read' | 'write';
+/**
+ * An applied annotation. Carries the namespace, the typed payload, and the
+ * `applicableTo` set the underlying handle declared. The `__annotation`
+ * brand lets `read` distinguish branded user annotations from arbitrary
+ * data that may happen to live under the same namespace key in
+ * `plan.meta.annotations` (e.g. framework-internal metadata such as
+ * `meta.annotations.codecs`).
+ *
+ * Constructed by calling an `AnnotationHandle` directly (e.g.
+ * `cacheAnnotation({ ttl: 60 })`); never instantiated by hand.
+ */
+interface AnnotationValue<Payload, Kinds extends OperationKind> {
+  readonly __annotation: true;
+  readonly namespace: string;
+  readonly value: Payload;
+  readonly applicableTo: ReadonlySet<Kinds>;
+}
+/**
+ * Handle returned by `defineAnnotation`. The handle is **callable**: the
+ * call signature wraps a `Payload` into an `AnnotationValue` ready to
+ * pass to a lane terminal's variadic `annotations` argument. The handle
+ * also carries static metadata as own properties:
+ *
+ * - `namespace` — the namespace string the handle was declared with.
+ * - `applicableTo` — the frozen `ReadonlySet<Kinds>` consumed by both
+ *   the type-level `ValidAnnotations` gate and the runtime
+ *   `assertAnnotationsApplicable` gate.
+ * - `read(plan)` — extract the `Payload` from a plan's `meta.annotations`
+ *   if a value was previously written under this handle's namespace.
+ *   Returns `undefined` when the annotation is absent or when the stored
+ *   value is not a branded `AnnotationValue` (e.g. framework-internal
+ *   metadata under the same namespace key).
+ *
+ * Handles are the only supported public entry point for reading and
+ * writing annotations. Direct mutation of `plan.meta.annotations` is not
+ * part of the public API.
+ *
+ * ```typescript
+ * const cacheAnnotation = defineAnnotation<{ ttl: number }>()({
+ *   namespace: 'cache',
+ *   applicableTo: ['read'],
+ * });
+ *
+ * // Call the handle to construct a value:
+ * const applied = cacheAnnotation({ ttl: 60 });
+ *
+ * // Read a stored value off a plan:
+ * const payload = cacheAnnotation.read(plan);
+ * ```
+ *
+ * Note on the inherited `Function.prototype.apply`: because the handle is
+ * a function, the property name `apply` resolves to JavaScript's built-in
+ * `Function.prototype.apply` (which lets you invoke a function with an
+ * array of arguments). This is **not** the construction entry point — to
+ * build an `AnnotationValue`, call the handle directly. The
+ * `AnnotationHandle` interface deliberately does not declare an `apply`
+ * member of its own.
+ */
+interface AnnotationHandle<Payload, Kinds extends OperationKind> {
+  (value: Payload): AnnotationValue<Payload, Kinds>;
+  readonly namespace: string;
+  readonly applicableTo: ReadonlySet<Kinds>;
+  read(plan: {
+    readonly meta: {
+      readonly annotations?: Record<string, unknown>;
+    };
+  }): Payload | undefined;
+}
+/**
+ * Options accepted by `defineAnnotation`.
+ *
+ * `namespace` is the string key under which the annotation is stored in
+ * `plan.meta.annotations`. **Reserved namespaces** include framework-
+ * internal metadata keys; user handles must not use them:
+ *
+ * - `codecs` — used by the SQL emitter to record per-alias codec ids
+ *   (`meta.annotations.codecs[alias] = 'pg/text@1'`); the SQL runtime's
+ *   `decodeRow` reads from this key. A user `defineAnnotation('codecs')`
+ *   handle is not structurally prevented, but its behavior with the
+ *   emitter and the runtime is undefined and we make no compatibility
+ *   guarantees about it.
+ * - Target-specific keys such as `pg` (and equivalents on other
+ *   targets) are similarly reserved for adapter / target use.
+ *
+ * `applicableTo` declares which operation kinds the annotation may attach
+ * to. The lane terminals' type-level `ValidAnnotations<K, As>` gate rejects
+ * annotations whose `Kinds` does not include the terminal's `K`; the
+ * runtime helper `assertAnnotationsApplicable` does the equivalent at
+ * runtime so casts and `any` cannot bypass the gate.
+ */
+interface DefineAnnotationOptions<Kinds extends OperationKind> {
+  readonly namespace: string;
+  readonly applicableTo: readonly Kinds[];
+}
+/**
+ * Defines a typed annotation handle.
+ *
+ * Two-step call form. The first step takes the `Payload` type argument
+ * (TypeScript cannot infer `Payload` from anything in the options, so it
+ * must be supplied explicitly); the second step takes the runtime options
+ * and infers `Kinds` from the `applicableTo` array via a `const` type
+ * parameter, so the operation kinds appear exactly once at the call site.
+ *
+ * @example
+ * ```typescript
+ * // Read-only annotation. Lane terminals like `db.User.first(...)` accept
+ * // it; `db.User.create(...)` rejects it at the type level.
+ * const cacheAnnotation = defineAnnotation<{ ttl?: number; skip?: boolean }>()({
+ *   namespace: 'cache',
+ *   applicableTo: ['read'],
+ * }); // Kinds inferred as 'read'
+ *
+ * // Write-only annotation. Mirror image.
+ * const auditAnnotation = defineAnnotation<{ actor: string }>()({
+ *   namespace: 'audit',
+ *   applicableTo: ['write'],
+ * }); // Kinds inferred as 'write'
+ *
+ * // Annotation applicable to both kinds (e.g. tracing).
+ * const otelAnnotation = defineAnnotation<{ traceId: string }>()({
+ *   namespace: 'otel',
+ *   applicableTo: ['read', 'write'],
+ * }); // Kinds inferred as 'read' | 'write'
+ * ```
+ *
+ * **Reserved namespaces.** See `DefineAnnotationOptions.namespace` for the
+ * list of framework-internal namespaces (`codecs`, target-specific keys).
+ * `defineAnnotation` does not structurally prevent a user from naming a
+ * reserved namespace, but the framework makes no compatibility guarantee
+ * about handles that do.
+ */
+declare function defineAnnotation<Payload>(): <const Kinds extends OperationKind>(options: DefineAnnotationOptions<Kinds>) => AnnotationHandle<Payload, Kinds>;
+/**
+ * Type-level applicability gate consumed by lane terminals.
+ *
+ * Maps a tuple of `AnnotationValue`s to a tuple where each element either
+ * keeps its annotation type (when the annotation's declared `Kinds`
+ * includes the terminal's operation kind `K`) or resolves to `never`
+ * (when the kinds are incompatible). A `never` element makes the entire
+ * tuple unassignable, surfacing the mismatch as a type error at the call
+ * site of the terminal.
+ *
+ * The SQL DSL builders constrain their variadic `...annotations`
+ * parameter via `As & ValidAnnotations<K, As>`. **The intersection is
+ * load-bearing** — see the note below. The ORM terminals deliberately
+ * sidestep this trick by taking one annotation per `meta.annotate(...)`
+ * call (no variadic-tuple inference involved), so `ValidAnnotations` is
+ * consumed only by the SQL DSL today.
+ *
+ * @example
+ * ```typescript
+ * class SelectQuery<Row> {
+ *   annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
+ *     ...annotations: As & ValidAnnotations<'read', As>
+ *   ): SelectQuery<Row>;
+ * }
+ *
+ * class InsertQuery<Row> {
+ *   annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
+ *     ...annotations: As & ValidAnnotations<'write', As>
+ *   ): InsertQuery<Row>;
+ * }
+ *
+ * db.users.select('id').annotate(cacheAnnotation({ ttl: 60 }));
+ * // ✓ cacheAnnotation declares 'read'; SelectQuery.annotate requires 'read'.
+ *
+ * db.users.insert([{ name: 'Alice' }]).annotate(cacheAnnotation({ ttl: 60 }));
+ * // ✗ cacheAnnotation declares 'read'; InsertQuery.annotate requires 'write'.
+ * //   Element resolves to `never` → tuple unassignable → type error.
+ * ```
+ *
+ * **Why `As & ValidAnnotations<K, As>` and not `ValidAnnotations<K, As>`
+ * alone.** TypeScript's variadic-tuple inference is too forgiving when
+ * the parameter type refers to `As` only through `ValidAnnotations`: it
+ * will pick an `As` that makes the call valid even when the gated tuple
+ * would contain `never` for an inapplicable element. The intersection
+ * pins `As` to the actual call-site tuple AND requires it to be
+ * assignable to the gated form. A `never` element in the gated tuple
+ * then collapses the corresponding intersection position to `never`,
+ * and the inapplicable argument fails to assign — surfacing the mismatch
+ * as a type error at the call site.
+ *
+ * The runtime helper `assertAnnotationsApplicable` covers the equivalent
+ * check at runtime so casts and `any` cannot bypass this gate.
+ */
+type ValidAnnotations<K extends OperationKind, As extends readonly AnnotationValue<unknown, OperationKind>[]> = { readonly [I in keyof As]: As[I] extends AnnotationValue<infer P, infer Kinds> ? K extends Kinds ? AnnotationValue<P, Kinds> : never : never; };
+/**
+ * Runtime applicability gate. Throws `RUNTIME.ANNOTATION_INAPPLICABLE` if
+ * any annotation in `annotations` declares an `applicableTo` set that does
+ * not include `kind`. Used by lane terminals (SQL DSL builders' `.build()`,
+ * ORM `Collection` terminals) to fail closed when the type-level
+ * `ValidAnnotations` gate is bypassed via cast / `any` / dynamic
+ * invocation.
+ *
+ * Passes silently on:
+ *  - empty arrays
+ *  - annotations whose `applicableTo` includes `kind`
+ *
+ * Throws on:
+ *  - any annotation whose `applicableTo` does not include `kind`. The
+ *    error names the offending annotation's `namespace` and the
+ *    `terminalName` so users can locate the misuse.
+ *
+ * @example
+ * ```typescript
+ * // Inside an ORM read terminal:
+ * assertAnnotationsApplicable(annotations, 'read', 'first');
+ * ```
+ */
+declare function assertAnnotationsApplicable(annotations: readonly AnnotationValue<unknown, OperationKind>[], kind: OperationKind, terminalName: string): void;
+//#endregion
+//#region src/execution/async-iterable-result.d.ts
+declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
+  private readonly generator;
+  private consumed;
+  private consumedBy;
+  private bufferedArrayPromise;
+  constructor(generator: AsyncGenerator<Row, void, unknown>);
+  [Symbol.asyncIterator](): AsyncIterator<Row>;
+  toArray(): Promise<Row[]>;
+  first(): Promise<Row | null>;
+  firstOrThrow(): Promise<Row>;
+  then<TResult1 = Row[], TResult2 = never>(onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+}
+//#endregion
+//#region src/execution/query-plan.d.ts
+/**
+ * Family-agnostic plan marker.
+ *
+ * Carries only `meta` (the family-agnostic plan metadata) and the optional
+ * phantom `_row` parameter that lets type-level utilities recover the row
+ * type from a plan value. SQL and Mongo extend this marker with their own
+ * concrete shapes (`SqlQueryPlan`, `MongoQueryPlan`).
+ *
+ * `QueryPlan` is the *pre-lowering* marker — i.e. the surface a builder
+ * produces before family-specific lowering turns it into an executable
+ * plan (`ExecutionPlan`).
+ */
+interface QueryPlan<Row = unknown> {
+  readonly meta: PlanMeta;
+  /**
+   * Phantom property to carry the Row generic for type-level utilities.
+   * Not set at runtime; used only for `ResultType` extraction.
+   */
+  readonly _row?: Row;
+}
+/**
+ * Family-agnostic execution-plan marker.
+ *
+ * Extends `QueryPlan` with no additional structural fields — the marker
+ * exists to nominally distinguish executable plans from pre-lowering plans
+ * in the type system. Family-specific execution plans (`SqlExecutionPlan`,
+ * `MongoExecutionPlan`) extend this marker with their concrete shapes
+ * (e.g. `sql + params` for SQL, `wireCommand` for Mongo).
+ */
+interface ExecutionPlan<Row = unknown> extends QueryPlan<Row> {}
+/**
+ * Extracts the `Row` type from a plan via the phantom `_row` property.
+ *
+ * Works with any plan that extends `QueryPlan<Row>` — including
+ * `ExecutionPlan<Row>`, `SqlQueryPlan<Row>`, `SqlExecutionPlan<Row>`,
+ * `MongoQueryPlan<Row>`, and `MongoExecutionPlan<Row>`.
+ *
+ * The `_row` property must be present in the plan's static type for the
+ * conditional to bind `R`; objects whose type lacks `_row` resolve to
+ * `never`. Without the `keyof` guard, `extends { _row?: infer R }` would
+ * silently match any object and infer `unknown`.
+ *
+ * Example: `type Row = ResultType<typeof plan>`.
+ */
+type ResultType<P> = '_row' extends keyof P ? P extends {
+  readonly _row?: infer R;
+} ? R : never : never;
+//#endregion
+//#region src/execution/runtime-middleware.d.ts
+interface RuntimeLog {
+  info(event: unknown): void;
+  warn(event: unknown): void;
+  error(event: unknown): void;
+  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.
+ */
+interface RuntimeMiddlewareContext {
+  readonly contract: unknown;
+  readonly mode: 'strict' | 'permissive';
+  readonly now: () => number;
+  readonly log: RuntimeLog;
+  /**
+   * Returns a stable string identifying the (storage, statement, params)
+   * tuple of an execution. Two semantically equivalent executions return
+   * the same string. Used by middleware that need per-execution identity
+   * (caching, request coalescing).
+   *
+   * The family runtime owns the implementation:
+   * - SQL: `meta.storageHash` + `exec.sql` + `canonicalStringify(exec.params)`
+   * - Mongo: `meta.storageHash` + `canonicalStringify({ ...exec.command })`
+   *
+   * The method is `async` because the underlying digest helper
+   * (`hashContent`) uses the WebCrypto API, whose `crypto.subtle.digest`
+   * primitive is asynchronous by design.
+   *
+   * The returned string is intended to be consumed directly as a `Map` key
+   * — it is not (and should not be) further hashed by callers.
+   */
+  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.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Identifies the queryable scope this execution 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`.
+   *
+   * Middleware that should only act at the top level read this field to
+   * bypass non-runtime scopes. The cache middleware uses it to skip
+   * caching inside transactions (where read-after-write coherence is the
+   * caller's expectation) and dedicated connections (where the user has
+   * explicitly stepped outside the shared cache surface). Observers that
+   * don't care about the scope can ignore the field.
+   *
+   * Family runtimes populate this at context-construction time per
+   * scope. Existing middleware that ignore the field are unaffected.
+   */
+  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
+   * (tracing, timing, audit). See ADR 220.
+   */
+  readonly planExecutionId: string;
+}
+interface AfterExecuteResult {
+  readonly rowCount: number;
+  readonly latencyMs: number;
+  readonly completed: boolean;
+  /**
+   * Indicates where the rows observed during this execution came from.
+   *
+   * - `'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.
+   *
+   * Observers (telemetry, lints, budgets) that need to distinguish between
+   * driver-served and middleware-served executions read this field.
+   * Observers that don't care can ignore it.
+   */
+  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 {
+  readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+}
+/**
+ * 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`).
+ *
+ * Extension authors target the family-specific mutator type, not this
+ * marker.
+ */
+declare const PARAM_REF_MUTATOR_BRAND: unique symbol;
+type ParamRefMutator = {
+  readonly [PARAM_REF_MUTATOR_BRAND]?: never;
+};
+/**
+ * Family-agnostic middleware SPI parameterized over the plan marker.
+ *
+ * `TPlan` defaults to the framework `QueryPlan` marker so a generic
+ * middleware (e.g. cross-family telemetry) can be authored without
+ * naming a family. Family-specific middleware (`SqlMiddleware`,
+ * `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.
+ */
+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.
+   *
+   * On a hit, `beforeExecute`, `runDriver`, and `onRow` are all skipped.
+   * `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 `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).
+   *
+   * Used by middleware that need to short-circuit execution and supply
+   * rows directly: caching, mocks, rate limiting, circuit breaking.
+   */
+  intercept?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<InterceptResult | undefined>;
+  /**
+   * 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`.
+   *
+   * 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-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.
+   *
+   * 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.
+   */
+  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext, params?: TMutator): void | Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  afterExecute?(plan: TPlan, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
+}
+/**
+ * Cross-family middleware — one that doesn't constrain `familyId` or
+ * `targetId` and is therefore compatible with any family runtime's
+ * middleware array (`SqlMiddleware[]`, `MongoMiddleware[]`, etc.).
+ *
+ * The intersection `RuntimeMiddleware & { familyId?: undefined; targetId?: undefined }`
+ * pins both optional properties to exactly `undefined` (intersecting
+ * `string | undefined` with `undefined` collapses to `undefined`). Under
+ * `exactOptionalPropertyTypes: true`, the plain `RuntimeMiddleware` shape
+ * — with `familyId?: string` — is *not* assignable to `SqlMiddleware`
+ * (which narrows `familyId?: 'sql'`) because `string` is wider than
+ * `'sql'`. Pinning the property to `undefined` makes the value a subtype
+ * of every narrowed variant: `undefined` extends both `'sql' | undefined`
+ * and `'mongo' | undefined`, so a `CrossFamilyMiddleware` value drops
+ * into a SQL or Mongo middleware slot without a cast.
+ *
+ * Cross-family middleware factories (`createCacheMiddleware`, future
+ * `audit` / OTel middleware) declare this as their return type so the
+ * cross-family typing is named once rather than re-spelled at every call
+ * site.
+ */
+type CrossFamilyMiddleware<TPlan extends QueryPlan = QueryPlan> = RuntimeMiddleware<TPlan> & {
+  readonly familyId?: undefined;
+  readonly targetId?: undefined;
+};
+/**
+ * Optional per-`execute` 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.
+ */
+interface RuntimeExecuteOptions {
+  readonly signal?: AbortSignal;
+  readonly scope?: 'runtime' | 'connection' | 'transaction';
+}
+/**
+ * Cross-family SPI for any runtime that can 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
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
+ */
+interface RuntimeExecutor<TPlan extends QueryPlan> {
+  execute<Row>(plan: TPlan & {
+    readonly _row?: Row;
+  }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
+  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 `beforeExecute` hook in registration order,
+ * threading through the (optional) family-specific `paramsMutator`.
+ *
+ * Why this lives outside {@link runWithMiddleware}: 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`,
+ * `afterExecute`) but no longer fires `beforeExecute` itself.
+ *
+ * Lifecycle within this helper:
+ *
+ *  1. For each middleware in registration order, if `beforeExecute`
+ *     is implemented:
+ *     - `checkAborted(ctx, 'beforeExecute')` 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:
+ *       'beforeExecute' }` envelope even when the body itself
+ *       ignores the signal.
+ *
+ * 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.
+ *
+ * Relationship to {@link runWithMiddleware}: 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
+ * 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`.
+ */
+declare function runBeforeExecuteChain<TExec extends ExecutionPlan, TMutator extends ParamRefMutator = ParamRefMutator>(plan: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec, TMutator>>, ctx: RuntimeMiddlewareContext, paramsMutator?: TMutator): Promise<void>;
+//#endregion
+//#region src/shared/runtime-error.d.ts
+interface RuntimeErrorEnvelope extends Error {
+  readonly code: string;
+  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME' | 'DRIVER' | 'MIGRATION' | 'ORM';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+/**
+ * Type guard for the runtime-error envelope produced by `runtimeError`.
+ *
+ * Prefer this over duck-typing on `error.code` directly so consumers stay
+ * insulated from the envelope's internal shape.
+ */
+declare function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope;
+declare function runtimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeErrorEnvelope;
+//#endregion
+//#region src/execution/runtime-error.d.ts
+/**
+ * Stable code emitted by the runtime when an in-flight `execute()`
+ * is cancelled via the per-query `AbortSignal`. The envelope's
+ * `details.phase` distinguishes where the abort was observed:
+ *
+ * - `'encode'` — abort fired during `encodeParams` (SQL) or
+ *   `resolveValue` (Mongo).
+ * - `'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
+ *   (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';
+/**
+ * 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
+ * enumerated on {@link RuntimeAbortedPhase}. Cause carries
+ * `signal.reason` verbatim from the platform — native abort produces a
+ * `DOMException`, explicit `controller.abort(reason)` produces whatever
+ * the caller passed. No synthesis happens here.
+ */
+declare function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope;
+//#endregion
+//#region src/execution/race-against-abort.d.ts
+/**
+ * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
+ * context is already aborted at the precheck site. Centralises the
+ * `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+ * every codec dispatch site (and the `beforeExecute` middleware phase)
+ * repeats. Accepts both the framework `CodecCallContext` and the
+ * `RuntimeMiddlewareContext`; both expose `signal?: AbortSignal`.
+ */
+declare function checkAborted(ctx: {
+  readonly signal?: AbortSignal;
+}, phase: RuntimeAbortedPhase): void;
+/**
+ * Race a per-cell `Promise.all` (or any other in-flight work promise) against
+ * the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly
+ * even when codec bodies ignore the signal. In-flight bodies that ignore the
+ * signal are abandoned and run to completion in the background — the
+ * cooperative-cancellation contract documented in ADR 204.
+ *
+ * Call sites still SHOULD pre-check `signal.aborted` and short-circuit with
+ * a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —
+ * that path is the canonical "aborted at entry" surface and avoids
+ * scheduling the work promise. As a defensive belt-and-braces, this helper
+ * also handles the already-aborted case internally: `AbortSignal` does not
+ * replay past abort events to listeners registered after the abort, so we
+ * inspect `signal.aborted` synchronously and reject with the sentinel
+ * before installing the listener. The rejection is still attributed to the
+ * abort path via the sentinel-identity check.
+ *
+ * Distinguishing the rejection source is load-bearing for AC-ERR4
+ * (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).
+ * The semantically equivalent `abortable(signal)` helper in
+ * `@internal/utils` rejects with `signal.reason ?? new DOMException(...)`,
+ * which is not stably distinguishable from a codec-thrown error by identity
+ * alone (a fresh fallback DOMException is allocated per call). We instead
+ * track abort attribution with a unique sentinel: only the `onAbort` listener
+ * installed here ever rejects with the sentinel, so an `error === sentinel`
+ * identity check after the race is unambiguous.
+ *
+ * Lives in `framework-components` (rather than the SQL family, where it
+ * originated in m2) so every family runtime that needs cooperative
+ * cancellation around a codec-dispatch `Promise.all` (SQL encode + decode
+ * today, Mongo encode in m3) shares the same attribution logic.
+ */
+declare function raceAgainstAbort<T>(work: Promise<T>, signal: AbortSignal | undefined, phase: RuntimeAbortedPhase): Promise<T>;
+//#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.
+ *
+ * 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()`.
+ *  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 },
+ *     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`
+ *     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,
+ * 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.
+ *
+ * This helper is the single canonical implementation of the
+ * intercept-and-row-source loop; family runtimes should not
+ * reimplement it.
+ */
+declare function runWithMiddleware<TExec extends ExecutionPlan, Row>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => AsyncIterable<Row>): AsyncIterableResult<Row>;
+//#endregion
+//#region src/execution/runtime-core.d.ts
+/**
+ * Constructor options shared by every concrete `RuntimeCore` subclass.
+ *
+ * Family runtimes typically build the middleware list and the
+ * `RuntimeMiddlewareContext` themselves (running compatibility checks,
+ * narrowing the context's `contract` field, etc.) before calling `super`.
+ */
+interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {
+  readonly middleware: ReadonlyArray<TMiddleware>;
+  readonly ctx: RuntimeMiddlewareContext;
+}
+/**
+ * Family-agnostic abstract runtime base.
+ *
+ * Defines the entire `execute(plan)` template in one place:
+ *
+ * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides
+ *    this to run its `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`.
+ *
+ * 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.)
+ */
+declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends ExecutionPlan, TMiddleware extends RuntimeMiddleware<TExec>> implements RuntimeExecutor<TPlan> {
+  protected readonly middleware: ReadonlyArray<TMiddleware>;
+  protected readonly ctx: RuntimeMiddlewareContext;
+  constructor(options: RuntimeCoreOptions<TMiddleware>);
+  /**
+   * Pre-lowering hook for plan rewriting. Defaults to identity. Subclasses
+   * may override to run a `beforeCompile` middleware chain (SQL does this
+   * to support typed AST rewrites — see `before-compile-chain.ts`).
+   */
+  protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan>;
+  /**
+   * Lower a pre-lowering `TPlan` into the family's executable `TExec`.
+   * 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
+   * `signal` field inside may be `undefined`, but the ctx object itself
+   * is always present.
+   */
+  protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
+  /**
+   * 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.
+   *
+   * The `Row` type parameter on `execute()` 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>>;
+  abstract close(): Promise<void>;
+  execute<Row>(plan: TPlan & {
+    readonly _row?: Row;
+  }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
+}
+//#endregion
+//#region src/meta-builder.d.ts
+/**
+ * Per-terminal meta configurator handed to user callbacks. The terminal's
+ * operation kind `K` is fixed by the terminal that constructed the builder;
+ * `annotate(...)` accepts only annotations whose declared `Kinds` include
+ * `K`.
+ *
+ * The conditional parameter type
+ * `K extends Kinds ? AnnotationValue<P, Kinds> : never` collapses to `never`
+ * for inapplicable annotations, surfacing the mismatch as a type error at
+ * the call site of `meta.annotate(...)`. No variadic-tuple inference is
+ * involved — TypeScript infers `Kinds` from the annotation argument and
+ * checks the conditional directly.
+ *
+ * The runtime gate inside `annotate` (via
+ * `assertAnnotationsApplicable`) catches cast / `any` / dynamic bypasses
+ * and throws `RUNTIME.ANNOTATION_INAPPLICABLE`.
+ *
+ * `annotate` returns the builder for chaining; the return value of the
+ * configurator callback is unused, so both block-body and expression-body
+ * callbacks compile.
+ *
+ * @example
+ * ```typescript
+ * await db.User.find({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+ * await db.User.create(input, (meta) => {
+ *   meta.annotate(auditAnnotation({ actor: 'system' }));
+ *   meta.annotate(otelAnnotation({ traceId }));
+ * });
+ * ```
+ */
+interface MetaBuilder<K extends OperationKind> {
+  annotate<P, Kinds extends OperationKind>(annotation: K extends Kinds ? AnnotationValue<P, Kinds> : never): this;
+}
+/**
+ * Lane-side view of a meta builder. Extends the public `MetaBuilder<K>`
+ * surface with `annotations` so lane terminals can read the recorded map
+ * after invoking the user configurator.
+ *
+ * Lane terminals construct one of these via `createMetaBuilder(kind, terminalName)`,
+ * pass it to the user callback as `MetaBuilder<K>` (the narrower public
+ * view), then read `meta.annotations` to thread the recorded values into
+ * `plan.meta.annotations`.
+ */
+interface LaneMetaBuilder<K extends OperationKind> extends MetaBuilder<K> {
+  readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
+}
+/**
+ * Construct a lane-side meta builder for a terminal of operation kind `K`.
+ *
+ * Lane terminals call this with their `kind` (`'read'` or `'write'`) and a
+ * `terminalName` for error messages, hand the resulting builder to the
+ * user-supplied configurator callback (typed as `MetaBuilder<K>`, the
+ * narrower public view), and read `meta.annotations` afterwards to thread
+ * the recorded values into `plan.meta.annotations`.
+ */
+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--RZXG1zP.d.mts.map