@prisma-next/framework-components 0.4.0-dev.1 → 0.4.0-dev.10

package/dist/framework-components-C8ZhSwXe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"framework-components-C8ZhSwXe.mjs","names":[],"sources":["../src/framework-components.ts"],"sourcesContent":["import type { Codec } from './codec-types';\nimport type { AuthoringContributions } from './framework-authoring';\nimport type { TypesImportSpec } from './types-import-spec';\n\n/**\n * Declarative fields that describe component metadata.\n */\nexport interface ComponentMetadata {\n  /** Component version (semver) */\n  readonly version: string;\n\n  /**\n   * Capabilities this component provides.\n   *\n   * For adapters, capabilities must be declared on the adapter descriptor (so they are emitted into\n   * the contract) and also exposed in runtime adapter code (e.g. `adapter.profile.capabilities`);\n   * keep these declarations in sync. Targets are identifiers/descriptors and typically do not\n   * declare capabilities.\n   */\n  readonly capabilities?: Record<string, unknown>;\n\n  /** Type imports for contract.d.ts generation */\n  readonly types?: {\n    readonly codecTypes?: {\n      /**\n       * Base codec types import spec.\n       * Optional: adapters typically provide this, extensions usually don't.\n       */\n      readonly import?: TypesImportSpec;\n      /**\n       * Additional type-only imports for parameterized codec branded types.\n       *\n       * These imports are included in generated `contract.d.ts` but are NOT treated as\n       * codec type maps (i.e., they should not be intersected into `export type CodecTypes = ...`).\n       *\n       * Example: `Vector<N>` for pgvector codecs that emit `Vector<1536>`\n       */\n      readonly typeImports?: ReadonlyArray<TypesImportSpec>;\n      /**\n       * Optional control-plane hooks keyed by codecId.\n       * Used by family-specific planners/verifiers to handle storage types.\n       */\n      readonly controlPlaneHooks?: Record<string, unknown>;\n      /**\n       * Codec instances contributed by this component.\n       * Used to build a CodecLookup for codec-dispatched type rendering during emission.\n       */\n      readonly codecInstances?: ReadonlyArray<Codec>;\n    };\n    readonly operationTypes?: { readonly import: TypesImportSpec };\n    readonly queryOperationTypes?: { readonly import: TypesImportSpec };\n    readonly storage?: ReadonlyArray<{\n      readonly typeId: string;\n      readonly familyId: string;\n      readonly targetId: string;\n      readonly nativeType?: string;\n    }>;\n  };\n\n  /**\n   * Optional pure-data authoring contributions exposed by this component.\n   *\n   * These contributions are safe to include on pack refs and descriptors because\n   * they contain only declarative metadata. Higher-level authoring packages may\n   * project them into concrete helper functions for TS-first workflows.\n   */\n  readonly authoring?: AuthoringContributions;\n}\n\n/**\n * Base descriptor for any framework component.\n *\n * All component descriptors share these fundamental properties that identify\n * the component and provide its metadata. This interface is extended by\n * specific descriptor types (FamilyDescriptor, TargetDescriptor, etc.).\n *\n * @template Kind - Discriminator literal identifying the component type.\n *   Built-in kinds are 'family', 'target', 'adapter', 'driver', 'extension',\n *   but the type accepts any string to allow ecosystem extensions.\n *\n * @example\n * ```ts\n * // All descriptors have these properties\n * descriptor.kind     // The Kind type parameter (e.g., 'family', 'target', or custom kinds)\n * descriptor.id       // Unique string identifier (e.g., 'sql', 'postgres')\n * descriptor.version  // Component version (semver)\n * ```\n */\nexport interface ComponentDescriptor<Kind extends string> extends ComponentMetadata {\n  /** Discriminator identifying the component type */\n  readonly kind: Kind;\n\n  /** Unique identifier for this component (e.g., 'sql', 'postgres', 'pgvector') */\n  readonly id: string;\n}\n\nexport interface ContractComponentRequirementsCheckInput {\n  readonly contract: {\n    readonly target: string;\n    readonly targetFamily?: string | undefined;\n    readonly extensionPacks?: Record<string, unknown> | undefined;\n  };\n  readonly expectedTargetFamily?: string | undefined;\n  readonly expectedTargetId?: string | undefined;\n  readonly providedComponentIds: Iterable<string>;\n}\n\nexport interface ContractComponentRequirementsCheckResult {\n  readonly familyMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n  readonly targetMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n  readonly missingExtensionPackIds: readonly string[];\n}\n\nexport function checkContractComponentRequirements(\n  input: ContractComponentRequirementsCheckInput,\n): ContractComponentRequirementsCheckResult {\n  const providedIds = new Set<string>();\n  for (const id of input.providedComponentIds) {\n    providedIds.add(id);\n  }\n\n  const requiredExtensionPackIds = input.contract.extensionPacks\n    ? Object.keys(input.contract.extensionPacks)\n    : [];\n  const missingExtensionPackIds = requiredExtensionPackIds.filter((id) => !providedIds.has(id));\n\n  const expectedTargetFamily = input.expectedTargetFamily;\n  const contractTargetFamily = input.contract.targetFamily;\n  const familyMismatch =\n    expectedTargetFamily !== undefined &&\n    contractTargetFamily !== undefined &&\n    contractTargetFamily !== expectedTargetFamily\n      ? { expected: expectedTargetFamily, actual: contractTargetFamily }\n      : undefined;\n\n  const expectedTargetId = input.expectedTargetId;\n  const contractTargetId = input.contract.target;\n  const targetMismatch =\n    expectedTargetId !== undefined && contractTargetId !== expectedTargetId\n      ? { expected: expectedTargetId, actual: contractTargetId }\n      : undefined;\n\n  return {\n    ...(familyMismatch ? { familyMismatch } : {}),\n    ...(targetMismatch ? { targetMismatch } : {}),\n    missingExtensionPackIds,\n  };\n}\n\n/**\n * Descriptor for a family component.\n *\n * A \"family\" represents a category of data sources with shared semantics\n * (e.g., SQL databases, document stores). Families define:\n * - Query semantics and operations (SELECT, INSERT, find, aggregate, etc.)\n * - Contract structure (tables vs collections, columns vs fields)\n * - Type system and codecs\n *\n * Families are the top-level grouping. Each family contains multiple targets\n * (e.g., SQL family contains Postgres, MySQL, SQLite targets).\n *\n * Extended by plane-specific descriptors:\n * - `ControlFamilyDescriptor` - adds `emission` for CLI/tooling operations\n * - `RuntimeFamilyDescriptor` - adds runtime-specific factory methods\n *\n * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')\n *\n * @example\n * ```ts\n * import sql from '@prisma-next/family-sql/control';\n *\n * sql.kind     // 'family'\n * sql.familyId // 'sql'\n * sql.id       // 'sql'\n * ```\n */\nexport interface FamilyDescriptor<TFamilyId extends string> extends ComponentDescriptor<'family'> {\n  /** The family identifier (e.g., 'sql', 'document') */\n  readonly familyId: TFamilyId;\n}\n\n/**\n * Descriptor for a target component.\n *\n * A \"target\" represents a specific database or data store within a family\n * (e.g., Postgres, MySQL, MongoDB). Targets define:\n * - Native type mappings (e.g., Postgres int4 → TypeScript number)\n * - Target-specific capabilities (e.g., RETURNING, LATERAL joins)\n *\n * Targets are bound to a family and provide the target-specific implementation\n * details that adapters and drivers use.\n *\n * Extended by plane-specific descriptors:\n * - `ControlTargetDescriptor` - adds optional `migrations` capability\n * - `RuntimeTargetDescriptor` - adds runtime factory method\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')\n *\n * @example\n * ```ts\n * import postgres from '@prisma-next/target-postgres/control';\n *\n * postgres.kind     // 'target'\n * postgres.familyId // 'sql'\n * postgres.targetId // 'postgres'\n * ```\n */\nexport interface TargetDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'target'> {\n  /** The family this target belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Base shape for any pack reference.\n * Pack refs are pure JSON-friendly objects safe to import in authoring flows.\n */\nexport interface PackRefBase<Kind extends string, TFamilyId extends string>\n  extends ComponentMetadata {\n  readonly kind: Kind;\n  readonly id: string;\n  readonly familyId: TFamilyId;\n  readonly targetId?: string;\n  readonly authoring?: AuthoringContributions;\n}\n\nexport type FamilyPackRef<TFamilyId extends string = string> = PackRefBase<'family', TFamilyId>;\n\nexport type TargetPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'target', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type AdapterPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'adapter', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type ExtensionPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'extension', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type DriverPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'driver', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\n/**\n * Descriptor for an adapter component.\n *\n * An \"adapter\" provides the protocol and dialect implementation for a target.\n * Adapters handle:\n * - SQL/query generation (lowering AST to target-specific syntax)\n * - Codec registration (encoding/decoding between JS and wire types)\n * - Type mappings and coercions\n *\n * Adapters are bound to a specific family+target combination and work with\n * any compatible driver for that target.\n *\n * Extended by plane-specific descriptors:\n * - `ControlAdapterDescriptor` - control-plane factory\n * - `RuntimeAdapterDescriptor` - runtime factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresAdapter from '@prisma-next/adapter-postgres/control';\n *\n * postgresAdapter.kind     // 'adapter'\n * postgresAdapter.familyId // 'sql'\n * postgresAdapter.targetId // 'postgres'\n * ```\n */\nexport interface AdapterDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'adapter'> {\n  /** The family this adapter belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this adapter is designed for */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for a driver component.\n *\n * A \"driver\" provides the connection and execution layer for a target.\n * Drivers handle:\n * - Connection management (pooling, timeouts, retries)\n * - Query execution (sending SQL/commands, receiving results)\n * - Transaction management\n * - Wire protocol communication\n *\n * Drivers are bound to a specific family+target and work with any compatible\n * adapter. Multiple drivers can exist for the same target (e.g., node-postgres\n * vs postgres.js for Postgres).\n *\n * Extended by plane-specific descriptors:\n * - `ControlDriverDescriptor` - creates driver from connection URL\n * - `RuntimeDriverDescriptor` - creates driver with runtime options\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresDriver from '@prisma-next/driver-postgres/control';\n *\n * postgresDriver.kind     // 'driver'\n * postgresDriver.familyId // 'sql'\n * postgresDriver.targetId // 'postgres'\n * ```\n */\nexport interface DriverDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'driver'> {\n  /** The family this driver belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this driver connects to */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for an extension component.\n *\n * An \"extension\" adds optional capabilities to a target. Extensions can provide:\n * - Additional operations (e.g., vector similarity search with pgvector)\n * - Custom types and codecs (e.g., vector type)\n * - Extended query capabilities\n *\n * Extensions are bound to a specific family+target and are registered in the\n * config alongside the core components. Multiple extensions can be used together.\n *\n * Extended by plane-specific descriptors:\n * - `ControlExtensionDescriptor` - control-plane extension factory\n * - `RuntimeExtensionDescriptor` - runtime extension factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import pgvector from '@prisma-next/extension-pgvector/control';\n *\n * pgvector.kind     // 'extension'\n * pgvector.familyId // 'sql'\n * pgvector.targetId // 'postgres'\n * ```\n */\nexport interface ExtensionDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'extension'> {\n  /** The family this extension belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this extension is designed for */\n  readonly targetId: TTargetId;\n}\n\n/** Components bound to a specific family+target combination. */\nexport type TargetBoundComponentDescriptor<TFamilyId extends string, TTargetId extends string> =\n  | TargetDescriptor<TFamilyId, TTargetId>\n  | AdapterDescriptor<TFamilyId, TTargetId>\n  | DriverDescriptor<TFamilyId, TTargetId>\n  | ExtensionDescriptor<TFamilyId, TTargetId>;\n\nexport interface FamilyInstance<TFamilyId extends string> {\n  readonly familyId: TFamilyId;\n}\n\nexport interface TargetInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface AdapterInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface DriverInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface ExtensionInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n"],"mappings":";AAiHA,SAAgB,mCACd,OAC0C;CAC1C,MAAM,8BAAc,IAAI,KAAa;AACrC,MAAK,MAAM,MAAM,MAAM,qBACrB,aAAY,IAAI,GAAG;CAMrB,MAAM,2BAH2B,MAAM,SAAS,iBAC5C,OAAO,KAAK,MAAM,SAAS,eAAe,GAC1C,EAAE,EACmD,QAAQ,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;CAE7F,MAAM,uBAAuB,MAAM;CACnC,MAAM,uBAAuB,MAAM,SAAS;CAC5C,MAAM,iBACJ,yBAAyB,UACzB,yBAAyB,UACzB,yBAAyB,uBACrB;EAAE,UAAU;EAAsB,QAAQ;EAAsB,GAChE;CAEN,MAAM,mBAAmB,MAAM;CAC/B,MAAM,mBAAmB,MAAM,SAAS;CACxC,MAAM,iBACJ,qBAAqB,UAAa,qBAAqB,mBACnD;EAAE,UAAU;EAAkB,QAAQ;EAAkB,GACxD;AAEN,QAAO;EACL,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C;EACD"}
+{"version":3,"file":"framework-components-C8ZhSwXe.mjs","names":[],"sources":["../src/framework-components.ts"],"sourcesContent":["import type { Codec } from './codec-types';\nimport type { AuthoringContributions } from './framework-authoring';\nimport type { ControlMutationDefaults } from './mutation-default-types';\nimport type { TypesImportSpec } from './types-import-spec';\n\n/**\n * Declarative fields that describe component metadata.\n */\nexport interface ComponentMetadata {\n  /** Component version (semver) */\n  readonly version: string;\n\n  /**\n   * Capabilities this component provides.\n   *\n   * For adapters, capabilities must be declared on the adapter descriptor (so they are emitted into\n   * the contract) and also exposed in runtime adapter code (e.g. `adapter.profile.capabilities`);\n   * keep these declarations in sync. Targets are identifiers/descriptors and typically do not\n   * declare capabilities.\n   */\n  readonly capabilities?: Record<string, unknown>;\n\n  /** Type imports for contract.d.ts generation */\n  readonly types?: {\n    readonly codecTypes?: {\n      /**\n       * Base codec types import spec.\n       * Optional: adapters typically provide this, extensions usually don't.\n       */\n      readonly import?: TypesImportSpec;\n      /**\n       * Additional type-only imports for parameterized codec branded types.\n       *\n       * These imports are included in generated `contract.d.ts` but are NOT treated as\n       * codec type maps (i.e., they should not be intersected into `export type CodecTypes = ...`).\n       *\n       * Example: `Vector<N>` for pgvector codecs that emit `Vector<1536>`\n       */\n      readonly typeImports?: ReadonlyArray<TypesImportSpec>;\n      /**\n       * Optional control-plane hooks keyed by codecId.\n       * Used by family-specific planners/verifiers to handle storage types.\n       */\n      readonly controlPlaneHooks?: Record<string, unknown>;\n      /**\n       * Codec instances contributed by this component.\n       * Used to build a CodecLookup for codec-dispatched type rendering during emission.\n       */\n      readonly codecInstances?: ReadonlyArray<Codec>;\n    };\n    readonly operationTypes?: { readonly import: TypesImportSpec };\n    readonly queryOperationTypes?: { readonly import: TypesImportSpec };\n    readonly storage?: ReadonlyArray<{\n      readonly typeId: string;\n      readonly familyId: string;\n      readonly targetId: string;\n      readonly nativeType?: string;\n    }>;\n  };\n\n  /**\n   * Optional pure-data authoring contributions exposed by this component.\n   *\n   * These contributions are safe to include on pack refs and descriptors because\n   * they contain only declarative metadata. Higher-level authoring packages may\n   * project them into concrete helper functions for TS-first workflows.\n   */\n  readonly authoring?: AuthoringContributions;\n\n  /**\n   * Scalar type name to codec ID mapping contributed by this component.\n   * Assembled by `createControlStack` with duplicate detection.\n   */\n  readonly scalarTypeDescriptors?: ReadonlyMap<string, string>;\n\n  /**\n   * Mutation default function handlers and generator descriptors contributed\n   * by this component. Assembled by `createControlStack` with duplicate detection.\n   */\n  readonly controlMutationDefaults?: ControlMutationDefaults;\n}\n\n/**\n * Base descriptor for any framework component.\n *\n * All component descriptors share these fundamental properties that identify\n * the component and provide its metadata. This interface is extended by\n * specific descriptor types (FamilyDescriptor, TargetDescriptor, etc.).\n *\n * @template Kind - Discriminator literal identifying the component type.\n *   Built-in kinds are 'family', 'target', 'adapter', 'driver', 'extension',\n *   but the type accepts any string to allow ecosystem extensions.\n *\n * @example\n * ```ts\n * // All descriptors have these properties\n * descriptor.kind     // The Kind type parameter (e.g., 'family', 'target', or custom kinds)\n * descriptor.id       // Unique string identifier (e.g., 'sql', 'postgres')\n * descriptor.version  // Component version (semver)\n * ```\n */\nexport interface ComponentDescriptor<Kind extends string> extends ComponentMetadata {\n  /** Discriminator identifying the component type */\n  readonly kind: Kind;\n\n  /** Unique identifier for this component (e.g., 'sql', 'postgres', 'pgvector') */\n  readonly id: string;\n}\n\nexport interface ContractComponentRequirementsCheckInput {\n  readonly contract: {\n    readonly target: string;\n    readonly targetFamily?: string | undefined;\n    readonly extensionPacks?: Record<string, unknown> | undefined;\n  };\n  readonly expectedTargetFamily?: string | undefined;\n  readonly expectedTargetId?: string | undefined;\n  readonly providedComponentIds: Iterable<string>;\n}\n\nexport interface ContractComponentRequirementsCheckResult {\n  readonly familyMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n  readonly targetMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n  readonly missingExtensionPackIds: readonly string[];\n}\n\nexport function checkContractComponentRequirements(\n  input: ContractComponentRequirementsCheckInput,\n): ContractComponentRequirementsCheckResult {\n  const providedIds = new Set<string>();\n  for (const id of input.providedComponentIds) {\n    providedIds.add(id);\n  }\n\n  const requiredExtensionPackIds = input.contract.extensionPacks\n    ? Object.keys(input.contract.extensionPacks)\n    : [];\n  const missingExtensionPackIds = requiredExtensionPackIds.filter((id) => !providedIds.has(id));\n\n  const expectedTargetFamily = input.expectedTargetFamily;\n  const contractTargetFamily = input.contract.targetFamily;\n  const familyMismatch =\n    expectedTargetFamily !== undefined &&\n    contractTargetFamily !== undefined &&\n    contractTargetFamily !== expectedTargetFamily\n      ? { expected: expectedTargetFamily, actual: contractTargetFamily }\n      : undefined;\n\n  const expectedTargetId = input.expectedTargetId;\n  const contractTargetId = input.contract.target;\n  const targetMismatch =\n    expectedTargetId !== undefined && contractTargetId !== expectedTargetId\n      ? { expected: expectedTargetId, actual: contractTargetId }\n      : undefined;\n\n  return {\n    ...(familyMismatch ? { familyMismatch } : {}),\n    ...(targetMismatch ? { targetMismatch } : {}),\n    missingExtensionPackIds,\n  };\n}\n\n/**\n * Descriptor for a family component.\n *\n * A \"family\" represents a category of data sources with shared semantics\n * (e.g., SQL databases, document stores). Families define:\n * - Query semantics and operations (SELECT, INSERT, find, aggregate, etc.)\n * - Contract structure (tables vs collections, columns vs fields)\n * - Type system and codecs\n *\n * Families are the top-level grouping. Each family contains multiple targets\n * (e.g., SQL family contains Postgres, MySQL, SQLite targets).\n *\n * Extended by plane-specific descriptors:\n * - `ControlFamilyDescriptor` - adds `emission` for CLI/tooling operations\n * - `RuntimeFamilyDescriptor` - adds runtime-specific factory methods\n *\n * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')\n *\n * @example\n * ```ts\n * import sql from '@prisma-next/family-sql/control';\n *\n * sql.kind     // 'family'\n * sql.familyId // 'sql'\n * sql.id       // 'sql'\n * ```\n */\nexport interface FamilyDescriptor<TFamilyId extends string> extends ComponentDescriptor<'family'> {\n  /** The family identifier (e.g., 'sql', 'document') */\n  readonly familyId: TFamilyId;\n}\n\n/**\n * Descriptor for a target component.\n *\n * A \"target\" represents a specific database or data store within a family\n * (e.g., Postgres, MySQL, MongoDB). Targets define:\n * - Native type mappings (e.g., Postgres int4 → TypeScript number)\n * - Target-specific capabilities (e.g., RETURNING, LATERAL joins)\n *\n * Targets are bound to a family and provide the target-specific implementation\n * details that adapters and drivers use.\n *\n * Extended by plane-specific descriptors:\n * - `ControlTargetDescriptor` - adds optional `migrations` capability\n * - `RuntimeTargetDescriptor` - adds runtime factory method\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')\n *\n * @example\n * ```ts\n * import postgres from '@prisma-next/target-postgres/control';\n *\n * postgres.kind     // 'target'\n * postgres.familyId // 'sql'\n * postgres.targetId // 'postgres'\n * ```\n */\nexport interface TargetDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'target'> {\n  /** The family this target belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Base shape for any pack reference.\n * Pack refs are pure JSON-friendly objects safe to import in authoring flows.\n */\nexport interface PackRefBase<Kind extends string, TFamilyId extends string>\n  extends ComponentMetadata {\n  readonly kind: Kind;\n  readonly id: string;\n  readonly familyId: TFamilyId;\n  readonly targetId?: string;\n  readonly authoring?: AuthoringContributions;\n}\n\nexport type FamilyPackRef<TFamilyId extends string = string> = PackRefBase<'family', TFamilyId>;\n\nexport type TargetPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'target', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type AdapterPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'adapter', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type ExtensionPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'extension', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\nexport type DriverPackRef<\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> = PackRefBase<'driver', TFamilyId> & {\n  readonly targetId: TTargetId;\n};\n\n/**\n * Descriptor for an adapter component.\n *\n * An \"adapter\" provides the protocol and dialect implementation for a target.\n * Adapters handle:\n * - SQL/query generation (lowering AST to target-specific syntax)\n * - Codec registration (encoding/decoding between JS and wire types)\n * - Type mappings and coercions\n *\n * Adapters are bound to a specific family+target combination and work with\n * any compatible driver for that target.\n *\n * Extended by plane-specific descriptors:\n * - `ControlAdapterDescriptor` - control-plane factory\n * - `RuntimeAdapterDescriptor` - runtime factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresAdapter from '@prisma-next/adapter-postgres/control';\n *\n * postgresAdapter.kind     // 'adapter'\n * postgresAdapter.familyId // 'sql'\n * postgresAdapter.targetId // 'postgres'\n * ```\n */\nexport interface AdapterDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'adapter'> {\n  /** The family this adapter belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this adapter is designed for */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for a driver component.\n *\n * A \"driver\" provides the connection and execution layer for a target.\n * Drivers handle:\n * - Connection management (pooling, timeouts, retries)\n * - Query execution (sending SQL/commands, receiving results)\n * - Transaction management\n * - Wire protocol communication\n *\n * Drivers are bound to a specific family+target and work with any compatible\n * adapter. Multiple drivers can exist for the same target (e.g., node-postgres\n * vs postgres.js for Postgres).\n *\n * Extended by plane-specific descriptors:\n * - `ControlDriverDescriptor` - creates driver from connection URL\n * - `RuntimeDriverDescriptor` - creates driver with runtime options\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresDriver from '@prisma-next/driver-postgres/control';\n *\n * postgresDriver.kind     // 'driver'\n * postgresDriver.familyId // 'sql'\n * postgresDriver.targetId // 'postgres'\n * ```\n */\nexport interface DriverDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'driver'> {\n  /** The family this driver belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this driver connects to */\n  readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for an extension component.\n *\n * An \"extension\" adds optional capabilities to a target. Extensions can provide:\n * - Additional operations (e.g., vector similarity search with pgvector)\n * - Custom types and codecs (e.g., vector type)\n * - Extended query capabilities\n *\n * Extensions are bound to a specific family+target and are registered in the\n * config alongside the core components. Multiple extensions can be used together.\n *\n * Extended by plane-specific descriptors:\n * - `ControlExtensionDescriptor` - control-plane extension factory\n * - `RuntimeExtensionDescriptor` - runtime extension factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import pgvector from '@prisma-next/extension-pgvector/control';\n *\n * pgvector.kind     // 'extension'\n * pgvector.familyId // 'sql'\n * pgvector.targetId // 'postgres'\n * ```\n */\nexport interface ExtensionDescriptor<TFamilyId extends string, TTargetId extends string>\n  extends ComponentDescriptor<'extension'> {\n  /** The family this extension belongs to */\n  readonly familyId: TFamilyId;\n\n  /** The target this extension is designed for */\n  readonly targetId: TTargetId;\n}\n\n/** Components bound to a specific family+target combination. */\nexport type TargetBoundComponentDescriptor<TFamilyId extends string, TTargetId extends string> =\n  | TargetDescriptor<TFamilyId, TTargetId>\n  | AdapterDescriptor<TFamilyId, TTargetId>\n  | DriverDescriptor<TFamilyId, TTargetId>\n  | ExtensionDescriptor<TFamilyId, TTargetId>;\n\nexport interface FamilyInstance<TFamilyId extends string> {\n  readonly familyId: TFamilyId;\n}\n\nexport interface TargetInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface AdapterInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface DriverInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n\nexport interface ExtensionInstance<TFamilyId extends string, TTargetId extends string> {\n  readonly familyId: TFamilyId;\n  readonly targetId: TTargetId;\n}\n"],"mappings":";AA8HA,SAAgB,mCACd,OAC0C;CAC1C,MAAM,8BAAc,IAAI,KAAa;AACrC,MAAK,MAAM,MAAM,MAAM,qBACrB,aAAY,IAAI,GAAG;CAMrB,MAAM,2BAH2B,MAAM,SAAS,iBAC5C,OAAO,KAAK,MAAM,SAAS,eAAe,GAC1C,EAAE,EACmD,QAAQ,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;CAE7F,MAAM,uBAAuB,MAAM;CACnC,MAAM,uBAAuB,MAAM,SAAS;CAC5C,MAAM,iBACJ,yBAAyB,UACzB,yBAAyB,UACzB,yBAAyB,uBACrB;EAAE,UAAU;EAAsB,QAAQ;EAAsB,GAChE;CAEN,MAAM,mBAAmB,MAAM;CAC/B,MAAM,mBAAmB,MAAM,SAAS;CACxC,MAAM,iBACJ,qBAAqB,UAAa,qBAAqB,mBACnD;EAAE,UAAU;EAAkB,QAAQ;EAAkB,GACxD;AAEN,QAAO;EACL,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C;EACD"}

package/dist/{framework-components-DoWmh6GH.d.mts → framework-components-EJXe-pum.d.mts}

@@ -1,9 +1,90 @@
 import { i as AuthoringContributions } from "./framework-authoring-D1-JZ37B.mjs";
 import { t as Codec } from "./codec-types-B58nCJiu.mjs";
-import { t as TypesImportSpec } from "./types-import-spec-Ddp4fNmt.mjs";
+import { t as TypesImportSpec } from "./types-import-spec-C4sc7wbb.mjs";
+import { ColumnDefault, ExecutionMutationDefaultValue } from "@prisma-next/contract/types";
 
+//#region src/mutation-default-types.d.ts
+interface SourcePosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+interface SourceSpan {
+  readonly start: SourcePosition;
+  readonly end: SourcePosition;
+}
+interface SourceDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly sourceId?: string;
+  readonly span?: SourceSpan;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+interface DefaultFunctionArgument {
+  readonly raw: string;
+  readonly span: SourceSpan;
+}
+interface ParsedDefaultFunctionCall {
+  readonly name: string;
+  readonly raw: string;
+  readonly args: readonly DefaultFunctionArgument[];
+  readonly span: SourceSpan;
+}
+interface DefaultFunctionLoweringContext {
+  readonly sourceId: string;
+  readonly modelName: string;
+  readonly fieldName: string;
+  readonly columnCodecId?: string;
+}
+type LoweredDefaultValue = {
+  readonly kind: 'storage';
+  readonly defaultValue: ColumnDefault;
+} | {
+  readonly kind: 'execution';
+  readonly generated: ExecutionMutationDefaultValue;
+};
+type LoweredDefaultResult = {
+  readonly ok: true;
+  readonly value: LoweredDefaultValue;
+} | {
+  readonly ok: false;
+  readonly diagnostic: SourceDiagnostic;
+};
+type DefaultFunctionLoweringHandler = (input: {
+  readonly call: ParsedDefaultFunctionCall;
+  readonly context: DefaultFunctionLoweringContext;
+}) => LoweredDefaultResult;
+interface DefaultFunctionRegistryEntry {
+  readonly lower: DefaultFunctionLoweringHandler;
+  readonly usageSignatures?: readonly string[];
+}
+type DefaultFunctionRegistry = ReadonlyMap<string, DefaultFunctionRegistryEntry>;
+interface MutationDefaultGeneratorDescriptor {
+  readonly id: string;
+  readonly applicableCodecIds: readonly string[];
+  readonly resolveGeneratedColumnDescriptor?: (input: {
+    readonly generated: ExecutionMutationDefaultValue;
+  }) => {
+    readonly codecId: string;
+    readonly nativeType: string;
+    readonly typeRef?: string;
+    readonly typeParams?: Record<string, unknown>;
+  } | undefined;
+}
+interface ControlMutationDefaultEntry {
+  readonly lower: (input: {
+    readonly call: ParsedDefaultFunctionCall;
+    readonly context: DefaultFunctionLoweringContext;
+  }) => LoweredDefaultResult;
+  readonly usageSignatures?: readonly string[];
+}
+type ControlMutationDefaultRegistry = ReadonlyMap<string, ControlMutationDefaultEntry>;
+interface ControlMutationDefaults {
+  readonly defaultFunctionRegistry: ControlMutationDefaultRegistry;
+  readonly generatorDescriptors: readonly MutationDefaultGeneratorDescriptor[];
+}
+//#endregion
 //#region src/framework-components.d.ts
-
 /**
  * Declarative fields that describe component metadata.
  */
@@ -68,6 +149,16 @@ interface ComponentMetadata {
    * project them into concrete helper functions for TS-first workflows.
    */
   readonly authoring?: AuthoringContributions;
+  /**
+   * Scalar type name to codec ID mapping contributed by this component.
+   * Assembled by `createControlStack` with duplicate detection.
+   */
+  readonly scalarTypeDescriptors?: ReadonlyMap<string, string>;
+  /**
+   * Mutation default function handlers and generator descriptors contributed
+   * by this component. Assembled by `createControlStack` with duplicate detection.
+   */
+  readonly controlMutationDefaults?: ControlMutationDefaults;
 }
 /**
  * Base descriptor for any framework component.
@@ -329,5 +420,5 @@ interface ExtensionInstance<TFamilyId extends string, TTargetId extends string>
   readonly targetId: TTargetId;
 }
 //#endregion
-export { checkContractComponentRequirements as S, PackRefBase as _, ComponentMetadata as a, TargetInstance as b, DriverDescriptor as c, ExtensionDescriptor as d, ExtensionInstance as f, FamilyPackRef as g, FamilyInstance as h, ComponentDescriptor as i, DriverInstance as l, FamilyDescriptor as m, AdapterInstance as n, ContractComponentRequirementsCheckInput as o, ExtensionPackRef as p, AdapterPackRef as r, ContractComponentRequirementsCheckResult as s, AdapterDescriptor as t, DriverPackRef as u, TargetBoundComponentDescriptor as v, TargetPackRef as x, TargetDescriptor as y };
-//# sourceMappingURL=framework-components-DoWmh6GH.d.mts.map
+export { LoweredDefaultResult as A, ControlMutationDefaultEntry as C, DefaultFunctionLoweringHandler as D, DefaultFunctionLoweringContext as E, SourceSpan as F, MutationDefaultGeneratorDescriptor as M, ParsedDefaultFunctionCall as N, DefaultFunctionRegistry as O, SourceDiagnostic as P, checkContractComponentRequirements as S, ControlMutationDefaults as T, PackRefBase as _, ComponentMetadata as a, TargetInstance as b, DriverDescriptor as c, ExtensionDescriptor as d, ExtensionInstance as f, FamilyPackRef as g, FamilyInstance as h, ComponentDescriptor as i, LoweredDefaultValue as j, DefaultFunctionRegistryEntry as k, DriverInstance as l, FamilyDescriptor as m, AdapterInstance as n, ContractComponentRequirementsCheckInput as o, ExtensionPackRef as p, AdapterPackRef as r, ContractComponentRequirementsCheckResult as s, AdapterDescriptor as t, DriverPackRef as u, TargetBoundComponentDescriptor as v, ControlMutationDefaultRegistry as w, TargetPackRef as x, TargetDescriptor as y };
+//# sourceMappingURL=framework-components-EJXe-pum.d.mts.map

package/dist/framework-components-EJXe-pum.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-components-EJXe-pum.d.mts","names":[],"sources":["../src/mutation-default-types.ts","../src/framework-components.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/{types-import-spec-Ddp4fNmt.d.mts → types-import-spec-C4sc7wbb.d.mts}

@@ -10,4 +10,4 @@ interface TypesImportSpec {
 }
 //#endregion
 export { TypesImportSpec as t };
-//# sourceMappingURL=types-import-spec-Ddp4fNmt.d.mts.map
+//# sourceMappingURL=types-import-spec-C4sc7wbb.d.mts.map

package/dist/types-import-spec-C4sc7wbb.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-import-spec-C4sc7wbb.d.mts","names":[],"sources":["../src/types-import-spec.ts"],"sourcesContent":[],"mappings":";;AAIA;;;UAAiB,eAAA"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.4.0-dev.1",
+  "version": "0.4.0-dev.10",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/operations": "0.4.0-dev.1",
-    "@prisma-next/utils": "0.4.0-dev.1",
-    "@prisma-next/contract": "0.4.0-dev.1"
+    "@prisma-next/operations": "0.4.0-dev.10",
+    "@prisma-next/utils": "0.4.0-dev.10",
+    "@prisma-next/contract": "0.4.0-dev.10"
   },
   "devDependencies": {
     "tsdown": "0.18.4",

package/src/control-migration-types.ts

@@ -145,6 +145,32 @@ export interface MigrationPlan {
   readonly operations: readonly MigrationPlanOperation[];
 }
 
+/**
+ * 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 (class-flow `Migration` subclasses) satisfy
+ * `MigrationPlan` but not this interface: they are already the source.
+ *
+ * Descriptor-flow targets (e.g. Postgres) that do not materialize their
+ * planner plans back to TypeScript provide a throwing stub so that
+ * `MigrationPlannerSuccessResult.plan` has a uniform type at the framework
+ * level. In practice the CLI only calls `renderTypeScript()` in the
+ * class-flow branch of `migration plan`.
+ */
+export 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.
+   */
+  renderTypeScript(): string;
+}
+
 // ============================================================================
 // Planner Result Types
 // ============================================================================
@@ -163,10 +189,16 @@ export interface MigrationPlannerConflict {
 
 /**
  * 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. Targets whose
+ * planners do not support that (descriptor-flow targets like Postgres)
+ * supply a throwing `renderTypeScript()` stub — the CLI only calls it in
+ * the class-flow branch of `migration plan`.
  */
 export interface MigrationPlannerSuccessResult {
   readonly kind: 'success';
-  readonly plan: MigrationPlan;
+  readonly plan: MigrationPlanWithAuthoringSurface;
 }
 
 /**
@@ -258,6 +290,13 @@ export interface MigrationPlanner<
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
+    /**
+     * Storage hash of the "from" contract (the state the planner assumes the
+     * database starts at). Class-flow planners use this to populate
+     * `describe()` on the produced plan so the rendered `migration.ts` has
+     * correct `from`/`to` metadata.
+     */
+    readonly fromHash: string;
     /**
      * Active framework components participating in this composition.
      * Families/targets can interpret this list to derive family-specific metadata.
@@ -267,6 +306,16 @@ export interface MigrationPlanner<
       TargetBoundComponentDescriptor<TFamilyId, TTargetId>
     >;
   }): MigrationPlannerResult;
+
+  /**
+   * Produce an empty migration with the target's authoring conventions.
+   *
+   * Used by `migration new` to scaffold a fresh `migration.ts` without the
+   * CLI needing to know whether the target uses descriptor-flow or class-flow
+   * authoring. The returned plan has no operations; its `renderTypeScript()`
+   * yields a stub the user can edit.
+   */
+  emptyMigration(context: MigrationScaffoldContext): MigrationPlanWithAuthoringSurface;
 }
 
 /**
@@ -343,8 +392,10 @@ export interface TargetMigrationsCapability<
 
   /**
    * Plans a migration using the descriptor-based planner.
-   * Returns operation descriptors and whether data migration is needed.
-   * The caller decides whether to resolve immediately or scaffold migration.ts.
+   * Returns operation descriptors that the caller scaffolds into a
+   * `migration.ts` file. Whether the resulting migration can be emitted
+   * end-to-end is determined at emit time (via `placeholder()` errors
+   * thrown for unfilled slots), not by the planner.
    */
   planWithDescriptors?(context: {
     readonly fromContract: Contract | null;
@@ -356,7 +407,6 @@ export interface TargetMigrationsCapability<
     | {
         readonly ok: true;
         readonly descriptors: readonly OperationDescriptor[];
-        readonly needsDataMigration: boolean;
       }
     | {
         readonly ok: false;
@@ -365,7 +415,7 @@ export interface TargetMigrationsCapability<
 
   /**
    * Resolves operation descriptors into target-specific migration plan operations
-   * with SQL/DDL, prechecks, and postchecks. Called by `migration verify` to
+   * with SQL/DDL, prechecks, and postchecks. Called by `migration emit` to
    * serialize migration.ts into ops.json.
    */
   resolveDescriptors?(
@@ -379,4 +429,81 @@ export interface TargetMigrationsCapability<
       >;
     },
   ): readonly MigrationPlanOperation[];
+
+  /**
+   * Optional: render a descriptor list back to a populated `migration.ts`
+   * source string.
+   *
+   * Descriptor-flow targets (e.g. Postgres) implement this so that
+   * `migration plan` can hand the user an editable authoring surface that
+   * already captures the planner's decisions. Class-flow targets do not
+   * implement it — their planner already returns a renderable plan via
+   * `MigrationPlannerSuccessResult.plan.renderTypeScript()`.
+   */
+  renderDescriptorTypeScript?(
+    descriptors: readonly OperationDescriptor[],
+    context: MigrationScaffoldContext,
+  ): string;
+
+  /**
+   * Optional: in-process emit capability for class-flow migration files.
+   *
+   * Targets that author `migration.ts` as an executable class (rather than
+   * an array of descriptors) implement `emit` to produce `ops.json` from
+   * the source file directly. The framework dispatches to `emit` whenever
+   * `resolveDescriptors` is not present on the target.
+   *
+   * The capability runs in the same Node process as the CLI:
+   *  - The target dynamically imports `<dir>/migration.ts`, locates the
+   *    authored class on the module's default export, and invokes whatever
+   *    runtime machinery it needs to obtain the operations list.
+   *  - Structured errors thrown during evaluation (notably
+   *    `errorUnfilledPlaceholder` with code `PN-MIG-2001`) propagate as
+   *    real JS exceptions so the CLI's normal error envelope can render
+   *    them with full structured metadata. No subprocess is spawned.
+   *  - The target is responsible for calling `writeMigrationOps(dir, ops)`
+   *    so that `ops.json` ends up on disk before `emit` returns. The
+   *    framework's `emitMigration` helper is the single owner of
+   *    `attestMigration(dir)` — the target MUST NOT call
+   *    `attestMigration` itself.
+   *  - The returned `MigrationPlanOperation[]` is the display-oriented
+   *    shape the CLI uses for output (id, label, operationClass).
+   */
+  emit?(options: {
+    readonly dir: string;
+    readonly frameworkComponents: ReadonlyArray<
+      TargetBoundComponentDescriptor<TFamilyId, TTargetId>
+    >;
+  }): Promise<readonly MigrationPlanOperation[]>;
+}
+
+// ============================================================================
+// Migration Scaffolding SPI
+// ============================================================================
+
+/**
+ * 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)` and to
+ * `TargetMigrationsCapability.renderDescriptorTypeScript(descriptors, context)`.
+ */
+export 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. Class-flow targets (e.g. Mongo) use
+   * this to populate `describe()` on the rendered empty migration so that
+   * `migration.json` generated at emit time has correct identity metadata.
+   */
+  readonly fromHash: string;
+  /**
+   * 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;
 }

package/src/control-stack.ts

@@ -14,6 +14,11 @@ import type {
   AuthoringTypeNamespace,
 } from './framework-authoring';
 import type { ComponentMetadata } from './framework-components';
+import type {
+  ControlMutationDefaultEntry,
+  ControlMutationDefaults,
+  MutationDefaultGeneratorDescriptor,
+} from './mutation-default-types';
 import type { TypesImportSpec } from './types-import-spec';
 
 export interface AssembledAuthoringContributions {
@@ -37,6 +42,8 @@ export interface ControlStack<
   readonly extensionIds: ReadonlyArray<string>;
   readonly codecLookup: CodecLookup;
   readonly authoringContributions: AssembledAuthoringContributions;
+  readonly scalarTypeDescriptors: ReadonlyMap<string, string>;
+  readonly controlMutationDefaults: ControlMutationDefaults;
 }
 
 export interface CreateControlStackInput<
@@ -244,6 +251,80 @@ export function assembleAuthoringContributions(
   };
 }
 
+export function assembleScalarTypeDescriptors(
+  descriptors: ReadonlyArray<
+    Pick<ComponentMetadata, 'scalarTypeDescriptors'> & { readonly id?: string }
+  >,
+): ReadonlyMap<string, string> {
+  const result = new Map<string, string>();
+  const owners = new Map<string, string>();
+
+  for (const descriptor of descriptors) {
+    const descriptorMap = descriptor.scalarTypeDescriptors;
+    if (!descriptorMap) continue;
+    const descriptorId = descriptor.id ?? '<unknown>';
+    for (const [typeName, codecId] of descriptorMap) {
+      const existingOwner = owners.get(typeName);
+      if (existingOwner !== undefined) {
+        throw new Error(
+          `Duplicate scalar type descriptor "${typeName}". ` +
+            `Descriptor "${descriptorId}" conflicts with "${existingOwner}".`,
+        );
+      }
+      result.set(typeName, codecId);
+      owners.set(typeName, descriptorId);
+    }
+  }
+
+  return result;
+}
+
+export function assembleControlMutationDefaults(
+  descriptors: ReadonlyArray<
+    Pick<ComponentMetadata, 'controlMutationDefaults'> & { readonly id?: string }
+  >,
+): ControlMutationDefaults {
+  const defaultFunctionRegistry = new Map<string, ControlMutationDefaultEntry>();
+  const functionOwners = new Map<string, string>();
+  const generatorMap = new Map<string, MutationDefaultGeneratorDescriptor>();
+  const generatorOwners = new Map<string, string>();
+
+  for (const descriptor of descriptors) {
+    const contributions = descriptor.controlMutationDefaults;
+    if (!contributions) continue;
+    const descriptorId = descriptor.id ?? '<unknown>';
+
+    for (const generatorDescriptor of contributions.generatorDescriptors) {
+      const existingOwner = generatorOwners.get(generatorDescriptor.id);
+      if (existingOwner !== undefined) {
+        throw new Error(
+          `Duplicate mutation default generator id "${generatorDescriptor.id}". ` +
+            `Descriptor "${descriptorId}" conflicts with "${existingOwner}".`,
+        );
+      }
+      generatorMap.set(generatorDescriptor.id, generatorDescriptor);
+      generatorOwners.set(generatorDescriptor.id, descriptorId);
+    }
+
+    for (const [functionName, handler] of contributions.defaultFunctionRegistry) {
+      const existingOwner = functionOwners.get(functionName);
+      if (existingOwner !== undefined) {
+        throw new Error(
+          `Duplicate mutation default function "${functionName}". ` +
+            `Descriptor "${descriptorId}" conflicts with "${existingOwner}".`,
+        );
+      }
+      defaultFunctionRegistry.set(functionName, handler);
+      functionOwners.set(functionName, descriptorId);
+    }
+  }
+
+  return {
+    defaultFunctionRegistry,
+    generatorDescriptors: Array.from(generatorMap.values()),
+  };
+}
+
 export function extractCodecLookup(
   descriptors: ReadonlyArray<Pick<ComponentMetadata & { id?: string }, 'types' | 'id'>>,
 ): CodecLookup {
@@ -268,6 +349,21 @@ export function extractCodecLookup(
   return { get: (id) => byId.get(id) };
 }
 
+export function validateScalarTypeCodecIds(
+  scalarTypeDescriptors: ReadonlyMap<string, string>,
+  codecLookup: CodecLookup,
+): string[] {
+  const errors: string[] = [];
+  for (const [typeName, codecId] of scalarTypeDescriptors) {
+    if (!codecLookup.get(codecId)) {
+      errors.push(
+        `Scalar type "${typeName}" references codec "${codecId}" which is not registered by any component.`,
+      );
+    }
+  }
+  return errors;
+}
+
 export function createControlStack<TFamilyId extends string, TTargetId extends string>(
   input: CreateControlStackInput<TFamilyId, TTargetId>,
 ): ControlStack<TFamilyId, TTargetId> {
@@ -275,6 +371,9 @@ export function createControlStack<TFamilyId extends string, TTargetId extends s
 
   const allDescriptors = [family, target, ...(adapter ? [adapter] : []), ...extensionPacks];
 
+  const codecLookup = extractCodecLookup(allDescriptors);
+  const scalarTypeDescriptors = assembleScalarTypeDescriptors(allDescriptors);
+
   return {
     family,
     target,
@@ -286,7 +385,9 @@ export function createControlStack<TFamilyId extends string, TTargetId extends s
     operationTypeImports: extractOperationTypeImports(allDescriptors),
     queryOperationTypeImports: extractQueryOperationTypeImports(allDescriptors),
     extensionIds: extractComponentIds(family, target, adapter, extensionPacks),
-    codecLookup: extractCodecLookup(allDescriptors),
+    codecLookup,
     authoringContributions: assembleAuthoringContributions(allDescriptors),
+    scalarTypeDescriptors,
+    controlMutationDefaults: assembleControlMutationDefaults(allDescriptors),
   };
 }

package/src/exports/control.ts

@@ -25,11 +25,13 @@ export type {
   MigrationPlannerResult,
   MigrationPlannerSuccessResult,
   MigrationPlanOperation,
+  MigrationPlanWithAuthoringSurface,
   MigrationRunner,
   MigrationRunnerExecutionChecks,
   MigrationRunnerFailure,
   MigrationRunnerResult,
   MigrationRunnerSuccessValue,
+  MigrationScaffoldContext,
   OperationDescriptor,
   SerializedQueryPlan,
   TargetMigrationsCapability,
@@ -66,6 +68,8 @@ export type {
 } from '../control-stack';
 export {
   assembleAuthoringContributions,
+  assembleControlMutationDefaults,
+  assembleScalarTypeDescriptors,
   assertUniqueCodecOwner,
   createControlStack,
   extractCodecLookup,
@@ -74,3 +78,18 @@ export {
   extractOperationTypeImports,
   extractQueryOperationTypeImports,
 } from '../control-stack';
+export type {
+  ControlMutationDefaultEntry,
+  ControlMutationDefaultRegistry,
+  ControlMutationDefaults,
+  DefaultFunctionLoweringContext,
+  DefaultFunctionLoweringHandler,
+  DefaultFunctionRegistry,
+  DefaultFunctionRegistryEntry,
+  LoweredDefaultResult,
+  LoweredDefaultValue,
+  MutationDefaultGeneratorDescriptor,
+  ParsedDefaultFunctionCall,
+  SourceDiagnostic,
+  SourceSpan,
+} from '../mutation-default-types';

package/src/framework-components.ts

@@ -1,5 +1,6 @@
 import type { Codec } from './codec-types';
 import type { AuthoringContributions } from './framework-authoring';
+import type { ControlMutationDefaults } from './mutation-default-types';
 import type { TypesImportSpec } from './types-import-spec';
 
 /**
@@ -65,6 +66,18 @@ export interface ComponentMetadata {
    * project them into concrete helper functions for TS-first workflows.
    */
   readonly authoring?: AuthoringContributions;
+
+  /**
+   * Scalar type name to codec ID mapping contributed by this component.
+   * Assembled by `createControlStack` with duplicate detection.
+   */
+  readonly scalarTypeDescriptors?: ReadonlyMap<string, string>;
+
+  /**
+   * Mutation default function handlers and generator descriptors contributed
+   * by this component. Assembled by `createControlStack` with duplicate detection.
+   */
+  readonly controlMutationDefaults?: ControlMutationDefaults;
 }
 
 /**