beads/docs
Steve Yegge 5a4c68a89c fix(leases): keep node_id off the committed config; tighten the replica guard (wy-jpd3.7)
Second adversarial review of the replica-aware lease work, against the opt-in
rewrite. One blocker, in the operating instruction rather than the code.

node_id was documented as "BEADS_NODE_ID, or node_id in config.yaml", and
`bd config set node_id` wrote the PROJECT .beads/config.yaml — a git-TRACKED
file (nothing in .beads/.gitignore excludes it). Commit "node_id: mini" and
every clone that pulls reads "mini", so every granted_node comparison matches
and the guard is at once fully ARMED and fully INERT: laptop reaps mini's
leases exactly as if they were local. That is the precise hazard the feature
exists to close, now happening while the operator believes they are protected
— strictly worse than the pre-feature state, where nobody thought they were.
node_id is per-machine state, the class .beads/.gitignore already excludes as
sync-state.json / push-state.json / redirect. It now routes to the user-global
~/.config/bd/config.yaml through a new exact-key arm of IsUserGlobalKey (the
prefix list only ever held "metrics."); viper already merges that file, so
config.NodeID() reads it straight back.

The docs also said to set it "on every replica sharing the queue", which on a
shared or remote dolt sql-server means every HOST — rebuilding the same
fail-closed regression this commit's parent removed the hostname fallback to
avoid. The load-bearing rule was never stated: node_id names the STORE, not
the host. Clients of one sql-server are ONE replica and must share a value or
leave it unset. Now said outright in federation.md and `bd reclaim --help`.

Also from the review:
- bd show claimed "reclaim will decline it" for any foreign node, but with an
  unnamed local node the guard is disarmed and reclaim reverts the lease
  happily. The annotation is now gated on config.NodeID() != "".
- TestNodeIDContextOverride's empty-override assertion had gone tautological
  when the hostname fallback went away: config.NodeID() is "" under test, so
  it passed whether or not WithNodeID worked at all. It now sets a non-empty
  fallback, asserts the fallback is what a no-override read returns, and only
  then asserts the empty override still beats it.
- The heartbeat backfill's bare `granted_node = ''` is COALESCE'd, matching
  the reclaim predicates; under NULL the IF took the else branch and the row
  was never backfilled. Unreachable today (0016 is NOT NULL DEFAULT ''), but
  the two sites disagreed about whether NULL was possible.
- The --any-replica audit line is skipped when localNode is "" rather than
  printing `not this node ("")`: nothing was overridden, the guard was never
  armed.
- reclaimReplicaSQL documents WHY granted_node stays unqualified — the DELETE
  splices it into a bare `DELETE FROM leases` with no alias to qualify with —
  and what to do if issues ever grows a column of that name.
- CHANGELOG entry, which this feature owed: a new flag, a new config key, two
  env vars, and two public struct fields shipped without one.
2026-07-25 02:32:31 -07:00
..
architecture docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
cli-reference docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
core-concepts Rename the reserved "graph" mermaid node id so diagrams render (#4958) 2026-07-23 17:14:09 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started docs(upgrading): document BD_ALLOW_REMOTE_MIGRATE for scripted upgrades 2026-07-17 21:07:18 -07:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
multi-agent fix(leases): keep node_id off the committed config; tighten the replica guard (wy-jpd3.7) 2026-07-25 02:32:31 -07:00
recovery docs(recovery): squash fence must cover every syncing machine's scheduled jobs (bd-g3di3) 2026-07-18 06:08:53 -07:00
reference docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
workflows docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
cli-docs.pin docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
CLI_REFERENCE.md docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
community-tools.md docs: add emBEADings to community tools (#4850) 2026-07-23 22:26:13 -07:00
docs.json Merge pull request #4864 from gastownhall/docs/bd-okqpv-history-squash-runbook 2026-07-17 20:38:17 -07:00
index.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00