refactor(docs): move requirements and test infra docs into docs/ subdirectories

Organize documentation by moving requirements (HighLevelReqs, Component-*,
lmxproxy_protocol) to docs/requirements/ and test infrastructure docs to
docs/test_infra/. Updates all cross-references in README, CLAUDE.md,
infra/README, component docs, and 23 plan files.
This commit is contained in:
Joseph Doherty
2026-03-21 01:11:35 -04:00
parent 0a85a839a2
commit d91aa83665
52 changed files with 486 additions and 124 deletions

View File

@@ -103,7 +103,7 @@
- [ ] `[KDD-cluster-4]` CoordinatedShutdown for graceful singleton handover.
- [ ] `[KDD-cluster-5]` Automatic dual-node recovery from persistent storage.
### From Component-ClusterInfrastructure.md
### From docs/requirements/Component-ClusterInfrastructure.md
- [ ] `[CD-CI-1]` Two-node cluster (active/standby) using Akka.NET Cluster.
- [ ] `[CD-CI-2]` Leader election and role assignment (active vs. standby).
@@ -120,7 +120,7 @@
- *Phase 3A scope*: Establish the pattern — no alarm persistence. Alarm Actors are Phase 3B, but the design must not persist alarm state.
- [ ] `[CD-CI-13]` Keep-oldest SBR rationale: with two nodes, quorum-based strategies cause total shutdown. Keep-oldest with `down-if-alone` ensures at most one node runs the singleton.
### From Component-SiteRuntime.md
### From docs/requirements/Component-SiteRuntime.md
- [ ] `[CD-SR-1]` Deployment Manager is an Akka.NET cluster singleton — guaranteed to run on exactly one node.
- [ ] `[CD-SR-2]` Startup behavior step 1: Read all deployed configurations from local SQLite.
@@ -133,7 +133,7 @@
- *Phase 3A scope*: Skeleton lifecycle — disable/enable/delete message handling in Deployment Manager. Full lifecycle with DCL/scripts is Phase 3B/3C.
- [ ] `[CD-SR-9]` When Instance Actor is stopped (disable, delete, redeployment), Akka.NET automatically stops all child actors.
### From Component-Host.md
### From docs/requirements/Component-Host.md
- [ ] `[CD-HOST-1]` REQ-HOST-6: Site-role Akka bootstrap with Remoting, Clustering, Persistence (SQLite), Split-Brain Resolver.
- [ ] `[CD-HOST-2]` REQ-HOST-7: Site nodes use `Host.CreateDefaultBuilder` — generic `IHost`, **not** `WebApplication`. No Kestrel, no HTTP port, no web endpoints.
@@ -418,7 +418,7 @@ Phase 3A is complete when **all** of the following pass:
| # | Question | Context | Impact | Status |
|---|----------|---------|--------|--------|
| Q-P3A-1 | What is the optimal batch size and delay for staggered Instance Actor startup? | Component-SiteRuntime.md suggests 20 with a "short delay." Actual values depend on OPC UA server capacity. | Performance tuning. Default to 20/100ms, make configurable. | Deferred — tune during Phase 3B when DCL is integrated. |
| Q-P3A-1 | What is the optimal batch size and delay for staggered Instance Actor startup? | docs/requirements/Component-SiteRuntime.md suggests 20 with a "short delay." Actual values depend on OPC UA server capacity. | Performance tuning. Default to 20/100ms, make configurable. | Deferred — tune during Phase 3B when DCL is integrated. |
| Q-P3A-2 | Should the SQLite schema use a single database file or separate files per concern (configs, overrides, S&F, events)? | Single file is simpler. Separate files isolate concerns and allow independent backup/maintenance. | Schema design. | Recommend single file with separate tables. Simpler transaction management. Final decision during implementation. |
| Q-P3A-3 | Should Akka.Persistence (event sourcing / snapshotting) be used for the Deployment Manager singleton, or is direct SQLite access sufficient? | Akka.Persistence adds complexity (journal, snapshots) but provides built-in recovery. Direct SQLite is simpler for this use case (singleton reads all configs on startup). | Architecture. | Recommend direct SQLite — Deployment Manager recovery is a full read-all-configs-and-rebuild pattern, not event replay. Akka.Persistence is overkill here. |