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

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

@@ -1,25 +1,30 @@
-import type { CodecLookup } from './codec-types';
-import type {
-  ControlAdapterDescriptor,
-  ControlDriverDescriptor,
-  ControlExtensionDescriptor,
-  ControlFamilyDescriptor,
-  ControlTargetDescriptor,
-} from './control-descriptors';
+import type { Codec } from '../shared/codec';
+import type { CodecLookup, CodecMeta } 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 {
+  assertNoCrossRegistryCollisions,
+  isAuthoringFieldPresetDescriptor,
+  isAuthoringTypeConstructorDescriptor,
+  mergeAuthoringNamespaces,
+} 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;
@@ -153,70 +158,6 @@ export function extractComponentIds(
   return ids;
 }
 
-function isTypeConstructorDescriptor(value: unknown): value is AuthoringTypeConstructorDescriptor {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    (value as { kind?: unknown }).kind === 'typeConstructor'
-  );
-}
-
-function isFieldPresetDescriptor(value: unknown): value is AuthoringFieldPresetDescriptor {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    (value as { kind?: unknown }).kind === 'fieldPreset'
-  );
-}
-
-function mergeAuthoringNamespaces(
-  target: Record<string, unknown>,
-  source: Record<string, unknown>,
-  path: readonly string[],
-  leafGuard: (value: unknown) => boolean,
-  label: string,
-): void {
-  const assertSafePath = (currentPath: readonly string[]) => {
-    const blockedSegment = currentPath.find(
-      (segment) => segment === '__proto__' || segment === 'constructor' || segment === 'prototype',
-    );
-    if (blockedSegment) {
-      throw new Error(
-        `Invalid authoring ${label} helper "${currentPath.join('.')}". Helper path segments must not use "${blockedSegment}".`,
-      );
-    }
-  };
-
-  for (const [key, sourceValue] of Object.entries(source)) {
-    const currentPath = [...path, key];
-    assertSafePath(currentPath);
-    const hasExistingValue = Object.hasOwn(target, key);
-    const existingValue = hasExistingValue ? target[key] : undefined;
-
-    if (!hasExistingValue) {
-      target[key] = sourceValue;
-      continue;
-    }
-
-    const existingIsLeaf = leafGuard(existingValue);
-    const sourceIsLeaf = leafGuard(sourceValue);
-
-    if (existingIsLeaf || sourceIsLeaf) {
-      throw new Error(
-        `Duplicate authoring ${label} helper "${currentPath.join('.')}". Descriptor contributions must be unique across composed components.`,
-      );
-    }
-
-    mergeAuthoringNamespaces(
-      existingValue as Record<string, unknown>,
-      sourceValue as Record<string, unknown>,
-      currentPath,
-      leafGuard,
-      label,
-    );
-  }
-}
-
 export function assembleAuthoringContributions(
   descriptors: ReadonlyArray<{ readonly authoring?: AuthoringContributions }>,
 ): AssembledAuthoringContributions {
@@ -229,7 +170,7 @@ export function assembleAuthoringContributions(
         field,
         descriptor.authoring.field,
         [],
-        isFieldPresetDescriptor,
+        isAuthoringFieldPresetDescriptor,
         'field',
       );
     }
@@ -240,14 +181,18 @@ export function assembleAuthoringContributions(
       type,
       descriptor.authoring.type,
       [],
-      isTypeConstructorDescriptor,
+      isAuthoringTypeConstructorDescriptor,
       'type',
     );
   }
 
+  const fieldNamespace = field as AuthoringFieldNamespace;
+  const typeNamespace = type as AuthoringTypeNamespace;
+  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace);
+
   return {
-    field: field as AuthoringFieldNamespace,
-    type: type as AuthoringTypeNamespace,
+    field: fieldNamespace,
+    type: typeNamespace,
   };
 }
 
@@ -326,27 +271,65 @@ export function assembleControlMutationDefaults(
 }
 
 export function extractCodecLookup(
-  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id?: string }, 'types' | 'id'>>,
+  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id: string }, 'types' | 'id'>>,
 ): CodecLookup {
-  const byId = new Map<string, import('./codec-types').Codec>();
+  const byId = new Map<string, Codec>();
+  const targetTypesById = new Map<string, readonly string[]>();
+  const metaById = new Map<string, CodecMeta>();
+  const renderersById = new Map<string, (params: Record<string, unknown>) => string | undefined>();
   const owners = new Map<string, string>();
   for (const descriptor of descriptors) {
-    const codecInstances = descriptor.types?.codecTypes?.codecInstances;
-    if (!codecInstances) continue;
-    const descriptorId = descriptor.id ?? '<unknown>';
-    for (const codec of codecInstances) {
+    const codecTypes = descriptor.types?.codecTypes;
+    const descriptorId = descriptor.id;
+    // Descriptor-side metadata is the single source of truth for `targetTypes` / `meta` / `renderOutputType`. Every contributor ships a `codecDescriptors` list on `types.codecTypes`.
+    for (const codecDescriptor of codecTypes?.codecDescriptors ?? []) {
       assertUniqueCodecOwner({
-        codecId: codec.id,
+        codecId: codecDescriptor.codecId,
         owners,
         descriptorId,
-        entityLabel: 'codec instance',
-        entityOwnershipLabel: 'codec instance provider',
+        entityLabel: 'codec descriptor',
+        entityOwnershipLabel: 'codec descriptor provider',
       });
-      owners.set(codec.id, descriptorId);
-      byId.set(codec.id, codec);
+      owners.set(codecDescriptor.codecId, descriptorId);
+      if (Array.isArray(codecDescriptor.targetTypes)) {
+        targetTypesById.set(codecDescriptor.codecId, codecDescriptor.targetTypes);
+      }
+      if (codecDescriptor.meta !== undefined) {
+        metaById.set(codecDescriptor.codecId, codecDescriptor.meta);
+      }
+      if (typeof codecDescriptor.renderOutputType === 'function') {
+        renderersById.set(codecDescriptor.codecId, codecDescriptor.renderOutputType);
+      }
+      // Materialize a representative `Codec` instance for `byId.get()` so consumers reading the lookup's instance side (e.g. SQL renderer's cast-policy lookup, or the contract emitter's literal-default `encodeJson` resolver) keep finding the codec.
+      //
+      // Two cohorts:
+      // - Non-parameterized descriptors: factory must succeed; any throw is a real bug and we let it propagate (no silent try/catch).
+      // - Parameterized descriptors: try with empty params. Many parameterized codecs treat params as advisory (e.g. `pg/timestamptz@1` whose precision is rendered into the `nativeType` only and never read by the runtime codec), so an empty-params construction yields a usable representative for id-keyed lookups (e.g. emit-time literal-default encoding). Codecs whose factory genuinely requires params (e.g. `pg/vector@1` threading `length` into the runtime codec) will throw; for those, per-column instances are materialized at runtime by `buildContractCodecRegistry` and the id-keyed lookup miss is correct (the column-aware path resolves them).
+      if (!byId.has(codecDescriptor.codecId)) {
+        if (codecDescriptor.isParameterized) {
+          try {
+            const representative = codecDescriptor.factory({} as never)({
+              name: `<lookup:${codecDescriptor.codecId}>`,
+            } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+            byId.set(codecDescriptor.codecId, representative);
+          } catch {
+            // Factory requires concrete params; skip representative materialization. Per-column instances are built at runtime; id-keyed lookup miss is the correct outcome here.
+          }
+        } else {
+          const representative = codecDescriptor.factory(undefined as never)({
+            name: `<lookup:${codecDescriptor.codecId}>`,
+          } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+          byId.set(codecDescriptor.codecId, representative);
+        }
+      }
     }
   }
-  return { get: (id) => byId.get(id) };
+  return {
+    get: (id) => byId.get(id),
+    targetTypesFor: (id) => targetTypesById.get(id),
+    metaFor: (id) => metaById.get(id),
+    renderOutputTypeFor: (id, params) => renderersById.get(id)?.(params),
+  };
 }
 
 export function validateScalarTypeCodecIds(

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,89 @@
+import type { RuntimeAbortedPhase } from './runtime-error';
+import { runtimeAborted } from './runtime-error';
+
+/**
+ * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
+ * context is already aborted at the precheck site. Centralises the
+ * `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+ * every codec dispatch site (and the `beforeExecute` middleware phase)
+ * repeats. Accepts both the framework `CodecCallContext` and the
+ * `RuntimeMiddlewareContext`; both expose `signal?: AbortSignal`.
+ */
+export function checkAborted(
+  ctx: { readonly signal?: AbortSignal },
+  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);
+    }
+  }
+}