docs: deploy runbook, install-force chore, and the operator-facing flag change - #34
Merged
Conversation
…ag change Three things learned on 2026-08-31 that were not written down anywhere. **BINARY FIRST, ALWAYS.** bd refuses outright when a database is ahead of the binary — "database is at v66, binary knows up to v62" — and bd ready, bd list and bd doctor all fail. That is NOT the same question as which migrations get applied: migrationSource.pendingVersions selects version > current from the binary's OWN set, so a stale binary finds nothing pending, and reasoning from that alone gives exactly the wrong answer. I did reason from it, migrated vct before deploying, and took wise-stack down for fifteen minutes. It was the quietest rig only because the rehearsal was deliberately run there. The new "Deploying a new bd to the fleet" section records the order that works, and why each step is the way it is: back up THROUGH THE SERVER (the fleet holds live connections, so a filesystem copy can catch a torn write) and actually restore one before trusting it; build out of band; capture the rehearsal baseline by direct SQL rather than through bd, because store-open runs autoMigrateOnVersionBump and even a read command can start migrating; deploy; then let the rest migrate on first touch and watch them converge. Also records that bd-deploy — named by the check-deploy-bd guard — does not exist on the dev machine, and what the working path is instead. **make install cannot succeed in this fork.** check-up-to-date compares HEAD against origin/main, and origin is UPSTREAM here, so it always reports the fork as stale. install-force is the correct target for this repo, not an override being abused. The inverted-remote convention surfacing in the build system. **The flag change gets a CHANGELOG entry** under Unreleased/Changed, written for whoever types the command rather than for whoever reviewed the diff: what to type now, which bead types look emptier (session/workflow/step/convergence are written no_history), that bd count --type <infra> answers 0, and that no programmatic caller is affected. Claude-Session: https://claude.ai/code/session_01EF1jg1uS2tJPRoAsbsXuza
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Records three things learned during today's resync + fleet deploy that were not written down.
Binary first, always
bd refuses outright when a database is ahead of the binary:
bd ready,bd listandbd doctorall fail. That is not the same question as which migrations get applied —migrationSource.pendingVersionsselectsversion > currentfrom the binary's own set, so a stale binary finds nothing pending. Reasoning from that alone gives exactly the wrong answer, which is what happened:vctwas migrated before the binary was deployed and wise-stack was down for ~15 minutes. It was the quietest rig only because the rehearsal was deliberately run there.New "Deploying a new bd to the fleet" section gives the order that works and why each step is shaped the way it is — back up through the server (live connections make a filesystem copy risk a torn write) and actually restore one before trusting it; build out of band; take the rehearsal baseline by direct SQL rather than through
bd, since store-open runsautoMigrateOnVersionBumpand even a read can start migrating; deploy; then watch the rest converge.Also records that
bd-deploy— named by thecheck-deploy-bdguard — does not exist on the dev machine, and what the working path is instead.make installcannot succeed in this forkcheck-up-to-datecompares HEAD againstorigin/main, andoriginis upstream here, so it always reports the fork as stale.install-forceis the correct target for this repo, not an override being abused — the inverted-remote convention surfacing in the build system.Operator-facing flag change
CHANGELOG entry under Unreleased/Changed, written for whoever types the command: what to type now, which bead types look emptier (
session/workflow/step/convergenceare writtenno_history), thatbd count --type <infra>answers 0, and that no programmatic caller is affected.