Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract

[codeforester]

Parent: #214

Train position: 25 of 26
Phase: P3 — Ecosystem trust and broad adoption

Problem

The v2 framework is intentionally incompatible with the 1.x API, but first-party consumers and distribution are coupled today: Base accepts only compatible 1.* libraries, Base and Base Demo pin v1.4.0 and v1.3.0 release commits in CI, and Homebrew's unversioned Base formula depends on the latest base-bash-libs formula. Publishing the v2 formula before a compatible Base release would break existing Homebrew Base installations.

Acceptance criteria

• Inventory every first-party API use, version gate, full-SHA pin, fixture, workflow, formula, bottle, active document, and release contract across base, base-demo, homebrew-base, and every other Basefoundry repository discovered before cutover.
• Migrate Base from its current case 1.* / minimum 1.3.0 gate and legacy function names to an explicit supported v2 contract, with no dependency on compatibility aliases.
• Update every Base CI pin, Base Demo's Base and base-bash-libs pins, validators, fixtures, messages, documents, and end-to-end tests to the exact verified v2 artifact and compatible Base release.
• Update Homebrew to the canonical v2.0.0 GA release asset—not the previously used automatic tag-archive URL—plus its checksum, version assertions, and bottles while retaining version_scheme 1; update and bottle the dependent Base formula in the same tap change so no stable formula combination exposes Base 1.x code to v2 libraries.
• Validate source-checkout, Homebrew, vendor, and bundle paths against the same v2 release candidate on supported macOS and Linux environments.
• Document and rehearse the publish order: v2 RC validation; Base migration and release preparation; base-bash-libs v2.0.0 GA; compatible Base release; atomic tap formula and bottle promotion; Base Demo pin and release update.
• Document a rollback that moves the tap formulas and first-party pins back as compatible pairs without deleting, moving, or reusing published tags.
• Remove stale active references to “compatible later 1.x,” the 1.3.0 minimum, v1.4.0/v1.3.0 pins, and pre-v2 API assertions.
• Prove the coordinated cutover with green release, integration, and upgrade checks and record links to every cross-repository PR and release in this issue.

Dependencies

• Establish the v2.0.0 release line and enforce trustworthy version invariants #215
• Namespace public functions and globals for safe embedding #223
• Standardize public error, status, output, and mutation semantics #224
• Unify imports, version provenance, and pinned consumption #226
• Make base-bash a conventional, stable application launcher #227
• Ship pinned bundle, vendor, update, and verified release workflows #233
• Establish full Bash, OS, strict-option, and supply-chain release gates #234
• Publish stability, support, security, and deprecation policies #235
• Launch versioned documentation with a five-minute adoption path #236
• Publish official generator, testing, and package-manager integrations #237
• Ship production-grade reference applications and transparent benchmarks #238

[codeforester]

Status update after the engineering train:

• Base migration PR #1881 is merged and its corrected basectl help path passes the focused and full Base tests.
• base-bash-libs cutover handoff PR ci(cutover): add first-party v2 release handoff checks (#240) #271 is merged; docs(cutover): record merged Base migration status (#240) #276 synchronizes the manifest to record the merged Base state.
• first-party-cutover.yaml remains intentionally release_status: pending-ga-asset; Base Demo and Homebrew are unchanged until a canonical v2.0.0 asset, checksum, and provenance exist.
• The repository release-preparation PR release: prepare v2.0.0 metadata (#215) #274 is merged, with v2.0.0 metadata and full macOS/Ubuntu validation green.

The remaining acceptance items are the real GA asset/tag, downstream Base Demo/Homebrew updates, rollback rehearsal, and cross-repository verification.