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

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

@@ -1,9 +1,4 @@
 import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
-import type {
-  SignDatabaseResult,
-  VerifyDatabaseResult,
-  VerifyDatabaseSchemaResult,
-} from './control-result-types';
 import type {
   AdapterInstance,
   DriverInstance,
@@ -11,7 +6,12 @@ import type {
   FamilyInstance,
   TargetBoundComponentDescriptor,
   TargetInstance,
-} from './framework-components';
+} from '../shared/framework-components';
+import type {
+  SignDatabaseResult,
+  VerifyDatabaseResult,
+  VerifyDatabaseSchemaResult,
+} from './control-result-types';
 
 export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
   extends FamilyInstance<TFamilyId> {

package/src/{control-migration-types.ts → control/control-migration-types.ts}

@@ -11,8 +11,8 @@
 
 import type { Contract } from '@prisma-next/contract/types';
 import type { Result } from '@prisma-next/utils/result';
+import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
 import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
-import type { TargetBoundComponentDescriptor } from './framework-components';
 
 // ============================================================================
 // Operation Classes and Policy

package/src/control/control-operation-preview.ts

@@ -0,0 +1,23 @@
+/**
+ * Family-agnostic textual preview of a migration plan, used by the CLI to
+ * render a "DDL preview" section for `db init` / `db update` / `migration plan`
+ * / `migration show`. Each statement carries a free-form `language` tag so
+ * formatters can suffix `;` for SQL but render Mongo shell lines verbatim.
+ *
+ * Producers are family-specific: SQL emits `language: 'sql'` (existing DDL
+ * extraction); Mongo emits `language: 'mongodb-shell'` via the
+ * `MongoDdlCommandFormatter` visitor.
+ *
+ * The capability `OperationPreviewCapable` (declared in
+ * `./control-capabilities`) is how a family announces it can produce these.
+ */
+
+export interface OperationPreviewStatement {
+  readonly text: string;
+  /** Dialect identifier, e.g. `'sql'`, `'mongodb-shell'`. Free-form by design (OQ-3). */
+  readonly language: string;
+}
+
+export interface OperationPreview {
+  readonly statements: readonly OperationPreviewStatement[];
+}

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

@@ -1,25 +1,25 @@
-import type { CodecLookup } from './codec-types';
-import type {
-  ControlAdapterDescriptor,
-  ControlDriverDescriptor,
-  ControlExtensionDescriptor,
-  ControlFamilyDescriptor,
-  ControlTargetDescriptor,
-} from './control-descriptors';
+import type { CodecLookup } from '../shared/codec-types';
 import type {
   AuthoringContributions,
   AuthoringFieldNamespace,
   AuthoringFieldPresetDescriptor,
   AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from './framework-authoring';
-import type { ComponentMetadata } from './framework-components';
+} from '../shared/framework-authoring';
+import type { ComponentMetadata } from '../shared/framework-components';
 import type {
   ControlMutationDefaultEntry,
   ControlMutationDefaults,
   MutationDefaultGeneratorDescriptor,
-} from './mutation-default-types';
-import type { TypesImportSpec } from './types-import-spec';
+} from '../shared/mutation-default-types';
+import type { TypesImportSpec } from '../shared/types-import-spec';
+import type {
+  ControlAdapterDescriptor,
+  ControlDriverDescriptor,
+  ControlExtensionDescriptor,
+  ControlFamilyDescriptor,
+  ControlTargetDescriptor,
+} from './control-descriptors';
 
 export interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
@@ -328,7 +328,7 @@ export function assembleControlMutationDefaults(
 export function extractCodecLookup(
   descriptors: ReadonlyArray<Pick<ComponentMetadata & { id?: string }, 'types' | 'id'>>,
 ): CodecLookup {
-  const byId = new Map<string, import('./codec-types').Codec>();
+  const byId = new Map<string, import('../shared/codec-types').Codec>();
   const owners = new Map<string, string>();
   for (const descriptor of descriptors) {
     const codecInstances = descriptor.types?.codecTypes?.codecInstances;

package/src/{emission-types.ts → control/emission-types.ts}

@@ -1,5 +1,5 @@
 import type { Contract, ContractModel } from '@prisma-next/contract/types';
-import type { TypesImportSpec } from './types-import-spec';
+import type { TypesImportSpec } from '../shared/types-import-spec';
 
 export interface GenerateContractTypesOptions {
   readonly queryOperationTypeImports?: ReadonlyArray<TypesImportSpec>;

package/src/control/psl-ast.ts

@@ -0,0 +1,193 @@
+export interface PslPosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+
+export interface PslSpan {
+  readonly start: PslPosition;
+  readonly end: PslPosition;
+}
+
+export type PslDiagnosticCode =
+  | 'PSL_UNTERMINATED_BLOCK'
+  | 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK'
+  | 'PSL_INVALID_ATTRIBUTE_SYNTAX'
+  | 'PSL_INVALID_MODEL_MEMBER'
+  | 'PSL_UNSUPPORTED_MODEL_ATTRIBUTE'
+  | 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE'
+  | 'PSL_INVALID_RELATION_ATTRIBUTE'
+  | 'PSL_INVALID_REFERENTIAL_ACTION'
+  | 'PSL_INVALID_DEFAULT_VALUE'
+  | 'PSL_INVALID_ENUM_MEMBER'
+  | 'PSL_INVALID_TYPES_MEMBER';
+
+export interface PslDiagnostic {
+  readonly code: PslDiagnosticCode;
+  readonly message: string;
+  readonly sourceId: string;
+  readonly span: PslSpan;
+}
+
+export interface PslDefaultFunctionValue {
+  readonly kind: 'function';
+  readonly name: 'autoincrement' | 'now';
+}
+
+export interface PslDefaultLiteralValue {
+  readonly kind: 'literal';
+  readonly value: string | number | boolean;
+}
+
+export type PslDefaultValue = PslDefaultFunctionValue | PslDefaultLiteralValue;
+
+export type PslAttributeTarget = 'field' | 'model' | 'enum' | 'namedType';
+
+export interface PslAttributePositionalArgument {
+  readonly kind: 'positional';
+  readonly value: string;
+  readonly span: PslSpan;
+}
+
+export interface PslAttributeNamedArgument {
+  readonly kind: 'named';
+  readonly name: string;
+  readonly value: string;
+  readonly span: PslSpan;
+}
+
+export type PslAttributeArgument = PslAttributePositionalArgument | PslAttributeNamedArgument;
+
+export interface PslTypeConstructorCall {
+  readonly kind: 'typeConstructor';
+  readonly path: readonly string[];
+  readonly args: readonly PslAttributeArgument[];
+  readonly span: PslSpan;
+}
+
+export interface PslAttribute {
+  readonly kind: 'attribute';
+  readonly target: PslAttributeTarget;
+  readonly name: string;
+  readonly args: readonly PslAttributeArgument[];
+  readonly span: PslSpan;
+}
+
+export type PslReferentialAction = string;
+
+export type PslFieldAttribute = PslAttribute;
+
+export interface PslField {
+  readonly kind: 'field';
+  readonly name: string;
+  readonly typeName: string;
+  readonly typeConstructor?: PslTypeConstructorCall;
+  readonly optional: boolean;
+  readonly list: boolean;
+  readonly typeRef?: string;
+  readonly attributes: readonly PslFieldAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslUniqueConstraint {
+  readonly kind: 'unique';
+  readonly fields: readonly string[];
+  readonly span: PslSpan;
+}
+
+export interface PslIndexConstraint {
+  readonly kind: 'index';
+  readonly fields: readonly string[];
+  readonly span: PslSpan;
+}
+
+export type PslModelAttribute = PslAttribute;
+
+export interface PslModel {
+  readonly kind: 'model';
+  readonly name: string;
+  readonly fields: readonly PslField[];
+  readonly attributes: readonly PslModelAttribute[];
+  readonly span: PslSpan;
+  /**
+   * Optional leading comment line emitted above the `model` keyword by the
+   * printer. Producers (e.g. `sqlSchemaIrToPslAst`) attach introspection
+   * advisories such as "// WARNING: This table has no primary key in the
+   * database" here. The parser leaves this field unset; round-tripping a
+   * parsed schema does not re-attach comments.
+   */
+  readonly comment?: string;
+}
+
+export interface PslEnumValue {
+  readonly kind: 'enumValue';
+  readonly name: string;
+  /**
+   * Optional storage label for the enum member, captured from a trailing
+   * `@map("...")` attribute on the member line. The parser populates this
+   * when the source PSL carries an explicit `@map`. Producers (e.g.
+   * `sqlSchemaIrToPslAst`) leave it unset; the printer emits `@map(...)`
+   * automatically when normalisation would change the printed member name
+   * (so an enum value `'in-progress'` becomes `inProgress @map("in-progress")`
+   * in PSL, preserving the round-trip).
+   */
+  readonly mapName?: string;
+  readonly span: PslSpan;
+}
+
+export interface PslEnum {
+  readonly kind: 'enum';
+  readonly name: string;
+  readonly values: readonly PslEnumValue[];
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslCompositeType {
+  readonly kind: 'compositeType';
+  readonly name: string;
+  readonly fields: readonly PslField[];
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslNamedTypeDeclaration {
+  readonly kind: 'namedType';
+  readonly name: string;
+  /**
+   * Parser invariant: exactly one of `baseType` and `typeConstructor` is set.
+   * Expressing this as a discriminated union trips TypeScript narrowing when
+   * the declaration flows through helpers that accept the full union.
+   */
+  readonly baseType?: string;
+  readonly typeConstructor?: PslTypeConstructorCall;
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslTypesBlock {
+  readonly kind: 'types';
+  readonly declarations: readonly PslNamedTypeDeclaration[];
+  readonly span: PslSpan;
+}
+
+export interface PslDocumentAst {
+  readonly kind: 'document';
+  readonly sourceId: string;
+  readonly models: readonly PslModel[];
+  readonly enums: readonly PslEnum[];
+  readonly compositeTypes: readonly PslCompositeType[];
+  readonly types?: PslTypesBlock;
+  readonly span: PslSpan;
+}
+
+export interface ParsePslDocumentInput {
+  readonly schema: string;
+  readonly sourceId: string;
+}
+
+export interface ParsePslDocumentResult {
+  readonly ast: PslDocumentAst;
+  readonly diagnostics: readonly PslDiagnostic[];
+  readonly ok: boolean;
+}

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

@@ -1,3 +1,10 @@
+import type {
+  AdapterDescriptor,
+  DriverDescriptor,
+  ExtensionDescriptor,
+  FamilyDescriptor,
+  TargetDescriptor,
+} from '../shared/framework-components';
 import type {
   RuntimeAdapterInstance,
   RuntimeDriverInstance,
@@ -6,13 +13,6 @@ import type {
   RuntimeTargetInstance,
 } from './execution-instances';
 import type { ExecutionStack } from './execution-stack';
-import type {
-  AdapterDescriptor,
-  DriverDescriptor,
-  ExtensionDescriptor,
-  FamilyDescriptor,
-  TargetDescriptor,
-} from './framework-components';
 
 export interface RuntimeFamilyDescriptor<
   TFamilyId extends string,

package/src/{execution-instances.ts → execution/execution-instances.ts}

@@ -4,7 +4,7 @@ import type {
   ExtensionInstance,
   FamilyInstance,
   TargetInstance,
-} from './framework-components';
+} from '../shared/framework-components';
 
 export interface RuntimeFamilyInstance<TFamilyId extends string>
   extends FamilyInstance<TFamilyId> {}

package/src/{execution-requirements.ts → execution/execution-requirements.ts}

@@ -1,10 +1,10 @@
+import { checkContractComponentRequirements } from '../shared/framework-components';
 import type {
   RuntimeAdapterDescriptor,
   RuntimeExtensionDescriptor,
   RuntimeFamilyDescriptor,
   RuntimeTargetDescriptor,
 } from './execution-descriptors';
-import { checkContractComponentRequirements } from './framework-components';
 
 export function assertRuntimeContractRequirementsSatisfied<
   TFamilyId extends string,

package/src/execution/race-against-abort.ts

@@ -0,0 +1,85 @@
+import type { CodecCallContext } from '../shared/codec-types';
+import type { RuntimeAbortedPhase } from './runtime-error';
+import { runtimeAborted } from './runtime-error';
+
+/**
+ * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
+ * codec-call context is already aborted at the precheck site. Centralises
+ * the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+ * every codec dispatch site repeats.
+ */
+export function checkAborted(ctx: CodecCallContext, phase: RuntimeAbortedPhase): void {
+  if (ctx.signal?.aborted) {
+    throw runtimeAborted(phase, ctx.signal.reason);
+  }
+}
+
+/**
+ * Race a per-cell `Promise.all` (or any other in-flight work promise) against
+ * the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly
+ * even when codec bodies ignore the signal. In-flight bodies that ignore the
+ * signal are abandoned and run to completion in the background — the
+ * cooperative-cancellation contract documented in ADR 204.
+ *
+ * Call sites still SHOULD pre-check `signal.aborted` and short-circuit with
+ * a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —
+ * that path is the canonical "aborted at entry" surface and avoids
+ * scheduling the work promise. As a defensive belt-and-braces, this helper
+ * also handles the already-aborted case internally: `AbortSignal` does not
+ * replay past abort events to listeners registered after the abort, so we
+ * inspect `signal.aborted` synchronously and reject with the sentinel
+ * before installing the listener. The rejection is still attributed to the
+ * abort path via the sentinel-identity check.
+ *
+ * Distinguishing the rejection source is load-bearing for AC-ERR4
+ * (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).
+ * The semantically equivalent `abortable(signal)` helper in
+ * `@prisma-next/utils` rejects with `signal.reason ?? new DOMException(...)`,
+ * which is not stably distinguishable from a codec-thrown error by identity
+ * alone (a fresh fallback DOMException is allocated per call). We instead
+ * track abort attribution with a unique sentinel: only the `onAbort` listener
+ * installed here ever rejects with the sentinel, so an `error === sentinel`
+ * identity check after the race is unambiguous.
+ *
+ * Lives in `framework-components` (rather than the SQL family, where it
+ * originated in m2) so every family runtime that needs cooperative
+ * cancellation around a codec-dispatch `Promise.all` (SQL encode + decode
+ * today, Mongo encode in m3) shares the same attribution logic.
+ */
+export async function raceAgainstAbort<T>(
+  work: Promise<T>,
+  signal: AbortSignal | undefined,
+  phase: RuntimeAbortedPhase,
+): Promise<T> {
+  if (signal === undefined) {
+    return await work;
+  }
+  const sentinel: { reason: unknown } = { reason: undefined };
+  let onAbort: (() => void) | undefined;
+
+  const abortPromise = new Promise<never>((_, reject) => {
+    if (signal.aborted) {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+      return;
+    }
+    onAbort = () => {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+
+  try {
+    return await Promise.race([work, abortPromise]);
+  } catch (error) {
+    if (error === sentinel) {
+      throw runtimeAborted(phase, sentinel.reason);
+    }
+    throw error;
+  } finally {
+    if (onAbort) {
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+}

package/src/{runtime-core.ts → execution/runtime-core.ts}

@@ -1,7 +1,10 @@
+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,
@@ -71,8 +74,16 @@ export abstract class RuntimeCore<
    * Lower a pre-lowering `TPlan` into the family's executable `TExec`.
    * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo
    * produces `{ command, ... }`.
+   *
+   * `ctx` carries per-query cancellation (and any future fields on
+   * `CodecCallContext`); concrete subclasses forward it to the
+   * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,
+   * Mongo's `resolveValue` in m3). The runtime allocates one ctx per
+   * `execute()` call and threads the same reference everywhere; the
+   * `signal` field inside may be `undefined`, but the ctx object itself
+   * is always present.
    */
-  protected abstract lower(plan: TPlan): TExec | Promise<TExec>;
+  protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
 
   /**
    * Drive the underlying transport for a lowered `TExec`. Yields raw rows
@@ -88,12 +99,25 @@ export abstract class RuntimeCore<
 
   abstract close(): Promise<void>;
 
-  execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row> {
+  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);
+      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>(

package/src/{runtime-error.ts → execution/runtime-error.ts}

@@ -5,6 +5,22 @@ export interface RuntimeErrorEnvelope extends 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).
+ */
+export const RUNTIME_ABORTED = 'RUNTIME.ABORTED' as const;
+
+/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
+export type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';
+
 /**
  * Type guard for the runtime-error envelope produced by `runtimeError`.
  *
@@ -53,3 +69,15 @@ function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
       return 'RUNTIME';
   }
 }
+
+/**
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+ * abort was observed (encode / decode / stream); cause carries `signal.reason`
+ * verbatim from the platform — native abort produces a `DOMException`,
+ * explicit `controller.abort(reason)` produces whatever the caller passed.
+ * No synthesis happens here.
+ */
+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/{runtime-middleware.ts → execution/runtime-middleware.ts}

@@ -43,6 +43,19 @@ export interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
   ): 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,
@@ -52,7 +65,10 @@ export interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
  * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
  */
 export interface RuntimeExecutor<TPlan extends QueryPlan> {
-  execute<Row>(plan: TPlan & { readonly _row?: Row }): AsyncIterableResult<Row>;
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row>;
   close(): Promise<void>;
 }
 

package/src/exports/authoring.ts

@@ -10,7 +10,7 @@ export type {
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';
 export {
   instantiateAuthoringFieldPreset,
   instantiateAuthoringTypeConstructor,
@@ -19,4 +19,4 @@ export {
   isAuthoringTypeConstructorDescriptor,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
-} from '../framework-authoring';
+} from '../shared/framework-authoring';

package/src/exports/codec.ts

@@ -1,2 +1,2 @@
-export type { Codec, CodecLookup, CodecTrait } from '../codec-types';
-export { emptyCodecLookup } from '../codec-types';
+export type { Codec, CodecCallContext, CodecLookup, CodecTrait } from '../shared/codec-types';
+export { emptyCodecLookup } from '../shared/codec-types';

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';