feat(resolver): add the declarative source: configuration

docs/concepts/bootstrapper-architecture.rst

@@ -16,6 +16,12 @@ Bootstrap Phase Flow
 
 Every package passes through a sequence of phases.  Source packages
 traverse the full pipeline; prebuilt wheels skip the build phases.
+``pypi-prebuilt`` and ``hook-prebuilt`` use the selected source resolver to
+download a fresh wheel in ``PrepareSource``. The legacy ``pre_built`` setting
+keeps its existing wheel download path. Both routes update the local mirror
+and record the package as prebuilt in the graph and build order.
+When a local wheel is already available, bootstrap reuses it before asking
+the selected provider to resolve a fresh wheel.
 
 .. code-block:: text
 
@@ -57,7 +63,8 @@ the contract every phase must satisfy:
    * - ``Start``
      - Add to dependency graph; deduplicate already-seen packages
    * - ``PrepareSource``
-     - Download source or prebuilt wheel; read build-system deps
+     - Download source or prebuilt wheel; prepare archives or checkouts;
+       read build-system deps
    * - ``PrepareBuild``
      - Install build-system deps; discover backend and sdist deps
    * - ``Build``
@@ -67,6 +74,10 @@ the contract every phase must satisfy:
    * - ``Complete``
      - Clean up build directories (terminal phase)
 
+.. versionchanged:: 0.103.0
+   ``PrepareSource`` passes the downloaded artifact kind through preparation,
+   so Git checkouts can be prepared without unpacking them.
+
 Each phase wraps a ``WorkItem`` dataclass that accumulates per-package
 state (resolved version, build environment, build result, etc.) as it
 moves through the pipeline.

docs/concepts/hooks-and-overrides.rst

@@ -56,6 +56,16 @@ a Python module.
 See :doc:`/reference/hooks` for the complete list of hooks and their
 arguments.
 
+.. versionchanged:: 0.103.0
+
+   Configured ``hook-sdist`` and ``hook-prebuilt`` profiles support typed
+   download results with explicit artifact kinds. See :ref:`download_source_hook`
+   for the contract, legacy path defaults, and a migration example.
+
+   ``prepare_source`` selects an archive or Git default using the downloaded
+   artifact kind. Package overrides remain active. See :ref:`prepare_source_hook`
+   for their arguments and the public Git checkout helper.
+
 Global Hooks
 ------------
 

docs/concepts/package-settings.rst

@@ -35,6 +35,25 @@ Settings Loading Flow
 ``PackageBuildInfo`` objects are created lazily the first time a
 package is queried and cached for the rest of the run.
 
+``PackageSettings`` validates source settings when it loads each package.
+A package-level ``source`` cannot be combined with an explicitly set
+variant ``pre_built`` or ``wheel_server_url``. A variant-level ``source``
+cannot be combined with package-level ``download_source`` or
+``resolver_dist``. An explicit ``pre_built: false`` also conflicts;
+an omitted ``pre_built`` does not.
+
+``PackageBuildInfo.pre_built`` follows the selected ``source`` resolver's
+``resolves_prebuilt_wheel`` capability. Without ``source``, it reads the
+legacy variant ``pre_built`` setting. Configured prebuilt resolvers download
+fresh wheels through their ``download()`` contract; legacy prebuilt packages
+keep the wheel downloader.
+
+.. versionchanged:: 0.103.0
+   Configured prebuilt source resolvers now select the prebuilt pipeline
+   during bootstrap and later builds.
+   Source and legacy settings mixed across package and variant levels
+   now raise a validation error when package settings load.
+
 Directory Structure
 -------------------