@prisma-next/framework-components 0.5.0-dev.27 → 0.5.0-dev.29

package/dist/runtime.d.mts

@@ -1,6 +1,7 @@
+import { n as CodecCallContext } from "./codec-types-DXv-ROhF.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,7 +15,7 @@ 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/query-plan.d.ts
+//#region src/execution/query-plan.d.ts
 /**
  * Family-agnostic plan marker.
  *
@@ -63,7 +64,87 @@ type ResultType<P> = '_row' extends keyof P ? P extends {
   readonly _row?: infer R;
 } ? R : never : never;
 //#endregion
-//#region src/runtime-middleware.d.ts
+//#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/execution/runtime-middleware.d.ts
 interface RuntimeLog {
   info(event: unknown): void;
   warn(event: unknown): void;
@@ -97,6 +178,18 @@ interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
   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.
  * Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,
@@ -108,12 +201,12 @@ interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
 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
-//#region src/run-with-middleware.d.ts
+//#region src/execution/run-with-middleware.d.ts
 /**
  * Drives a single execution of `runDriver()` through the middleware lifecycle.
  *
@@ -134,7 +227,7 @@ declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, run
  */
 declare function runWithMiddleware<TExec extends ExecutionPlan, Row>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => AsyncIterable<Row>): AsyncIterableResult<Row>;
 //#endregion
-//#region src/runtime-core.d.ts
+//#region src/execution/runtime-core.d.ts
 /**
  * Constructor options shared by every concrete `RuntimeCore` subclass.
  *
@@ -185,8 +278,16 @@ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends Execut
    * 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): TExec | Promise<TExec>;
+  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
@@ -201,24 +302,8 @@ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends Execut
   abstract close(): Promise<void>;
   execute<Row>(plan: TPlan & {
     readonly _row?: Row;
-  }): AsyncIterableResult<Row>;
-}
-//#endregion
-//#region src/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>;
+  }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
 }
-/**
- * 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
-export { type AfterExecuteResult, AsyncIterableResult, type ExecutionPlan, type QueryPlan, type ResultType, RuntimeCore, type RuntimeCoreOptions, type RuntimeErrorEnvelope, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkMiddlewareCompatibility, isRuntimeError, runWithMiddleware, runtimeError };
+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/query-plan.ts","../src/runtime-middleware.ts","../src/run-with-middleware.ts","../src/runtime-core.ts","../src/runtime-error.ts"],"sourcesContent":[],"mappings":"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"}
+{"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,16 @@
-//#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`.
 *
@@ -32,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;
@@ -81,7 +104,76 @@ var AsyncIterableResult = class {
 };
 
 //#endregion
-//#region src/run-with-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.
 *
@@ -135,7 +227,7 @@ function runWithMiddleware(exec, middleware, ctx, runDriver) {
 }
 
 //#endregion
-//#region src/runtime-core.ts
+//#region src/execution/runtime-core.ts
 /**
 * Family-agnostic abstract runtime base.
 *
@@ -176,11 +268,14 @@ var RuntimeCore = class {
 	runBeforeCompile(plan) {
 		return plan;
 	}
-	execute(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);
+			const exec = await self.lower(compiled, codecCtx);
 			yield* runWithMiddleware(exec, self.middleware, self.ctx, () => self.runDriver(exec));
 		}
 		return new AsyncIterableResult(generator());
@@ -188,7 +283,7 @@ var RuntimeCore = class {
 };
 
 //#endregion
-//#region src/runtime-middleware.ts
+//#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,
@@ -207,5 +302,5 @@ function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTarget
 }
 
 //#endregion
-export { AsyncIterableResult, RuntimeCore, checkMiddlewareCompatibility, isRuntimeError, runWithMiddleware, runtimeError };
+export { AsyncIterableResult, RUNTIME_ABORTED, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeAborted, runtimeError };
 //# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":["out: Row[]","latencyMs"],"sources":["../src/runtime-error.ts","../src/async-iterable-result.ts","../src/run-with-middleware.ts","../src/runtime-core.ts","../src/runtime-middleware.ts"],"sourcesContent":["export interface RuntimeErrorEnvelope extends Error {\n  readonly code: string;\n  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';\n  readonly severity: 'error';\n  readonly details?: Record<string, unknown>;\n}\n\n/**\n * Type guard for the runtime-error envelope produced by `runtimeError`.\n *\n * Prefer this over duck-typing on `error.code` directly so consumers stay\n * insulated from the envelope's internal shape.\n */\nexport function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {\n  return (\n    error instanceof Error &&\n    'code' in error &&\n    typeof (error as { code?: unknown }).code === 'string' &&\n    'category' in error &&\n    'severity' in error\n  );\n}\n\nexport function runtimeError(\n  code: string,\n  message: string,\n  details?: Record<string, unknown>,\n): RuntimeErrorEnvelope {\n  const error = new Error(message) as RuntimeErrorEnvelope;\n  Object.defineProperty(error, 'name', {\n    value: 'RuntimeError',\n    configurable: true,\n  });\n\n  return Object.assign(error, {\n    code,\n    category: resolveCategory(code),\n    severity: 'error' as const,\n    message,\n    details,\n  });\n}\n\nfunction resolveCategory(code: string): RuntimeErrorEnvelope['category'] {\n  const prefix = code.split('.')[0] ?? 'RUNTIME';\n  switch (prefix) {\n    case 'PLAN':\n    case 'CONTRACT':\n    case 'LINT':\n    case 'BUDGET':\n      return prefix;\n    default:\n      return 'RUNTIME';\n  }\n}\n","import { runtimeError } from './runtime-error';\n\nexport class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {\n  private readonly generator: AsyncGenerator<Row, void, unknown>;\n  private consumed = false;\n  private consumedBy: 'bufferedArray' | 'iterator' | undefined;\n  private bufferedArrayPromise: Promise<Row[]> | undefined;\n\n  constructor(generator: AsyncGenerator<Row, void, unknown>) {\n    this.generator = generator;\n  }\n\n  [Symbol.asyncIterator](): AsyncIterator<Row> {\n    if (this.consumed) {\n      throw runtimeError(\n        'RUNTIME.ITERATOR_CONSUMED',\n        `AsyncIterableResult iterator has already been consumed via ${this.consumedBy === 'bufferedArray' ? 'toArray()/then()' : 'for-await loop'}. Each AsyncIterableResult can only be iterated once.`,\n        {\n          consumedBy: this.consumedBy,\n          suggestion:\n            this.consumedBy === 'bufferedArray'\n              ? 'If you need to iterate multiple times, store the results from toArray() in a variable and reuse that.'\n              : 'If you need to iterate multiple times, use toArray() to collect all results first.',\n        },\n      );\n    }\n    this.consumed = true;\n    this.consumedBy = 'iterator';\n    return this.generator;\n  }\n\n  toArray(): Promise<Row[]> {\n    if (this.consumedBy === 'iterator') {\n      return Promise.reject(\n        runtimeError(\n          'RUNTIME.ITERATOR_CONSUMED',\n          'AsyncIterableResult iterator has already been consumed via for-await loop. Each AsyncIterableResult can only be iterated once.',\n          {\n            consumedBy: this.consumedBy,\n            suggestion:\n              'The iterator was already consumed by a for-await loop. Use toArray() or await the result before iterating.',\n          },\n        ),\n      );\n    }\n\n    if (this.bufferedArrayPromise) {\n      return this.bufferedArrayPromise;\n    }\n\n    this.consumed = true;\n    this.consumedBy = 'bufferedArray';\n    this.bufferedArrayPromise = (async () => {\n      const out: Row[] = [];\n      for await (const item of this.generator) {\n        out.push(item);\n      }\n      return out;\n    })();\n    return this.bufferedArrayPromise;\n  }\n\n  async first(): Promise<Row | null> {\n    const rows = await this.toArray();\n    return rows[0] ?? null;\n  }\n\n  async firstOrThrow(): Promise<Row> {\n    const row = await this.first();\n    if (row === null)\n      throw runtimeError(\n        'RUNTIME.NO_ROWS',\n        'Expected at least one row, but none were returned',\n        {},\n      );\n    return row;\n  }\n\n  // biome-ignore lint/suspicious/noThenProperty: PromiseLike implementation is intentional for await support.\n  then<TResult1 = Row[], TResult2 = never>(\n    onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null,\n  ): PromiseLike<TResult1 | TResult2> {\n    return this.toArray().then(onfulfilled, onrejected);\n  }\n}\n","import { AsyncIterableResult } from './async-iterable-result';\nimport type { ExecutionPlan } from './query-plan';\nimport type { RuntimeMiddleware, RuntimeMiddlewareContext } from './runtime-middleware';\n\n/**\n * Drives a single execution of `runDriver()` through the middleware lifecycle.\n *\n * Lifecycle, in order:\n *  1. For each middleware in registration order: `beforeExecute(exec, ctx)`.\n *  2. For each row yielded by `runDriver()`: for each middleware in registration\n *     order: `onRow(row, exec, ctx)`; then yield the row to the consumer.\n *  3. On successful completion: for each middleware in registration order:\n *     `afterExecute(exec, { rowCount, latencyMs, completed: true }, ctx)`.\n *  4. On any error thrown by the driver loop: for each middleware in\n *     registration order: `afterExecute(exec, { rowCount, latencyMs,\n *     completed: false }, ctx)`. Errors thrown by `afterExecute` during the\n *     error path are swallowed so they do not mask the original driver error.\n *     The original error is then rethrown.\n *\n * This helper is the single canonical implementation of the middleware\n * orchestration loop; family runtimes should not reimplement it.\n */\nexport function runWithMiddleware<TExec extends ExecutionPlan, Row>(\n  exec: TExec,\n  middleware: ReadonlyArray<RuntimeMiddleware<TExec>>,\n  ctx: RuntimeMiddlewareContext,\n  runDriver: () => AsyncIterable<Row>,\n): AsyncIterableResult<Row> {\n  const iterator = async function* (): AsyncGenerator<Row, void, unknown> {\n    const startedAt = Date.now();\n    let rowCount = 0;\n    let completed = false;\n\n    try {\n      for (const mw of middleware) {\n        if (mw.beforeExecute) {\n          await mw.beforeExecute(exec, ctx);\n        }\n      }\n\n      for await (const row of runDriver()) {\n        for (const mw of middleware) {\n          if (mw.onRow) {\n            await mw.onRow(row as Record<string, unknown>, exec, ctx);\n          }\n        }\n        rowCount++;\n        yield row;\n      }\n\n      completed = true;\n    } catch (error) {\n      const latencyMs = Date.now() - startedAt;\n      for (const mw of middleware) {\n        if (mw.afterExecute) {\n          try {\n            await mw.afterExecute(exec, { rowCount, latencyMs, completed }, ctx);\n          } catch {\n            // Swallow afterExecute errors during the error path so they do not\n            // mask the original driver error.\n          }\n        }\n      }\n\n      throw error;\n    }\n\n    const latencyMs = Date.now() - startedAt;\n    for (const mw of middleware) {\n      if (mw.afterExecute) {\n        await mw.afterExecute(exec, { rowCount, latencyMs, completed }, ctx);\n      }\n    }\n  };\n\n  return new AsyncIterableResult(iterator());\n}\n","import { AsyncIterableResult } from './async-iterable-result';\nimport type { ExecutionPlan, QueryPlan } from './query-plan';\nimport { runWithMiddleware } from './run-with-middleware';\nimport type {\n  RuntimeExecutor,\n  RuntimeMiddleware,\n  RuntimeMiddlewareContext,\n} from './runtime-middleware';\n\n/**\n * Constructor options shared by every concrete `RuntimeCore` subclass.\n *\n * Family runtimes typically build the middleware list and the\n * `RuntimeMiddlewareContext` themselves (running compatibility checks,\n * narrowing the context's `contract` field, etc.) before calling `super`.\n */\nexport interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {\n  readonly middleware: ReadonlyArray<TMiddleware>;\n  readonly ctx: RuntimeMiddlewareContext;\n}\n\n/**\n * Family-agnostic abstract runtime base.\n *\n * Defines the entire `execute(plan)` template in one place:\n *\n * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides\n *    this to run its `beforeCompile` middleware-hook chain.\n * 2. `lower(plan)` — abstract. Each family produces its `*ExecutionPlan`\n *    (SQL via `lowerSqlPlan`, Mongo via `adapter.lower`).\n * 3. `runWithMiddleware(exec, this.middleware, this.ctx,\n *    () => runDriver(exec))` — concrete; lifts the middleware lifecycle\n *    out of the family runtimes into the canonical helper.\n *\n * Concrete subclasses must implement `lower`, `runDriver`, and `close`.\n *\n * The class is generic over:\n * - `TPlan` — the family's pre-lowering plan type.\n * - `TExec` — the family's post-lowering (executable) plan type.\n * - `TMiddleware` — the family's middleware type. Constrained to\n *   `RuntimeMiddleware<TExec>` because `runWithMiddleware` invokes the\n *   `beforeExecute` / `onRow` / `afterExecute` hooks with the lowered\n *   `TExec`. (The spec/plan wording \"RuntimeMiddleware<TPlan>\" is\n *   tightened to `<TExec>` here so the helper call typechecks; the\n *   intent is unchanged — middleware sees the post-lowering plan.)\n */\nexport abstract class RuntimeCore<\n  TPlan extends QueryPlan,\n  TExec extends ExecutionPlan,\n  TMiddleware extends RuntimeMiddleware<TExec>,\n> implements RuntimeExecutor<TPlan>\n{\n  protected readonly middleware: ReadonlyArray<TMiddleware>;\n  protected readonly ctx: RuntimeMiddlewareContext;\n\n  constructor(options: RuntimeCoreOptions<TMiddleware>) {\n    this.middleware = options.middleware;\n    this.ctx = options.ctx;\n  }\n\n  /**\n   * Pre-lowering hook for plan rewriting. Defaults to identity. Subclasses\n   * may override to run a `beforeCompile` middleware chain (SQL does this\n   * to support typed AST rewrites — see `before-compile-chain.ts`).\n   */\n  protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan> {\n    return plan;\n  }\n\n  /**\n   * Lower a pre-lowering `TPlan` into the family's executable `TExec`.\n   * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo\n   * produces `{ command, ... }`.\n   */\n  protected abstract lower(plan: TPlan): TExec | Promise<TExec>;\n\n  /**\n   * Drive the underlying transport for a lowered `TExec`. Yields raw rows\n   * directly from the driver as `Record<string, unknown>`; codec decoding\n   * (if any) is the subclass's responsibility, applied by wrapping\n   * `execute()` rather than living inside this hook.\n   *\n   * The `Row` type parameter on `execute()` is satisfied by the caller via\n   * the plan's phantom `_row`; the runtime treats rows as opaque records\n   * here and trusts the caller's row typing.\n   */\n  protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;\n\n  abstract close(): Promise<void>;\n\n  execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row> {\n    const self = this;\n\n    async function* generator(): AsyncGenerator<Row, void, unknown> {\n      const compiled = await self.runBeforeCompile(plan);\n      const exec = await self.lower(compiled);\n      // The driver yields raw `Record<string, unknown>`; we cast to `Row` here.\n      // The Row contract is enforced by the caller via `plan._row`.\n      yield* runWithMiddleware<TExec, Row>(\n        exec,\n        self.middleware,\n        self.ctx,\n        () => self.runDriver(exec) as AsyncIterable<Row>,\n      );\n    }\n\n    return new AsyncIterableResult(generator());\n  }\n}\n","import type { AsyncIterableResult } from './async-iterable-result';\nimport type { QueryPlan } from './query-plan';\nimport { runtimeError } from './runtime-error';\n\nexport interface RuntimeLog {\n  info(event: unknown): void;\n  warn(event: unknown): void;\n  error(event: unknown): void;\n  debug?(event: unknown): void;\n}\n\nexport interface RuntimeMiddlewareContext {\n  readonly contract: unknown;\n  readonly mode: 'strict' | 'permissive';\n  readonly now: () => number;\n  readonly log: RuntimeLog;\n}\n\nexport interface AfterExecuteResult {\n  readonly rowCount: number;\n  readonly latencyMs: number;\n  readonly completed: boolean;\n}\n\n/**\n * Family-agnostic middleware SPI parameterized over the plan marker.\n *\n * `TPlan` defaults to the framework `QueryPlan` marker so a generic\n * middleware (e.g. cross-family telemetry) can be authored without\n * naming a family. Family-specific middleware (`SqlMiddleware`,\n * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.\n */\nexport interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {\n  readonly name: string;\n  readonly familyId?: string;\n  readonly targetId?: string;\n  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;\n  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;\n  afterExecute?(\n    plan: TPlan,\n    result: AfterExecuteResult,\n    ctx: RuntimeMiddlewareContext,\n  ): Promise<void>;\n}\n\n/**\n * Cross-family SPI for any runtime that can execute plans and be shut down.\n * Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,\n * Mongo structurally (due to its phantom Row parameter using a unique symbol).\n *\n * The `_row` intersection on `execute` connects the `Row` type parameter to the\n * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.\n */\nexport interface RuntimeExecutor<TPlan extends QueryPlan> {\n  execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row>;\n  close(): Promise<void>;\n}\n\nexport function checkMiddlewareCompatibility(\n  middleware: RuntimeMiddleware,\n  runtimeFamilyId: string,\n  runtimeTargetId: string,\n): void {\n  if (middleware.targetId !== undefined && middleware.familyId === undefined) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_INCOMPATIBLE',\n      `Middleware '${middleware.name}' specifies targetId '${middleware.targetId}' without familyId`,\n      { middleware: middleware.name, targetId: middleware.targetId },\n    );\n  }\n\n  if (middleware.familyId !== undefined && middleware.familyId !== runtimeFamilyId) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_FAMILY_MISMATCH',\n      `Middleware '${middleware.name}' requires family '${middleware.familyId}' but the runtime is configured for family '${runtimeFamilyId}'`,\n      { middleware: middleware.name, middlewareFamilyId: middleware.familyId, runtimeFamilyId },\n    );\n  }\n\n  if (middleware.targetId !== undefined && middleware.targetId !== runtimeTargetId) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_TARGET_MISMATCH',\n      `Middleware '${middleware.name}' requires target '${middleware.targetId}' but the runtime is configured for target '${runtimeTargetId}'`,\n      { middleware: middleware.name, middlewareTargetId: middleware.targetId, runtimeTargetId },\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"runtime.mjs","names":["out: Row[]","sentinel: { reason: unknown }","onAbort: (() => void) | undefined","latencyMs","codecCtx: CodecCallContext"],"sources":["../src/execution/runtime-error.ts","../src/execution/async-iterable-result.ts","../src/execution/race-against-abort.ts","../src/execution/run-with-middleware.ts","../src/execution/runtime-core.ts","../src/execution/runtime-middleware.ts"],"sourcesContent":["export interface RuntimeErrorEnvelope extends Error {\n  readonly code: string;\n  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';\n  readonly severity: 'error';\n  readonly details?: Record<string, unknown>;\n}\n\n/**\n * Stable code emitted by the runtime when an in-flight `execute()`\n * is cancelled via the per-query `AbortSignal`. The envelope's\n * `details.phase` distinguishes where the abort was observed:\n *\n * - `'encode'` — abort fired during `encodeParams` (SQL) or\n *   `resolveValue` (Mongo).\n * - `'decode'` — abort fired during `decodeRow` / `decodeField`.\n * - `'stream'` — abort fired between rows or before any codec call\n *   (already-aborted at entry).\n */\nexport const RUNTIME_ABORTED = 'RUNTIME.ABORTED' as const;\n\n/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */\nexport type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';\n\n/**\n * Type guard for the runtime-error envelope produced by `runtimeError`.\n *\n * Prefer this over duck-typing on `error.code` directly so consumers stay\n * insulated from the envelope's internal shape.\n */\nexport function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {\n  return (\n    error instanceof Error &&\n    'code' in error &&\n    typeof (error as { code?: unknown }).code === 'string' &&\n    'category' in error &&\n    'severity' in error\n  );\n}\n\nexport function runtimeError(\n  code: string,\n  message: string,\n  details?: Record<string, unknown>,\n): RuntimeErrorEnvelope {\n  const error = new Error(message) as RuntimeErrorEnvelope;\n  Object.defineProperty(error, 'name', {\n    value: 'RuntimeError',\n    configurable: true,\n  });\n\n  return Object.assign(error, {\n    code,\n    category: resolveCategory(code),\n    severity: 'error' as const,\n    message,\n    details,\n  });\n}\n\nfunction resolveCategory(code: string): RuntimeErrorEnvelope['category'] {\n  const prefix = code.split('.')[0] ?? 'RUNTIME';\n  switch (prefix) {\n    case 'PLAN':\n    case 'CONTRACT':\n    case 'LINT':\n    case 'BUDGET':\n      return prefix;\n    default:\n      return 'RUNTIME';\n  }\n}\n\n/**\n * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the\n * abort was observed (encode / decode / stream); cause carries `signal.reason`\n * verbatim from the platform — native abort produces a `DOMException`,\n * explicit `controller.abort(reason)` produces whatever the caller passed.\n * No synthesis happens here.\n */\nexport function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope {\n  const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });\n  return Object.assign(envelope, { cause });\n}\n","import { runtimeError } from './runtime-error';\n\nexport class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {\n  private readonly generator: AsyncGenerator<Row, void, unknown>;\n  private consumed = false;\n  private consumedBy: 'bufferedArray' | 'iterator' | undefined;\n  private bufferedArrayPromise: Promise<Row[]> | undefined;\n\n  constructor(generator: AsyncGenerator<Row, void, unknown>) {\n    this.generator = generator;\n  }\n\n  [Symbol.asyncIterator](): AsyncIterator<Row> {\n    if (this.consumed) {\n      throw runtimeError(\n        'RUNTIME.ITERATOR_CONSUMED',\n        `AsyncIterableResult iterator has already been consumed via ${this.consumedBy === 'bufferedArray' ? 'toArray()/then()' : 'for-await loop'}. Each AsyncIterableResult can only be iterated once.`,\n        {\n          consumedBy: this.consumedBy,\n          suggestion:\n            this.consumedBy === 'bufferedArray'\n              ? 'If you need to iterate multiple times, store the results from toArray() in a variable and reuse that.'\n              : 'If you need to iterate multiple times, use toArray() to collect all results first.',\n        },\n      );\n    }\n    this.consumed = true;\n    this.consumedBy = 'iterator';\n    return this.generator;\n  }\n\n  toArray(): Promise<Row[]> {\n    if (this.consumedBy === 'iterator') {\n      return Promise.reject(\n        runtimeError(\n          'RUNTIME.ITERATOR_CONSUMED',\n          'AsyncIterableResult iterator has already been consumed via for-await loop. Each AsyncIterableResult can only be iterated once.',\n          {\n            consumedBy: this.consumedBy,\n            suggestion:\n              'The iterator was already consumed by a for-await loop. Use toArray() or await the result before iterating.',\n          },\n        ),\n      );\n    }\n\n    if (this.bufferedArrayPromise) {\n      return this.bufferedArrayPromise;\n    }\n\n    this.consumed = true;\n    this.consumedBy = 'bufferedArray';\n    this.bufferedArrayPromise = (async () => {\n      const out: Row[] = [];\n      for await (const item of this.generator) {\n        out.push(item);\n      }\n      return out;\n    })();\n    return this.bufferedArrayPromise;\n  }\n\n  async first(): Promise<Row | null> {\n    const rows = await this.toArray();\n    return rows[0] ?? null;\n  }\n\n  async firstOrThrow(): Promise<Row> {\n    const row = await this.first();\n    if (row === null)\n      throw runtimeError(\n        'RUNTIME.NO_ROWS',\n        'Expected at least one row, but none were returned',\n        {},\n      );\n    return row;\n  }\n\n  // biome-ignore lint/suspicious/noThenProperty: PromiseLike implementation is intentional for await support.\n  then<TResult1 = Row[], TResult2 = never>(\n    onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null,\n  ): PromiseLike<TResult1 | TResult2> {\n    return this.toArray().then(onfulfilled, onrejected);\n  }\n}\n","import type { CodecCallContext } from '../shared/codec-types';\nimport type { RuntimeAbortedPhase } from './runtime-error';\nimport { runtimeAborted } from './runtime-error';\n\n/**\n * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied\n * codec-call context is already aborted at the precheck site. Centralises\n * the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that\n * every codec dispatch site repeats.\n */\nexport function checkAborted(ctx: CodecCallContext, phase: RuntimeAbortedPhase): void {\n  if (ctx.signal?.aborted) {\n    throw runtimeAborted(phase, ctx.signal.reason);\n  }\n}\n\n/**\n * Race a per-cell `Promise.all` (or any other in-flight work promise) against\n * the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly\n * even when codec bodies ignore the signal. In-flight bodies that ignore the\n * signal are abandoned and run to completion in the background — the\n * cooperative-cancellation contract documented in ADR 204.\n *\n * Call sites still SHOULD pre-check `signal.aborted` and short-circuit with\n * a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —\n * that path is the canonical \"aborted at entry\" surface and avoids\n * scheduling the work promise. As a defensive belt-and-braces, this helper\n * also handles the already-aborted case internally: `AbortSignal` does not\n * replay past abort events to listeners registered after the abort, so we\n * inspect `signal.aborted` synchronously and reject with the sentinel\n * before installing the listener. The rejection is still attributed to the\n * abort path via the sentinel-identity check.\n *\n * Distinguishing the rejection source is load-bearing for AC-ERR4\n * (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).\n * The semantically equivalent `abortable(signal)` helper in\n * `@prisma-next/utils` rejects with `signal.reason ?? new DOMException(...)`,\n * which is not stably distinguishable from a codec-thrown error by identity\n * alone (a fresh fallback DOMException is allocated per call). We instead\n * track abort attribution with a unique sentinel: only the `onAbort` listener\n * installed here ever rejects with the sentinel, so an `error === sentinel`\n * identity check after the race is unambiguous.\n *\n * Lives in `framework-components` (rather than the SQL family, where it\n * originated in m2) so every family runtime that needs cooperative\n * cancellation around a codec-dispatch `Promise.all` (SQL encode + decode\n * today, Mongo encode in m3) shares the same attribution logic.\n */\nexport async function raceAgainstAbort<T>(\n  work: Promise<T>,\n  signal: AbortSignal | undefined,\n  phase: RuntimeAbortedPhase,\n): Promise<T> {\n  if (signal === undefined) {\n    return await work;\n  }\n  const sentinel: { reason: unknown } = { reason: undefined };\n  let onAbort: (() => void) | undefined;\n\n  const abortPromise = new Promise<never>((_, reject) => {\n    if (signal.aborted) {\n      sentinel.reason = signal.reason;\n      reject(sentinel);\n      return;\n    }\n    onAbort = () => {\n      sentinel.reason = signal.reason;\n      reject(sentinel);\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n\n  try {\n    return await Promise.race([work, abortPromise]);\n  } catch (error) {\n    if (error === sentinel) {\n      throw runtimeAborted(phase, sentinel.reason);\n    }\n    throw error;\n  } finally {\n    if (onAbort) {\n      signal.removeEventListener('abort', onAbort);\n    }\n  }\n}\n","import { AsyncIterableResult } from './async-iterable-result';\nimport type { ExecutionPlan } from './query-plan';\nimport type { RuntimeMiddleware, RuntimeMiddlewareContext } from './runtime-middleware';\n\n/**\n * Drives a single execution of `runDriver()` through the middleware lifecycle.\n *\n * Lifecycle, in order:\n *  1. For each middleware in registration order: `beforeExecute(exec, ctx)`.\n *  2. For each row yielded by `runDriver()`: for each middleware in registration\n *     order: `onRow(row, exec, ctx)`; then yield the row to the consumer.\n *  3. On successful completion: for each middleware in registration order:\n *     `afterExecute(exec, { rowCount, latencyMs, completed: true }, ctx)`.\n *  4. On any error thrown by the driver loop: for each middleware in\n *     registration order: `afterExecute(exec, { rowCount, latencyMs,\n *     completed: false }, ctx)`. Errors thrown by `afterExecute` during the\n *     error path are swallowed so they do not mask the original driver error.\n *     The original error is then rethrown.\n *\n * This helper is the single canonical implementation of the middleware\n * orchestration loop; family runtimes should not reimplement it.\n */\nexport function runWithMiddleware<TExec extends ExecutionPlan, Row>(\n  exec: TExec,\n  middleware: ReadonlyArray<RuntimeMiddleware<TExec>>,\n  ctx: RuntimeMiddlewareContext,\n  runDriver: () => AsyncIterable<Row>,\n): AsyncIterableResult<Row> {\n  const iterator = async function* (): AsyncGenerator<Row, void, unknown> {\n    const startedAt = Date.now();\n    let rowCount = 0;\n    let completed = false;\n\n    try {\n      for (const mw of middleware) {\n        if (mw.beforeExecute) {\n          await mw.beforeExecute(exec, ctx);\n        }\n      }\n\n      for await (const row of runDriver()) {\n        for (const mw of middleware) {\n          if (mw.onRow) {\n            await mw.onRow(row as Record<string, unknown>, exec, ctx);\n          }\n        }\n        rowCount++;\n        yield row;\n      }\n\n      completed = true;\n    } catch (error) {\n      const latencyMs = Date.now() - startedAt;\n      for (const mw of middleware) {\n        if (mw.afterExecute) {\n          try {\n            await mw.afterExecute(exec, { rowCount, latencyMs, completed }, ctx);\n          } catch {\n            // Swallow afterExecute errors during the error path so they do not\n            // mask the original driver error.\n          }\n        }\n      }\n\n      throw error;\n    }\n\n    const latencyMs = Date.now() - startedAt;\n    for (const mw of middleware) {\n      if (mw.afterExecute) {\n        await mw.afterExecute(exec, { rowCount, latencyMs, completed }, ctx);\n      }\n    }\n  };\n\n  return new AsyncIterableResult(iterator());\n}\n","import type { CodecCallContext } from '../shared/codec-types';\nimport { AsyncIterableResult } from './async-iterable-result';\nimport type { ExecutionPlan, QueryPlan } from './query-plan';\nimport { checkAborted } from './race-against-abort';\nimport { runWithMiddleware } from './run-with-middleware';\nimport type {\n  RuntimeExecuteOptions,\n  RuntimeExecutor,\n  RuntimeMiddleware,\n  RuntimeMiddlewareContext,\n} from './runtime-middleware';\n\n/**\n * Constructor options shared by every concrete `RuntimeCore` subclass.\n *\n * Family runtimes typically build the middleware list and the\n * `RuntimeMiddlewareContext` themselves (running compatibility checks,\n * narrowing the context's `contract` field, etc.) before calling `super`.\n */\nexport interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {\n  readonly middleware: ReadonlyArray<TMiddleware>;\n  readonly ctx: RuntimeMiddlewareContext;\n}\n\n/**\n * Family-agnostic abstract runtime base.\n *\n * Defines the entire `execute(plan)` template in one place:\n *\n * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides\n *    this to run its `beforeCompile` middleware-hook chain.\n * 2. `lower(plan)` — abstract. Each family produces its `*ExecutionPlan`\n *    (SQL via `lowerSqlPlan`, Mongo via `adapter.lower`).\n * 3. `runWithMiddleware(exec, this.middleware, this.ctx,\n *    () => runDriver(exec))` — concrete; lifts the middleware lifecycle\n *    out of the family runtimes into the canonical helper.\n *\n * Concrete subclasses must implement `lower`, `runDriver`, and `close`.\n *\n * The class is generic over:\n * - `TPlan` — the family's pre-lowering plan type.\n * - `TExec` — the family's post-lowering (executable) plan type.\n * - `TMiddleware` — the family's middleware type. Constrained to\n *   `RuntimeMiddleware<TExec>` because `runWithMiddleware` invokes the\n *   `beforeExecute` / `onRow` / `afterExecute` hooks with the lowered\n *   `TExec`. (The spec/plan wording \"RuntimeMiddleware<TPlan>\" is\n *   tightened to `<TExec>` here so the helper call typechecks; the\n *   intent is unchanged — middleware sees the post-lowering plan.)\n */\nexport abstract class RuntimeCore<\n  TPlan extends QueryPlan,\n  TExec extends ExecutionPlan,\n  TMiddleware extends RuntimeMiddleware<TExec>,\n> implements RuntimeExecutor<TPlan>\n{\n  protected readonly middleware: ReadonlyArray<TMiddleware>;\n  protected readonly ctx: RuntimeMiddlewareContext;\n\n  constructor(options: RuntimeCoreOptions<TMiddleware>) {\n    this.middleware = options.middleware;\n    this.ctx = options.ctx;\n  }\n\n  /**\n   * Pre-lowering hook for plan rewriting. Defaults to identity. Subclasses\n   * may override to run a `beforeCompile` middleware chain (SQL does this\n   * to support typed AST rewrites — see `before-compile-chain.ts`).\n   */\n  protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan> {\n    return plan;\n  }\n\n  /**\n   * Lower a pre-lowering `TPlan` into the family's executable `TExec`.\n   * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo\n   * produces `{ command, ... }`.\n   *\n   * `ctx` carries per-query cancellation (and any future fields on\n   * `CodecCallContext`); concrete subclasses forward it to the\n   * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,\n   * Mongo's `resolveValue` in m3). The runtime allocates one ctx per\n   * `execute()` call and threads the same reference everywhere; the\n   * `signal` field inside may be `undefined`, but the ctx object itself\n   * is always present.\n   */\n  protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;\n\n  /**\n   * Drive the underlying transport for a lowered `TExec`. Yields raw rows\n   * directly from the driver as `Record<string, unknown>`; codec decoding\n   * (if any) is the subclass's responsibility, applied by wrapping\n   * `execute()` rather than living inside this hook.\n   *\n   * The `Row` type parameter on `execute()` is satisfied by the caller via\n   * the plan's phantom `_row`; the runtime treats rows as opaque records\n   * here and trusts the caller's row typing.\n   */\n  protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;\n\n  abstract close(): Promise<void>;\n\n  execute<Row>(\n    plan: TPlan & { readonly _row?: Row },\n    options?: RuntimeExecuteOptions,\n  ): AsyncIterableResult<Row> {\n    const self = this;\n    const signal = options?.signal;\n    // One ctx per execute() call. The ctx object is always allocated; the\n    // `signal` field is only included when a signal was supplied (required\n    // under exactOptionalPropertyTypes — `{ signal: undefined }` would not\n    // satisfy `signal?: AbortSignal`).\n    const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };\n\n    async function* generator(): AsyncGenerator<Row, void, unknown> {\n      // Pre-check the signal at entry so an already-aborted caller observes\n      // RUNTIME.ABORTED on the first `next()` without any work being done.\n      checkAborted(codecCtx, 'stream');\n\n      const compiled = await self.runBeforeCompile(plan);\n      const exec = await self.lower(compiled, codecCtx);\n      // The driver yields raw `Record<string, unknown>`; we cast to `Row` here.\n      // The Row contract is enforced by the caller via `plan._row`.\n      yield* runWithMiddleware<TExec, Row>(\n        exec,\n        self.middleware,\n        self.ctx,\n        () => self.runDriver(exec) as AsyncIterable<Row>,\n      );\n    }\n\n    return new AsyncIterableResult(generator());\n  }\n}\n","import type { AsyncIterableResult } from './async-iterable-result';\nimport type { QueryPlan } from './query-plan';\nimport { runtimeError } from './runtime-error';\n\nexport interface RuntimeLog {\n  info(event: unknown): void;\n  warn(event: unknown): void;\n  error(event: unknown): void;\n  debug?(event: unknown): void;\n}\n\nexport interface RuntimeMiddlewareContext {\n  readonly contract: unknown;\n  readonly mode: 'strict' | 'permissive';\n  readonly now: () => number;\n  readonly log: RuntimeLog;\n}\n\nexport interface AfterExecuteResult {\n  readonly rowCount: number;\n  readonly latencyMs: number;\n  readonly completed: boolean;\n}\n\n/**\n * Family-agnostic middleware SPI parameterized over the plan marker.\n *\n * `TPlan` defaults to the framework `QueryPlan` marker so a generic\n * middleware (e.g. cross-family telemetry) can be authored without\n * naming a family. Family-specific middleware (`SqlMiddleware`,\n * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.\n */\nexport interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {\n  readonly name: string;\n  readonly familyId?: string;\n  readonly targetId?: string;\n  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;\n  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;\n  afterExecute?(\n    plan: TPlan,\n    result: AfterExecuteResult,\n    ctx: RuntimeMiddlewareContext,\n  ): Promise<void>;\n}\n\n/**\n * Optional per-`execute` options accepted by every family runtime.\n *\n * `signal` is the per-query cancellation signal. The runtime threads the\n * signal through to every codec call for the query and uses it to short-\n * circuit the row stream with `RUNTIME.ABORTED` when the caller aborts.\n * Omitting the option (or passing `undefined`) preserves today's behavior\n * bit-for-bit.\n */\nexport interface RuntimeExecuteOptions {\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Cross-family SPI for any runtime that can execute plans and be shut down.\n * Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,\n * Mongo structurally (due to its phantom Row parameter using a unique symbol).\n *\n * The `_row` intersection on `execute` connects the `Row` type parameter to the\n * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.\n */\nexport interface RuntimeExecutor<TPlan extends QueryPlan> {\n  execute<Row>(\n    plan: TPlan & { readonly _row?: Row },\n    options?: RuntimeExecuteOptions,\n  ): AsyncIterableResult<Row>;\n  close(): Promise<void>;\n}\n\nexport function checkMiddlewareCompatibility(\n  middleware: RuntimeMiddleware,\n  runtimeFamilyId: string,\n  runtimeTargetId: string,\n): void {\n  if (middleware.targetId !== undefined && middleware.familyId === undefined) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_INCOMPATIBLE',\n      `Middleware '${middleware.name}' specifies targetId '${middleware.targetId}' without familyId`,\n      { middleware: middleware.name, targetId: middleware.targetId },\n    );\n  }\n\n  if (middleware.familyId !== undefined && middleware.familyId !== runtimeFamilyId) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_FAMILY_MISMATCH',\n      `Middleware '${middleware.name}' requires family '${middleware.familyId}' but the runtime is configured for family '${runtimeFamilyId}'`,\n      { middleware: middleware.name, middlewareFamilyId: middleware.familyId, runtimeFamilyId },\n    );\n  }\n\n  if (middleware.targetId !== undefined && middleware.targetId !== runtimeTargetId) {\n    throw runtimeError(\n      'RUNTIME.MIDDLEWARE_TARGET_MISMATCH',\n      `Middleware '${middleware.name}' requires target '${middleware.targetId}' but the runtime is configured for target '${runtimeTargetId}'`,\n      { middleware: middleware.name, middlewareTargetId: middleware.targetId, runtimeTargetId },\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/{types-import-spec-C4sc7wbb.d.mts → types-import-spec-D-O6GotH.d.mts}

@@ -1,4 +1,4 @@
-//#region src/types-import-spec.d.ts
+//#region src/shared/types-import-spec.d.ts
 /**
  * Specifies how to import TypeScript types from a package.
  * Used in extension pack manifests to declare codec and operation type imports.
@@ -10,4 +10,4 @@ interface TypesImportSpec {
 }
 //#endregion
 export { TypesImportSpec as t };
-//# sourceMappingURL=types-import-spec-C4sc7wbb.d.mts.map
+//# sourceMappingURL=types-import-spec-D-O6GotH.d.mts.map

package/dist/types-import-spec-D-O6GotH.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-import-spec-D-O6GotH.d.mts","names":[],"sources":["../src/shared/types-import-spec.ts"],"sourcesContent":[],"mappings":";;AAIA;;;UAAiB,eAAA"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.5.0-dev.27",
+  "version": "0.5.0-dev.29",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.27",
-    "@prisma-next/operations": "0.5.0-dev.27",
-    "@prisma-next/utils": "0.5.0-dev.27"
+    "@prisma-next/contract": "0.5.0-dev.29",
+    "@prisma-next/operations": "0.5.0-dev.29",
+    "@prisma-next/utils": "0.5.0-dev.29"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
@@ -27,6 +27,7 @@
     "./control": "./dist/control.mjs",
     "./emission": "./dist/emission.mjs",
     "./execution": "./dist/execution.mjs",
+    "./psl-ast": "./dist/psl-ast.mjs",
     "./runtime": "./dist/runtime.mjs",
     "./package.json": "./package.json"
   },

package/src/control/control-capabilities.ts

@@ -0,0 +1,71 @@
+import type { ControlTargetDescriptor } from './control-descriptors';
+import type { ControlFamilyInstance } from './control-instances';
+import type { MigrationPlanOperation, TargetMigrationsCapability } from './control-migration-types';
+import type { OperationPreview } from './control-operation-preview';
+import type { CoreSchemaView } from './control-schema-view';
+import type { PslDocumentAst } from './psl-ast';
+
+export interface MigratableTargetDescriptor<
+  TFamilyId extends string,
+  TTargetId extends string,
+  TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<
+    TFamilyId,
+    unknown
+  >,
+> extends ControlTargetDescriptor<TFamilyId, TTargetId> {
+  readonly migrations: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
+}
+
+export function hasMigrations<TFamilyId extends string, TTargetId extends string>(
+  target: ControlTargetDescriptor<TFamilyId, TTargetId>,
+): target is MigratableTargetDescriptor<TFamilyId, TTargetId> {
+  return 'migrations' in target && !!(target as Record<string, unknown>)['migrations'];
+}
+
+export interface SchemaViewCapable<TSchemaIR = unknown> {
+  toSchemaView(schema: TSchemaIR): CoreSchemaView;
+}
+
+export function hasSchemaView<TFamilyId extends string, TSchemaIR>(
+  instance: ControlFamilyInstance<TFamilyId, TSchemaIR>,
+): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & SchemaViewCapable<TSchemaIR> {
+  return (
+    'toSchemaView' in instance &&
+    typeof (instance as Record<string, unknown>)['toSchemaView'] === 'function'
+  );
+}
+
+/**
+ * Capability declaring that a family can infer a PSL contract AST from its
+ * opaque introspected schema IR. Consumed by `prisma-next contract infer`.
+ */
+export interface PslContractInferCapable<TSchemaIR = unknown> {
+  inferPslContract(schemaIR: TSchemaIR): PslDocumentAst;
+}
+
+export function hasPslContractInfer<TFamilyId extends string, TSchemaIR>(
+  instance: ControlFamilyInstance<TFamilyId, TSchemaIR>,
+): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & PslContractInferCapable<TSchemaIR> {
+  return (
+    'inferPslContract' in instance &&
+    typeof (instance as Record<string, unknown>)['inferPslContract'] === 'function'
+  );
+}
+
+/**
+ * Capability declaring that a family can render a textual preview of migration
+ * operations for the CLI's "DDL preview" output. SQL families emit
+ * `language: 'sql'` statements; Mongo families emit `language: 'mongodb-shell'`.
+ */
+export interface OperationPreviewCapable {
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
+}
+
+export function hasOperationPreview<TFamilyId extends string, TSchemaIR>(
+  instance: ControlFamilyInstance<TFamilyId, TSchemaIR>,
+): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & OperationPreviewCapable {
+  return (
+    'toOperationPreview' in instance &&
+    typeof (instance as Record<string, unknown>)['toOperationPreview'] === 'function'
+  );
+}

package/src/{control-descriptors.ts → control/control-descriptors.ts}

@@ -1,3 +1,10 @@
+import type {
+  AdapterDescriptor,
+  DriverDescriptor,
+  ExtensionDescriptor,
+  FamilyDescriptor,
+  TargetDescriptor,
+} from '../shared/framework-components';
 import type {
   ControlAdapterInstance,
   ControlDriverInstance,
@@ -7,13 +14,6 @@ import type {
 } from './control-instances';
 import type { ControlStack } from './control-stack';
 import type { EmissionSpi } from './emission-types';
-import type {
-  AdapterDescriptor,
-  DriverDescriptor,
-  ExtensionDescriptor,
-  FamilyDescriptor,
-  TargetDescriptor,
-} from './framework-components';
 
 export interface ControlFamilyDescriptor<
   TFamilyId extends string,