@prisma-next/framework-components 0.5.0-dev.8 → 0.5.0-dev.80

package/src/execution/run-with-middleware.ts

@@ -0,0 +1,153 @@
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan } from './query-plan';
+import { checkAborted, raceAgainstAbort } from './race-against-abort';
+import type {
+  ParamRefMutator,
+  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: `intercept(exec, ctx)`. The
+ *     first non-`undefined` result wins; subsequent middleware's `intercept`
+ *     does not fire. On a hit, the runtime emits a `middleware.intercept`
+ *     debug event naming the winning middleware, switches the row source to
+ *     the intercepted rows, and proceeds with `source: 'middleware'`. On
+ *     all-passthrough (every `intercept` returns `undefined` or is omitted),
+ *     `source: 'driver'` is used and the row source is `runDriver()`.
+ *  2. If `source === 'driver'`: for each middleware in registration order,
+ *     `beforeExecute(exec, ctx)`. Skipped on the intercepted hit path —
+ *     `beforeExecute` semantically means "about to hit the driver".
+ *  3. Iterate the row source. On the driver path, for each row, for each
+ *     middleware in registration order: `onRow(row, exec, ctx)`; then yield
+ *     the row. On the intercepted hit path, `onRow` is skipped — intercepted
+ *     rows did not originate from a driver row stream — but rows are still
+ *     yielded to the consumer in order.
+ *  4. On successful completion: for each middleware in registration order:
+ *     `afterExecute(exec, { rowCount, latencyMs, completed: true, source },
+ *     ctx)`.
+ *  5. On any error thrown during steps 1–3: for each middleware in
+ *     registration order: `afterExecute(exec, { rowCount, latencyMs,
+ *     completed: false, source }, ctx)`. Errors thrown by `afterExecute`
+ *     during the error path are swallowed so they do not mask the original
+ *     error. The original error is then rethrown.
+ *
+ * The `source` field on `AfterExecuteResult` lets observers (telemetry,
+ * lints, budgets) distinguish driver-served from middleware-served
+ * executions without needing their own out-of-band signal.
+ *
+ * This helper is the single canonical implementation of the middleware
+ * orchestration loop; family runtimes should not reimplement it.
+ */
+export function runWithMiddleware<
+  TExec extends ExecutionPlan,
+  Row,
+  TMutator extends ParamRefMutator = ParamRefMutator,
+>(
+  exec: TExec,
+  middleware: ReadonlyArray<RuntimeMiddleware<TExec, TMutator>>,
+  ctx: RuntimeMiddlewareContext,
+  runDriver: () => AsyncIterable<Row>,
+  paramsMutator?: TMutator,
+): AsyncIterableResult<Row> {
+  const iterator = async function* (): AsyncGenerator<Row, void, unknown> {
+    const startedAt = Date.now();
+    let rowCount = 0;
+    let completed = false;
+    let source: 'driver' | 'middleware' = 'driver';
+    // Deferred so a winning interceptor can skip `runDriver()` entirely.
+    // For factories that lazily produce async generators this is a no-op,
+    // but factories that do eager work (e.g. acquiring a connection,
+    // sending a query) must not run on the intercepted hit path.
+    let rowSource: AsyncIterable<Row> | Iterable<Row> | undefined;
+
+    try {
+      for (const mw of middleware) {
+        if (!mw.intercept) {
+          continue;
+        }
+        // Mark the lifecycle as middleware-driven *before* awaiting the
+        // hook. If `intercept` throws, the catch block reports the failure
+        // as `source: 'middleware'` — the failure originated in the
+        // intercept chain, not in the driver. If `intercept` returns
+        // `undefined` (passthrough), we revert to `'driver'` and continue.
+        source = 'middleware';
+        const result = await mw.intercept(exec, ctx);
+        if (result === undefined) {
+          source = 'driver';
+          continue;
+        }
+        ctx.log.debug?.({ event: 'middleware.intercept', middleware: mw.name });
+        // The intercepted rows are typed as `Record<string, unknown>` at
+        // the SPI level; the consumer's `Row` type parameter is enforced by
+        // the caller (via the plan's phantom `_row`) the same way driver
+        // rows are. Cast through unknown to bridge the SPI shape to the
+        // caller-supplied Row.
+        rowSource = result.rows as unknown as AsyncIterable<Row> | Iterable<Row>;
+        break;
+      }
+
+      if (source === 'driver') {
+        for (const mw of middleware) {
+          if (mw.beforeExecute) {
+            checkAborted(ctx, 'beforeExecute');
+            // The framework only forwards the mutator the caller supplied; a
+            // pass-through `undefined` for non-mutating families is safe — the
+            // base `RuntimeMiddleware` declares the third parameter, and
+            // existing `(plan, ctx)` bodies that ignore it stay unchanged.
+            // The cast below is the single point at which the framework's
+            // generic mutator slot meets the (possibly absent) caller value;
+            // `runWithMiddleware` cannot synthesize a TMutator instance.
+            const work = mw.beforeExecute(exec, ctx, paramsMutator as TMutator);
+            if (work !== undefined) {
+              await raceAgainstAbort(Promise.resolve(work), ctx.signal, 'beforeExecute');
+            }
+          }
+        }
+        rowSource = runDriver();
+      }
+
+      // `rowSource` is always assigned by this point: either the intercepted
+      // rows (on a hit) or `runDriver()` (on the driver path).
+      for await (const row of rowSource as AsyncIterable<Row> | Iterable<Row>) {
+        if (source === 'driver') {
+          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, source }, ctx);
+          } catch {
+            // Swallow afterExecute errors during the error path so they do not
+            // mask the original error.
+          }
+        }
+      }
+
+      throw error;
+    }
+
+    const latencyMs = Date.now() - startedAt;
+    for (const mw of middleware) {
+      if (mw.afterExecute) {
+        await mw.afterExecute(exec, { rowCount, latencyMs, completed, source }, ctx);
+      }
+    }
+  };
+
+  return new AsyncIterableResult(iterator());
+}

package/src/execution/runtime-core.ts

@@ -0,0 +1,133 @@
+import type { CodecCallContext } from '../shared/codec-types';
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan, QueryPlan } from './query-plan';
+import { checkAborted } from './race-against-abort';
+import { runWithMiddleware } from './run-with-middleware';
+import type {
+  RuntimeExecuteOptions,
+  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, ... }`.
+   *
+   * `ctx` carries per-query cancellation (and any future fields on
+   * `CodecCallContext`); concrete subclasses forward it to the
+   * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,
+   * Mongo's `resolveValue` in m3). The runtime allocates one ctx per
+   * `execute()` call and threads the same reference everywhere; the
+   * `signal` field inside may be `undefined`, but the ctx object itself
+   * is always present.
+   */
+  protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
+
+  /**
+   * Drive the underlying transport for a lowered `TExec`. Yields raw rows
+   * directly from the driver as `Record<string, unknown>`; codec decoding
+   * (if any) is the subclass's responsibility, applied by wrapping
+   * `execute()` rather than living inside this hook.
+   *
+   * The `Row` type parameter on `execute()` is satisfied by the caller via
+   * the plan's phantom `_row`; the runtime treats rows as opaque records
+   * here and trusts the caller's row typing.
+   */
+  protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;
+
+  abstract close(): Promise<void>;
+
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row> {
+    const self = this;
+    const signal = options?.signal;
+    // One ctx per execute() call. The ctx object is always allocated; the
+    // `signal` field is only included when a signal was supplied (required
+    // under exactOptionalPropertyTypes — `{ signal: undefined }` would not
+    // satisfy `signal?: AbortSignal`).
+    const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };
+
+    async function* generator(): AsyncGenerator<Row, void, unknown> {
+      // Pre-check the signal at entry so an already-aborted caller observes
+      // RUNTIME.ABORTED on the first `next()` without any work being done.
+      checkAborted(codecCtx, 'stream');
+
+      const compiled = await self.runBeforeCompile(plan);
+      const exec = await self.lower(compiled, codecCtx);
+      // 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/execution/runtime-error.ts

@@ -0,0 +1,94 @@
+export 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).
+ * - `'beforeExecute'` / `'afterExecute'` / `'onRow'` — abort fired
+ *   on entry to or during the corresponding middleware phase
+ *   (cooperative cancellation per the param-transform seam).
+ */
+export const RUNTIME_ABORTED = 'RUNTIME.ABORTED' as const;
+
+/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
+export type RuntimeAbortedPhase =
+  | 'encode'
+  | 'decode'
+  | 'stream'
+  | 'beforeExecute'
+  | 'afterExecute'
+  | 'onRow';
+
+/**
+ * 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,
+  details?: Record<string, unknown>,
+): RuntimeErrorEnvelope {
+  const error = new Error(message) as RuntimeErrorEnvelope;
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+
+  return Object.assign(error, {
+    code,
+    category: resolveCategory(code),
+    severity: 'error' as const,
+    message,
+    details,
+  });
+}
+
+function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
+  const prefix = code.split('.')[0] ?? 'RUNTIME';
+  switch (prefix) {
+    case 'PLAN':
+    case 'CONTRACT':
+    case 'LINT':
+    case 'BUDGET':
+      return prefix;
+    default:
+      return 'RUNTIME';
+  }
+}
+
+/**
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+ * abort was observed — codec call sites (`encode` / `decode` / `stream`)
+ * or middleware seams (`beforeExecute` / `afterExecute` / `onRow`), as
+ * enumerated on {@link RuntimeAbortedPhase}. Cause carries
+ * `signal.reason` verbatim from the platform — native abort produces a
+ * `DOMException`, explicit `controller.abort(reason)` produces whatever
+ * the caller passed. No synthesis happens here.
+ */
+export function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope {
+  const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });
+  return Object.assign(envelope, { cause });
+}

package/src/execution/runtime-middleware.ts

@@ -0,0 +1,235 @@
+import type { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan, QueryPlan } from './query-plan';
+import { runtimeError } from './runtime-error';
+
+export interface RuntimeLog {
+  info(event: unknown): void;
+  warn(event: unknown): void;
+  error(event: unknown): void;
+  debug?(event: unknown): void;
+}
+
+/**
+ * Per-execute context threaded through every middleware phase
+ * (`beforeExecute`, `onRow`, `afterExecute`). Allocated once per
+ * `runtime.execute()` call and shared by reference across all
+ * middleware in the chain.
+ *
+ * - `signal` carries the per-query `AbortSignal` -- the same
+ *   reference that `runtime.execute(plan, { signal })` was invoked
+ *   with, and the same reference threaded into the per-call
+ *   `CodecCallContext` (ADR 207). Middleware that wraps a
+ *   network-backed SDK forwards `ctx.signal` into that SDK to
+ *   propagate caller cancellation; pure-CPU middleware ignores it.
+ *
+ * Symmetric plumbing across all middleware phases (rather than only
+ * `beforeExecute`) is a deliberate choice: a middleware that wraps a
+ * downstream observability hook or post-processor in `afterExecute` /
+ * `onRow` needs the same cancellation reach as its `beforeExecute`
+ * counterpart.
+ */
+export interface RuntimeMiddlewareContext {
+  readonly contract: unknown;
+  readonly mode: 'strict' | 'permissive';
+  readonly now: () => number;
+  readonly log: RuntimeLog;
+  /**
+   * Returns a stable string identifying the (storage, statement, params)
+   * tuple of an execution. Two semantically equivalent executions return
+   * the same string. Used by middleware that need per-execution identity
+   * (caching, request coalescing).
+   *
+   * The family runtime owns the implementation:
+   * - SQL: `meta.storageHash` + `exec.sql` + `canonicalStringify(exec.params)`
+   * - Mongo: `meta.storageHash` + `canonicalStringify({ ...exec.command })`
+   *
+   * The method is `async` because the underlying digest helper
+   * (`hashContent`) uses the WebCrypto API, whose `crypto.subtle.digest`
+   * primitive is asynchronous by design.
+   *
+   * The returned string is intended to be consumed directly as a `Map` key
+   * — it is not (and should not be) further hashed by callers.
+   */
+  contentHash(exec: ExecutionPlan): Promise<string>;
+  /**
+   * Per-execute cancellation signal threaded through every middleware
+   * phase. Middleware that wraps async work or downstream cancellable
+   * primitives should observe this and abort early when the consumer
+   * cancels.
+   */
+  readonly signal?: AbortSignal;
+}
+
+export interface AfterExecuteResult {
+  readonly rowCount: number;
+  readonly latencyMs: number;
+  readonly completed: boolean;
+  /**
+   * Indicates where the rows observed during this execution came from.
+   *
+   * - `'driver'` — the default. Rows came from the underlying driver via
+   *   `runDriver` / `runWithMiddleware`'s normal path.
+   * - `'middleware'` — a `RuntimeMiddleware.intercept` hook short-circuited
+   *   execution and supplied the rows directly. The driver was not invoked.
+   *
+   * Observers (telemetry, lints, budgets) that need to distinguish between
+   * driver-served and middleware-served executions read this field.
+   * Observers that don't care can ignore it.
+   */
+  readonly source: 'driver' | 'middleware';
+}
+
+/**
+ * Result of a successful `RuntimeMiddleware.intercept` hook.
+ *
+ * Carries the rows that the middleware wishes to return in place of
+ * invoking the driver. The runtime iterates `rows` in order and yields
+ * each row to the consumer; `beforeExecute`, `runDriver`, and `onRow` are
+ * all skipped on the hit path. `afterExecute` still fires with
+ * `source: 'middleware'`.
+ *
+ * `rows` accepts both `Iterable` (arrays, sync generators) and
+ * `AsyncIterable` (async generators). `for await` natively handles both
+ * via `Symbol.asyncIterator` / `Symbol.iterator` fallback, so the
+ * orchestrator does not need to branch on the variant. Cached arrays in
+ * the cache middleware are the common case; streaming variants support
+ * future use cases like mock layers replaying recordings.
+ *
+ * Row shape is `Record<string, unknown>` — the same untyped shape
+ * `onRow` receives. The SQL runtime decodes intercepted rows through its
+ * normal codec pass, so interceptors cache and return raw (undecoded)
+ * rows.
+ */
+export interface InterceptResult {
+  readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
+}
+
+/**
+ * Marker interface for family-specific param-ref mutators threaded into
+ * `beforeExecute` as the third argument. The framework treats the mutator
+ * opaquely — it allocates and forwards the family's mutator instance so
+ * `runWithMiddleware` can stay family-agnostic. SQL extends this with
+ * `SqlParamRefMutator` (over `ParamRef`); Mongo extends with
+ * `MongoParamRefMutator` (over `MongoParamRef`).
+ *
+ * Extension authors target the family-specific mutator type, not this
+ * marker.
+ */
+declare const PARAM_REF_MUTATOR_BRAND: unique symbol;
+export type ParamRefMutator = { readonly [PARAM_REF_MUTATOR_BRAND]?: never };
+
+/**
+ * Family-agnostic middleware SPI parameterized over the plan marker.
+ *
+ * `TPlan` defaults to the framework `QueryPlan` marker so a generic
+ * middleware (e.g. cross-family telemetry) can be authored without
+ * naming a family. Family-specific middleware (`SqlMiddleware`,
+ * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.
+ *
+ * `TMutator` is the family-specific {@link ParamRefMutator} the runtime
+ * threads into `beforeExecute(plan, ctx, params)` as a third argument.
+ * Existing `(plan)` / `(plan, ctx)` middleware bodies continue to compile
+ * — TypeScript permits assigning a function with fewer parameters to a
+ * function-typed slot that declares more. The third arg is additive.
+ */
+export interface RuntimeMiddleware<
+  TPlan extends QueryPlan = QueryPlan,
+  TMutator extends ParamRefMutator = ParamRefMutator,
+> {
+  readonly name: string;
+  readonly familyId?: string;
+  readonly targetId?: string;
+  /**
+   * Optional short-circuit hook. Runs inside `runWithMiddleware`, after
+   * the orchestrator receives the lowered plan and before any
+   * `beforeExecute` hook fires. Middleware run in registration order; the
+   * first to return a non-`undefined` `InterceptResult` wins, and
+   * subsequent middleware's `intercept` does not fire.
+   *
+   * On a hit, `beforeExecute`, `runDriver`, and `onRow` are all skipped.
+   * `afterExecute` still fires with `source: 'middleware'`.
+   *
+   * Returning `undefined` (or omitting the hook entirely) signals
+   * passthrough — execution proceeds through the normal driver path.
+   *
+   * Errors thrown inside `intercept` are rethrown by `runWithMiddleware`
+   * as the original `Error` — no envelope is guaranteed at this layer.
+   * Before rethrowing, `afterExecute` fires with `completed: false` and
+   * `source: 'middleware'`. Errors thrown by `afterExecute` during the
+   * error path remain swallowed (existing semantics, unchanged).
+   *
+   * Used by middleware that need to short-circuit execution and supply
+   * rows directly: caching, mocks, rate limiting, circuit breaking.
+   */
+  intercept?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<InterceptResult | undefined>;
+  beforeExecute?(
+    plan: TPlan,
+    ctx: RuntimeMiddlewareContext,
+    params?: TMutator,
+  ): void | Promise<void>;
+  onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
+  afterExecute?(
+    plan: TPlan,
+    result: AfterExecuteResult,
+    ctx: RuntimeMiddlewareContext,
+  ): Promise<void>;
+}
+
+/**
+ * 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.
+ */
+export 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,
+ * Mongo structurally (due to its phantom Row parameter using a unique symbol).
+ *
+ * The `_row` intersection on `execute` connects the `Row` type parameter to the
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
+ */
+export interface RuntimeExecutor<TPlan extends QueryPlan> {
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row>;
+  close(): Promise<void>;
+}
+
+export function checkMiddlewareCompatibility(
+  middleware: RuntimeMiddleware,
+  runtimeFamilyId: string,
+  runtimeTargetId: string,
+): void {
+  if (middleware.targetId !== undefined && middleware.familyId === undefined) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_INCOMPATIBLE',
+      `Middleware '${middleware.name}' specifies targetId '${middleware.targetId}' without familyId`,
+      { middleware: middleware.name, targetId: middleware.targetId },
+    );
+  }
+
+  if (middleware.familyId !== undefined && middleware.familyId !== runtimeFamilyId) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_FAMILY_MISMATCH',
+      `Middleware '${middleware.name}' requires family '${middleware.familyId}' but the runtime is configured for family '${runtimeFamilyId}'`,
+      { middleware: middleware.name, middlewareFamilyId: middleware.familyId, runtimeFamilyId },
+    );
+  }
+
+  if (middleware.targetId !== undefined && middleware.targetId !== runtimeTargetId) {
+    throw runtimeError(
+      'RUNTIME.MIDDLEWARE_TARGET_MISMATCH',
+      `Middleware '${middleware.name}' requires target '${middleware.targetId}' but the runtime is configured for target '${runtimeTargetId}'`,
+      { middleware: middleware.name, middlewareTargetId: middleware.targetId, runtimeTargetId },
+    );
+  }
+}

package/src/exports/authoring.ts

@@ -10,13 +10,16 @@ export type {
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';
 export {
+  assertNoCrossRegistryCollisions,
+  hasRegisteredFieldNamespace,
   instantiateAuthoringFieldPreset,
   instantiateAuthoringTypeConstructor,
   isAuthoringArgRef,
   isAuthoringFieldPresetDescriptor,
   isAuthoringTypeConstructorDescriptor,
+  mergeAuthoringNamespaces,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';

package/src/exports/codec.ts

@@ -1,2 +1,27 @@
-export type { Codec, CodecLookup, CodecTrait } from '../codec-types';
-export { emptyCodecLookup } from '../codec-types';
+/**
+ * Codec model: interfaces (consumer surface) plus abstract `Impl` classes (codec-author surface) plus the column packager.
+ *
+ * Consumers depend on the interfaces: {@link Codec}, {@link CodecDescriptor}, {@link AnyCodecDescriptor}, {@link ColumnSpec}, {@link ColumnTypeDescriptor}.
+ *
+ * Codec authors `extend` the abstract bases: {@link CodecImpl} and {@link CodecDescriptorImpl}. They write a per-codec column helper that calls `descriptor.factory(...)` directly and tie the helper to its descriptor with `satisfies ColumnHelperFor<D>` (or `ColumnHelperForStrict<D>`).
+ */
+
+export type { Codec } from '../shared/codec';
+export { CodecImpl } from '../shared/codec';
+export type { AnyCodecDescriptor, CodecDescriptor } from '../shared/codec-descriptor';
+export { CodecDescriptorImpl } from '../shared/codec-descriptor';
+export type {
+  CodecCallContext,
+  CodecInstanceContext,
+  CodecLookup,
+  CodecMeta,
+  CodecTrait,
+} from '../shared/codec-types';
+export { emptyCodecLookup, voidParamsSchema } from '../shared/codec-types';
+export type {
+  ColumnHelperFor,
+  ColumnHelperForStrict,
+  ColumnSpec,
+  ColumnTypeDescriptor,
+} from '../shared/column-spec';
+export { column } from '../shared/column-spec';

package/src/exports/components.ts

@@ -20,5 +20,5 @@ export type {
   TargetDescriptor,
   TargetInstance,
   TargetPackRef,
-} from '../framework-components';
-export { checkContractComponentRequirements } from '../framework-components';
+} from '../shared/framework-components';
+export { checkContractComponentRequirements } from '../shared/framework-components';