chore(ci,docs): reconcile runbooks, add Pact Broker can-i-deploy gate, modernize CI

[Emeka000]

Summary

Implements SR-220, SR-216, SR-211, and SR-210. All changes are backward-compatible: the Pact Broker integration is inert until a broker is configured, and the two CI-modernization changes are drop-in action/runtime bumps.

SR-220 — Reconcile RUNBOOK.md and docs/ROLLBACK_RUNBOOK.md into one on-call procedure

RUNBOOK.md was moved to docs/ in an earlier docs-consolidation commit, but that move left scripts/check-alert-runbooks.js crashing on a missing root RUNBOOK.md — monitoring-ci was effectively broken.

• Fixed the broken check: check-alert-runbooks.js reads docs/RUNBOOK.md; monitoring/alerts.yml + monitoring/slo.yml runbook_url annotations repointed to docs/RUNBOOK.md#…; monitoring-ci.yml path triggers updated. check-alert-runbooks.js now passes (27 alerts, all sections resolve).
• Canonical vs. general split: cross-link callouts added at the top of both files. docs/ROLLBACK_RUNBOOK.md is canonical for mainnet incident recovery (severity matrix, WASM rollback, state migration, authority matrix); docs/RUNBOOK.md is the network-agnostic day-to-day reference and the "start here" doc.
• CLI consistency: all soroban contract … commands in docs/RUNBOOK.md converted to stellar contract …, so commands are copy-paste compatible between the two runbooks.
• Updated runbook references in README.md, docs/README.md, docs/PRODUCTION_READINESS_CHECKLIST.md; fixed a few pre-existing broken links in the runbook files while there.

SR-216 — Pact Broker + can-i-deploy gate

Everything is gated on the PACT_BROKER_BASE_URL repository variable — with it unset the pipeline behaves exactly as before (artifacts + commit-to-main), so this is safe to merge before the broker exists.

• Broker: pact-broker + dedicated Postgres added to docker-compose.yml under a pact-broker profile (docker compose --profile pact-broker up).
• Consumer publish: scripts/pact-publish.sh; consumer jobs in pact-contract-tests.yml publish pacts to the broker (tagged by branch + commit SHA) alongside the existing artifact upload.
• Provider verification: provider-verification.pact.test.ts is now broker-aware — pulls pacts by consumer-version selector and publishes verification results keyed by the API commit SHA when a broker is configured; falls back to local pact files otherwise (unchanged behavior).
• Deploy gate: scripts/pact-can-i-deploy.sh + a pact-can-i-deploy job in deploy-staging.yml (gates deploy) and a gate-pact job in deploy-mainnet.yml (between require-checklist and build-wasm).
• Retire commit job: publish-pacts now only runs while no broker is configured.
• Docs: docs/PACT_BROKER.md covers PactFlow and self-hosted setup, required secrets, and how the gate decides.

SR-211 — Upgrade openapi-validation.yml off Node 18 / v3 actions

Both jobs now use actions/checkout@v4 and the ./.github/actions/setup-node composite (Node 20 + npm caching), replacing checkout@v3 / setup-node@v3 / node-version: '18' / manual npm ci. Matches every other Node workflow in the repo.

SR-210 — Replace archived actions-rs/toolchain@v1 in release.yml

build-artifacts now uses ./.github/actions/setup-rust with targets: wasm32-unknown-unknown, matching every other Rust job. stellar-cli install and WASM optimize steps unchanged.

Incidental fix

deploy-staging.yml's smoke-tests job referenced needs.build-images.outputs.sha_short without depending on build-images — added it to needs.

Testing

• node scripts/check-alert-runbooks.js → passes
• All modified workflow / compose YAML validated
• scripts/pact-*.sh pass bash -n
• check-markdown-links.js failure count went from 16 → 14 (remaining are pre-existing, in files unrelated to this PR)
• Not runnable locally (deps not installed): tsc, vitest, promtool, actionlint. Follow-ups: create the broker / PactFlow account and set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN (see docs/PACT_BROKER.md); re-run openapi-validation against a PR touching api/openapi.yaml to confirm Node 20; tag a test release to confirm release.yml build output is unchanged.

closes #1354

closes #1353

closes #1359

closes #1363

[vercel]

@chidinma000 is attempting to deploy a commit to the Harold's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Emeka000 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits