@prisma-next/framework-components 0.5.0-dev.5 → 0.5.0-dev.50

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
@@ -28,61 +28,23 @@ import type { TargetBoundComponentDescriptor } from './framework-components';
 export type MigrationOperationClass = 'additive' | 'widening' | 'destructive' | 'data';
 
 // ============================================================================
-// Data Transform Operation
+// Serialized Query Plan
 // ============================================================================
 
 /**
  * A lowered query statement as stored in ops.json.
  * Contains the SQL string and parameter values — ready for execution.
  * Lowering from query builder AST to SQL happens at verify time.
+ *
+ * The Postgres `dataTransform` factory uses this shape internally to
+ * carry the user's lowered `check`/`run` plans before wrapping them
+ * into precheck/execute/postcheck steps on the unified migration op.
  */
 export interface SerializedQueryPlan {
   readonly sql: string;
   readonly params: readonly unknown[];
 }
 
-/**
- * A data transform operation within a migration edge.
- *
- * Data transforms are authored in TypeScript using the query builder,
- * serialized to JSON ASTs at verification time, and rendered to SQL
- * by the target adapter at apply time.
- *
- * The `name` serves as the invariant identity — it's recorded in the
- * ledger and used for invariant-aware routing via environment refs.
- *
- * In draft state (before verification), `check` and `run` are null.
- * After verification, they contain the serialized query ASTs.
- */
-export interface DataTransformOperation extends MigrationPlanOperation {
-  readonly operationClass: 'data';
-  /**
-   * The invariant name for this data transform.
-   * Recorded in the ledger on successful edge completion.
-   * Used by environment refs to declare required invariants.
-   */
-  readonly name: string;
-  /**
-   * Path to the TypeScript source file that produced this operation.
-   * Not part of edgeId computation — for traceability only.
-   */
-  readonly source: string;
-  /**
-   * Serialized check query plan, or a boolean literal.
-   * - SerializedQueryPlan: describes violations; empty result = already applied.
-   * - false: always run (no check).
-   * - true: always skip.
-   * - null: not yet serialized (draft state).
-   */
-  readonly check: SerializedQueryPlan | boolean | null;
-  /**
-   * Serialized run query plans.
-   * - Array of serialized query plans to execute sequentially.
-   * - null: not yet serialized (draft state).
-   */
-  readonly run: readonly SerializedQueryPlan[] | null;
-}
-
 /**
  * Policy defining which operation classes are allowed during a migration.
  */
@@ -105,6 +67,17 @@ export interface MigrationPlanOperation {
   readonly label: string;
   /** The class of operation (additive, widening, destructive). */
   readonly operationClass: MigrationOperationClass;
+  /**
+   * Optional opt-in routing identity for data-transform operations.
+   * Presence opts the transform into invariant-aware routing; absence
+   * means it is path-dependent and not referenceable from refs.
+   *
+   * Lives on the base op so the manifest emitter and
+   * `deriveProvidedInvariants` can read it without depending on a
+   * target-specific shape. Schema-DDL ops (additive / widening /
+   * destructive) leave it undefined.
+   */
+  readonly invariantId?: string;
 }
 
 // ============================================================================
@@ -151,6 +124,17 @@ export interface MigrationPlan {
   };
   /** Ordered list of operations to execute. */
   readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids declared by this plan's data-transform
+   * ops. Authored migrations carry the canonical value from
+   * `migration.json.providedInvariants`; planner-built plans (`db init`,
+   * `db update`) omit it (the runner treats it as `[]`). Runners read this
+   * field for marker writes and self-edge no-op detection rather than
+   * re-deriving from `operations`, since the manifest is the canonical
+   * source for the invariant set across all runners (postgres, sqlite,
+   * mongo).
+   */
+  readonly providedInvariants?: readonly string[];
 }
 
 /**
@@ -289,21 +273,23 @@ export interface MigrationPlanner<
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
-    /**
-     * Storage hash of the "from" contract (the state the planner assumes the
-     * database starts at). Planners use this to populate `describe()` on the
-     * produced plan so the rendered `migration.ts` has correct `from`/`to`
-     * metadata.
-     */
-    readonly fromHash: string;
     /**
      * The "from" contract (the state the planner assumes the database starts
-     * at). Planners pass this to data-safety strategies so they can compare
-     * `from` and `to` column shapes (e.g. to detect unsafe type changes).
-     * `db update` / `db init` reconcile against the live schema and have no
-     * "from" contract; only `migration plan` provides one.
+     * at), or `null` for a baseline plan with no prior state.
+     *
+     * Planners derive any "from" identity they need to stamp onto the
+     * produced plan's `describe()` from `fromContract?.storage.storageHash
+     * ?? null`. They also pass this to data-safety strategies so they can
+     * compare `from` and `to` column shapes (e.g. to detect unsafe type
+     * changes).
+     *
+     * Required at every call site to make the structural fact "I have a
+     * prior contract / I don't" visible in the type. Reconciliation
+     * commands (`db init`, `db update`) introspect a live schema and pass
+     * `null`; authoring commands (`migration plan`) pass the previous
+     * bundle's `metadata.toContract`.
      */
-    readonly fromContract?: unknown;
+    readonly fromContract: Contract | null;
     /**
      * Active framework components participating in this composition.
      * Families/targets can interpret this list to derive family-specific metadata.
@@ -335,6 +321,16 @@ export interface MigrationRunner<
   TFamilyId extends string = string,
   TTargetId extends string = string,
 > {
+  /**
+   * Execute a migration plan against the configured driver.
+   *
+   * The `plan` parameter is trusted input. Callers are responsible for
+   * upstream verification of the originating migration package — typically
+   * by obtaining the package via `readMigrationPackage` from
+   * `@prisma-next/migration-tools/io`, which performs hash-integrity checks
+   * at the load boundary. Runners do not re-verify the plan and assume the
+   * `(metadata, ops)` pair on disk has not been tampered with since emit.
+   */
   execute(options: {
     readonly plan: MigrationPlan;
     readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
@@ -414,11 +410,12 @@ export interface MigrationScaffoldContext {
   /** Absolute path to the contract.json file, if one exists. Used by targets that emit typed-contract imports. */
   readonly contractJsonPath?: string;
   /**
-   * Storage hash of the "from" contract. Targets use this to populate
-   * `describe()` on the rendered empty migration so that identity metadata
-   * is correctly populated.
+   * Storage hash of the "from" contract, or `null` for a baseline scaffold
+   * with no prior state. Targets use this to populate `describe()` on the
+   * rendered empty migration so that identity metadata is correctly
+   * populated.
    */
-  readonly fromHash: string;
+  readonly fromHash: string | null;
   /**
    * Storage hash of the "to" contract. Same purpose as `fromHash` — threaded
    * through so the rendered class's `describe()` declares the correct

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/control/emission-types.ts

@@ -0,0 +1,49 @@
+import type { Contract, ContractModel } from '@prisma-next/contract/types';
+import type { TypesImportSpec } from '../shared/types-import-spec';
+
+export interface GenerateContractTypesOptions {
+  readonly queryOperationTypeImports?: ReadonlyArray<TypesImportSpec>;
+}
+
+export interface ValidationContext {
+  readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly extensionIds?: ReadonlyArray<string>;
+}
+
+export interface EmissionSpi {
+  readonly id: string;
+
+  generateStorageType(contract: Contract, storageHashTypeName: string): string;
+
+  generateModelStorageType(modelName: string, model: ContractModel): string;
+
+  getFamilyImports(): string[];
+
+  getFamilyTypeAliases(options?: GenerateContractTypesOptions): string;
+
+  getTypeMapsExpression(): string;
+
+  getContractWrapper(contractBaseName: string, typeMapsName: string): string;
+
+  /**
+   * Per-family resolver for typeParams that don't live inline on the
+   * framework-domain `ContractField`. Some families (notably SQL) let columns
+   * reference a named entry in `storage.types` via `typeRef`; the typeParams
+   * live on that named entry rather than on the domain field. The framework
+   * emit path consults this hook so the codec's `renderOutputType` can run
+   * for typeRef-shaped columns.
+   *
+   * Inline `field.type.typeParams` always takes precedence; the hook is only
+   * consulted when the domain field has no typeParams. Families without
+   * named storage types (e.g. mongo) don't implement this hook.
+   *
+   * Returns `undefined` when the field has no resolvable typeParams.
+   */
+  resolveFieldTypeParams?(
+    modelName: string,
+    fieldName: string,
+    model: ContractModel,
+    contract: Contract,
+  ): Record<string, unknown> | undefined;
+}

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/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/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);
+    }
+  }
+}