Skip to content

docs(bridge): add operations and cutover runbooks - #371

Merged
islandbitcoin merged 4 commits into
tmp/bridge-rebase-pr-readyfrom
docs/bridge-operations-runbook
May 26, 2026
Merged

docs(bridge): add operations and cutover runbooks#371
islandbitcoin merged 4 commits into
tmp/bridge-rebase-pr-readyfrom
docs/bridge-operations-runbook

Conversation

@islandbitcoin

@islandbitcoin islandbitcoin commented May 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Bridge operations documentation for deploys, webhook handling, replay, reconciliation, incidents, and Cash Wallet cutover execution.

Includes:

  • docs/bridge-integration/OPERATIONS.md for steady-state Bridge operations
  • docs/bridge-integration/CUTOVER-RUNBOOK.md for OPS-50 cutover-day go/no-go execution

Review-driven fixes before PR

Ran an external DeepSeek Reasoner review, then passed that critique to GPT-5.5 for second-pass validation. Patched the confirmed blockers before opening this PR:

  • Rebased onto current tmp/bridge-rebase-pr-ready, which includes ENG-345 cutover CLI/schema/Bruno files.
  • Replaced production replay/reconciliation examples using dev/config/base-config.yaml with PROD_CONFIG_PATH and explicit environment preflight checks.
  • Corrected Bridge webhook signature docs to match implementation: X-Webhook-Signature: t=<timestamp_ms>,v0=<base64_signature>.
  • Added exact Cash Wallet cutover CLI commands for preview, prepare, start, run-batch, status, and complete.
  • Split admin vs client-safe public cutover query guidance.
  • Strengthened staging rehearsal evidence for partial migration, resume, failure, abort, old-client compatibility, and reconciliation triage.
  • Reworded the review canary balance example so it is not mistaken for a universal production smoke expectation.

Second review iteration

Ran a second DeepSeek Reasoner review against the patched PR, then passed those findings to GPT-5.5. Patched the confirmed issues:

  • Changed wallet presentation expectations to match the actual cutover guard behavior:
    • PRE: old and capable clients both see legacy USD.
    • IN_PROGRESS: not-started accounts remain USD; completed/skipped migrated accounts show USDT to capable clients and legacy-compatible USD to old clients.
    • COMPLETE: capable clients see USDT; old clients see legacy-compatible USD.
  • Made CLI the required production path for IN_PROGRESS and COMPLETE.
  • Reframed admin mutation/Bruno IN_PROGRESS and COMPLETE actions as emergency overrides requiring backend-owner approval and operator-log entries.
  • Added production-readiness caveat for Bridge signature fixture verification and linked follow-up ENG-402.
  • Added lifecycle hardening follow-up ENG-403 for start/prepared-record checks.

Follow-ups created:

  • ENG-402: Verify Bridge webhook signature fixture against middleware
  • ENG-403: Harden Cash Wallet cutover start lifecycle checks

Verification

  • git diff --check origin/tmp/bridge-rebase-pr-ready...HEAD
  • ASCII-only check on both docs
  • Grep check for stale/dangerous strings:
    • Bridge-Signature
    • Bridge-Timestamp
    • --configPath dev/config/base-config.yaml
    • approved migration job
    • approved admin operation
    • stale capable-client USDT pre-cutover expectations
    • direct admin/Bruno production IN_PROGRESS/COMPLETE guidance

Notes

This PR intentionally does not implement ENG-364 rollback mechanics. The cutover runbook treats rollback after irreversible wallet/default changes as a separate data-repair process and defines the handoff packet for ENG-364.

@linear

linear Bot commented May 26, 2026

Copy link
Copy Markdown

ENG-364

@islandbitcoin
islandbitcoin merged commit d448b2b into tmp/bridge-rebase-pr-ready May 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants