@prisma-next/framework-components 0.5.0-dev.7 → 0.5.0-dev.9

package/README.md

@@ -10,19 +10,32 @@ Framework component types, authoring logic, control stack assembly, and emission
 
 - **Component types** (`./components`): Base descriptor and instance interfaces for framework components (family, target, adapter, driver, extension), pack refs, and type renderer system
 - **Authoring types** (`./authoring`): Declarative authoring contribution types, template resolution, and validation for type constructors and field presets
+- **Codec base interface** (`./codec`): The cross-family `Codec` base type that SQL `Codec` and Mongo `MongoCodec` extend
 - **Control stack** (`./control`): Assembly functions that combine component descriptors into a unified `ControlStack` with derived state (codec imports, renderers, authoring contributions)
 - **Emission SPI** (`./emission`): Types for the emission pipeline — `TargetFamilyHook`, `ValidationContext`, `GenerateContractTypesOptions`, `TypeRenderEntry`, `TypeRenderer`, `ParameterizedCodecDescriptor`, and related types
 - **Execution types** (`./execution`): Execution-plane stack and instance interfaces
+- **Runtime SPI** (`./runtime`): Abstract `RuntimeCore<TPlan, TExec, TMiddleware>` base class, `RuntimeMiddleware` interface, and the canonical `runWithMiddleware` orchestrator helper. Family runtimes (`@prisma-next/sql-runtime`, `@prisma-next/mongo-runtime`) extend `RuntimeCore` directly per [ADR 204](../../../../../docs/architecture%20docs/adrs/ADR%20204%20-%20Single-tier%20runtime.md).
 
 ## Subpath exports
 
 ```typescript
 import { ComponentMetadata, FamilyDescriptor, normalizeRenderer } from '@prisma-next/framework-components/components';
 import { AuthoringContributions, instantiateAuthoringTypeConstructor } from '@prisma-next/framework-components/authoring';
+import type { Codec } from '@prisma-next/framework-components/codec';
 import { createControlStack, ControlStack } from '@prisma-next/framework-components/control';
 import type { EmissionSpi } from '@prisma-next/framework-components/emission';
+import { RuntimeCore, runWithMiddleware, type RuntimeMiddleware } from '@prisma-next/framework-components/runtime';
 ```
 
+## `Codec` interface
+
+The base `Codec` interface lands on the seam between **query-time** methods (per-row, IO-relevant) and **build-time** methods (per-contract-load):
+
+- Query-time: `encode(value): Promise<TWire>` and `decode(wire): Promise<TInput>` are required and **Promise-returning at the public boundary**, regardless of whether the codec body is synchronous or asynchronous. Family factories (`codec()` for SQL, `mongoCodec()` for Mongo) accept either sync or async author functions and lift sync ones to Promise-shaped methods, so authors write whichever shape is natural per method without annotations.
+- Build-time: `encodeJson`, `decodeJson`, and the optional `renderOutputType` are **synchronous** so `validateContract` and client construction stay synchronous.
+
+There is no `runtime` / `kind` / equivalent async marker on the interface and no `TRuntime` generic. The runtime always awaits the query-time methods. See [ADR 204 — Single-Path Async Codec Runtime](../../../../../docs/architecture%20docs/adrs/ADR%20204%20-%20Single-Path%20Async%20Codec%20Runtime.md) for the full design.
+
 ## Why SPI types live here (dependency inversion)
 
 This package sits in the **core** layer — below the tooling layer where family-specific emitters and control implementations live. SPI interfaces like `EmissionSpi` define the contract between framework orchestration code (control-plane emission, CLI) and family-specific implementations (SQL emitter, Mongo emitter).

package/dist/codec-types-DQ1Agjom.d.mts

@@ -0,0 +1,58 @@
+import { JsonValue } from "@prisma-next/contract/types";
+
+//#region src/codec-types.d.ts
+type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
+/**
+ * A codec is the contract between an application value and its on-wire and
+ * on-contract-disk representations.
+ *
+ * The author's mental model is two JS-side types — `TInput` (the
+ * application JS type) and `TWire` (the database driver wire format) —
+ * plus `JsonValue` for build-time contract artifacts. The codec translates
+ * `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue`
+ * during contract emission and loading.
+ *
+ * Three representations participate:
+ * - **Input** (`TInput`): the JS type at the application boundary.
+ * - **Wire** (`TWire`): the format exchanged with the database driver.
+ * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.
+ *
+ * Codec methods split into two groups:
+ *
+ * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the
+ *   IO boundary; they are required and Promise-returning. The per-family
+ *   codec factory accepts sync or async author functions and lifts sync
+ *   ones to Promise-shaped methods automatically.
+ * - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)
+ *   run when the contract is serialized, loaded, or when client types are
+ *   emitted. They stay synchronous so contract validation and client
+ *   construction are synchronous.
+ *
+ * Target-family codec interfaces extend this base with target-shaped
+ * metadata.
+ */
+interface Codec<Id extends string = string, TTraits extends readonly CodecTrait[] = readonly CodecTrait[], TWire = unknown, TInput = unknown> {
+  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
+  readonly id: Id;
+  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
+  readonly targetTypes: readonly string[];
+  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
+  readonly traits?: TTraits;
+  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. */
+  encode(value: TInput): Promise<TWire>;
+  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. */
+  decode(wire: TWire): Promise<TInput>;
+  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
+  encodeJson(value: TInput): JsonValue;
+  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
+  decodeJson(json: JsonValue): TInput;
+  /** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */
+  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
+}
+interface CodecLookup {
+  get(id: string): Codec | undefined;
+}
+declare const emptyCodecLookup: CodecLookup;
+//#endregion
+export { emptyCodecLookup as i, CodecLookup as n, CodecTrait as r, Codec as t };
+//# sourceMappingURL=codec-types-DQ1Agjom.d.mts.map

package/dist/codec-types-DQ1Agjom.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-types-DQ1Agjom.d.mts","names":[],"sources":["../src/codec-types.ts"],"sourcesContent":[],"mappings":";;;KAEY,UAAA;;AAAZ;AA+BA;;;;;;;;;;;;;;;;;AAwBA;AAIA;;;;;;;;;UA5BiB,2DAEU,wBAAwB;;eAKpC;;;;oBAIK;;gBAEJ,SAAS,QAAQ;;eAElB,QAAQ,QAAQ;;oBAEX,SAAS;;mBAEV,YAAY;;gCAEC;;UAGf,WAAA;mBACE;;cAGN,kBAAkB"}

package/dist/codec.d.mts

@@ -1,2 +1,2 @@
-import { i as emptyCodecLookup, n as CodecLookup, r as CodecTrait, t as Codec } from "./codec-types-B58nCJiu.mjs";
+import { i as emptyCodecLookup, n as CodecLookup, r as CodecTrait, t as Codec } from "./codec-types-DQ1Agjom.mjs";
 export { type Codec, type CodecLookup, type CodecTrait, emptyCodecLookup };

package/dist/codec.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"codec.mjs","names":["emptyCodecLookup: CodecLookup"],"sources":["../src/codec-types.ts"],"sourcesContent":["import type { JsonValue } from '@prisma-next/contract/types';\n\nexport type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';\n\n/**\n * Base codec interface for all target families.\n *\n * A codec maps between three representations of a value:\n * - **JS** (`TJs`): the JavaScript type used in application code\n * - **Wire** (`TWire`): the format sent to/from the database driver\n * - **JSON** (`JsonValue`): the JSON-safe form stored in contract artifacts\n *\n * Family-specific codec interfaces (SQL `Codec`, Mongo `MongoCodec`) extend\n * this base to add family-specific metadata.\n */\nexport interface Codec<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TJs = unknown,\n> {\n  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */\n  readonly id: Id;\n  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */\n  readonly targetTypes: readonly string[];\n  /** Semantic traits for operator gating (e.g. equality, order, numeric). */\n  readonly traits?: TTraits;\n  /** Converts a JS value to the wire format expected by the database driver. Optional when the driver accepts the JS type directly. */\n  encode?(value: TJs): TWire;\n  /** Converts a wire value from the database driver into the JS type. */\n  decode(wire: TWire): TJs;\n  /** Converts a JS value to a JSON-safe representation for contract serialization. Called during contract emission. */\n  encodeJson(value: TJs): JsonValue;\n  /** Converts a JSON representation back to the JS type. Called during contract loading via `validateContract`. */\n  decodeJson(json: JsonValue): TJs;\n  /** Produces the TypeScript output type expression for a field given its `typeParams`. Used during contract.d.ts emission. */\n  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;\n}\n\nexport interface CodecLookup {\n  get(id: string): Codec | undefined;\n}\n\nexport const emptyCodecLookup: CodecLookup = {\n  get: () => undefined,\n};\n"],"mappings":";AA2CA,MAAaA,mBAAgC,EAC3C,WAAW,QACZ"}
+{"version":3,"file":"codec.mjs","names":["emptyCodecLookup: CodecLookup"],"sources":["../src/codec-types.ts"],"sourcesContent":["import type { JsonValue } from '@prisma-next/contract/types';\n\nexport type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';\n\n/**\n * A codec is the contract between an application value and its on-wire and\n * on-contract-disk representations.\n *\n * The author's mental model is two JS-side types — `TInput` (the\n * application JS type) and `TWire` (the database driver wire format) —\n * plus `JsonValue` for build-time contract artifacts. The codec translates\n * `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue`\n * during contract emission and loading.\n *\n * Three representations participate:\n * - **Input** (`TInput`): the JS type at the application boundary.\n * - **Wire** (`TWire`): the format exchanged with the database driver.\n * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.\n *\n * Codec methods split into two groups:\n *\n * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the\n *   IO boundary; they are required and Promise-returning. The per-family\n *   codec factory accepts sync or async author functions and lifts sync\n *   ones to Promise-shaped methods automatically.\n * - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)\n *   run when the contract is serialized, loaded, or when client types are\n *   emitted. They stay synchronous so contract validation and client\n *   construction are synchronous.\n *\n * Target-family codec interfaces extend this base with target-shaped\n * metadata.\n */\nexport interface Codec<\n  Id extends string = string,\n  TTraits extends readonly CodecTrait[] = readonly CodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> {\n  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */\n  readonly id: Id;\n  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */\n  readonly targetTypes: readonly string[];\n  /** Semantic traits for operator gating (e.g. equality, order, numeric). */\n  readonly traits?: TTraits;\n  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. */\n  encode(value: TInput): Promise<TWire>;\n  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. */\n  decode(wire: TWire): Promise<TInput>;\n  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */\n  encodeJson(value: TInput): JsonValue;\n  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */\n  decodeJson(json: JsonValue): TInput;\n  /** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */\n  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;\n}\n\nexport interface CodecLookup {\n  get(id: string): Codec | undefined;\n}\n\nexport const emptyCodecLookup: CodecLookup = {\n  get: () => undefined,\n};\n"],"mappings":";AA6DA,MAAaA,mBAAgC,EAC3C,WAAW,QACZ"}

package/dist/components.d.mts

@@ -1,2 +1,2 @@
-import { S as checkContractComponentRequirements, _ as PackRefBase, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, g as FamilyPackRef, h as FamilyInstance, i as ComponentDescriptor, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, o as ContractComponentRequirementsCheckInput, p as ExtensionPackRef, r as AdapterPackRef, s as ContractComponentRequirementsCheckResult, t as AdapterDescriptor, u as DriverPackRef, v as TargetBoundComponentDescriptor, x as TargetPackRef, y as TargetDescriptor } from "./framework-components-EJXe-pum.mjs";
+import { S as checkContractComponentRequirements, _ as PackRefBase, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, g as FamilyPackRef, h as FamilyInstance, i as ComponentDescriptor, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, o as ContractComponentRequirementsCheckInput, p as ExtensionPackRef, r as AdapterPackRef, s as ContractComponentRequirementsCheckResult, t as AdapterDescriptor, u as DriverPackRef, v as TargetBoundComponentDescriptor, x as TargetPackRef, y as TargetDescriptor } from "./framework-components-DFZMi2h7.mjs";
 export { type AdapterDescriptor, type AdapterInstance, type AdapterPackRef, type ComponentDescriptor, type ComponentMetadata, type ContractComponentRequirementsCheckInput, type ContractComponentRequirementsCheckResult, type DriverDescriptor, type DriverInstance, type DriverPackRef, type ExtensionDescriptor, type ExtensionInstance, type ExtensionPackRef, type FamilyDescriptor, type FamilyInstance, type FamilyPackRef, type PackRefBase, type TargetBoundComponentDescriptor, type TargetDescriptor, type TargetInstance, type TargetPackRef, checkContractComponentRequirements };

package/dist/control.d.mts

@@ -1,6 +1,6 @@
 import { a as AuthoringFieldNamespace, d as AuthoringTypeNamespace, i as AuthoringContributions } from "./framework-authoring-D1-JZ37B.mjs";
-import { n as CodecLookup } from "./codec-types-B58nCJiu.mjs";
-import { A as LoweredDefaultResult, C as ControlMutationDefaultEntry, D as DefaultFunctionLoweringHandler, E as DefaultFunctionLoweringContext, F as SourceSpan, M as MutationDefaultGeneratorDescriptor, N as ParsedDefaultFunctionCall, O as DefaultFunctionRegistry, P as SourceDiagnostic, T as ControlMutationDefaults, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, j as LoweredDefaultValue, k as DefaultFunctionRegistryEntry, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, v as TargetBoundComponentDescriptor, w as ControlMutationDefaultRegistry, y as TargetDescriptor } from "./framework-components-EJXe-pum.mjs";
+import { n as CodecLookup } from "./codec-types-DQ1Agjom.mjs";
+import { A as LoweredDefaultResult, C as ControlMutationDefaultEntry, D as DefaultFunctionLoweringHandler, E as DefaultFunctionLoweringContext, F as SourceSpan, M as MutationDefaultGeneratorDescriptor, N as ParsedDefaultFunctionCall, O as DefaultFunctionRegistry, P as SourceDiagnostic, T as ControlMutationDefaults, a as ComponentMetadata, b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, j as LoweredDefaultValue, k as DefaultFunctionRegistryEntry, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, v as TargetBoundComponentDescriptor, w as ControlMutationDefaultRegistry, y as TargetDescriptor } from "./framework-components-DFZMi2h7.mjs";
 import { t as TypesImportSpec } from "./types-import-spec-C4sc7wbb.mjs";
 import { t as EmissionSpi } from "./emission-types-BPAALJbF.mjs";
 import { Contract, ContractMarkerRecord } from "@prisma-next/contract/types";

package/dist/execution.d.mts

@@ -1,4 +1,4 @@
-import { b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, y as TargetDescriptor } from "./framework-components-EJXe-pum.mjs";
+import { b as TargetInstance, c as DriverDescriptor, d as ExtensionDescriptor, f as ExtensionInstance, h as FamilyInstance, l as DriverInstance, m as FamilyDescriptor, n as AdapterInstance, t as AdapterDescriptor, y as TargetDescriptor } from "./framework-components-DFZMi2h7.mjs";
 
 //#region src/execution-instances.d.ts
 interface RuntimeFamilyInstance<TFamilyId extends string> extends FamilyInstance<TFamilyId> {}

package/dist/{framework-components-EJXe-pum.d.mts → framework-components-DFZMi2h7.d.mts}

@@ -1,5 +1,5 @@
 import { i as AuthoringContributions } from "./framework-authoring-D1-JZ37B.mjs";
-import { t as Codec } from "./codec-types-B58nCJiu.mjs";
+import { t as Codec } from "./codec-types-DQ1Agjom.mjs";
 import { t as TypesImportSpec } from "./types-import-spec-C4sc7wbb.mjs";
 import { ColumnDefault, ExecutionMutationDefaultValue } from "@prisma-next/contract/types";
 
@@ -421,4 +421,4 @@ interface ExtensionInstance<TFamilyId extends string, TTargetId extends string>
 }
 //#endregion
 export { LoweredDefaultResult as A, ControlMutationDefaultEntry as C, DefaultFunctionLoweringHandler as D, DefaultFunctionLoweringContext as E, SourceSpan as F, MutationDefaultGeneratorDescriptor as M, ParsedDefaultFunctionCall as N, DefaultFunctionRegistry as O, SourceDiagnostic as P, checkContractComponentRequirements as S, ControlMutationDefaults as T, PackRefBase as _, ComponentMetadata as a, TargetInstance as b, DriverDescriptor as c, ExtensionDescriptor as d, ExtensionInstance as f, FamilyPackRef as g, FamilyInstance as h, ComponentDescriptor as i, LoweredDefaultValue as j, DefaultFunctionRegistryEntry as k, DriverInstance as l, FamilyDescriptor as m, AdapterInstance as n, ContractComponentRequirementsCheckInput as o, ExtensionPackRef as p, AdapterPackRef as r, ContractComponentRequirementsCheckResult as s, AdapterDescriptor as t, DriverPackRef as u, TargetBoundComponentDescriptor as v, ControlMutationDefaultRegistry as w, TargetPackRef as x, TargetDescriptor as y };
-//# sourceMappingURL=framework-components-EJXe-pum.d.mts.map
+//# sourceMappingURL=framework-components-DFZMi2h7.d.mts.map

package/dist/{framework-components-EJXe-pum.d.mts.map → framework-components-DFZMi2h7.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"framework-components-EJXe-pum.d.mts","names":[],"sources":["../src/mutation-default-types.ts","../src/framework-components.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"framework-components-DFZMi2h7.d.mts","names":[],"sources":["../src/mutation-default-types.ts","../src/framework-components.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/runtime.d.mts

@@ -14,14 +14,54 @@ 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
-interface RuntimeErrorEnvelope extends Error {
-  readonly code: string;
-  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
-  readonly severity: 'error';
-  readonly details?: Record<string, unknown>;
+//#region src/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;
 }
-declare function runtimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeErrorEnvelope;
+/**
+ * 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/runtime-middleware.d.ts
 interface RuntimeLog {
@@ -41,19 +81,21 @@ 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>;
 }
 /**
  * Cross-family SPI for any runtime that can execute plans and be shut down.
@@ -61,11 +103,9 @@ 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>;
@@ -73,5 +113,112 @@ interface RuntimeExecutor<TPlan extends {
 }
 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/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/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, ... }`.
+   */
+  protected abstract lower(plan: TPlan): 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;
+  }): 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>;
+}
+/**
+ * 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 };
 //# 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":"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"}
+{"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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"}

package/dist/runtime.mjs

@@ -1,4 +1,13 @@
 //#region src/runtime-error.ts
+/**
+* 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", {
@@ -71,6 +80,113 @@ var AsyncIterableResult = class {
 	}
 };
 
+//#endregion
+//#region src/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/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) {
+		const self = this;
+		async function* generator() {
+			const compiled = await self.runBeforeCompile(plan);
+			const exec = await self.lower(compiled);
+			yield* runWithMiddleware(exec, self.middleware, self.ctx, () => self.runDriver(exec));
+		}
+		return new AsyncIterableResult(generator());
+	}
+};
+
 //#endregion
 //#region src/runtime-middleware.ts
 function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTargetId) {
@@ -91,5 +207,5 @@ function checkMiddlewareCompatibility(middleware, runtimeFamilyId, runtimeTarget
 }
 
 //#endregion
-export { AsyncIterableResult, checkMiddlewareCompatibility, runtimeError };
+export { AsyncIterableResult, RuntimeCore, checkMiddlewareCompatibility, isRuntimeError, runWithMiddleware, runtimeError };
 //# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":["out: Row[]"],"sources":["../src/runtime-error.ts","../src/async-iterable-result.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\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 type { PlanMeta } from '@prisma-next/contract/types';\nimport type { AsyncIterableResult } from './async-iterable-result';\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\nexport interface RuntimeMiddleware {\n  readonly name: string;\n  readonly familyId?: string;\n  readonly targetId?: string;\n  beforeExecute?(plan: { readonly meta: PlanMeta }, ctx: RuntimeMiddlewareContext): Promise<void>;\n  onRow?(\n    row: Record<string, unknown>,\n    plan: { readonly meta: PlanMeta },\n    ctx: RuntimeMiddlewareContext,\n  ): Promise<void>;\n  afterExecute?(\n    plan: { readonly meta: PlanMeta },\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 `ExecutionPlan<Row>` carries a phantom `_row?: Row`.\n */\nexport interface RuntimeExecutor<TPlan extends { readonly meta: PlanMeta }> {\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":";AAOA,SAAgB,aACd,MACA,SACA,SACsB;CACtB,MAAM,QAAQ,IAAI,MAAM,QAAQ;AAChC,QAAO,eAAe,OAAO,QAAQ;EACnC,OAAO;EACP,cAAc;EACf,CAAC;AAEF,QAAO,OAAO,OAAO,OAAO;EAC1B;EACA,UAAU,gBAAgB,KAAK;EAC/B,UAAU;EACV;EACA;EACD,CAAC;;AAGJ,SAAS,gBAAgB,MAAgD;CACvE,MAAM,SAAS,KAAK,MAAM,IAAI,CAAC,MAAM;AACrC,SAAQ,QAAR;EACE,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,SACH,QAAO;EACT,QACE,QAAO;;;;;;AClCb,IAAa,sBAAb,MAAwF;CACtF,AAAiB;CACjB,AAAQ,WAAW;CACnB,AAAQ;CACR,AAAQ;CAER,YAAY,WAA+C;AACzD,OAAK,YAAY;;CAGnB,CAAC,OAAO,iBAAqC;AAC3C,MAAI,KAAK,SACP,OAAM,aACJ,6BACA,8DAA8D,KAAK,eAAe,kBAAkB,qBAAqB,iBAAiB,wDAC1I;GACE,YAAY,KAAK;GACjB,YACE,KAAK,eAAe,kBAChB,0GACA;GACP,CACF;AAEH,OAAK,WAAW;AAChB,OAAK,aAAa;AAClB,SAAO,KAAK;;CAGd,UAA0B;AACxB,MAAI,KAAK,eAAe,WACtB,QAAO,QAAQ,OACb,aACE,6BACA,kIACA;GACE,YAAY,KAAK;GACjB,YACE;GACH,CACF,CACF;AAGH,MAAI,KAAK,qBACP,QAAO,KAAK;AAGd,OAAK,WAAW;AAChB,OAAK,aAAa;AAClB,OAAK,wBAAwB,YAAY;GACvC,MAAMA,MAAa,EAAE;AACrB,cAAW,MAAM,QAAQ,KAAK,UAC5B,KAAI,KAAK,KAAK;AAEhB,UAAO;MACL;AACJ,SAAO,KAAK;;CAGd,MAAM,QAA6B;AAEjC,UADa,MAAM,KAAK,SAAS,EACrB,MAAM;;CAGpB,MAAM,eAA6B;EACjC,MAAM,MAAM,MAAM,KAAK,OAAO;AAC9B,MAAI,QAAQ,KACV,OAAM,aACJ,mBACA,qDACA,EAAE,CACH;AACH,SAAO;;CAIT,KACE,aACA,YACkC;AAClC,SAAO,KAAK,SAAS,CAAC,KAAK,aAAa,WAAW;;;;;;AC7BvD,SAAgB,6BACd,YACA,iBACA,iBACM;AACN,KAAI,WAAW,aAAa,UAAa,WAAW,aAAa,OAC/D,OAAM,aACJ,mCACA,eAAe,WAAW,KAAK,wBAAwB,WAAW,SAAS,qBAC3E;EAAE,YAAY,WAAW;EAAM,UAAU,WAAW;EAAU,CAC/D;AAGH,KAAI,WAAW,aAAa,UAAa,WAAW,aAAa,gBAC/D,OAAM,aACJ,sCACA,eAAe,WAAW,KAAK,qBAAqB,WAAW,SAAS,8CAA8C,gBAAgB,IACtI;EAAE,YAAY,WAAW;EAAM,oBAAoB,WAAW;EAAU;EAAiB,CAC1F;AAGH,KAAI,WAAW,aAAa,UAAa,WAAW,aAAa,gBAC/D,OAAM,aACJ,sCACA,eAAe,WAAW,KAAK,qBAAqB,WAAW,SAAS,8CAA8C,gBAAgB,IACtI;EAAE,YAAY,WAAW;EAAM,oBAAoB,WAAW;EAAU;EAAiB,CAC1F"}
+{"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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"}

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.5.0-dev.7",
+  "version": "0.5.0-dev.9",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.7",
-    "@prisma-next/operations": "0.5.0-dev.7",
-    "@prisma-next/utils": "0.5.0-dev.7"
+    "@prisma-next/contract": "0.5.0-dev.9",
+    "@prisma-next/operations": "0.5.0-dev.9",
+    "@prisma-next/utils": "0.5.0-dev.9"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/tsconfig": "0.0.0"
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",

package/src/codec-types.ts

@@ -3,21 +3,39 @@ import type { JsonValue } from '@prisma-next/contract/types';
 export type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
 
 /**
- * Base codec interface for all target families.
+ * A codec is the contract between an application value and its on-wire and
+ * on-contract-disk representations.
  *
- * A codec maps between three representations of a value:
- * - **JS** (`TJs`): the JavaScript type used in application code
- * - **Wire** (`TWire`): the format sent to/from the database driver
- * - **JSON** (`JsonValue`): the JSON-safe form stored in contract artifacts
+ * The author's mental model is two JS-side types — `TInput` (the
+ * application JS type) and `TWire` (the database driver wire format) —
+ * plus `JsonValue` for build-time contract artifacts. The codec translates
+ * `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue`
+ * during contract emission and loading.
  *
- * Family-specific codec interfaces (SQL `Codec`, Mongo `MongoCodec`) extend
- * this base to add family-specific metadata.
+ * Three representations participate:
+ * - **Input** (`TInput`): the JS type at the application boundary.
+ * - **Wire** (`TWire`): the format exchanged with the database driver.
+ * - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.
+ *
+ * Codec methods split into two groups:
+ *
+ * - **Query-time** methods (`encode`, `decode`) run per row/parameter at the
+ *   IO boundary; they are required and Promise-returning. The per-family
+ *   codec factory accepts sync or async author functions and lifts sync
+ *   ones to Promise-shaped methods automatically.
+ * - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)
+ *   run when the contract is serialized, loaded, or when client types are
+ *   emitted. They stay synchronous so contract validation and client
+ *   construction are synchronous.
+ *
+ * Target-family codec interfaces extend this base with target-shaped
+ * metadata.
  */
 export interface Codec<
   Id extends string = string,
   TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
   TWire = unknown,
-  TJs = unknown,
+  TInput = unknown,
 > {
   /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
   readonly id: Id;
@@ -25,15 +43,15 @@ export interface Codec<
   readonly targetTypes: readonly string[];
   /** Semantic traits for operator gating (e.g. equality, order, numeric). */
   readonly traits?: TTraits;
-  /** Converts a JS value to the wire format expected by the database driver. Optional when the driver accepts the JS type directly. */
-  encode?(value: TJs): TWire;
-  /** Converts a wire value from the database driver into the JS type. */
-  decode(wire: TWire): TJs;
-  /** Converts a JS value to a JSON-safe representation for contract serialization. Called during contract emission. */
-  encodeJson(value: TJs): JsonValue;
-  /** Converts a JSON representation back to the JS type. Called during contract loading via `validateContract`. */
-  decodeJson(json: JsonValue): TJs;
-  /** Produces the TypeScript output type expression for a field given its `typeParams`. Used during contract.d.ts emission. */
+  /** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. */
+  encode(value: TInput): Promise<TWire>;
+  /** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. */
+  decode(wire: TWire): Promise<TInput>;
+  /** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
+  encodeJson(value: TInput): JsonValue;
+  /** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
+  decodeJson(json: JsonValue): TInput;
+  /** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */
   renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
 }
 

package/src/exports/runtime.ts

@@ -1,6 +1,10 @@
 export { AsyncIterableResult } from '../async-iterable-result';
+export type { ExecutionPlan, QueryPlan, ResultType } from '../query-plan';
+export { runWithMiddleware } from '../run-with-middleware';
+export type { RuntimeCoreOptions } from '../runtime-core';
+export { RuntimeCore } from '../runtime-core';
 export type { RuntimeErrorEnvelope } from '../runtime-error';
-export { runtimeError } from '../runtime-error';
+export { isRuntimeError, runtimeError } from '../runtime-error';
 export type {
   AfterExecuteResult,
   RuntimeExecutor,

package/src/query-plan.ts

@@ -0,0 +1,53 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+
+/**
+ * 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`).
+ */
+export 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).
+ */
+export 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>`.
+ */
+export type ResultType<P> = '_row' extends keyof P
+  ? P extends { readonly _row?: infer R }
+    ? R
+    : never
+  : never;

package/src/run-with-middleware.ts

@@ -0,0 +1,77 @@
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan } from './query-plan';
+import type { RuntimeMiddleware, RuntimeMiddlewareContext } from './runtime-middleware';
+
+/**
+ * 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.
+ */
+export function runWithMiddleware<TExec extends ExecutionPlan, Row>(
+  exec: TExec,
+  middleware: ReadonlyArray<RuntimeMiddleware<TExec>>,
+  ctx: RuntimeMiddlewareContext,
+  runDriver: () => AsyncIterable<Row>,
+): AsyncIterableResult<Row> {
+  const iterator = async function* (): AsyncGenerator<Row, void, unknown> {
+    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 as Record<string, unknown>, exec, ctx);
+          }
+        }
+        rowCount++;
+        yield row;
+      }
+
+      completed = true;
+    } catch (error) {
+      const latencyMs = Date.now() - startedAt;
+      for (const mw of middleware) {
+        if (mw.afterExecute) {
+          try {
+            await mw.afterExecute(exec, { rowCount, latencyMs, completed }, ctx);
+          } catch {
+            // Swallow afterExecute errors during the error path so they do not
+            // mask the original driver error.
+          }
+        }
+      }
+
+      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());
+}

package/src/runtime-core.ts

@@ -0,0 +1,109 @@
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan, QueryPlan } from './query-plan';
+import { runWithMiddleware } from './run-with-middleware';
+import type {
+  RuntimeExecutor,
+  RuntimeMiddleware,
+  RuntimeMiddlewareContext,
+} from './runtime-middleware';
+
+/**
+ * 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`.
+ */
+export 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.)
+ */
+export 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>) {
+    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`).
+   */
+  protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan> {
+    return plan;
+  }
+
+  /**
+   * Lower a pre-lowering `TPlan` into the family's executable `TExec`.
+   * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo
+   * produces `{ command, ... }`.
+   */
+  protected abstract lower(plan: TPlan): 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 }): AsyncIterableResult<Row> {
+    const self = this;
+
+    async function* generator(): AsyncGenerator<Row, void, unknown> {
+      const compiled = await self.runBeforeCompile(plan);
+      const exec = await self.lower(compiled);
+      // The driver yields raw `Record<string, unknown>`; we cast to `Row` here.
+      // The Row contract is enforced by the caller via `plan._row`.
+      yield* runWithMiddleware<TExec, Row>(
+        exec,
+        self.middleware,
+        self.ctx,
+        () => self.runDriver(exec) as AsyncIterable<Row>,
+      );
+    }
+
+    return new AsyncIterableResult(generator());
+  }
+}

package/src/runtime-error.ts

@@ -5,6 +5,22 @@ export interface RuntimeErrorEnvelope extends 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.
+ */
+export function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as { code?: unknown }).code === 'string' &&
+    'category' in error &&
+    'severity' in error
+  );
+}
+
 export function runtimeError(
   code: string,
   message: string,

package/src/runtime-middleware.ts

@@ -1,5 +1,5 @@
-import type { PlanMeta } from '@prisma-next/contract/types';
 import type { AsyncIterableResult } from './async-iterable-result';
+import type { QueryPlan } from './query-plan';
 import { runtimeError } from './runtime-error';
 
 export interface RuntimeLog {
@@ -22,18 +22,22 @@ export interface AfterExecuteResult {
   readonly completed: boolean;
 }
 
-export 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.
+ */
+export 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>;
+  beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
   afterExecute?(
-    plan: { readonly meta: PlanMeta },
+    plan: TPlan,
     result: AfterExecuteResult,
     ctx: RuntimeMiddlewareContext,
   ): Promise<void>;
@@ -45,9 +49,9 @@ export 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`.
  */
-export interface RuntimeExecutor<TPlan extends { readonly meta: PlanMeta }> {
+export interface RuntimeExecutor<TPlan extends QueryPlan> {
   execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row>;
   close(): Promise<void>;
 }

package/dist/codec-types-B58nCJiu.d.mts

@@ -1,40 +0,0 @@
-import { JsonValue } from "@prisma-next/contract/types";
-
-//#region src/codec-types.d.ts
-type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
-/**
- * Base codec interface for all target families.
- *
- * A codec maps between three representations of a value:
- * - **JS** (`TJs`): the JavaScript type used in application code
- * - **Wire** (`TWire`): the format sent to/from the database driver
- * - **JSON** (`JsonValue`): the JSON-safe form stored in contract artifacts
- *
- * Family-specific codec interfaces (SQL `Codec`, Mongo `MongoCodec`) extend
- * this base to add family-specific metadata.
- */
-interface Codec<Id extends string = string, TTraits extends readonly CodecTrait[] = readonly CodecTrait[], TWire = unknown, TJs = unknown> {
-  /** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
-  readonly id: Id;
-  /** Database-native type names this codec handles (e.g. `['timestamptz']`). */
-  readonly targetTypes: readonly string[];
-  /** Semantic traits for operator gating (e.g. equality, order, numeric). */
-  readonly traits?: TTraits;
-  /** Converts a JS value to the wire format expected by the database driver. Optional when the driver accepts the JS type directly. */
-  encode?(value: TJs): TWire;
-  /** Converts a wire value from the database driver into the JS type. */
-  decode(wire: TWire): TJs;
-  /** Converts a JS value to a JSON-safe representation for contract serialization. Called during contract emission. */
-  encodeJson(value: TJs): JsonValue;
-  /** Converts a JSON representation back to the JS type. Called during contract loading via `validateContract`. */
-  decodeJson(json: JsonValue): TJs;
-  /** Produces the TypeScript output type expression for a field given its `typeParams`. Used during contract.d.ts emission. */
-  renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
-}
-interface CodecLookup {
-  get(id: string): Codec | undefined;
-}
-declare const emptyCodecLookup: CodecLookup;
-//#endregion
-export { emptyCodecLookup as i, CodecLookup as n, CodecTrait as r, Codec as t };
-//# sourceMappingURL=codec-types-B58nCJiu.d.mts.map

package/dist/codec-types-B58nCJiu.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec-types-B58nCJiu.d.mts","names":[],"sources":["../src/codec-types.ts"],"sourcesContent":[],"mappings":";;;KAEY,UAAA;;AAAZ;AAaA;;;;;;;;;AAiBoB,UAjBH,KAiBG,CAAA,WAAA,MAAA,GAAA,MAAA,EAAA,gBAAA,SAfO,UAeP,EAAA,GAAA,SAf+B,UAe/B,EAAA,EAAA,QAAA,OAAA,EAAA,MAAA,OAAA,CAAA,CAAA;EAAM;EAEP,SAAA,EAAA,EAZJ,EAYI;EAAY;EAEC,SAAA,WAAA,EAAA,SAAA,MAAA,EAAA;EAAM;EAGrB,SAAA,MAAW,CAAA,EAbR,OAcD;EAGN;iBAfI,MAAM;;eAER,QAAQ;;oBAEH,MAAM;;mBAEP,YAAY;;gCAEC;;UAGf,WAAA;mBACE;;cAGN,kBAAkB"}