[Docs] ADR-MF-03 — Release V3 and multi-provider source resolution (design gate for PR-4) #161

Problem

The release/update subsystem must become multi-provider (GitHub.com, GitLab.com,
local directory) without weakening the integrity chain, the credential
confinement introduced by PR-0A, or the exact-runtime contract. The decision
cluster exists only in the external architecture document plus its final
addendum; it must be recorded as an accepted ADR before PR-4 starts.

Source: Multi-Forge v1.3.2-final §18–20, §33–43, §60–73 (ADR-MF-03 + final
addendum).

Expected outcome

An accepted ADR (decisions only) that freezes:

• ReleaseProviderEndpointConfig: provider, api_base_url, auth_origin,
  api_version, release_project_ref where required, credential_source;
  endpoint trust separated from secret source; repository cannot set
  auth_origin.
• Machine config ~/.ai-native/release-providers.json; reserved provider names;
  no project-local provider trust configuration.
• resolve_release_source() as the single resolution function consumed by
  update, update check, status, doctor; conflict validation before source
  precedence; selector rules (local pair, UPDATE_SOURCE_CONFLICT cases,
  anonymous AINATIVE_UPDATE_URL, machine default, built-in GitHub.com);
  no last-selector-wins.
• Anonymous release API compatibility: AINATIVE_UPDATE_URL stays HTTPS,
  anonymous, GitHub-Release-API-compatible; not a ZIP URL, mirror index or
  arbitrary JSON; missing V3 integrity metadata fails closed.
• Release V3: ReleaseManifest v3 (schema, protocol, version, channel,
  compatibility, artifacts, provenance); EnumerationResult with
  complete=false → RELEASE_ENUMERATION_INCOMPLETE; complete-with-zero →
  RELEASE_NO_CANDIDATE; SemVer restrictions (1.2.3, 1.2.3-rc.1 allowed;
  1.2.3+build1 → RELEASE_BUILD_METADATA_UNSUPPORTED; conflicting identities
  → RELEASE_DUPLICATE_VERSION).
• Trust chain: provider metadata → manifest SHA-256 + size → download → verify →
  parse → select lifecycle artifact → download → verify size + SHA-256; never
  parse trust-bearing artifact declarations before verifying the manifest.
• Exact version chain equality across candidate/manifest/runtime/artifact/
  filename/lifecycle-protocol.json.release_version; mismatch →
  UPDATE_VERSION_MISMATCH.
• Transport split: metadata/blob policies per PR-0A; GitHub private asset API;
  GitLab object-storage redirects strip credentials and verify the expected
  digest.
• GitLab single-project invariant (Releases API + Generic Package Registry +
  package files use the same project identity; release_project_ref is a
  numeric ID or namespace/project, never a URL); exact package match; exhaustive
  pagination; duplicate handling; manifest file lookup
  ainative-release-v3.json (0 → RELEASE_MANIFEST_MISSING, >1 →
  RELEASE_MANIFEST_AMBIGUOUS); package digest anchor (file_sha256, size).
• Mandatory secret patterns (MANDATORY_SECRET_PATTERNS) union operator extras;
  repository configuration may not remove, replace, disable or shadow mandatory
  patterns; GitLab token prefixes; Self-Managed custom-prefix qualification
  tuple.
• V2 bridge-release gate before the first V3 publication.

Acceptance criteria

• ADR written in docs/adr/ following the repository series format,
  incorporating every frozen point above and the final addendum
  (release_project_ref, AnonymousReleaseApiProvider).
• Rejected alternatives recorded (universal provider SDK, project-local
  trust config, warning-and-continue on integrity uncertainty, duplicate
  tolerance).
• resolve_release_source() selector precedence and all conflict cases stated
  exactly; identical behavior required from every consuming command.
• The exact-runtime contract and V2 compatibility mode (exact-runtime)
  stated.
• Accepted by the maintainer before PR-4 begins.
• Issue [Security] Add cryptographically verifiable release artifacts #24 (cryptographic release authority) remains independent and
  unchanged.

Out of scope

• Implementing V3 (PR-4), GitLab provider (PR-5).
• GHES support; Bitbucket/Azure DevOps/Forgejo/Gitea.
• Home-made cryptographic signing; global forge trust registry.

Context

• ainative/lifecycle/provider.py, docs/DISTRIBUTION-LIFECYCLE.md,
  docs/RELEASING.md.
• PR-0A delivers the transport primitives this ADR specifies.
• Blocks PR-4.

Dependencies

• None. Consumes the transport primitives from PR-0A ([Security] Release transport: credential confinement across origins and redirects (PR-0A) #158). Blocks PR-4 ([Feature] Release V3: source resolver, manifest, GitHub + Local providers (PR-4) #165).