Introduce typed download-result and hook compatibility contract #1331

Context

Phase 3 (#1293) propagates (Path, DownloadKind). Phase 4 (#1205 and #1206) will use both values to prepare and build different source types.

This is Phase 3b of #1254.

Why

Without this card, Phase 4 would depend on a temporary positional tuple and undefined hook behavior. Stabilizing the contract first prevents repeated API changes and gives legacy hooks a documented migration path.

Proposed change

Add an immutable result type:

@dataclasses.dataclass(frozen=True, slots=True)
class DownloadedSource:
    path: pathlib.Path
    kind: DownloadKind

Update source-resolver download() methods to return it. Implement HookSDistResolver.download() and HookPrebuiltResolver.download() so they no longer raise NotImplementedError, and adapt legacy hook Path results using documented defaults.

Acceptance criteria

• Built-in resolvers return DownloadedSource.
• HookSDistResolver.download() and HookPrebuiltResolver.download() are implemented and no longer raise NotImplementedError.
• Legacy hook Path results remain supported.
• Ambiguous artifacts require an explicit DownloadKind.
• Invalid results produce actionable errors.
• Tests and hook documentation cover the contract.

Non-goals

• Candidate preservation (Redesign sdist handle to support VCS urls #776).
• Git preparation (Wire prepare_source and build_sdist for git-clone-based source resolvers #1205).
• Sdist strategy selection (build_sdist uses tarball instead of PEP 517 #1206).
• Resolver/downloader separation (Separate resolution and download concerns in resolver providers #1257).

Dependencies

Depends on #1293 and should land before #1205 and #1206.