@prisma-next/sql-relational-core 0.5.0-dev.8 → 0.5.0-dev.81

package/src/codec-descriptor-registry.ts

@@ -0,0 +1,52 @@
+import type { CodecDescriptor } from '@prisma-next/framework-components/codec';
+import type { AnyCodecDescriptor } from './ast/codec-types';
+import type { CodecDescriptorRegistry } from './query-lane-context';
+
+/**
+ * Build a {@link CodecDescriptorRegistry} from a flat descriptor list.
+ *
+ * Used by:
+ * - Each codec-shipping package's `core/registry.ts` to expose a package-scoped registry as the public consumer surface (replacing raw descriptor-array exports). See ADR 208.
+ * - The runtime's `buildExecutionContext` to construct the contract-bound combined registry from every contributor's `codecs:` slot.
+ *
+ * The descriptor map is heterogeneous in `P` — each codec id has its own params shape. The public {@link CodecDescriptorRegistry} interface widens to `CodecDescriptor<unknown>` and consumers narrow per codec id at the call site (the descriptor's `paramsSchema` validates JSON-sourced params before the factory ever sees them, so the runtime narrow is safe). The cast at registration goes through `unknown` because
+ * `CodecDescriptor<P>` is invariant in `P` (the `factory` and `renderOutputType` slots use `P` contravariantly).
+ */
+export function buildCodecDescriptorRegistry(
+  allDescriptors: ReadonlyArray<AnyCodecDescriptor>,
+): CodecDescriptorRegistry {
+  type AnyDescriptor = CodecDescriptor<unknown>;
+  const byId = new Map<string, AnyDescriptor>();
+  const byTargetType = new Map<string, Array<AnyDescriptor>>();
+
+  for (const descriptor of allDescriptors) {
+    if (byId.has(descriptor.codecId)) {
+      throw new Error(
+        `Duplicate codec descriptor id: '${descriptor.codecId}' — registered twice during registry construction. ` +
+          'Each codecId must be contributed by exactly one component (target / adapter / extension pack).',
+      );
+    }
+    const widened = descriptor as unknown as AnyDescriptor;
+    byId.set(descriptor.codecId, widened);
+    for (const targetType of descriptor.targetTypes) {
+      const list = byTargetType.get(targetType);
+      if (list) {
+        list.push(widened);
+      } else {
+        byTargetType.set(targetType, [widened]);
+      }
+    }
+  }
+
+  return {
+    descriptorFor(codecId: string): AnyDescriptor | undefined {
+      return byId.get(codecId);
+    },
+    *values(): IterableIterator<AnyDescriptor> {
+      yield* byId.values();
+    },
+    byTargetType(targetType: string): readonly AnyDescriptor[] {
+      return byTargetType.get(targetType) ?? Object.freeze([]);
+    },
+  };
+}

package/src/exports/ast.ts

@@ -1,6 +1,8 @@
 export * from '../ast/adapter-types';
 export * from '../ast/codec-types';
 export * from '../ast/driver-types';
+export * from '../ast/sql-codec-helpers';
 export * from '../ast/sql-codecs';
 export * from '../ast/types';
 export * from '../ast/util';
+export * from '../ast/validate-param-refs';

package/src/exports/codec-descriptor-registry.ts

@@ -0,0 +1 @@
+export * from '../codec-descriptor-registry';

package/src/exports/expression.ts

@@ -0,0 +1 @@
+export * from '../expression';

package/src/exports/middleware.ts

@@ -0,0 +1,8 @@
+export type {
+  ParamRefEntry,
+  ParamRefEntryUnion,
+  ParamRefHandle,
+  SqlParamRefMutator,
+  SqlParamRefMutatorInternal,
+} from '../middleware/param-ref-mutator';
+export { createSqlParamRefMutator } from '../middleware/param-ref-mutator';

package/src/exports/plan.ts

@@ -1 +1,2 @@
 export * from '../plan';
+export type { SqlExecutionPlan } from '../sql-execution-plan';

package/src/exports/types.ts

@@ -1 +1,2 @@
+export type { RuntimeScope, SqlOrmPlan } from '../runtime-scope';
 export * from '../types';

package/src/expression.ts

@@ -0,0 +1,134 @@
+import type { ParamSpec } from '@prisma-next/operations';
+import type { QueryOperationReturn } from '@prisma-next/sql-contract/types';
+import type { SqlLoweringSpec } from '@prisma-next/sql-operations';
+import type { AnyExpression as AstExpression } from './ast/types';
+import { OperationExpr, ParamRef } from './ast/types';
+
+export type ScopeField = { codecId: string; nullable: boolean };
+
+/**
+ * A typed SQL expression. Identity is carried by the `returnType` descriptor (inherited from `QueryOperationReturn` and narrowed to `T`) — distinct `T` makes distinct Expression types structurally. `buildAst()` materialises the underlying AST node.
+ */
+export type Expression<T extends ScopeField> = QueryOperationReturn & {
+  readonly returnType: T;
+  buildAst(): AstExpression;
+};
+
+type CodecIdsWithTrait<
+  CT extends Record<string, { readonly input: unknown }>,
+  RequiredTraits extends readonly string[],
+> = {
+  [K in keyof CT & string]: CT[K] extends { readonly traits: infer T }
+    ? [RequiredTraits[number]] extends [T]
+      ? K
+      : never
+    : never;
+}[keyof CT & string];
+
+type NullSuffix<N> = N extends true ? null : never;
+
+/**
+ * An expression or literal value targeting a specific codec.
+ *
+ * Accepts any of:
+ * - An `Expression` whose codec matches exactly
+ * - A raw JS value of the codec's `input` type
+ * - `null` when `Nullable` is true
+ */
+export type CodecExpression<
+  CodecId extends string,
+  Nullable extends boolean,
+  CT extends Record<string, { readonly input: unknown }>,
+> =
+  | Expression<{ codecId: CodecId; nullable: Nullable }>
+  | (CodecId extends keyof CT ? CT[CodecId]['input'] : never)
+  | NullSuffix<Nullable>;
+
+/**
+ * An expression or literal value targeting any codec whose trait set contains all the required traits.
+ *
+ * Resolves the trait set to the union of matching codec identities via `CodecIdsWithTrait`, then reuses `CodecExpression` for the codec-id form.
+ */
+export type TraitExpression<
+  Traits extends readonly string[],
+  Nullable extends boolean,
+  CT extends Record<string, { readonly input: unknown }>,
+> = CodecExpression<CodecIdsWithTrait<CT, Traits>, Nullable, CT>;
+
+/**
+ * Resolve a raw value or an Expression into an AST expression node.
+ *
+ * When `value` is an Expression (duck-typed by its `buildAst` method), the AST it wraps is returned. Otherwise the value is embedded as a ParamRef tagged with `codecId` (if given) and optionally `refs: { table, column }` (if the caller knows the column-bound site).
+ *
+ * For parameterized codec ids (e.g. `pg/vector@1`), encode-side dispatch requires `refs` to select the per-instance codec — so operation implementations that compare a column to a user-supplied value should derive `refs` from the column-bound side and pass it down. Non-parameterized codec ids (e.g. `pg/int4@1`) tolerate refs-less ParamRefs; the validator pass enforces refs only for parameterized ids.
+ */
+export function toExpr(
+  value: unknown,
+  codecId?: string,
+  refs?: { table: string; column: string },
+): AstExpression {
+  if (isExpressionLike(value)) {
+    return value.buildAst();
+  }
+  if (codecId === undefined && refs === undefined) return ParamRef.of(value);
+  return ParamRef.of(value, {
+    ...(codecId !== undefined ? { codecId } : {}),
+    ...(refs !== undefined ? { refs } : {}),
+  });
+}
+
+/**
+ * Derive `(table, column)` refs from an expression-like value when it carries column-bound metadata. Returns `undefined` for non-column-bound expressions and for raw scalar values.
+ *
+ * Two sources are consulted, in order: 1. An optional `refs` slot on the `Expression` wrapper (the SQL builder's `ExpressionImpl` records `(table, column)` for top-level fields whose AST is `IdentifierRef` — the AST stays bare to preserve SQL rendering, the metadata lives on the wrapper). 2. The wrapped AST when it's already a `ColumnRef` (the namespaced field-proxy form, or operation impls passing column-bound exprs
+ * directly).
+ *
+ * Operation implementations call this on the column-bound side of a comparison and forward the refs to {@link toExpr} on the user-value side, so the resulting `ParamRef` carries the table+column required by encode-side `forColumn` dispatch.
+ */
+export function refsOf(value: unknown): { table: string; column: string } | undefined {
+  if (!isExpressionLike(value)) return undefined;
+  const wrapperRefs = (value as { refs?: { table: string; column: string } }).refs;
+  if (wrapperRefs) return { table: wrapperRefs.table, column: wrapperRefs.column };
+  const ast = value.buildAst();
+  if (ast.kind === 'column-ref') {
+    return { table: ast.table, column: ast.column };
+  }
+  return undefined;
+}
+
+function isExpressionLike(value: unknown): value is Expression<ScopeField> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'buildAst' in value &&
+    typeof (value as { buildAst: unknown }).buildAst === 'function'
+  );
+}
+
+export interface BuildOperationSpec<R extends ScopeField> {
+  readonly method: string;
+  /**
+   * The operation's arguments. The first element is the self argument (the value the operation is being applied to); the rest are the remaining user-supplied arguments.
+   */
+  readonly args: readonly [AstExpression, ...AstExpression[]];
+  readonly returns: R & ParamSpec;
+  readonly lowering: SqlLoweringSpec;
+}
+
+/**
+ * Construct an OperationExpr AST node and wrap it as a typed Expression. Operation implementations use this to turn their user-facing arguments into the AST node the compilation pipeline eventually lowers to SQL.
+ */
+export function buildOperation<R extends ScopeField>(spec: BuildOperationSpec<R>): Expression<R> {
+  const [self, ...rest] = spec.args;
+  const op = new OperationExpr({
+    method: spec.method,
+    self,
+    args: rest.length > 0 ? rest : undefined,
+    returns: spec.returns,
+    lowering: spec.lowering,
+  });
+  return {
+    returnType: spec.returns,
+    buildAst: () => op,
+  };
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from './exports/ast';
 export * from './exports/errors';
+export * from './exports/expression';
+export * from './exports/middleware';
 export * from './exports/plan';
 export * from './exports/query-lane-context';
 export * from './exports/types';

package/src/middleware/param-ref-mutator.ts

@@ -0,0 +1,230 @@
+import type { ParamRefMutator } from '@prisma-next/framework-components/runtime';
+import type { SqlColumnRef } from '../ast/codec-types';
+import type { ParamRef } from '../ast/types';
+import { collectOrderedParamRefs } from '../ast/util';
+import type { SqlExecutionPlan } from '../sql-execution-plan';
+
+/**
+ * Brand applied to {@link ParamRefHandle} so user-constructed handles
+ * are rejected by the type system. The mutator only accepts handles it
+ * produced from `entries()`.
+ *
+ * The brand is a phantom type — there is no runtime token. At runtime
+ * the handle is the underlying `ParamRef` instance from the plan's
+ * `ast`; the brand only narrows the type-level surface so callers
+ * cannot fabricate a handle from a fresh `ParamRef.of(...)`.
+ */
+declare const paramRefHandleBrand: unique symbol;
+
+/**
+ * Opaque token identifying a single `ParamRef` in the plan. Produced by
+ * {@link SqlParamRefMutator.entries}; consumed by `replaceValue` /
+ * `replaceValues`.
+ *
+ * The phantom `TCodecId` parameter records the codec id of the
+ * referenced `ParamRef` so type-level inference can route replacement
+ * values through `TCodecMap` to the codec's declared `TInput`.
+ */
+export interface ParamRefHandle<TCodecId extends string | undefined = string | undefined> {
+  readonly [paramRefHandleBrand]: TCodecId;
+}
+
+/**
+ * One outbound `ParamRef` slot in the plan exposed to middleware.
+ * `value` is the current value (post any prior middleware mutations);
+ * `codecId` is the codec id declared on the underlying `ParamRef`;
+ * `column` is populated for `ParamRef`s the lowering site could resolve
+ * to a single `(table, column)` via `ParamRef.refs` (encode-side column
+ * metadata is the middleware's domain — encode itself currently leaves
+ * `ctx.column` unset).
+ */
+export interface ParamRefEntry<TCodecId extends string | undefined = string | undefined> {
+  readonly ref: ParamRefHandle<TCodecId>;
+  readonly value: unknown;
+  readonly codecId: TCodecId;
+  readonly column?: SqlColumnRef;
+}
+
+/**
+ * Discriminated entry union over a codec map. For each `K` in
+ * `TCodecMap`, `entries()` may yield a `ParamRefEntry<K>`; ParamRefs
+ * with no codec id (or a codec id outside the map) yield a
+ * `ParamRefEntry<undefined>`. Pattern-matching on `entry.codecId`
+ * narrows `entry.ref` to a `ParamRefHandle<K>`, which routes through
+ * the typed `replaceValue` overload.
+ */
+export type ParamRefEntryUnion<TCodecMap extends Record<string, unknown>> =
+  | { [K in keyof TCodecMap & string]: ParamRefEntry<K> }[keyof TCodecMap & string]
+  | ParamRefEntry<undefined>;
+
+/**
+ * SQL-family mutator threaded into `SqlMiddleware.beforeExecute` as
+ * `params`. Scope is `ParamRef.value` slots only — middleware cannot
+ * insert / remove `ParamRef`s, rewrite SQL, or modify projection. The
+ * type-level `ParamRefHandle` brand and the `replaceValue(ref,
+ * newValue)` shape enforce this at compile time.
+ *
+ * Allocation discipline: the mutator is constructed lazily from the
+ * plan. `entries()` walks the plan's existing AST without allocating
+ * an intermediate array; the working params buffer is only allocated
+ * on the first `replaceValue` / `replaceValues` call. If no middleware
+ * mutates, `currentParams()` returns the plan's original `params` by
+ * reference identity.
+ *
+ * The `TCodecMap` parameter is a record keyed by codec id; `replaceValue`
+ * infers `newValue` from `TCodecMap[H['codecId']]` for handles whose
+ * codec id is statically resolvable. For codec ids the type system
+ * cannot resolve, `newValue` falls back to `unknown` and the middleware
+ * is on the hook for runtime correctness.
+ */
+export interface SqlParamRefMutator<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+> extends ParamRefMutator {
+  /** Iterate every outbound `ParamRef` the plan currently carries, in canonical order. */
+  entries(): IterableIterator<ParamRefEntryUnion<TCodecMap>>;
+
+  /**
+   * Replace one `ParamRef`'s value with the result of bulk processing.
+   * `newValue` is constrained to the codec's declared `TInput` for codec
+   * ids the type system can resolve via `TCodecMap`; for unresolvable
+   * codec ids `newValue` is `unknown` (the second overload).
+   */
+  replaceValue<TCodecId extends keyof TCodecMap & string>(
+    ref: ParamRefHandle<TCodecId>,
+    newValue: TCodecMap[TCodecId],
+  ): void;
+  replaceValue(ref: ParamRefHandle<undefined>, newValue: unknown): void;
+
+  /** Replace many at once (typical for bulk-pattern middleware). */
+  replaceValues(
+    updates: Iterable<{
+      readonly ref: ParamRefHandle<(keyof TCodecMap & string) | undefined>;
+      readonly newValue: unknown;
+    }>,
+  ): void;
+}
+
+/**
+ * Internal-only view of the mutator that exposes the post-mutation params
+ * array to the SQL runtime. The runtime calls `currentParams()` after the
+ * `beforeExecute` chain has run; the result is the plan's original
+ * `params` by reference identity if no middleware mutated, otherwise a
+ * frozen new array carrying the mutations applied in chain order.
+ *
+ * Family-internal contract — `SqlMiddleware` consumers never see this
+ * shape; they receive the public `SqlParamRefMutator` view above.
+ */
+export interface SqlParamRefMutatorInternal<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+> extends SqlParamRefMutator<TCodecMap> {
+  currentParams(): readonly unknown[];
+}
+
+type AnyHandle = ParamRefHandle<string | undefined>;
+
+/**
+ * Build a {@link SqlParamRefMutatorInternal} for the given lowered plan.
+ *
+ * The mutator captures `plan.params` by reference and walks
+ * `plan.ast` (via `collectOrderedParamRefs`) on demand to build
+ * entries. Mutations write to a lazily-allocated working copy so the
+ * fast path (no mutation) preserves bit-for-bit reference identity to
+ * the original `plan.params`.
+ *
+ * Threading: `plan.ast` carries the canonical `ParamRef` ordering used
+ * by every consumer (renderer's `$N` index map, encode-side metadata
+ * walk, etc.). The mutator's `entries()` yields the same order so
+ * middleware that filters by codec id sees ParamRefs in the order the
+ * runtime will encode them.
+ */
+export function createSqlParamRefMutator<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+>(plan: SqlExecutionPlan): SqlParamRefMutatorInternal<TCodecMap> {
+  const originalParams = plan.params;
+  const refs: ReadonlyArray<ParamRef> = plan.ast ? collectOrderedParamRefs(plan.ast) : [];
+  let workingParams: unknown[] | undefined;
+
+  const indexOfRef = (handle: AnyHandle): number => {
+    // The handle is the underlying ParamRef instance the mutator yielded
+    // from entries(); equality is identity equality on the ParamRef. The
+    // brand on ParamRefHandle is unforgeable from outside, so the only
+    // legal handles came from this mutator's entries().
+    return refs.indexOf(handle as unknown as ParamRef);
+  };
+
+  const ensureWorkingParams = (): unknown[] => {
+    if (!workingParams) {
+      workingParams = [...originalParams];
+    }
+    return workingParams;
+  };
+
+  const writeAt = (index: number, value: unknown): void => {
+    const buffer = ensureWorkingParams();
+    buffer[index] = value;
+  };
+
+  function* entries(): IterableIterator<ParamRefEntryUnion<TCodecMap>> {
+    const view = workingParams ?? originalParams;
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (!ref) continue;
+      const handle = ref as unknown as ParamRefHandle<string | undefined>;
+      const value = i < view.length ? view[i] : ref.value;
+      const codecId = ref.codecId;
+      // Surface the column binding the lowering site resolved onto
+      // `ParamRef.refs` so column-aware middleware (e.g. cipherstash
+      // routing-key resolution) can address the cell without
+      // re-walking the AST. ParamRefs without a column binding stay
+      // `column: undefined`.
+      const column = ref.refs
+        ? ({ table: ref.refs.table, name: ref.refs.column } as const)
+        : undefined;
+      // The runtime erases the discriminated union to a single shape; the
+      // public type pins each entry's `ref` to the matching `codecId`
+      // arm at compile time.
+      const entry: ParamRefEntry<string | undefined> = column
+        ? { ref: handle, value, codecId, column }
+        : { ref: handle, value, codecId };
+      yield entry as ParamRefEntryUnion<TCodecMap>;
+    }
+  }
+
+  function replaceValue(handle: AnyHandle, newValue: unknown): void {
+    const index = indexOfRef(handle);
+    if (index < 0) {
+      // Handle does not belong to this plan. The type system pins this
+      // at the brand level; this runtime check guards against handles
+      // smuggled across plans.
+      return;
+    }
+    writeAt(index, newValue);
+  }
+
+  function replaceValues(
+    updates: Iterable<{ readonly ref: AnyHandle; readonly newValue: unknown }>,
+  ): void {
+    for (const { ref, newValue } of updates) {
+      const index = indexOfRef(ref);
+      if (index < 0) continue;
+      writeAt(index, newValue);
+    }
+  }
+
+  // The public `SqlParamRefMutator` declares overloaded `replaceValue`
+  // signatures (typed-by-codec / unresolvable-codec). The implementation
+  // is one function with a permissive runtime signature; the cast is the
+  // single point at which the runtime function meets the typed overload
+  // surface, matching the overload-implementation pattern.
+  return {
+    entries,
+    replaceValue: replaceValue as SqlParamRefMutator<TCodecMap>['replaceValue'],
+    replaceValues,
+    currentParams(): readonly unknown[] {
+      if (!workingParams) {
+        return originalParams;
+      }
+      return Object.freeze([...workingParams]);
+    },
+  };
+}

package/src/plan.ts

@@ -1,39 +1,56 @@
-import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
-import type { StorageColumn } from '@prisma-next/sql-contract/types';
+import type { Contract } from '@prisma-next/contract/types';
+import type { QueryPlan } from '@prisma-next/framework-components/runtime';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { AnyQueryAst } from './ast/types';
 
 /**
  * SQL query plan produced by lanes before lowering.
  *
- * Lanes build ASTs and metadata but do not perform SQL lowering.
- * The `sql` field is absent - lowering happens in the runtime executor.
+ * Lanes build ASTs and metadata but do not perform SQL lowering. The `sql`
+ * field is absent — `RuntimeCore` (the runtime base class in
+ * `@prisma-next/framework-components/runtime`) drives lowering via the
+ * SQL adapter and produces a `SqlExecutionPlan`.
  *
- * Structurally aligns with ExecutionPlan<Row, AnyQueryAst> (without sql field) to maintain
- * compatibility with ExecutionPlan/Plan-based utilities.
- * The generic parameter `_Row` is preserved for type extraction via ResultType.
+ * Extends the framework-level `QueryPlan<Row>` marker (`meta + _row`) and
+ * adds SQL-specific fields (`ast`, `params`). The phantom `_row` property
+ * (inherited from `QueryPlan`) is what `ResultType<P>` inspects to recover
+ * the row type.
  */
-export interface SqlQueryPlan<_Row = unknown>
-  extends Pick<ExecutionPlan<_Row, AnyQueryAst>, 'params' | 'meta'> {
+export interface SqlQueryPlan<Row = unknown> extends QueryPlan<Row> {
   readonly ast: AnyQueryAst;
-  // Phantom property to preserve generic parameter for type extraction
-  // This allows ResultType to extract _Row for SqlQueryPlan values.
-  readonly _Row?: _Row;
+  readonly params: readonly unknown[];
 }
 
 /**
- * Augments the last ParamDescriptor in the array with codecId and nativeType from columnMeta.
- * This is used when building WHERE expressions to ensure param descriptors have type information.
+ * Wraps an `AnyQueryAst` (typically a `RawSqlExpr` constructed package-internally
+ * by an extension's migration factory) in a fully-populated `SqlQueryPlan`
+ * whose `meta` is sourced from the supplied contract.
+ *
+ * Centralising the envelope here means consumers (cipherstash migration
+ * factories today; future raw-sql callers) cannot drift on `storageHash` /
+ * `target` / `targetFamily`, which would otherwise surface as a subtle
+ * `assertContractMatches` failure inside `dataTransform`. `params` defaults
+ * to `[]` because parameters embedded in the AST as `ParamRef`s are resolved
+ * at lowering time (`encodeParams` walks `plan.ast.collectParamRefs()`),
+ * not at plan-construction time.
+ *
+ * The default `laneId` of `'raw'` reflects raw-SQL plans' standard lane tag;
+ * callers (e.g. a future `sql-raw-factory`) may override to differentiate
+ * the plan's provenance.
  */
-export function augmentDescriptorWithColumnMeta(
-  descriptors: ParamDescriptor[],
-  columnMeta: StorageColumn | undefined,
-): void {
-  const descriptor = descriptors[descriptors.length - 1];
-  if (descriptor && columnMeta) {
-    descriptors[descriptors.length - 1] = {
-      ...descriptor,
-      codecId: columnMeta.codecId,
-      nativeType: columnMeta.nativeType,
-    };
-  }
+export function planFromAst<Row = unknown>(
+  ast: AnyQueryAst,
+  contract: Contract<SqlStorage>,
+  laneId = 'raw',
+): SqlQueryPlan<Row> {
+  return {
+    ast,
+    params: [],
+    meta: {
+      target: contract.target,
+      targetFamily: contract.targetFamily,
+      storageHash: contract.storage.storageHash,
+      lane: laneId,
+    },
+  };
 }