save document

src/docs/FUTURE_WORK.md

@@ -0,0 +1,52 @@
+# XCE Controller: Future Work Items
+
+> **Status**: Tracked from config-replication-design.md review
+> **Last Updated**: 2026-05-12
+
+---
+
+## 1. Admin Config Tool (prerequisite for Phase 2)
+
+`OP_upgradeConfig` requires an admin tool to drive it. The tool must:
+
+- Encode a `ClusterConfig` YAML/JSON file to Cap'n Proto binary
+- Compute SHA-256 over the binary bytes
+- Connect to the primary controller's endpoint (SSL, same CA as controllers)
+- Send `OP_upgradeConfig` with the binary blob and SHA-256
+- Display the reply: new version tag, acked count, and any error message
+- Poll `OP_probe` after restart to confirm the primary is back online with the new config
+
+Suggested interface: `xce-config push --controller <host:port> --config cluster.yaml`
+
+---
+
+## 2. Quorum-ACK Gate Before Restart (§14.4 extension)
+
+Current `OP_upgradeConfig` restarts the primary after best-effort push to standbys.
+A quorum-ACK gate would refuse to restart unless a minimum number of standbys
+acknowledge the push, preventing silent rollback when all standbys are offline.
+
+Requires: `OP_upgradeConfig` reply to include `--require-standby-ack=N` flag.
+
+---
+
+## 3. OP_heartbeat Peers Cross-Validation (§11.2)
+
+Include a hash of the local `--peers` string in the heartbeat request. If two
+candidates disagree on the peers list, log ERROR. Detects misconfigured nodes
+at election time rather than silently producing dual-primary split-brain.
+
+---
+
+## 4. Lost and Found Drain Command (§6.5 extension)
+
+`xcecli lost-and-found drain` — reassign or cancel sidelined jobs, reset
+`lost_and_found_job_count` to 0. Automates operator cleanup after config upgrade.
+
+---
+
+## 5. OP_upgradeConfig Standby Redirect (§10.12 verification)
+
+Test that a standby correctly returns an error reply with the primary's address
+when an admin tool sends `OP_upgradeConfig` to a standby, and the admin tool
+retries against the primary.