dohertj2/lmxopcua
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(archreview): remediation plans + fix flagged doc drift

Browse Source 
Add the 7 per-domain design+implementation plans (archreview/plans/) with
an index, produced from the 2026-07-08 architecture review.

Fix two confirmed doc drifts the review flagged (theme #5):
- CLAUDE.md KNOWN LIMITATION 2: the continuous-historization historized-ref
  feed IS wired (AddressSpaceApplier.FeedHistorizedRefs -> UpdateHistorizedRefs
  -> recorder); rewrite to reflect that value-capture is code-complete and only
  the live end-to-end + restart-convergence verification remains.
- CLAUDE.md ScriptAnalysis gating: endpoints use Roles=Administrator,Designer
  via RequireAuthorization, not the FleetAdmin policy.
This commit is contained in:
Joseph Doherty
2026-07-08 16:14:37 -04:00
parent 9cad9ed0fc
commit 9fadead6a6
17 changed files with 5846 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
archreview/plans/00-INDEX.md
+69
View File
@@ -0,0 +1,69 @@
# Arch-Review Remediation Plans — Index
Design + implementation plans for every finding in the 2026-07-08 architecture review
(`archreview/*.md`, review commit `9cad9ed0`). Each plan verifies every finding against
the current tree, then gives root cause → design (with alternatives) → concrete file-level
steps → tests → effort/risk.
## Plan documents
| # | Plan | Findings | Verification |
|---|---|---|---|
| 01 | [Core & composition](01-core-composition-plan.md) | 21 | all confirmed, 0 stale |
| 02 | [Scripting & alarms](02-scripting-alarms-plan.md) | 30 | all confirmed, 0 stale |
| 03 | [Server & runtime](03-server-runtime-plan.md) | 28 | all confirmed (U1 = stale *doc* only) |
| 04 | [AdminUI](04-adminui-plan.md) | 20 | all confirmed (C-3/C-4 good, no action) |
| 05 | [Protocol drivers](05-protocol-drivers-plan.md) | 37 + 1 positive | all confirmed, 0 stale |
| 06 | [Gateway integrations](06-gateway-integrations-plan.md) | 28 (23 actionable) | all confirmed (U-1 = stale *doc*) |
| 07 | [Client, tooling & engineering](07-client-tooling-engineering-plan.md) | 26 | all confirmed, 0 stale |
**Total: ~190 findings planned. Zero were stale-because-already-fixed; the only "stale" items are
two documentation drifts (CLAUDE.md Known Limitation 2) both flagged for correction.**
## The 4 Criticals (fix first)
| # | Critical | Plan | Fix shape |
|---|---|---|---|
| 1 | Split-brain resolver never activated → no hard-crash failover | 03 S1 | `ClusterOptions.SplitBrainResolver = KeepOldestOption` + hard-kill failover test |
| 2 | Production VT script timeout is dead code → one loop wedges the actor | 02 U2 (+U3) | Route through `TimedScriptEvaluator` + `CompiledScriptCache` |
| 3 | S7 has no reconnect path → PLC reboot kills the driver | 05 STAB-1 | `IS7PlcFactory` seam + lazy `EnsureConnectedAsync` |
| 4 | TwinCAT ADS subs orphaned after reconnect → silent data stop | 05 STAB-2 | Store replayable registration intent, replay on client swap |
## Cross-cutting guardrails (from OVERALL themes, span multiple plans)
- **Theme #1 built-but-never-wired** — the recurring failure mode. Guardrails proposed across plans:
reflection-exhaustive `DeferredAddressSpaceSink` forwarding test (03 U2, sequenced *before* the
surgical-add work), wiring the OTOPCUA0001 analyzer repo-wide (07 C-1), a startup log line proving
SBR is active (03 S1), and wiring/removing the dormant historian health surface (06 S-6).
- **Theme #2/#6 fixes don't flow to shared templates** — Part B of plan 05: `PollGroupEngine` v2
(backoff + onError + delete the S7 fork), shared strict `ReadEnum`/`ReadBool`, `ConnectionBackoff`
primitive, `ResolveHost`-via-resolver; plus `TagConfigIntent.Parse` in Commons (01 C-1) killing the
4-project byte-parity duplication.
- **Theme #3 optimistic success** — failure-visibility fixes: `AddressSpaceApplyOutcome` failure field
(01 S-1), Galaxy write fail-closed (06 S-1), primary-gate default-deny on unknown role (03 S4).
- **Theme #4 verification gap** — CI to all unit suites + fail-on-skip (07 S-1/S-2), fault-injection tier
(hard-kill / drop-PLC), the missing bUnit substitute = reflection/policy guards (04 C-1).
- **Theme #5 doc drift** — fix CLAUDE.md Known Limitation 2 + scadaproj index (03 U1 / 06 U-1),
ScriptAnalysis policy doc, Client.CLI docs (07 U-3).
- **Theme #7 repo hygiene** — `git rm -r lib/` AVEVA DLLs, untrack planning files, delete Wonderware
husks (07 U-4/U-5/U-6).
## Suggested execution order
Front-loaded per the OVERALL prioritized action list — items 1–6 eliminate every Critical plus the two
systemic guards (analyzer + CI) that stop the built-but-never-wired pattern recurring:
1. **Criticals** — 03 S1, 02 U2+U3, 05 STAB-1, 05 STAB-2 (each with its missing test)
2. **Systemic guards** — 07 C-1 (analyzer) + 07 S-1/S-2 (CI to all suites, fail-on-skip); 03 U2 (Deferred-sink forwarding test)
3. **Silent-corruption Highs** — 05 STAB-4/5 (AbCip lock, FOCAS caches), 05 Modbus timeout-fatal classification
4. **Failure-visibility Highs** — 01 S-1, 06 S-1, 03 S4
5. **AdminUI authz** — 04 C-1 (ConfigEditor policy + reflection guard)
6. **Perf** — 03 P1 (surgical pure-adds, after 03 U2 guard)
7. **Consolidation + hygiene + docs** — 01 C-1, 05 Part B, 07 U-4/U-5, doc fixes
## Open maintainer decision
- **Prune vs. keep the dormant machinery** (01 U-2 / 02 U-1): the callerless Tier-C recycle machinery +
`IDriverSupervisor`, and the ~2.4k-line `Core.VirtualTags` engine that production bypasses. Plans
recommend retiring both *after* the live paths are hardened (02 U2/U3 first), but the delete-vs-keep
call is the maintainer's.