@prisma-next/framework-components 0.11.0 → 0.12.0

package/src/control/control-migration-types.ts

@@ -14,26 +14,12 @@ import type { ImportRequirement } from '@prisma-next/ts-render';
 import type { Result } from '@prisma-next/utils/result';
 import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
 import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
+import type { OperationContext } from './control-result-types';
 
 // ============================================================================
 // Migration Package Metadata
 // ============================================================================
 
-/**
- * Planner provenance recorded inside {@link MigrationMetadata}.
- *
- * `used` / `applied` track which migration hints the planner consulted
- * vs. which it actually applied during emission; `plannerVersion`
- * pins the planner build that produced the migration so future
- * verification passes can recognise plans authored against an older
- * planner.
- */
-export interface MigrationHints {
-  readonly used: readonly string[];
-  readonly applied: readonly string[];
-  readonly plannerVersion: string;
-}
-
 /**
  * In-memory migration metadata envelope. Every migration is
  * content-addressed: the `migrationHash` is a hash over the metadata
@@ -63,8 +49,6 @@ export interface MigrationMetadata {
   readonly migrationHash: string;
   readonly from: string | null;
   readonly to: string;
-  readonly hints: MigrationHints;
-  readonly labels: readonly string[];
   /**
    * Sorted, deduplicated list of `invariantId`s declared by the
    * migration's data-transform ops. Always present; an empty array
@@ -216,11 +200,10 @@ export interface MigrationPlan {
   /**
    * Contract space this plan applies to. Runners cross-check
    * `options.space` against `plan.spaceId` so the marker row gets keyed
-   * by the right space when applying via `executeAcrossSpaces`.
+   * by the right space when applying via {@link MigrationRunner.execute}.
    *
-   * Optional for backward compatibility with single-space callers that
-   * pre-date the contract-space aggregate; when present, runners
-   * enforce that it matches `options.space`.
+   * Optional because not every plan carries a space id; when present,
+   * runners enforce that it matches `options.space`.
    */
   readonly spaceId?: string;
   /**
@@ -316,13 +299,25 @@ export type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPl
 // ============================================================================
 
 /**
- * Success value for migration runner execution.
+ * Per-space success payload returned inside
+ * {@link MigrationRunnerSuccessValue.perSpaceResults}.
  */
-export interface MigrationRunnerSuccessValue {
+export interface MigrationRunnerPerSpaceSuccessValue {
   readonly operationsPlanned: number;
   readonly operationsExecuted: number;
 }
 
+/**
+ * Success value for migration runner execution across one or more contract
+ * spaces.
+ */
+export interface MigrationRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: MigrationRunnerPerSpaceSuccessValue;
+  }>;
+}
+
 /**
  * Failure details for migration runner execution.
  */
@@ -335,6 +330,11 @@ export interface MigrationRunnerFailure {
   readonly why?: string;
   /** Optional metadata for debugging and UX (e.g., schema issues, SQL state). */
   readonly meta?: Record<string, unknown>;
+  /**
+   * Identifier of the space whose plan caused the rollback when
+   * {@link MigrationRunner.execute} processes multiple spaces.
+   */
+  readonly failingSpace?: string;
 }
 
 /**
@@ -445,64 +445,20 @@ export interface MigrationPlanner<
  * @template TFamilyId - The family ID (e.g., 'sql', 'document')
  * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  */
-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>;
-    readonly destinationContract: unknown;
-    readonly policy: MigrationOperationPolicy;
-    readonly callbacks?: {
-      onOperationStart?(op: MigrationPlanOperation): void;
-      onOperationComplete?(op: MigrationPlanOperation): void;
-    };
-    /**
-     * Execution-time checks configuration.
-     * All checks default to `true` (enabled) when omitted.
-     */
-    readonly executionChecks?: MigrationRunnerExecutionChecks;
-    /**
-     * Active framework components participating in this composition.
-     * Families/targets can interpret this list to derive family-specific metadata.
-     * All components must have matching familyId and targetId.
-     */
-    readonly frameworkComponents: ReadonlyArray<
-      TargetBoundComponentDescriptor<TFamilyId, TTargetId>
-    >;
-  }): Promise<MigrationRunnerResult>;
-}
-
-// ============================================================================
-// Multi-space runner protocol (extension contract spaces, TML-2397)
-// ============================================================================
-
 /**
- * Per-space input for {@link MultiSpaceCapableRunner.executeAcrossSpaces}.
+ * Per-space input for {@link MigrationRunner.execute}.
  *
- * Mirrors the single-space `MigrationRunner.execute` options, extended with a
- * required `space` identifier. Each entry's `driver` must reference the same
- * connection the outer transaction is opened on (typically the same value as
- * the top-level `driver` on `executeAcrossSpaces`).
+ * Each entry's `driver` must reference the same connection the outer
+ * transaction is opened on (typically the same value as the top-level
+ * `driver` on `execute`). An apply that targets one space passes a
+ * one-element `perSpaceOptions` list.
  *
  * Family-specific runners (e.g. the SQL family's `SqlMigrationRunner`) define
  * a richer per-space option shape that is structurally compatible with this
- * one — additional optional fields (e.g. SQL's `strictVerification`,
- * `schemaName`, `callbacks`) are tolerated by the underlying runner without
- * affecting cross-target wiring.
+ * one — additional optional fields (e.g. SQL's `schemaName`, `callbacks`) are
+ * tolerated by the underlying runner without affecting cross-target wiring.
  */
-export interface MultiSpaceRunnerPerSpaceOptions<
+export interface MigrationRunnerPerSpaceOptions<
   TFamilyId extends string = string,
   TTargetId extends string = string,
 > {
@@ -513,45 +469,40 @@ export interface MultiSpaceRunnerPerSpaceOptions<
   readonly policy: MigrationOperationPolicy;
   readonly executionChecks?: MigrationRunnerExecutionChecks;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  /**
+   * When `false`, schema verification tolerates objects owned by sibling
+   * contract spaces. Aggregate apply passes `false` per space because each
+   * `destinationContract` describes only that space's slice.
+   */
+  readonly strictVerification?: boolean;
+  /**
+   * Paths and metadata forwarded to schema verification diagnostics.
+   */
+  readonly context?: OperationContext;
 }
 
-export interface MultiSpaceRunnerSuccessValue {
-  readonly perSpaceResults: ReadonlyArray<{
-    readonly space: string;
-    readonly value: MigrationRunnerSuccessValue;
-  }>;
-}
-
-export interface MultiSpaceRunnerFailure extends MigrationRunnerFailure {
-  /** Identifier of the space whose plan caused the rollback. */
-  readonly failingSpace: string;
-}
-
-export type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
-
-/**
- * Optional capability for runners that can apply a list of per-space plans.
- * Atomicity semantics differ by family:
- *
- * - SQL (`SqlMigrationRunner`) opens one outer transaction across every
- *   space; a failure on any space rolls back every space's writes.
- * - Mongo (`mongoTargetDescriptor`) cannot wrap most DDL ops in a session
- *   transaction (TML-2408), so it iterates per-space without an outer
- *   transaction and relies on per-space-internal verify-gated marker
- *   atomicity. Earlier-advanced markers are not rolled back when a later
- *   space fails; re-running resumes from the failing space.
- *
- * The capability is declared at the framework layer so CLI utilities can
- * route through it without importing any specific family directly.
- */
-export interface MultiSpaceCapableRunner<
+export interface MigrationRunner<
   TFamilyId extends string = string,
   TTargetId extends string = string,
 > {
-  executeAcrossSpaces(options: {
+  /**
+   * Apply one or more per-space migration plans against the configured driver.
+   *
+   * Each plan 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 plans and assume the
+   * `(metadata, ops)` pairs on disk have not been tampered with since emit.
+   *
+   * Atomicity semantics differ by family: SQL targets open one outer
+   * transaction across every space; Mongo iterates per-space without an
+   * outer transaction and relies on per-space verify-gated marker atomicity.
+   */
+  execute(options: {
     readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
-    readonly perSpaceOptions: ReadonlyArray<MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
-  }): Promise<MultiSpaceRunnerResult>;
+    readonly perSpaceOptions: ReadonlyArray<MigrationRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
+  }): Promise<MigrationRunnerResult>;
 }
 
 // ============================================================================

package/src/control/control-result-types.ts

@@ -85,6 +85,13 @@ export interface BaseSchemaIssue {
 
 export interface EnumValuesChangedIssue {
   readonly kind: 'enum_values_changed';
+  /**
+   * Namespace coordinate of the enum type that changed values. Populated by
+   * family verifiers that have the coordinate in scope when constructing the
+   * issue. Downstream planners trust this field as the authoritative subject
+   * coordinate and do not re-derive it by name lookup.
+   */
+  readonly namespaceId: string;
   readonly typeName: string;
   readonly addedValues: readonly string[];
   readonly removedValues: readonly string[];

package/src/execution/runtime-core.ts

@@ -119,6 +119,17 @@ export abstract class RuntimeCore<
     // satisfy `signal?: AbortSignal`).
     const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };
 
+    // Per-execute middleware context. Spread the stored runtime-level
+    // template and mint a fresh `planExecutionId` so every hook in this
+    // call observes the same value, and two executions of the same plan
+    // observe distinct values. ADR 220. The same reference is threaded
+    // through `runBeforeExecuteChain` and `runWithMiddleware`; the plan
+    // itself flows through unchanged.
+    const execCtx: RuntimeMiddlewareContext = {
+      ...self.ctx,
+      planExecutionId: crypto.randomUUID(),
+    };
+
     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.
@@ -130,13 +141,13 @@ export abstract class RuntimeCore<
       // plan before opening the row source. Families that need
       // pre-encode mutator visibility (SQL) override `execute` to
       // inject the same chain at the equivalent point.
-      await runBeforeExecuteChain<TExec>(exec, self.middleware, self.ctx);
+      await runBeforeExecuteChain<TExec>(exec, self.middleware, execCtx);
       // The driver yields raw `Record<string, unknown>`; we cast to `Row` here.
       // The Row contract is enforced by the caller via `plan._row`.
       yield* runWithMiddleware<TExec, Row>(
         exec,
         self.middleware,
-        self.ctx,
+        execCtx,
         () => self.runDriver(exec) as AsyncIterable<Row>,
       );
     }

package/src/execution/runtime-middleware.ts

@@ -79,6 +79,17 @@ export interface RuntimeMiddlewareContext {
    * scope. Existing middleware that ignore the field are unaffected.
    */
   readonly scope: 'runtime' | 'connection' | 'transaction';
+  /**
+   * Identity for one `execute()` call. The runtime mints a fresh value via
+   * `crypto.randomUUID()` when it constructs the per-execute context, and
+   * the same context reference is threaded through every middleware phase
+   * (`beforeExecute`, `intercept`, `onRow`, `afterExecute`). Every hook in
+   * one execute call therefore observes the same `planExecutionId`; two
+   * executions of the same plan observe distinct values. Use this to
+   * correlate observations across the lifecycle of a single execute call
+   * (tracing, timing, audit). See ADR 220.
+   */
+  readonly planExecutionId: string;
 }
 
 export interface AfterExecuteResult {

package/src/exports/components.ts

@@ -1,3 +1,4 @@
+export { mergeCapabilityMatrices } from '../shared/capabilities';
 export type {
   AdapterDescriptor,
   AdapterInstance,

package/src/exports/control.ts

@@ -8,7 +8,6 @@ export type {
 } from '../control/control-capabilities';
 export {
   hasMigrations,
-  hasMultiSpaceRunner,
   hasOperationPreview,
   hasPslContractInfer,
   hasSchemaView,
@@ -28,7 +27,6 @@ export type {
   ControlTargetInstance,
 } from '../control/control-instances';
 export type {
-  MigrationHints,
   MigrationMetadata,
   MigrationOperationClass,
   MigrationOperationPolicy,
@@ -43,14 +41,11 @@ export type {
   MigrationRunner,
   MigrationRunnerExecutionChecks,
   MigrationRunnerFailure,
+  MigrationRunnerPerSpaceOptions,
+  MigrationRunnerPerSpaceSuccessValue,
   MigrationRunnerResult,
   MigrationRunnerSuccessValue,
   MigrationScaffoldContext,
-  MultiSpaceCapableRunner,
-  MultiSpaceRunnerFailure,
-  MultiSpaceRunnerPerSpaceOptions,
-  MultiSpaceRunnerResult,
-  MultiSpaceRunnerSuccessValue,
   OpFactoryCall,
   SerializedQueryPlan,
   TargetMigrationsCapability,

package/src/exports/ir.ts

@@ -1,3 +1,4 @@
+export { domainElementCoordinates } from '../ir/domain';
 export type { IRNode } from '../ir/ir-node';
 export { freezeNode, IRNodeBase } from '../ir/ir-node';
 export type { Namespace } from '../ir/namespace';

package/src/ir/domain.ts

@@ -0,0 +1,23 @@
+import type { ApplicationDomain } from '@prisma-next/contract/types';
+import type { EntityCoordinate } from './storage';
+
+/**
+ * Lazy walk over every named domain entity in a {@link ApplicationDomain},
+ * yielded as {@link EntityCoordinate} tuples with `plane: 'domain'`.
+ *
+ * Same structural rules as {@link elementCoordinates} over storage: skip
+ * scalar `id`; each other object-valued property is an entity-kind slot.
+ */
+export function* domainElementCoordinates(
+  domain: Pick<ApplicationDomain, 'namespaces'>,
+): Generator<EntityCoordinate> {
+  for (const [namespaceId, ns] of Object.entries(domain.namespaces)) {
+    for (const [entityKind, slot] of Object.entries(ns)) {
+      if (entityKind === 'id') continue;
+      if (slot === null || typeof slot !== 'object') continue;
+      for (const entityName of Object.keys(slot)) {
+        yield { plane: 'domain', namespaceId, entityKind, entityName };
+      }
+    }
+  }
+}

package/src/ir/ir-node.ts

@@ -17,7 +17,7 @@
  * through a union of leaves where each leaf carries a literal kind, so
  * requiring `kind` at the base would be unearned. Future leaves that
  * earn polymorphic dispatch override with a required literal at that
- * leaf (e.g. `override readonly kind = 'postgres-enum' as const`).
+ * leaf (e.g. `override readonly kind = 'pack-contributed-kind' as const`).
  *
  * `IRNodeBase` carries no methods: the freeze-and-assign affordance
  * lives in the free `freezeNode` helper below. Keeping `freezeNode` out

package/src/ir/namespace.ts

@@ -1,3 +1,4 @@
+import type { StorageNamespace } from '@prisma-next/contract/types';
 import { type IRNode, IRNodeBase } from './ir-node';
 
 /**
@@ -44,8 +45,8 @@ export const UNBOUND_NAMESPACE_ID = '__unbound__' as const;
  * own native idiom). Generic consumers walking "all named entries" go
  * through a family-typed namespace, not the framework `Namespace`.
  *
- * Every namespace concretion (e.g. `SqlNamespacePayload`,
- * `MongoNamespacePayload`, target-promoted namespaces like
+ * Every namespace concretion (e.g. family-built SQL namespaces,
+ * `MongoUnboundNamespace`, target-promoted namespaces like
  * `PostgresSchema`) carries exactly: `id` (enumerable string), `kind`
  * (non-enumerable string discriminator set via `Object.defineProperty`),
  * and one or more entity-kind slot maps — each an own-enumerable property
@@ -57,8 +58,7 @@ export const UNBOUND_NAMESPACE_ID = '__unbound__' as const;
  * on this invariant to enumerate entities structurally without
  * family-specific knowledge.
  */
-export interface Namespace extends IRNode {
-  readonly id: string;
+export interface Namespace extends IRNode, StorageNamespace {
   readonly kind: string;
 }
 

package/src/ir/storage-type.ts

@@ -6,7 +6,7 @@ import type { IRNode } from './ir-node';
  * The slot is polymorphic at the framework level: a family or target can
  * persist either a JSON-clean codec-triple object literal (carrying
  * `kind: 'codec-instance'`) or a class-instance IR node with a narrower
- * kind discriminator (e.g. `'postgres-enum'`). Hydration walkers,
+ * kind discriminator (e.g. `'<kind>'`). Hydration walkers,
  * verifiers, and planners dispatch on the `kind` literal to recover the
  * precise variant.
  *

package/src/ir/storage.ts

@@ -1,3 +1,4 @@
+import type { StorageBase } from '@prisma-next/contract/types';
 import type { IRNode } from './ir-node';
 import type { Namespace } from './namespace';
 
@@ -5,10 +6,9 @@ import type { Namespace } from './namespace';
  * Canonical address for a named entity in Contract IR / Schema IR.
  *
  * `plane` is `'domain' | 'storage'`: which top-level contract plane the
- * entity lives on. Domain-side walks (once domain content is populated)
- * yield `plane: 'domain'`; {@link elementCoordinates} over storage yields
- * `plane: 'storage'`. A sibling `elementCoordinates(domain)` is not wired
- * yet — domain-plane content lands in S1.C; the sibling walk lands there.
+ * entity lives on. Domain-side walks yield `plane: 'domain'` via
+ * {@link domainElementCoordinates}; {@link elementCoordinates} over storage
+ * yields `plane: 'storage'`.
  *
  * Cross-plane references obey a directional invariant: domain → storage is
  * allowed; storage → domain is forbidden. That rule is enforced by a
@@ -36,7 +36,9 @@ export interface EntityCoordinate {
  * property whose value is a non-null object, yields one coordinate per
  * entry key in that map. No family-specific slot vocabulary is required.
  */
-export function* elementCoordinates(storage: Storage): Generator<EntityCoordinate> {
+export function* elementCoordinates(
+  storage: Pick<StorageBase, 'namespaces'>,
+): Generator<EntityCoordinate> {
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
     for (const [entityKind, slot] of Object.entries(ns)) {
       if (entityKind === 'id') continue;

package/src/shared/capabilities.ts

@@ -0,0 +1,90 @@
+/**
+ * Capability matrix merge primitive shared by emit-time and runtime stack composition.
+ *
+ * The CLI's `enrichContract` and the SQL runtime's `createExecutionContext` both need
+ * to fold a stack of component descriptors' `capabilities` declarations into a single
+ * matrix keyed by namespace. Keeping the primitive here lets both call sites stay
+ * byte-for-byte consistent without one depending on the other.
+ */
+
+import { blindCast } from '@prisma-next/utils/casts';
+
+type CapabilityMatrix = Record<string, Record<string, boolean>>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortDeep);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  const next: Record<string, unknown> = {};
+  for (const [key, child] of entries) {
+    next[key] = sortDeep(child);
+  }
+  return next;
+}
+
+function extractCapabilityMatrix(value: unknown): CapabilityMatrix {
+  if (!isPlainObject(value)) return {};
+
+  const out: CapabilityMatrix = {};
+  for (const [namespace, maybeCaps] of Object.entries(value)) {
+    if (!isPlainObject(maybeCaps)) continue;
+    const caps: Record<string, boolean> = {};
+    for (const [key, flag] of Object.entries(maybeCaps)) {
+      if (typeof flag === 'boolean') {
+        caps[key] = flag;
+      }
+    }
+    if (Object.keys(caps).length > 0) {
+      out[namespace] = caps;
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Merge an ordered list of contributor capability declarations into a base matrix.
+ *
+ * Behaviour:
+ * - `base` and each contributor's `capabilities` are filtered through the same
+ *   structural extraction: non-plain-object namespace blocks are dropped,
+ *   non-boolean leaves inside a namespace block are dropped, and a namespace
+ *   block that ends up with zero boolean leaves is omitted entirely (so a
+ *   later contributor with a malformed namespace cannot erase a namespace
+ *   already present in `base`).
+ * - Non-plain-object `capabilities` on a contributor (including `undefined`,
+ *   `null`, arrays, primitives) are skipped silently — the contributor
+ *   contributes nothing.
+ * - Later contributors win on `(namespace, key)` collisions.
+ * - The returned object is fresh — neither `base` nor any contributor is mutated.
+ * - Output keys are sorted lexicographically at every plain-object level.
+ */
+export function mergeCapabilityMatrices(
+  base: Record<string, Record<string, boolean>>,
+  contributors: ReadonlyArray<{ readonly capabilities?: unknown }>,
+): Record<string, Record<string, boolean>> {
+  const merged: CapabilityMatrix = extractCapabilityMatrix(base);
+
+  for (const contributor of contributors) {
+    const extracted = extractCapabilityMatrix(contributor.capabilities);
+    for (const [namespace, capabilities] of Object.entries(extracted)) {
+      merged[namespace] = {
+        ...(merged[namespace] ?? {}),
+        ...capabilities,
+      };
+    }
+  }
+
+  return blindCast<
+    CapabilityMatrix,
+    "sortDeep preserves the matrix shape but the recursive generic relationship can't be expressed to TS"
+  >(sortDeep(merged));
+}