@prisma/orm-framework 0.16.0

package/dist/control-CBvTj7Ia.d.mts

@@ -0,0 +1,1383 @@
+import { B as LedgerEntryRecord, m as ContractMarkerRecord } from "./domain-envelope-D6Wn9AmZ-BqZKTT9U.mjs";
+import { i as ControlPolicy, t as Contract } from "./contract-types-CkdMH7F7-9EHXSwbH.mjs";
+import { u as CodecRegistry } from "./codec-types-XJO6eC9U-B_K2q0zm.mjs";
+import { E as AuthoringTypeNamespace, b as AuthoringPslBlockDescriptorNamespace, d as AuthoringFieldNamespace, g as AuthoringModelAttributeDescriptorNamespace, i as AuthoringContributions, l as AuthoringEntityTypeNamespace } from "./framework-authoring-7YMP9TwM-C9P-N6_a.mjs";
+import { t as CapabilityMatrix } from "./capabilities-Cupq4-1--C71ORI3N.mjs";
+import { t as TypesImportSpec } from "./types-import-spec-DRKzrJ20-WYwyCtil.mjs";
+import { D as TargetBoundComponentDescriptor, O as TargetDescriptor, a as ComponentMetadata, f as DriverDescriptor, g as ExtensionInstance, h as ExtensionDescriptor, k as TargetInstance, n as AdapterInstance, p as DriverInstance, t as AdapterDescriptor, u as ControlMutationDefaults, v as FamilyDescriptor, y as FamilyInstance } from "./framework-components-MFoo0sYx-G_6k9jt4.mjs";
+import { r as ImportSpecifierResolver, t as EmissionSpi } from "./emission-types-hfRVB_Yw-DpQ3hISB.mjs";
+import { m as PslDocumentAst } from "./psl-ast-Chgi8e4o-rSlBk1UV.mjs";
+import { t as ImportRequirement } from "./index-GY2oGH9L.mjs";
+import { n as JsonObject } from "./json-Dkqr3say.mjs";
+import { i as StorageSort, n as PreserveEmptyPredicate } from "./canonicalization-DFpB09nP-4OdB2nsy.mjs";
+import { r as Result } from "./result-Bpupv5vO.mjs";
+//#region ../../../1-framework/1-core/framework-components/dist/control.d.mts
+//#region src/control/contract-serializer.d.ts
+/**
+ * Framework SPI for moving a contract between its canonical on-disk JSON
+ * form and its in-memory class-hierarchy form. Both directions live on the
+ * same SPI so the conceptual seam — "the boundary where the contract
+ * crosses between persisted JSON and live class instances" — has a single
+ * named home.
+ *
+ * Both faces are needed by the framework today (round-trip property tests,
+ * drift detection, future canonicalization), not eventually. For most
+ * targets `serializeContract` is identity over JSON-clean class instances;
+ * the method exists because the seam is real, not as a convention placeholder.
+ *
+ * Implementers compose this SPI as a named property on their target
+ * descriptor (`descriptor.contractSerializer`); the descriptor itself
+ * remains the aggregator of all per-target SPIs.
+ */
+interface ContractSerializer<TContract> {
+  /**
+   * Validate the JSON shape and construct typed class instances. Throws on
+   * structural / domain / storage validation failures. Returns the typed
+   * contract on success.
+   *
+   * The method-level type parameter lets call sites that hold a
+   * precisely-typed contract literal (e.g. `typeof contract` from a
+   * generated `contract.d.ts`) recover that literal type without an
+   * external cast. The default `T = TContract` preserves the inferred
+   * return type for every caller that does not opt in.
+   */
+  deserializeContract<T extends TContract = TContract>(json: unknown): T;
+  /**
+   * Serialize a typed contract to its canonical JSON shape. Returns
+   * `JsonObject` so callers can stringify, hash, or feed the result into
+   * another SPI without re-asserting JSON-cleanness. Targets whose contract
+   * fields are JSON-clean by construction return the contract unchanged
+   * (the symmetric pair to `deserializeContract`); targets that need to
+   * canonicalize on the way out (key ordering, dropping computed-only
+   * fields, normalizing numeric encodings) do that work here.
+   */
+  serializeContract(contract: TContract): JsonObject;
+  /**
+   * Optional family-contributed preserve-empty predicate for the
+   * framework canonicalizer. When present, the canonicalizer calls this
+   * inside its default-omission walk to let the family veto the stripping
+   * of empty objects/arrays/`false` values at family-specific storage paths.
+   * Families whose storage has no such special-case paths omit this hook.
+   */
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  /**
+   * Optional family-contributed storage sort hook for the framework
+   * canonicalizer. When present, the canonicalizer applies this to the
+   * serialized `storage` subtree after the omission walk and before the
+   * final key sort. Families that need deterministic ordering of storage
+   * arrays (e.g. SQL `indexes`/`uniques`) supply this hook.
+   */
+  readonly sortStorage?: StorageSort;
+}
+//#endregion
+//#region src/control/contract-snapshot-layout.d.ts
+declare const CONTRACT_SNAPSHOTS_DIRNAME = "snapshots";
+/** Validate a storage hash for use as a directory name. */
+declare function storageHashHex(storageHash: string): string;
+/** Module specifier for the store's `contract.json`, POSIX separators. */
+declare function contractSnapshotJsonSpecifier(snapshotsImportPath: string, storageHash: string): string;
+/** Type-only module specifier for the store's `contract.d.ts` (no extension). */
+declare function contractSnapshotTypesSpecifier(snapshotsImportPath: string, storageHash: string): string;
+//#endregion
+//#region src/control/schema-diff.d.ts
+/**
+ * A root-anchored chain of `(nodeKind, id)` steps identifying a node in a
+ * schema tree — the same vocabulary the differ pairs siblings with. Used by
+ * `DiffableNode.dependsOn` to name a node's structural prerequisites without
+ * holding a reference to the node itself (the target may live on the other
+ * diff side, or not exist at all).
+ */
+type SchemaNodeRef = readonly {
+  readonly nodeKind: string;
+  readonly id: string;
+}[];
+interface SchemaDiffIssue<TNode extends DiffableNode = DiffableNode> {
+  /** Path from the root node down to the diffed node, as a sequence of local keys. */
+  readonly path: readonly string[];
+  /** The expected (desired-side) node, when available. Absent for a drop. */
+  readonly expected?: TNode;
+  /** The actual (current-side) node, when available. Absent for a create. */
+  readonly actual?: TNode;
+  /**
+   * Paths of the other in-diff issues this issue depends on. Mirrored by
+   * `diffSchemas` from the node's own `dependsOn` refs: a ref resolves to a
+   * path only when some emitted issue sits at that exact path with a
+   * matching `nodeKind` — a ref whose target produced no issue is dropped
+   * (the dependency is satisfied by reality).
+   */
+  readonly dependsOn?: readonly (readonly string[])[];
+}
+/**
+ * The three ways an actual state can fail an expectation: it lacks a node that
+ * was expected (`not-found`), holds a node that was not expected
+ * (`not-expected`), or holds a node not equal to the expected one
+ * (`not-equal`). Expected is the desired side, actual the current side, of
+ * whatever comparison produced the issue (contract-vs-database, or
+ * contract-vs-contract in an offline plan), so the vocabulary is
+ * comparison-relative and never ambiguous about a base — and reads cleanly for
+ * both the planner and `db verify`.
+ *
+ * This is the RETURN TYPE of the derived {@link issueOutcome} helper, not a
+ * stored field: presence is the single source of truth, and the outcome is
+ * computed from it on demand.
+ */
+type ExpectationFailureReason = 'not-found' | 'not-expected' | 'not-equal';
+/**
+ * The outcome an issue represents, discriminated by presence rather than any
+ * stored field — the single source of truth every consumer reads. An issue
+ * always carries at least one side by construction; neither is a malformed
+ * issue and throws.
+ */
+declare function issueOutcome(issue: SchemaDiffIssue): ExpectationFailureReason;
+/**
+ * A node in the schema tree. Every node in the tree implements this interface.
+ *
+ * The differ pairs siblings by the combination of `nodeKind` and `id`, not by
+ * `id` alone: `id` needs only be unique among siblings of the same
+ * `nodeKind` at the same level, not globally unique at that level. Two
+ * distinct kinds of child in distinct slots (e.g. a role and a namespace) may
+ * legitimately share a name — they are never paired against each other, so
+ * the collision is harmless. A node never folds its kind into its id string
+ * to route around this; `nodeKind` is the discriminant that does that job.
+ * A same-`nodeKind`/same-`id` collision among siblings is a genuine
+ * duplicate and is enforced by a throw. The differ accumulates ids (not
+ * nodeKind) into a path that stamps every emitted issue.
+ */
+interface DiffableNode {
+  readonly id: string;
+  readonly nodeKind: string;
+  /**
+   * The nodes this node structurally depends on — resolved references to the
+   * prerequisites that must exist before it. Stamped by the derivation that
+   * holds the parent context; both the expected and the actual derivation
+   * stamp it by the same structural rules. Never compared by `isEqualTo`.
+   */
+  readonly dependsOn?: readonly SchemaNodeRef[];
+  isEqualTo(other: DiffableNode): boolean;
+  children(): readonly DiffableNode[];
+}
+/**
+ * Diff two schema trees starting from their roots.
+ *
+ * The differ is **total**: every node-level difference is reported. An unmatched
+ * non-leaf node emits its own issue and descends, emitting an issue for every
+ * node in the missing/extra subtree. Coalescing a parent change over its
+ * children is the planner's responsibility. Ownership filtering (dropping `extra`
+ * issues in namespaces a contract doesn't own) is the caller's responsibility.
+ */
+declare function diffSchemas(expected: DiffableNode, actual: DiffableNode): readonly SchemaDiffIssue[];
+/**
+ * The result of diffing a contract's expected schema against the introspected
+ * actual schema: one node-typed issue list. Carries no verdict, verification
+ * tree, or counts — those are the verifier's own presentation, built from the
+ * same underlying comparison.
+ *
+ * `TNode` is the concrete schema-IR node the issues carry; it defaults to
+ * `DiffableNode`, so this is purely additive — a caller that wants the
+ * concrete node opts in (the Postgres planner uses the concrete node type),
+ * everyone else keeps the default unchanged.
+ */
+declare class SchemaDiff<TNode extends DiffableNode = DiffableNode> {
+  readonly issues: readonly SchemaDiffIssue<TNode>[];
+  constructor(issues: readonly SchemaDiffIssue<TNode>[]);
+  /** Returns a new `SchemaDiff` narrowed to the issues `keep` returns true for. */
+  filter(keep: (issue: SchemaDiffIssue<TNode>) => boolean): SchemaDiff<TNode>;
+}
+//#endregion
+//#region src/control/control-operation-results.d.ts
+declare const VERIFY_CODE_MARKER_MISSING = "CONTRACT.MARKER_MISSING";
+declare const VERIFY_CODE_HASH_MISMATCH = "CONTRACT.MARKER_MISMATCH";
+declare const VERIFY_CODE_TARGET_MISMATCH = "CONTRACT.TARGET_MISMATCH";
+declare const VERIFY_CODE_SCHEMA_FAILURE = "CONTRACT.SCHEMA_VERIFICATION_FAILED";
+interface OperationContext {
+  readonly contractPath?: string;
+  readonly configPath?: string;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+interface VerifyDatabaseResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly marker?: {
+    readonly storageHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly missingCodecs?: readonly string[];
+  readonly codecCoverageSkipped?: boolean;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+/**
+ * The issue-based schema-verify result. `ok` derives from the FAILURE list
+ * only: a verify passes exactly when `schema.issues` is empty, post
+ * strict-gating and control-policy disposition.
+ *
+ * `schema.warnings` carries warn-graded issues (an `observed`-policy
+ * subject's drift, and any other `warn` disposition) in the same shape.
+ * Warnings are informational — they never affect `ok` — but they MUST be
+ * surfaced: an `observed` table that drifted yields `ok: true` with a
+ * non-empty warnings channel, which is what distinguishes "watch without
+ * failing" from full suppression.
+ */
+interface VerifyDatabaseSchemaResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly schema: {
+    readonly issues: readonly SchemaDiffIssue[];
+    readonly warnings?: {
+      readonly issues: readonly SchemaDiffIssue[];
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath?: string;
+    readonly strict: boolean;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+interface EmitContractResult {
+  readonly contractJson: string;
+  readonly contractDts: string;
+  readonly storageHash: string;
+  readonly executionHash?: string;
+  readonly profileHash: string;
+}
+interface IntrospectSchemaResult<TSchemaIR> {
+  readonly ok: true;
+  readonly summary: string;
+  readonly target: {
+    readonly familyId: string;
+    readonly id: string;
+  };
+  readonly schema: TSchemaIR;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly dbUrl?: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+interface SignDatabaseResult {
+  readonly ok: boolean;
+  readonly summary: string;
+  readonly contract: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly marker: {
+    readonly created: boolean;
+    readonly updated: boolean;
+    readonly previous?: {
+      readonly storageHash?: string;
+      readonly profileHash?: string;
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+//#endregion
+//#region src/control/control-instances.d.ts
+interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR> extends FamilyInstance<TFamilyId> {
+  /**
+   * The family seam-of-record for on-disk contract reads. Structurally
+   * validates the JSON envelope and hydrates IR-class instances via the
+   * per-target ContractSerializer. The single named entry point every
+   * CLI on-disk read crosses (TML-2536) — `as Contract` casts in
+   * production package sources are a serializer-bypass smell guarded by
+   * `pnpm lint:no-contract-cast`.
+   */
+  deserializeContract(contractJson: unknown): Contract;
+  verify(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contract: unknown;
+    readonly expectedTargetId: string;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<VerifyDatabaseResult>;
+  /**
+   * Verify a contract against an already-introspected schema.
+   *
+   * Callers that need to verify against the live database compose
+   * {@link introspect} + `verifySchema` directly. The aggregate verifier
+   * verifies each member against the full introspected schema and scopes the
+   * result to that member's contract space afterwards — it never prunes the
+   * schema up front.
+   *
+   * Synchronous — no I/O. Idempotent.
+   */
+  verifySchema(options: {
+    readonly contract: unknown;
+    readonly schema: TSchemaIR;
+    readonly strict: boolean;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
+  }): VerifyDatabaseSchemaResult;
+  sign(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contract: unknown;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<SignDatabaseResult>;
+  /**
+   * Reads the contract marker for `space` from the database, returning
+   * `null` if no marker row exists for that space (or if the marker
+   * table itself is missing).
+   *
+   * `space` is required at every call site so the type system surfaces
+   * every place that needs to thread the value: callers in app-only
+   * paths pass {@link import('./control-spaces').APP_SPACE_ID}
+   * (`'app'`); per-extension callers pass the extension's space id.
+   * Defaulting at the family-interface level was a silent bug door —
+   * it let callers forget to pass `space` and collapse onto the app's
+   * marker row.
+   *
+   * Families whose underlying storage doesn't yet support per-space
+   * markers (Mongo, today) accept `space` for interface conformance and
+   * reject any non-`APP_SPACE_ID` value rather than silently ignoring
+   * it; see the family-specific implementation for details.
+   */
+  readMarker(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly space: string;
+  }): Promise<ContractMarkerRecord | null>;
+  /**
+   * Reads every marker row keyed by `space`. Used by the per-space
+   * verifier to detect orphan marker rows and marker-vs-on-disk drift.
+   * Returns an empty map when the marker table does not yet exist.
+   */
+  readAllMarkers(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+  }): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+  /**
+   * Reads the per-migration ledger journal in apply order. When `space` is
+   * omitted, returns rows for every space. Returns an empty array when the
+   * ledger store does not yet exist or has no matching rows.
+   */
+  readLedger(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly space?: string;
+  }): Promise<readonly LedgerEntryRecord[]>;
+  introspect(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contract?: unknown;
+  }): Promise<TSchemaIR>;
+}
+interface ControlTargetInstance<TFamilyId extends string, TTargetId extends string> extends TargetInstance<TFamilyId, TTargetId> {}
+interface ControlAdapterInstance<TFamilyId extends string, TTargetId extends string> extends AdapterInstance<TFamilyId, TTargetId> {}
+interface ControlDriverInstance<TFamilyId extends string, TTargetId extends string> extends DriverInstance<TFamilyId, TTargetId> {
+  close(): Promise<void>;
+}
+interface ControlExtensionInstance<TFamilyId extends string, TTargetId extends string> extends ExtensionInstance<TFamilyId, TTargetId> {}
+//#endregion
+//#region src/control/control-migration-types.d.ts
+/**
+ * In-memory migration metadata envelope. Every migration is
+ * content-addressed: the `migrationHash` is a hash over the metadata
+ * envelope plus the operations list, computed at write time. There is no
+ * draft state — a migration directory either exists with fully attested
+ * metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with
+ * `migrationHash` hashed over `ops: []`. Re-running self-emit after the
+ * user fills the placeholder produces a *different* `migrationHash`
+ * (committed to the real ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type
+ * field-for-field — `JSON.stringify(metadata, null, 2)` is the canonical
+ * writer output (defined in `@internal/migration-tools/io`).
+ *
+ * The manifest carries identity (`from`, `to`, `migrationHash`) but
+ * not the full contract IRs themselves. The destination and predecessor
+ * contracts resolve by hash through the shared content-addressed store
+ * at `migrations/snapshots/<hex>/contract.json`. The runner depends only
+ * on `migration.json` + `ops.json` per package (plus the project-root
+ * head contract). See `docs/architecture docs/subsystems/7. Migration System.md`.
+ */
+interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string | null;
+  readonly to: string;
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
+  readonly createdAt: string;
+}
+/**
+ * Migration operation classes define the safety level of an operation.
+ * - 'additive': Adds new structures without modifying existing ones (safe)
+ * - 'widening': Relaxes constraints or expands types (generally safe)
+ * - 'destructive': Removes or alters existing structures (potentially unsafe)
+ * - 'data': Data transformation operation (e.g., backfill, type conversion)
+ */
+type MigrationOperationClass = 'additive' | 'widening' | 'destructive' | 'data';
+/**
+ * Policy defining which operation classes are allowed during a migration.
+ */
+interface MigrationOperationPolicy {
+  readonly allowedOperationClasses: readonly MigrationOperationClass[];
+}
+/**
+ * A single migration operation for display purposes.
+ * Contains only the fields needed for CLI output (tree view, JSON envelope).
+ */
+interface MigrationPlanOperation {
+  /** Unique identifier for this operation (e.g., "table.users.create"). */
+  readonly id: string;
+  /** Human-readable label for display in UI/CLI (e.g., "Create table users"). */
+  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;
+}
+/**
+ * Framework-level contract for a single factory call in a target's planner
+ * IR — the canonical shape for any node participating in the two-renderer
+ * pattern (source-text rendering for `migration.ts` + runtime-op derivation
+ * for `ops.json`).
+ *
+ * Implementations declare:
+ *
+ *   - **Identity / display metadata** (`factoryName`, `operationClass`,
+ *     `label`) used by CLI summaries and the issue planner.
+ *   - **`renderTypeScript()`** — emit the call as a TypeScript expression
+ *     suitable for inclusion in a generated `migration.ts`. Polymorphic
+ *     across postgres / mongo / sqlite / extension-owned calls.
+ *   - **`importRequirements()`** — the symbols this rendered expression
+ *     pulls in. Aggregated and deduplicated by the top-level renderer
+ *     into a single import block per file.
+ *   - **`toOp()`** — lower the call to a runtime
+ *     `MigrationPlanOperation`. Returns the framework base; concrete
+ *     implementations narrow via covariant return (e.g. SQL targets
+ *     return `SqlMigrationPlanOperation<TTargetDetails>`).
+ *
+ * Each domain (target, extension) defines its own set of concrete `*Call`
+ * classes that implement this interface — typically by extending
+ * {@link import('@prisma/orm-framework/ts-render').TsExpression} and adding the
+ * concrete `toOp()` body. Extensions can implement the interface
+ * directly without depending on a target's package-private base.
+ *
+ * @see ADR 195 — Planner IR with two renderers.
+ */
+interface OpFactoryCall {
+  /** The name of the factory that would produce this call's runtime op. */
+  readonly factoryName: string;
+  /** The operation's safety class (additive, widening, destructive, data). */
+  readonly operationClass: MigrationOperationClass;
+  /** Human-readable label for CLI output and diagnostics. */
+  readonly label: string;
+  /**
+   * Render this call as a TypeScript expression suitable for inclusion in
+   * a generated `migration.ts`. The output is composed alongside other
+   * calls' rendered expressions inside the migration's `operations`
+   * array.
+   */
+  renderTypeScript(): string;
+  /**
+   * Import requirements pulled in by the rendered TypeScript expression.
+   * Aggregated and deduplicated across all calls into a single import
+   * block per file.
+   */
+  importRequirements(): readonly ImportRequirement[];
+  /**
+   * Lower this call to a runtime migration plan operation suitable for
+   * execution / inclusion in `ops.json`. Concrete implementations narrow
+   * the return type via covariant return (e.g. SQL targets return
+   * `SqlMigrationPlanOperation<TTargetDetails>`). May return a Promise when
+   * the lowering requires async codec resolution (e.g. DDL with literal defaults).
+   */
+  toOp(): MigrationPlanOperation | Promise<MigrationPlanOperation>;
+}
+/**
+ * A migration plan for display purposes.
+ * Contains only the fields needed for CLI output (summary, JSON envelope).
+ */
+interface MigrationPlan {
+  /** The target ID this plan is for (e.g., 'postgres'). */
+  readonly targetId: string;
+  /**
+   * 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 {@link MigrationRunner.execute}.
+   *
+   * Optional because not every plan carries a space id; when present,
+   * runners enforce that it matches `options.space`.
+   */
+  readonly spaceId?: string;
+  /**
+   * Origin contract identity that the plan expects the database to currently be at.
+   * If omitted or null, the runner skips origin validation entirely.
+   */
+  readonly origin?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  } | null;
+  /** Destination contract identity that the plan intends to reach. */
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  /** Ordered list of operations to execute. May contain Promises for ops that require async codec resolution. */
+  readonly operations: readonly (MigrationPlanOperation | Promise<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[];
+}
+/**
+ * A migration plan that can also render itself back to user-editable
+ * TypeScript source (a `migration.ts` file).
+ *
+ * Planners produce this richer shape so that CLI commands can both:
+ *  - hand the plan to the runner for execution (via `MigrationPlan`), and
+ *  - materialize the plan as an editable source file via `renderTypeScript()`.
+ *
+ * User-authored migrations (`Migration` subclasses) satisfy `MigrationPlan`
+ * but not this interface: they are already the source.
+ */
+interface MigrationPlanWithAuthoringSurface extends MigrationPlan {
+  /**
+   * Render this plan back to TypeScript source suitable for writing to
+   * `migration.ts`. Output may start with a shebang; when it does, the caller
+   * should make the resulting file executable.
+   *
+   * `resolveImportSpecifier` rewrites every package name the rendered file
+   * imports for the import root the consuming application installed (ADR
+   * 242), exactly as the same resolver does for `contract.d.ts` — a
+   * scaffolded migration is a file the application keeps, so every name in
+   * it has to be one the application can resolve. The caller supplies it
+   * rather than the plan capturing it, because the project a plan is
+   * rendered into is known at the render call and not at planning time: `db
+   * init` and `db update` build plans they never render. Pass
+   * {@link import('../shared/import-specifier-resolver').keepInternalSpecifiers}
+   * to emit workspace names unchanged.
+   */
+  renderTypeScript(resolveImportSpecifier: ImportSpecifierResolver): string;
+}
+/**
+ * A conflict detected during migration planning.
+ */
+interface MigrationPlannerConflict {
+  /** Kind of conflict (e.g., 'typeMismatch', 'nullabilityConflict'). */
+  readonly kind: string;
+  /** Human-readable summary of the conflict. */
+  readonly summary: string;
+  /** Optional explanation of why this conflict occurred. */
+  readonly why?: string;
+}
+/**
+ * Successful planner result with the migration plan.
+ *
+ * The plan is typed as `MigrationPlanWithAuthoringSurface` so the CLI can
+ * uniformly ask any plan to render itself to TypeScript.
+ */
+interface MigrationPlannerSuccessResult {
+  readonly kind: 'success';
+  readonly plan: MigrationPlanWithAuthoringSurface;
+  readonly warnings?: readonly MigrationPlannerConflict[];
+}
+/**
+ * Failed planner result with the list of conflicts.
+ */
+interface MigrationPlannerFailureResult {
+  readonly kind: 'failure';
+  readonly conflicts: readonly MigrationPlannerConflict[];
+}
+/**
+ * Union type for planner results.
+ */
+type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPlannerFailureResult;
+/**
+ * Per-space success payload returned inside
+ * {@link MigrationRunnerSuccessValue.perSpaceResults}.
+ */
+interface MigrationRunnerPerSpaceSuccessValue {
+  readonly operationsPlanned: number;
+  readonly operationsExecuted: number;
+}
+/**
+ * Success value for migration runner execution across one or more contract
+ * spaces.
+ */
+interface MigrationRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: MigrationRunnerPerSpaceSuccessValue;
+  }>;
+}
+/**
+ * Failure details for migration runner execution.
+ */
+interface MigrationRunnerFailure {
+  /** Error code for the failure. */
+  readonly code: string;
+  /** Human-readable summary of the failure. */
+  readonly summary: string;
+  /** Optional explanation of why the failure occurred. */
+  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;
+}
+/**
+ * Result type for migration runner execution.
+ */
+type MigrationRunnerResult = Result<MigrationRunnerSuccessValue, MigrationRunnerFailure>;
+/**
+ * Execution-time checks configuration for migration runners.
+ * All checks default to `true` (enabled) when omitted.
+ */
+interface MigrationRunnerExecutionChecks {
+  /**
+   * Whether to run prechecks before executing operations.
+   * Defaults to `true` (prechecks are run).
+   */
+  readonly prechecks?: boolean;
+  /**
+   * Whether to run postchecks after executing operations.
+   * Defaults to `true` (postchecks are run).
+   */
+  readonly postchecks?: boolean;
+  /**
+   * Whether to run idempotency probe (check if postcheck is already satisfied before execution).
+   * Defaults to `true` (idempotency probe is run).
+   */
+  readonly idempotencyChecks?: boolean;
+}
+/**
+ * The canonical schema-IR entity coordinate: which namespace, which kind of
+ * entity, and which name. A bare entity name is not a unique identity —
+ * two namespaces can each declare an entity of the same name, and one
+ * namespace can declare two different-kind entities that share a name — so
+ * every schema-IR consumer that addresses one live or declared entity does
+ * it by this full triple.
+ *
+ * `entityKind` uses the same vocabulary as the contract storage's `entries`
+ * dictionary — the same vocabulary
+ * {@link import('../ir/storage').elementCoordinates} walks. This type has no
+ * `plane`: schema IR is storage-only (contract IR spans domain and storage,
+ * which is why its own coordinate type carries a plane), so a plane field
+ * here would always read `'storage'` and say nothing.
+ */
+interface SchemaEntityCoordinate {
+  readonly namespaceId: string;
+  readonly entityKind: string;
+  readonly entityName: string;
+}
+/**
+ * Contract-space ownership query the planner consults while planning one
+ * space against a live database.
+ *
+ * A live schema node the planned space does not own surfaces from the diff
+ * as `not-expected` (an extra). Before treating such a node as this plan's
+ * to drop, the planner asks the ownership oracle whether *any* contract
+ * space in the composition declares it: a node another (sibling) space owns
+ * is not an orphan, so it is left untouched; a node no space owns is a
+ * genuine extra the planner may drop under a destructive policy. (A node the
+ * planned space itself owns is in its expected tree and never surfaces as an
+ * extra, so a positive answer always means a sibling.)
+ *
+ * The oracle is a real domain object — the passive
+ * {@link import('@prisma/orm-toolchain/migration-tools/aggregate').ContractSpaceAggregate},
+ * which answers this from its loaded contract spaces. The planner holds no
+ * list of other spaces' names and no ownership rules of its own; it only
+ * asks. Single-space plans (offline `migration plan`) pass an aggregate of
+ * one — the same path, no special-casing.
+ */
+interface SchemaOwnership {
+  /**
+   * True when some contract space in the composition declares a storage
+   * entity at this coordinate.
+   */
+  declaresEntity(coordinate: SchemaEntityCoordinate): boolean;
+}
+/**
+ * Migration planner interface for planning schema changes.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends string = string> {
+  plan(options: {
+    readonly contract: unknown;
+    readonly schema: unknown;
+    readonly policy: MigrationOperationPolicy;
+    /**
+     * The "from" contract (the state the planner assumes the database starts
+     * 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`) read the predecessor's
+     * contract from the snapshot store by its storage hash and pass the
+     * parsed value.
+     */
+    readonly fromContract: Contract | null;
+    /**
+     * 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>>;
+    /**
+     * Contract space this plan applies to. Stamped onto the produced
+     * plan so the runner keys the marker row by the right space when
+     * executing. App-plan callers pass `APP_SPACE_ID` (`'app'`);
+     * per-extension callers pass the extension's space id.
+     */
+    readonly spaceId: string;
+    /**
+     * Ownership oracle over the whole contract-space composition (the
+     * passive aggregate). The planner asks it, per live extra node, whether
+     * any space declares that entity: a sibling-owned node is left
+     * untouched, an unowned node is a genuine extra. The planner holds no
+     * list of other spaces' names — ownership lives in the aggregate; it
+     * only asks. Absent for a single-space plan handed no aggregate.
+     * See {@link SchemaOwnership}.
+     */
+    readonly ownership?: SchemaOwnership;
+    /**
+     * POSIX-relative path from the migration package dir to
+     * `migrations/snapshots`, e.g. `'../../snapshots'`. Targets that render a
+     * family authoring surface pass this straight through to the produced
+     * plan's `renderTypeScript()` metadata. Callers that never render the
+     * produced plan to TypeScript (diff-based reconciliation for `db init` /
+     * `db update`) pass a placeholder — see `planFromDiff` in
+     * `@internal/migration-tools`.
+     */
+    readonly snapshotsImportPath: string;
+  }): MigrationPlannerResult;
+  /**
+   * Produce an empty migration with the target's authoring conventions.
+   *
+   * Used by `migration new` to scaffold a fresh `migration.ts`. The
+   * returned plan has no operations; its `renderTypeScript()` yields a
+   * stub the user can edit.
+   *
+   * `spaceId` is stamped onto the produced plan; reconciliation flows
+   * (`db init`, `db update`) and authoring flows (`migration new`) all
+   * pass it explicitly.
+   */
+  emptyMigration(context: MigrationScaffoldContext, spaceId: string): MigrationPlanWithAuthoringSurface;
+}
+/**
+ * Migration runner interface for executing migration plans.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+/**
+ * Per-space input for {@link MigrationRunner.execute}.
+ *
+ * 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 `schemaName`, `callbacks`) are
+ * tolerated by the underlying runner without affecting cross-target wiring.
+ */
+interface MigrationRunnerPerSpaceOptions<TFamilyId extends string = string, TTargetId extends string = string> {
+  readonly space: string;
+  readonly plan: MigrationPlan;
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly destinationContract: unknown;
+  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;
+  /**
+   * Per-edge breakdown from aggregate planning. Runners write one ledger row
+   * per edge in walk order.
+   */
+  readonly migrationEdges: ReadonlyArray<{
+    readonly migrationHash: string;
+    readonly dirName: string;
+    readonly from: string;
+    readonly to: string;
+    readonly operationCount: number;
+    readonly destinationContractJson?: unknown;
+  }>;
+}
+interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+  /**
+   * 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
+   * `@internal/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<MigrationRunnerPerSpaceOptions<TFamilyId, TTargetId>>;
+  }): Promise<MigrationRunnerResult>;
+}
+/**
+ * Optional capability interface for targets that support migrations.
+ * Targets that implement migrations expose this via their descriptor.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TFamilyInstance - The family instance type (e.g., SqlControlFamilyInstance)
+ */
+interface TargetMigrationsCapability<TFamilyId extends string = string, TTargetId extends string = string, TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<TFamilyId, unknown>> {
+  createPlanner(adapter: ControlAdapterInstance<TFamilyId, TTargetId>): MigrationPlanner<TFamilyId, TTargetId>;
+  createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
+  /**
+   * Synthesizes a family-specific schema IR from a contract for offline planning.
+   * The returned schema can be passed to `planner.plan({ schema })` as the "from" state.
+   *
+   * @param contract - The contract to convert, or null for a new project (empty schema).
+   * @param frameworkComponents - Active framework components, used to derive database
+   *   dependencies (e.g. extensions) that should be reflected in the schema IR.
+   * @returns Family-specific schema IR (e.g., `SqlSchemaIR` for SQL targets).
+   */
+  contractToSchema(contract: Contract | null, frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>): unknown;
+}
+/**
+ * Context for rendering migration source files.
+ *
+ * Kept minimal: only the paths a target might need to compute relative imports
+ * (e.g. the contract `.d.ts` import for typed-contract builders). Passed to
+ * `MigrationPlanner.emptyMigration(context)`.
+ */
+interface MigrationScaffoldContext {
+  /** Absolute path to the migration package directory. Used by targets to compute relative imports. */
+  readonly packageDir: string;
+  /** 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, 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 | null;
+  /**
+   * Storage hash of the "to" contract. Same purpose as `fromHash` — threaded
+   * through so the rendered class's `describe()` declares the correct
+   * destination identity.
+   */
+  readonly toHash: string;
+  /**
+   * POSIX-relative path from the migration package dir to
+   * `migrations/snapshots`, e.g. `'../../snapshots'` for an app-space
+   * package. Targets that emit contract-snapshot imports pass this straight
+   * through to their renderer's `RenderMigrationMeta.snapshotsImportPath`.
+   */
+  readonly snapshotsImportPath: string;
+}
+//#endregion
+//#region src/control/control-spaces.d.ts
+/**
+ * Canonical control-plane identifiers for contract spaces.
+ *
+ * A contract space is the disjoint `(contract.json, migration-graph)` unit
+ * the per-space planner / runner / verifier (project: extension contract
+ * spaces, TML-2397) operates on. The application owns one well-known
+ * space — the value below — and each loaded extension that contributes
+ * schema owns a uniquely-named space.
+ *
+ * Lives in `framework-components/control` so every layer that has to
+ * reason about space identity (the migration tooling, the SQL runtime's
+ * marker reader, target-side statement builders, target-side adapters)
+ * can import a single value rather than duplicating the literal. Raw
+ * `'app'` string literals in framework / target / runtime / adapter
+ * source code are forbidden and policed by
+ * `scripts/lint-app-space-id.mjs` (wired into `pnpm lint:deps`).
+ *
+ * @see specs/framework-mechanism.spec.md § 3 — Layout convention (γ).
+ */
+declare const APP_SPACE_ID: "app";
+/**
+ * Head ref for a contract space — the `(hash, invariants)` tuple
+ * a runner targets when applying that space's migration graph. Identical
+ * in shape to the on-disk `migrations/<space-id>/refs/head.json` the
+ * framework writes per loaded extension, and to the app-space
+ * `<projectRoot>/refs/head.json`. Family-agnostic: SQL, Mongo, and any
+ * future family share the same head-ref shape.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface ContractSpaceHeadRef {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+/**
+ * Canonical structural shape of a migration package — the unit a planner
+ * produces and a runner consumes: a directory name, the metadata
+ * envelope, and the operation list.
+ *
+ * In-memory by default. Readers in `@internal/migration-tools`
+ * (`readMigrationPackage` / `readMigrationsDir`) return the augmented
+ * {@link import('@prisma/orm-toolchain/migration-tools/package').OnDiskMigrationPackage}
+ * variant which adds `dirPath`; everything else operates against the
+ * canonical shape so the same value flows through pre-emission
+ * authoring, on-disk loading, and runner execution without conversion.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface MigrationPackage {
+  readonly dirName: string;
+  readonly metadata: MigrationMetadata;
+  readonly ops: readonly MigrationPlanOperation[];
+  /**
+   * Contract IR JSON of this migration's destination state, populated by
+   * the on-disk readers from the shared snapshot store entry for the
+   * migration's `to` hash when present (raw parsed JSON). Absent for
+   * packages loaded without a resolvable store entry — the runner never
+   * requires it (see ADR 199: identity is anchored on the storage-hash
+   * bookends). The edge's *start* state is deliberately not carried: it
+   * is by construction the end state of the predecessor edge, so
+   * consumers derive it from the previous row.
+   */
+  readonly endContractJson?: unknown;
+}
+/**
+ * Canonical structural shape of a contract space — one disjoint
+ * `(contractJson, migration-graph)` unit the per-space planner / runner
+ * / verifier operates on. The application owns one well-known space
+ * ({@link APP_SPACE_ID}); each loaded extension that contributes schema
+ * owns a uniquely-named space. Whether a value is the app's space or an
+ * extension's space is a control-plane concern; the type carries no
+ * such distinction.
+ *
+ * Generic over the contract so each family pins a typed contract value
+ * at consumption time. The SQL family specialises to
+ * `ContractSpace<Contract<SqlStorage>>` at the descriptor surface;
+ * Mongo's symmetrical `ContractSpace<Contract<MongoStorage>>` will land
+ * with that family.
+ *
+ * @see specs/framework-mechanism.spec.md § 1.
+ */
+interface ContractSpace<TContract extends Contract = Contract> {
+  readonly contractJson: TContract;
+  readonly migrations: readonly MigrationPackage[];
+  readonly headRef: ContractSpaceHeadRef;
+}
+//#endregion
+//#region src/control/control-stack.d.ts
+interface AssembledAuthoringContributions {
+  readonly field: AuthoringFieldNamespace;
+  readonly type: AuthoringTypeNamespace;
+  readonly entityTypes: AuthoringEntityTypeNamespace;
+  readonly pslBlockDescriptors: AuthoringPslBlockDescriptorNamespace;
+  readonly modelAttributes: AuthoringModelAttributeDescriptorNamespace;
+  /** The single {@link AuthoringContributions.valueObjectStorageType} declared across the composed components, validated at assembly against the merged `type` namespace. */
+  readonly valueObjectStorageType?: string;
+}
+interface ControlStack<TFamilyId extends string = string, TTargetId extends string = string> {
+  readonly family: ControlFamilyDescriptor<TFamilyId>;
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter?: ControlAdapterDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly extensions: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
+  readonly extensionContracts: ReadonlyMap<string, Contract>;
+  readonly codecTypeImports: ReadonlyArray<TypesImportSpec>;
+  readonly queryOperationTypeImports: ReadonlyArray<TypesImportSpec>;
+  readonly extensionIds: ReadonlyArray<string>;
+  readonly codecLookup: CodecRegistry;
+  readonly authoringContributions: AssembledAuthoringContributions;
+  /** Names of the top-level zero-arg type constructors in the assembled authoring namespace — the base scalars of the composed stack. */
+  readonly scalarTypes: ReadonlyArray<string>;
+  readonly controlMutationDefaults: ControlMutationDefaults;
+  readonly capabilities: CapabilityMatrix;
+}
+interface CreateControlStackInput<TFamilyId extends string = string, TTargetId extends string = string> {
+  readonly family: ControlFamilyDescriptor<TFamilyId>;
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter?: ControlAdapterDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly extensions?: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>> | undefined;
+}
+declare function assertUniqueCodecOwner(options: {
+  readonly codecId: string;
+  readonly owners: Map<string, string>;
+  readonly descriptorId: string;
+  readonly entityLabel: string;
+  readonly entityOwnershipLabel: string;
+}): void;
+declare function extractCodecTypeImports(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'types'>>): ReadonlyArray<TypesImportSpec>;
+declare function extractQueryOperationTypeImports(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'types'>>): ReadonlyArray<TypesImportSpec>;
+declare function extractComponentIds(family: {
+  readonly id: string;
+}, target: {
+  readonly id: string;
+}, adapter: {
+  readonly id: string;
+} | undefined, extensions: ReadonlyArray<{
+  readonly id: string;
+}>): ReadonlyArray<string>;
+declare function assembleAuthoringContributions(descriptors: ReadonlyArray<{
+  readonly id?: string;
+  readonly authoring?: AuthoringContributions;
+}>): AssembledAuthoringContributions;
+declare function assembleControlMutationDefaults(descriptors: ReadonlyArray<Pick<ComponentMetadata, 'controlMutationDefaults'> & {
+  readonly id?: string;
+}>): ControlMutationDefaults;
+declare function extractCodecLookup(descriptors: ReadonlyArray<Pick<ComponentMetadata & {
+  id: string;
+}, 'types' | 'id'>>): CodecRegistry;
+interface DependencyDeclaringDescriptor {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson?: {
+      readonly extensions?: Readonly<Record<string, unknown>>;
+    };
+  };
+}
+/**
+ * Builds a dependency-respecting load order for the given extension descriptors
+ * using Kahn's topological sort algorithm. Dependencies (packs declared in
+ * `contractSpace.contractJson.extensions`) are placed before the extensions
+ * that depend on them.
+ *
+ * Throws if the dependency graph contains a cycle, with an error message that
+ * names every extension involved in the cycle.
+ *
+ * Throws if any extension declares a dependency on a pack ID that is not present
+ * in the provided list — add the missing pack to the `extensions` list to
+ * resolve the error.
+ */
+declare function buildExtensionLoadOrder(extensions: ReadonlyArray<DependencyDeclaringDescriptor>): readonly string[];
+declare function createControlStack<TFamilyId extends string, TTargetId extends string>(input: CreateControlStackInput<TFamilyId, TTargetId>): ControlStack<TFamilyId, TTargetId>;
+//#endregion
+//#region src/control/control-descriptors.d.ts
+interface ControlFamilyDescriptor<TFamilyId extends string, TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<TFamilyId, unknown>> extends FamilyDescriptor<TFamilyId> {
+  readonly emission: EmissionSpi;
+  create<TTargetId extends string>(stack: ControlStack<TFamilyId, TTargetId>): TFamilyInstance;
+}
+interface ControlTargetDescriptor<TFamilyId extends string, TTargetId extends string, TTargetInstance extends ControlTargetInstance<TFamilyId, TTargetId> = ControlTargetInstance<TFamilyId, TTargetId>, TContract extends Contract = Contract> extends TargetDescriptor<TFamilyId, TTargetId> {
+  /**
+   * JSON ⇄ class boundary for this target's contract. Every target
+   * ships the SPI: framework consumers reach the serializer through
+   * `descriptor.contractSerializer` rather than importing a per-target
+   * `deserializeContract` helper. The descriptor IS the aggregator.
+   */
+  readonly contractSerializer: ContractSerializer<TContract>;
+  create(): TTargetInstance;
+}
+interface ControlAdapterDescriptor<TFamilyId extends string, TTargetId extends string, TAdapterInstance extends ControlAdapterInstance<TFamilyId, TTargetId> = ControlAdapterInstance<TFamilyId, TTargetId>> extends AdapterDescriptor<TFamilyId, TTargetId> {
+  /**
+   * Construct a control adapter instance for this stack.
+   *
+   * The `stack` argument mirrors `ControlFamilyDescriptor.create(stack)`:
+   * adapter implementations may inspect `stack.codecLookup`, extension packs,
+   * or other assembled metadata when constructing the instance.
+   */
+  create(stack: ControlStack<TFamilyId, TTargetId>): TAdapterInstance;
+}
+interface ControlDriverDescriptor<TFamilyId extends string, TTargetId extends string, TDriverInstance extends ControlDriverInstance<TFamilyId, TTargetId> = ControlDriverInstance<TFamilyId, TTargetId>, TConnection = string> extends DriverDescriptor<TFamilyId, TTargetId> {
+  create(connection: TConnection): Promise<TDriverInstance>;
+}
+interface ControlExtensionDescriptor<TFamilyId extends string, TTargetId extends string, TExtensionInstance extends ControlExtensionInstance<TFamilyId, TTargetId> = ControlExtensionInstance<TFamilyId, TTargetId>> extends ExtensionDescriptor<TFamilyId, TTargetId> {
+  readonly contractSpace?: ContractSpace;
+  create(): TExtensionInstance;
+}
+//#endregion
+//#region src/control/control-operation-preview.d.ts
+/**
+ * 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.
+ */
+interface OperationPreviewStatement {
+  readonly text: string;
+  /** Dialect identifier, e.g. `'sql'`, `'mongodb-shell'`. Free-form by design (OQ-3). */
+  readonly language: string;
+}
+interface OperationPreview {
+  readonly statements: readonly OperationPreviewStatement[];
+}
+//#endregion
+//#region src/control/control-schema-view.d.ts
+/**
+ * Core schema view types for family-agnostic schema visualization.
+ *
+ * These types provide a minimal, generic, tree-shaped representation of schemas
+ * across families, designed for CLI visualization and lightweight tooling.
+ *
+ * Families can optionally project their family-specific Schema IR into this
+ * core view via the `toSchemaView` method on `FamilyInstance`.
+ */
+type SchemaViewNodeKind = 'root' | 'namespace' | 'collection' | 'entity' | 'field' | 'index' | 'dependency';
+interface SchemaTreeVisitor<R> {
+  visit(node: SchemaTreeNode): R;
+}
+interface SchemaTreeNodeOptions {
+  readonly kind: SchemaViewNodeKind;
+  readonly id: string;
+  readonly label: string;
+  readonly meta?: Record<string, unknown>;
+  readonly children?: readonly SchemaTreeNode[];
+}
+declare class SchemaTreeNode {
+  readonly kind: SchemaViewNodeKind;
+  readonly id: string;
+  readonly label: string;
+  readonly meta?: Record<string, unknown>;
+  readonly children?: readonly SchemaTreeNode[];
+  constructor(options: SchemaTreeNodeOptions);
+  accept<R>(visitor: SchemaTreeVisitor<R>): R;
+}
+/**
+ * Core schema view providing a family-agnostic tree representation of a schema.
+ * Used by CLI and cross-family tooling for visualization.
+ */
+interface CoreSchemaView {
+  readonly root: SchemaTreeNode;
+}
+//#endregion
+//#region src/control/control-capabilities.d.ts
+interface MigratableTargetDescriptor<TFamilyId extends string, TTargetId extends string, TFamilyInstance extends ControlFamilyInstance<TFamilyId, unknown> = ControlFamilyInstance<TFamilyId, unknown>> extends ControlTargetDescriptor<TFamilyId, TTargetId> {
+  readonly migrations: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
+}
+declare function hasMigrations<TFamilyId extends string, TTargetId extends string>(target: ControlTargetDescriptor<TFamilyId, TTargetId>): target is MigratableTargetDescriptor<TFamilyId, TTargetId>;
+interface SchemaViewCapable<TSchemaIR = unknown> {
+  toSchemaView(schema: TSchemaIR): CoreSchemaView;
+}
+declare function hasSchemaView<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & SchemaViewCapable<TSchemaIR>;
+/**
+ * Capability declaring that a family can infer a PSL contract AST from its
+ * opaque introspected schema IR. Consumed by `prisma-next contract infer`.
+ */
+interface PslContractInferCapable<TSchemaIR = unknown> {
+  inferPslContract(schemaIR: TSchemaIR): PslDocumentAst;
+}
+declare function hasPslContractInfer<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & PslContractInferCapable<TSchemaIR>;
+/**
+ * Capability declaring that a family can render a textual preview of migration
+ * operations for the CLI's "DDL preview" output. SQL families emit
+ * `language: 'sql'` statements; Mongo families emit `language: 'mongodb-shell'`.
+ */
+interface OperationPreviewCapable {
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
+}
+declare function hasOperationPreview<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & OperationPreviewCapable;
+/**
+ * The granularity of a {@link SchemaDiffIssue}'s subject, resolved on demand
+ * from the issue's node `nodeKind` — never stamped on the issue or the node.
+ *
+ * - `namespace`: a whole namespace.
+ * - `entity`: a whole top-level entity (the thing a namespace contains).
+ * - `field`: a field of an entity.
+ * - `auxiliary`: a secondary part of an entity (an index, a default, a key).
+ * - `structural`: a cross-cutting object (an access policy, a tree root) that
+ *   is the owning space's own concern, never a sibling's unclaimed entity —
+ *   its extras fail verify in both modes.
+ */
+type DiffSubjectGranularity = 'namespace' | 'entity' | 'field' | 'auxiliary' | 'structural';
+/**
+ * Capability declaring that a family can classify a {@link SchemaDiffIssue}'s
+ * subject granularity, and separately its storage `entityKind`, on demand —
+ * both resolved from its node's `nodeKind` through the family/target
+ * vocabulary it owns. Consumed by framework code that spans contract spaces
+ * (the migration aggregate's unclaimed-elements sweep) and cannot itself read
+ * family/target node vocabulary, so it asks this capability instead of
+ * hardcoding a family entity kind. `undefined` when the issue's node kind is
+ * unrecognized, or when the family injects no classifier at all — callers
+ * fall back to path shape in that case.
+ *
+ * `classifyEntityKind` returns the same per-family vocabulary as the contract
+ * storage's `entries` dictionary keys (the vocabulary
+ * {@link import('../ir/storage').elementCoordinates} walks) — never a
+ * granularity word, and never a word this framework layer names itself.
+ */
+interface SchemaSubjectClassifierCapable {
+  classifySubjectGranularity(issue: SchemaDiffIssue): DiffSubjectGranularity | undefined;
+  classifyEntityKind(issue: SchemaDiffIssue): string | undefined;
+}
+declare function hasSchemaSubjectClassifier<TFamilyId extends string, TSchemaIR>(instance: ControlFamilyInstance<TFamilyId, TSchemaIR>): instance is ControlFamilyInstance<TFamilyId, TSchemaIR> & SchemaSubjectClassifierCapable;
+//#endregion
+//#region src/control/order-issues-by-dependencies.d.ts
+/**
+ * Orders schema-diff issues so that every dependency's op precedes its
+ * dependent on the way up and follows it on the way down, breaking ties
+ * deterministically by path.
+ *
+ * Edges come from two sources:
+ * - **`dependsOn` cross-links** — the resolved issue-to-issue paths the differ
+ *   mirrors onto each issue (a node's declared structural prerequisites). A
+ *   path that resolves to no issue in this list is skipped (the dependency is
+ *   satisfied by reality); a path shared by two same-id/different-kind siblings
+ *   links to every match, over-constraining safely.
+ * - **containment** — every issue depends on its nearest strict-ancestor issue
+ *   (a child entity on the parent entity that owns it). Subtree coalescing has
+ *   already removed the descendants of a whole create/drop, so this only links
+ *   the parent/child pairs that legitimately survive together.
+ *
+ * The ordering law reads each dependent's presence for direction: an issue that
+ * builds up (`expected` present — a create or alter) needs its dependency
+ * first; a pure drop needs its dependent removed first, so the edge reverses.
+ * The graph is a DAG by construction (dependencies point from dependents to
+ * their prerequisites, and prerequisites never point back), so a cycle is a
+ * derivation or authoring bug: the topological sort asserts acyclicity and
+ * throws, naming the issues it could not place.
+ */
+declare function orderIssuesByDependencies<TNode extends DiffableNode = DiffableNode>(issues: readonly SchemaDiffIssue<TNode>[]): readonly SchemaDiffIssue<TNode>[];
+//#endregion
+//#region src/control/schema-verifier.d.ts
+/**
+ * Framework SPI for verifying that an introspected schema matches the
+ * contract that authored it. The implementer walks the target's IR
+ * natively — concrete classes, target-only kinds — and reports issues.
+ *
+ * The framework verifier (per FR6) walks the contract-space aggregate,
+ * dispatches to the right target's verifier (`descriptor.schemaVerifier`)
+ * per space, and wraps the per-target results into a unified
+ * `VerifyDatabaseSchemaResult` with timings, summary, and the issue list.
+ *
+ * Family-level abstract bases (e.g. `SqlSchemaVerifierBase`) carry the
+ * shared SQL/Mongo walk logic and expose protected hooks for target
+ * extensions; concrete target verifiers (`PostgresSchemaVerifier extends
+ * SqlSchemaVerifierBase`) own the dispatch on target-specific kinds.
+ */
+interface SchemaVerifier<TContract, TSchema> {
+  verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult;
+}
+/**
+ * Minimal per-target verifier input. Family abstract bases extend this
+ * shape with family-specific options (`strict`, `frameworkComponents`,
+ * codec hooks, …) — the framework SPI itself stays at the contract +
+ * schema pair every implementer needs.
+ */
+interface SchemaVerifyOptions<TContract, TSchema> {
+  readonly contract: TContract;
+  readonly schema: TSchema;
+}
+/**
+ * Per-target verifier result. The framework verifier wraps these into the
+ * existing `VerifyDatabaseSchemaResult` envelope (with timings, summary,
+ * issue list); the SPI itself returns just the core ok/issues pair so the
+ * seam between target-walk and framework-aggregation is explicit.
+ */
+interface SchemaVerifyResult {
+  readonly ok: boolean;
+  readonly issues: readonly SchemaDiffIssue[];
+}
+//#endregion
+//#region src/control/verifier-disposition.d.ts
+type VerificationStatus = 'pass' | 'warn' | 'fail';
+type VerifierOutcome = VerificationStatus | 'suppress';
+/**
+ * Target-neutral classification of a verifier finding, abstracted away from any
+ * one storage model's vocabulary. Each family classifies its own concrete issue
+ * kinds into these categories; the framework only grades the category against a
+ * control policy.
+ *
+ * - `declaredMissing` — a declared object/element is absent from the database.
+ * - `declaredIncompatible` — a declared object/element exists but its shape diverges.
+ * - `valueDrift` — the value set of an existing type drifted (e.g. enum values).
+ * - `extraNestedElement` — an undeclared element nested inside a declared object
+ *   (a SQL column, a document field).
+ * - `extraAuxiliary` — an undeclared auxiliary attached to a declared object
+ *   (a SQL constraint/index, a Mongo index/validator).
+ * - `extraTopLevelObject` — an undeclared top-level object (a SQL table, a
+ *   Mongo collection).
+ */
+type VerifierIssueCategory = 'declaredMissing' | 'declaredIncompatible' | 'valueDrift' | 'extraNestedElement' | 'extraAuxiliary' | 'extraTopLevelObject';
+/**
+ * Grades a target-neutral issue category against a control policy.
+ *
+ * - `observed` warns on everything.
+ * - `tolerated` suppresses only an extra nested element (everything else fails).
+ * - `external` suppresses every extra category and value drift (existence and
+ *   declared-shape divergences still fail).
+ * - `managed` (and any other) fails.
+ */
+declare function dispositionForCategory(controlPolicy: ControlPolicy, category: VerifierIssueCategory): VerifierOutcome;
+//#endregion
+export { SchemaDiffIssue as $, MigrationPlan as A, diffSchemas as At, MigrationRunnerFailure as B, hasSchemaView as Bt, ExpectationFailureReason as C, assembleAuthoringContributions as Ct, MigrationOperationClass as D, contractSnapshotJsonSpecifier as Dt, MigrationMetadata as E, buildExtensionLoadOrder as Et, MigrationPlannerFailureResult as F, extractQueryOperationTypeImports as Ft, MigrationScaffoldContext as G, MigrationRunnerPerSpaceSuccessValue as H, orderIssuesByDependencies as Ht, MigrationPlannerResult as I, hasMigrations as It, OperationPreview as J, OpFactoryCall as K, MigrationPlannerSuccessResult as L, hasOperationPreview as Lt, MigrationPlanWithAuthoringSurface as M, extractCodecLookup as Mt, MigrationPlanner as N, extractCodecTypeImports as Nt, MigrationOperationPolicy as O, contractSnapshotTypesSpecifier as Ot, MigrationPlannerConflict as P, extractComponentIds as Pt, SchemaDiff as Q, MigrationRunner as R, hasPslContractInfer as Rt, EmitContractResult as S, VerifyDatabaseSchemaResult as St, MigratableTargetDescriptor as T, assertUniqueCodecOwner as Tt, MigrationRunnerResult as U, storageHashHex as Ut, MigrationRunnerPerSpaceOptions as V, issueOutcome as Vt, MigrationRunnerSuccessValue as W, OperationPreviewStatement as X, OperationPreviewCapable as Y, PslContractInferCapable as Z, ControlTargetInstance as _, VERIFY_CODE_TARGET_MISMATCH as _t, ContractSpace as a, SchemaTreeNodeOptions as at, DiffSubjectGranularity as b, VerifierOutcome as bt, ControlAdapterInstance as c, SchemaVerifyOptions as ct, ControlExtensionDescriptor as d, SchemaViewNodeKind as dt, SchemaEntityCoordinate as et, ControlExtensionInstance as f, SignDatabaseResult as ft, ControlTargetDescriptor as g, VERIFY_CODE_SCHEMA_FAILURE as gt, ControlStack as h, VERIFY_CODE_MARKER_MISSING as ht, ContractSerializer as i, SchemaTreeNode as it, MigrationPlanOperation as j, dispositionForCategory as jt, MigrationPackage as k, createControlStack as kt, ControlDriverDescriptor as l, SchemaVerifyResult as lt, ControlFamilyInstance as m, VERIFY_CODE_HASH_MISMATCH as mt, AssembledAuthoringContributions as n, SchemaOwnership as nt, ContractSpaceHeadRef as o, SchemaTreeVisitor as ot, ControlFamilyDescriptor as p, TargetMigrationsCapability as pt, OperationContext as q, CONTRACT_SNAPSHOTS_DIRNAME as r, SchemaSubjectClassifierCapable as rt, ControlAdapterDescriptor as s, SchemaVerifier as st, APP_SPACE_ID as t, SchemaNodeRef as tt, ControlDriverInstance as u, SchemaViewCapable as ut, CoreSchemaView as v, VerificationStatus as vt, IntrospectSchemaResult as w, assembleControlMutationDefaults as wt, DiffableNode as x, VerifyDatabaseResult as xt, CreateControlStackInput as y, VerifierIssueCategory as yt, MigrationRunnerExecutionChecks as z, hasSchemaSubjectClassifier as zt };
+//# sourceMappingURL=control-CBvTj7Ia.d.mts.map