tony/BACKBEAT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backbeat: add module sources

Browse Source
This commit is contained in:
anthonyrawlins
2025-10-17 08:56:25 +11:00
parent 627d15b3f7
commit 4b4eb16efb
48 changed files with 11636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
decision-records/DR-2025-10-06-tempo-1bpm.md Normal file
View File

@@ -0,0 +1,33 @@
# Decision Record — Slow BACKBEAT Pulse to 1 BPM
- **UCXL**: `ucxl://chorus-agent:arbiter@backbeat:tempo-calibration/*^/decisions/tempo-1bpm`
- **Date**: 2025-10-06
- **Status**: Accepted
## Problem
BACKBEAT pulse instances were emitting beats at 2 BPM by default, keeping the cluster cadence at 30-second intervals. Operations requested a slower system-wide pulse so councils and agents have a full minute between beats while stabilising the swarm elections and WHOOSH rebroadcast loops.
## Options Considered
1. **Just change deployment flags** — override `backbeat-pulse` with `-bpm 1` in compose files. *Pros*: no code changes. *Cons*: min/max validation rejects <4 BPM, mock SDK fallback still emits 2 BPM, and documentation would drift from runtime behaviour.
2. **Adjust runtime control messages** — send tempo change commands after startup. *Pros*: no rebuild. *Cons*: ±10% guard blocks the 2→1 jump, and services would still boot at the faster tempo.
3. **Update defaults and guardrails in code** *(chosen)* — set default/minimum BPM to 1, align SDK degradation cadence, and refresh guides/tests.
## Decision
Implement option 3. The pulse service now defaults to 1 BPM, accepts values down to 1 BPM, and the SDK’s local degradation beats mirror the slower cadence. Reference docs now mark 1 BPM as the default. Regression tests were updated and pass with `GOWORK=off go test ./...`.
## Impact
- ✅ Cluster pulse slows to 60-second beats without runtime overrides.
- ✅ Operators retain the ability to bump tempo up to 24 BPM within safeguards.
- ✅ SDK degradation flows remain consistent with production cadence.
- ⚠️ Deployments that relied on the old 2 BPM default should confirm updated expectations before release.
## Evidence / Links
- Code: `project-queues/active/BACKBEAT/backbeat/prototype/cmd/pulse/main.go`
- SDK fallback: `project-queues/active/BACKBEAT/backbeat/prototype/pkg/sdk/internal.go`
- Docs: `project-queues/active/BACKBEAT/backbeat/prototype/TEMPO-RECOMMENDATIONS.md`, `project-queues/active/BACKBEAT/backbeat/prototype/contracts/docs/tempo-guide.md`
- Tests: `GOWORK=off go test ./...` (module root)

31
decision-records/DR-2025-10-16-module-release.md Normal file
View File

@@ -0,0 +1,31 @@
# Decision Record: Publish BACKBEAT Go Module v0.1.0
- **Date:** 2025-10-16
- **Status:** Accepted
- **UCXL:** ucxl://backbeat:maintainer@BACKBEAT:releases/DRs/2025-10-16-module-release.md
## Problem
WHOOSH, CHORUS, and downstream SDK users depended on BACKBEAT via local `replace` directives because no tagged module version existed. This blocked clean dependency management and external consumption.
## Options
1. Keep using workspace replacements.
2. Fold BACKBEAT into the CHORUS repository.
3. Publish an initial semantic version (`v0.1.0`). *(Chosen)*
## Decision
Cut release tag `v0.1.0` from `master`, update documentation to advertise the module, and repoint consuming services at the tagged version while removing local overrides.
## Impact
- Establishes a canonical module reference for SDK consumers.
- Enables removal of `replace` directives in CHORUS/WHOOSH.
- No runtime changes; this is a packaging improvement.
## Follow-Up
1. Maintain a release checklist for future tags (change log, tests, artifact links).
2. Monitor CHORUS/WHOOSH builds to ensure GOPRIVATE/git config allow fetching the module.
3. Mirror the module to public hosting if external consumers require open access.