STD-BEADS-002: Beads Version Skew Mitigation & Schema Upgrades

Status: Active Owner: Core Platform Engineering

The Problem

When the macOS bd binary (via Homebrew) is upgraded to a newer version (e.g. 1.3.0 which uses schema v66) while the canonical Oracle NAS database is running on an older version (e.g. 1.2.2 which uses schema v53), the local bd binary will attempt to migrate the shared Oracle database schema.

The Danger

If a newer bd client migrates the shared hq schema from v53 to v66, older clients (including the canonical Oracle 1.2.2 runtime) will instantly be locked out of the database. This causes native_store_unavailable and blocks gc mail read in other lanes.

Governance Rule

DO NOT BLINDLY UPGRADE THE MAC LOCAL bd BINARY OR gascity if it introduces a newer schema version to the shared Oracle network.

Remediation Policy

When a schema mismatch is detected (schema version mismatch: database is at v66, binary knows up to v53): 1. Immediate Mitigation (Downgrade): Do not run bd migrate schema on the Mac. Instead, downgrade the Mac bd binary to match Oracle. Use bd --ignore-schema-skew for reads if absolutely necessary. 2. Factory-Wide Upgrade (Recommended): Coordinate upgrading Oracle to the new bd version via agent-docker provisioning, then upgrade the Mac, and finally run bd migrate schema centrally on the Oracle node.

See bc-ljc (gc mail version-skew defect) for the historical resolution of the v53 to v66 skew event.