@prisma-next/framework-components 0.5.0-dev.4 → 0.5.0-dev.41

package/dist/runtime.d.mts

@@ -1,6 +1,7 @@
+import { n as CodecCallContext } from "./codec-types-CB0jWeHU.mjs";
 import { PlanMeta } from "@prisma-next/contract/types";
 
-//#region src/async-iterable-result.d.ts
+//#region src/execution/async-iterable-result.d.ts
 declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
   private readonly generator;
   private consumed;
@@ -14,16 +15,136 @@ declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLik
   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/runtime-error.d.ts
+//#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-error.d.ts
 interface RuntimeErrorEnvelope extends Error {
   readonly code: string;
   readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
   readonly severity: 'error';
   readonly details?: Record<string, unknown>;
 }
+/**
+ * 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).
+ */
+declare const RUNTIME_ABORTED: "RUNTIME.ABORTED";
+/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
+type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';
+/**
+ * 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;
+/**
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+ * abort was observed (encode / decode / stream); 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
+ * codec-call context is already aborted at the precheck site. Centralises
+ * the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+ * every codec dispatch site repeats.
+ */
+declare function checkAborted(ctx: CodecCallContext, 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
+ * `@prisma-next/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/runtime-middleware.d.ts
+//#region src/execution/runtime-middleware.d.ts
 interface RuntimeLog {
   info(event: unknown): void;
   warn(event: unknown): void;
@@ -41,19 +162,33 @@ interface AfterExecuteResult {
   readonly latencyMs: number;
   readonly completed: boolean;
 }
-interface RuntimeMiddleware {
+/**
+ * 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.
+ */
+interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
   readonly name: string;
   readonly familyId?: string;
   readonly targetId?: string;
-  beforeExecute?(plan: {
-    readonly meta: PlanMeta;
-  }, ctx: RuntimeMiddlewareContext): Promise<void>;
-  onRow?(row: Record<string, unknown>, plan: {
-    readonly meta: PlanMeta;
-  }, ctx: RuntimeMiddlewareContext): Promise<void>;
-  afterExecute?(plan: {
-    readonly meta: PlanMeta;
-  }, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
+  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  afterExecute?(plan: TPlan, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
+}
+/**
+ * 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;
 }
 /**
  * Cross-family SPI for any runtime that can execute plans and be shut down.
@@ -61,17 +196,114 @@ interface RuntimeMiddleware {
  * 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 `ExecutionPlan<Row>` carries a phantom `_row?: Row`.
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
  */
-interface RuntimeExecutor<TPlan extends {
-  readonly meta: PlanMeta;
-}> {
+interface RuntimeExecutor<TPlan extends QueryPlan> {
   execute<Row>(plan: TPlan & {
     readonly _row?: Row;
-  }): AsyncIterableResult<Row>;
+  }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
   close(): Promise<void>;
 }
 declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, runtimeFamilyId: string, runtimeTargetId: string): void;
 //#endregion
-export { type AfterExecuteResult, AsyncIterableResult, type RuntimeErrorEnvelope, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkMiddlewareCompatibility, runtimeError };
+//#region src/execution/run-with-middleware.d.ts
+/**
+ * Drives a single execution of `runDriver()` through the middleware lifecycle.
+ *
+ * Lifecycle, in order:
+ *  1. For each middleware in registration order: `beforeExecute(exec, ctx)`.
+ *  2. For each row yielded by `runDriver()`: for each middleware in registration
+ *     order: `onRow(row, exec, ctx)`; then yield the row to the consumer.
+ *  3. On successful completion: for each middleware in registration order:
+ *     `afterExecute(exec, { rowCount, latencyMs, completed: true }, ctx)`.
+ *  4. On any error thrown by the driver loop: for each middleware in
+ *     registration order: `afterExecute(exec, { rowCount, latencyMs,
+ *     completed: false }, ctx)`. Errors thrown by `afterExecute` during the
+ *     error path are swallowed so they do not mask the original driver error.
+ *     The original error is then rethrown.
+ *
+ * This helper is the single canonical implementation of the middleware
+ * orchestration 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. `runWithMiddleware(exec, this.middleware, this.ctx,
+ *    () => runDriver(exec))` — concrete; lifts the middleware lifecycle
+ *    out of the family runtimes into the canonical helper.
+ *
+ * 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
+export { type AfterExecuteResult, AsyncIterableResult, type ExecutionPlan, type QueryPlan, RUNTIME_ABORTED, type ResultType, type RuntimeAbortedPhase, RuntimeCore, type RuntimeCoreOptions, type RuntimeErrorEnvelope, type RuntimeExecuteOptions, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeAborted, runtimeError };
 //# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/async-iterable-result.ts","../src/runtime-error.ts","../src/runtime-middleware.ts"],"sourcesContent":[],"mappings":";;;cAEa,oCAAoC,cAAc,MAAM,YAAY;;;EAApE,QAAA,UAAA;EAAkD,QAAA,oBAAA;EAAkB,WAAA,CAAA,SAAA,EAMxD,cANwD,CAMzC,GANyC,EAAA,IAAA,EAAA,OAAA,CAAA;EAMzC,CAIrC,MAAA,CAAO,aAAA,GAJ8B,EAIZ,aAJY,CAIE,GAJF,CAAA;EAAf,OAAA,CAAA,CAAA,EAuBZ,OAvBY,CAuBJ,GAvBI,EAAA,CAAA;EAIiB,KAAA,CAAA,CAAA,EAkDzB,OAlDyB,CAkDjB,GAlDiB,GAAA,IAAA,CAAA;EAAd,YAAA,CAAA,CAAA,EAuDJ,OAvDI,CAuDI,GAvDJ,CAAA;EAAzB,IAAO,CAAA,WAmEQ,GAnER,EAAA,EAAA,WAAA,KAAA,CAAA,CAAA,WAAA,CAAA,EAAA,CAAA,CAAA,KAAA,EAoEiB,GApEjB,EAAA,EAAA,GAoE2B,QApE3B,GAoEsC,WApEtC,CAoEkD,QApElD,CAAA,CAAA,GAAA,SAAA,GAAA,IAAA,EAAA,UAAA,CAAA,EAAA,CAAA,CAAA,MAAA,EAAA,OAAA,EAAA,GAqE6B,QArE7B,GAqEwC,WArExC,CAqEoD,QArEpD,CAAA,CAAA,GAAA,SAAA,GAAA,IAAA,CAAA,EAsEL,WAtEK,CAsEO,QAtEP,GAsEkB,QAtElB,CAAA;;;;UCZO,oBAAA,SAA6B;;;EDEjC,SAAA,QAAA,EAAA,OAAmB;EAA+B,SAAA,OAAA,CAAA,ECE1C,MDF0C,CAAA,MAAA,EAAA,OAAA,CAAA;;AAMvB,iBCDxB,YAAA,CDCwB,IAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,OAAA,CAAA,ECE5B,MDF4B,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,ECGrC,oBDHqC;;;UEJvB,UAAA;EFFJ,IAAA,CAAA,KAAA,EAAA,OAAA,CAAA,EAAmB,IAAA;EAA+B,IAAA,CAAA,KAAA,EAAA,OAAA,CAAA,EAAA,IAAA;EAAkB,KAAA,CAAA,KAAA,EAAA,OAAA,CAAA,EAAA,IAAA;EAMzC,KAAA,EAAA,KAAA,EAAA,OAAA,CAAA,EAAA,IAAA;;AAIE,UEDzB,wBAAA,CFCyB;EAAd,SAAA,QAAA,EAAA,OAAA;EAAzB,SAAO,IAAA,EAAA,QAAA,GAAA,YAAA;EAmBW,SAAA,GAAA,EAAA,GAAA,GAAA,MAAA;EAAR,SAAA,GAAA,EEhBG,UFgBH;;AA+BI,UE5CA,kBAAA,CF4CA;EAKe,SAAA,QAAA,EAAA,MAAA;EAAR,SAAA,SAAA,EAAA,MAAA;EAYN,SAAA,SAAA,EAAA,OAAA;;AACmB,UExDpB,iBAAA,CFwDoB;EAAuB,SAAA,IAAA,EAAA,MAAA;EAAZ,SAAA,QAAA,CAAA,EAAA,MAAA;EACT,SAAA,QAAA,CAAA,EAAA,MAAA;EAAuB,aAAA,EAAA,IAAA,EAAA;IAAZ,SAAA,IAAA,EErDV,QFqDU;EACjC,CAAA,EAAA,GAAA,EEtDwC,wBFsDxC,CAAA,EEtDmE,OFsDnE,CAAA,IAAA,CAAA;EAAW,KAAA,EAAA,GAAA,EEpDnB,MFoDmB,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,IAAA,EAAA;IAAvB,SAAA,IAAA,EEnDsB,QFmDtB;EAhF4C,CAAA,EAAA,GAAA,EE8BxC,wBF9BwC,CAAA,EE+B5C,OF/B4C,CAAA,IAAA,CAAA;EAAoB,YAAA,EAAA,IAAA,EAAA;IAAW,SAAA,IAAA,EEiCrD,QFjCqD;aEkCpE,yBACH,2BACJ;;;ADtCL;AAOA;;;;ACHA;AAOA;AAOiB,UA+BA,eA/BkB,CAAA,cAAA;EAMlB,SAAA,IAAA,EAyB+C,QAzB9B;CAIM,CAAA,CAAA;EAAiB,OAAA,CAAA,GAAA,CAAA,CAAA,IAAA,EAsBpC,KAtBoC,GAAA;IAA2B,SAAA,IAAA,CAAA,EAsBrC,GAtBqC;EAE3E,CAAA,CAAA,EAoB8C,mBApB9C,CAoBkE,GApBlE,CAAA;EACkB,KAAA,EAAA,EAoBhB,OApBgB,CAAA,IAAA,CAAA;;AAEtB,iBAqBW,4BAAA,CArBX,UAAA,EAsBS,iBAtBT,EAAA,eAAA,EAAA,MAAA,EAAA,eAAA,EAAA,MAAA,CAAA,EAAA,IAAA"}
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/execution/async-iterable-result.ts","../src/execution/query-plan.ts","../src/execution/runtime-error.ts","../src/execution/race-against-abort.ts","../src/execution/runtime-middleware.ts","../src/execution/run-with-middleware.ts","../src/execution/runtime-core.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/runtime.mjs

@@ -1,4 +1,25 @@
-//#region src/runtime-error.ts
+//#region src/execution/runtime-error.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).
+*/
+const RUNTIME_ABORTED = "RUNTIME.ABORTED";
+/**
+* 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.
+*/
+function isRuntimeError(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string" && "category" in error && "severity" in error;
+}
 function runtimeError(code, message, details) {
 	const error = new Error(message);
 	Object.defineProperty(error, "name", {
@@ -23,9 +44,20 @@ function resolveCategory(code) {
 		default: return "RUNTIME";
 	}
 }
+/**
+* Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+* abort was observed (encode / decode / stream); 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.
+*/
+function runtimeAborted(phase, cause) {
+	const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });
+	return Object.assign(envelope, { cause });
+}
 
 //#endregion
-//#region src/async-iterable-result.ts
+//#region src/execution/async-iterable-result.ts
 var AsyncIterableResult = class {
 	generator;
 	consumed = false;
@@ -72,7 +104,186 @@ var AsyncIterableResult = class {
 };
 
 //#endregion
-//#region src/runtime-middleware.ts
+//#region src/execution/race-against-abort.ts
+/**
+* Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
+* codec-call context is already aborted at the precheck site. Centralises
+* the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+* every codec dispatch site repeats.
+*/
+function checkAborted(ctx, phase) {
+	if (ctx.signal?.aborted) throw runtimeAborted(phase, ctx.signal.reason);
+}
+/**
+* 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
+* `@prisma-next/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.
+*/
+async function raceAgainstAbort(work, signal, phase) {
+	if (signal === void 0) return await work;
+	const sentinel = { reason: void 0 };
+	let onAbort;
+	const abortPromise = new Promise((_, reject) => {
+		if (signal.aborted) {
+			sentinel.reason = signal.reason;
+			reject(sentinel);
+			return;
+		}
+		onAbort = () => {
+			sentinel.reason = signal.reason;
+			reject(sentinel);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		return await Promise.race([work, abortPromise]);
+	} catch (error) {
+		if (error === sentinel) throw runtimeAborted(phase, sentinel.reason);
+		throw error;
+	} finally {
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+
+//#endregion
+//#region src/execution/run-with-middleware.ts
+/**
+* Drives a single execution of `runDriver()` through the middleware lifecycle.
+*
+* Lifecycle, in order:
+*  1. For each middleware in registration order: `beforeExecute(exec, ctx)`.
+*  2. For each row yielded by `runDriver()`: for each middleware in registration
+*     order: `onRow(row, exec, ctx)`; then yield the row to the consumer.
+*  3. On successful completion: for each middleware in registration order:
+*     `afterExecute(exec, { rowCount, latencyMs, completed: true }, ctx)`.
+*  4. On any error thrown by the driver loop: for each middleware in
+*     registration order: `afterExecute(exec, { rowCount, latencyMs,
+*     completed: false }, ctx)`. Errors thrown by `afterExecute` during the
+*     error path are swallowed so they do not mask the original driver error.
+*     The original error is then rethrown.
+*
+* This helper is the single canonical implementation of the middleware
+* orchestration loop; family runtimes should not reimplement it.
+*/
+function runWithMiddleware(exec, middleware, ctx, runDriver) {
+	const iterator = async function* () {
+		const startedAt = Date.now();
+		let rowCount = 0;
+		let completed = false;
+		try {
+			for (const mw of middleware) if (mw.beforeExecute) await mw.beforeExecute(exec, ctx);
+			for await (const row of runDriver()) {
+				for (const mw of middleware) if (mw.onRow) await mw.onRow(row, exec, ctx);
+				rowCount++;
+				yield row;
+			}
+			completed = true;
+		} catch (error) {
+			const latencyMs$1 = Date.now() - startedAt;
+			for (const mw of middleware) if (mw.afterExecute) try {
+				await mw.afterExecute(exec, {
+					rowCount,
+					latencyMs: latencyMs$1,
+					completed
+				}, ctx);
+			} catch {}
+			throw error;
+		}
+		const latencyMs = Date.now() - startedAt;
+		for (const mw of middleware) if (mw.afterExecute) await mw.afterExecute(exec, {
+			rowCount,
+			latencyMs,
+			completed
+		}, ctx);
+	};
+	return new AsyncIterableResult(iterator());
+}
+
+//#endregion
+//#region src/execution/runtime-core.ts
+/**
+* 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. `runWithMiddleware(exec, this.middleware, this.ctx,
+*    () => runDriver(exec))` — concrete; lifts the middleware lifecycle
+*    out of the family runtimes into the canonical helper.
+*
+* 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.)
+*/
+var RuntimeCore = class {
+	middleware;
+	ctx;
+	constructor(options) {
+		this.middleware = options.middleware;
+		this.ctx = options.ctx;
+	}
+	/**
+	* 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`).
+	*/
+	runBeforeCompile(plan) {
+		return plan;
+	}
+	execute(plan, options) {
+		const self = this;
+		const signal = options?.signal;
+		const codecCtx = signal === void 0 ? {} : { signal };
+		async function* generator() {
+			checkAborted(codecCtx, "stream");
+			const compiled = await self.runBeforeCompile(plan);
+			const exec = await self.lower(compiled, codecCtx);
+			yield* runWithMiddleware(exec, self.middleware, self.ctx, () => self.runDriver(exec));
+		}
+		return new AsyncIterableResult(generator());
+	}
+};
+
+//#endregion
+//#region src/execution/runtime-middleware.ts
 function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTargetId) {
 	if (middleware.targetId !== void 0 && middleware.familyId === void 0) throw runtimeError("RUNTIME.MIDDLEWARE_INCOMPATIBLE", `Middleware '${middleware.name}' specifies targetId '${middleware.targetId}' without familyId`, {
 		middleware: middleware.name,
@@ -91,5 +302,5 @@ function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTarget
 }
 
 //#endregion
-export { AsyncIterableResult, checkMiddlewareCompatibility, runtimeError };
+export { AsyncIterableResult, RUNTIME_ABORTED, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeAborted, runtimeError };
 //# sourceMappingURL=runtime.mjs.map