Joseph Doherty
d1ade5653b
A verified audit of all ~90 plan documents (2026-08-01) found ~30 .tasks.json
trackers and several plan headers still reporting 'pending'/'draft' for work
fully merged to main. Sync them so future audits don't re-litigate closed work:
- Flip ~380 stale task statuses to completed across March/May/June/July
trackers (audit-log series, milestones M5-M10, playwright waves, stillpending,
LocalDb, ClusterClient->gRPC DoD rows, and more), each verified against
code/git evidence before flipping.
- Annotate obsolete-not-done rows: ClusterClient CLI transport (never built,
HTTP shipped), TreeView Areas/Instances pages (replaced by Topology),
template-tree drag-drop (dropped for M9 menu reorder), otopcua item C
(premise superseded by #17).
- Flip stale headers: aggregated-live-alarm + kpi-rollups 'Draft not executed'
-> Delivered 2026-07-10; otopcua cutover-scope SCOPING -> DECIDED;
scadabridge-rename -> Implemented; LocalDb phase1/2 status strings ->
merged 28ca04d7.
- Fix doc drift: T9/T10 'deferred' -> shipped as SMS (Teams dropped); waitfor
sandbox follow-up shipped; followups #52/#53/#54/#162/#207 resolved; purge
TODO closed by PendingDeploymentPurgeActor; live-gate pre-existing failures
#28/#29/#31 fixed; auto-down boot-alone residual superseded by self-first
seeds; supersession banners on keep-oldest SBR + ClusterClient-era designs;
requirements-traceability 'Pending' clarified as frozen plan-generation
status.
Deliberately left pending (genuinely open, tracked in the pending-work list):
opcua-tag-browser task 19 (live smoke), ipsen tasks 7-8 (vd03 verification),
selfform task 7 (vd03 overlay, user-held), live-gate observation 1
(external-system delete orphan bug), otopcua item A + maxDepth calibration.
48 lines
2.8 KiB
Markdown
48 lines
2.8 KiB
Markdown
# Communication Layer Refinement — Design
|
||
|
||
**Date**: 2026-03-16
|
||
**Component**: Central–Site Communication (`docs/requirements/Component-Communication.md`)
|
||
**Status**: Approved — transport decisions superseded by the ClusterClient→gRPC migration (`docs/plans/2026-07-22-clusterclient-to-grpc-plan.md`); the "no buffering at central" decision still stands.
|
||
|
||
## Problem
|
||
|
||
The Communication Layer doc defined 8 message patterns clearly but lacked specification for timeouts, transport configuration, reconnection behavior, message ordering guarantees, and connection failure handling.
|
||
|
||
## Decisions
|
||
|
||
### Message Timeouts
|
||
- **Per-pattern timeouts with sensible defaults**, overridable in configuration.
|
||
- Deployment and system-wide artifacts: 120 seconds (script compilation can be slow).
|
||
- Lifecycle commands, integration routing, recipe/command delivery, remote queries: 30 seconds.
|
||
- Uses the Akka.NET ask pattern; timeout results in failure to caller.
|
||
|
||
### Transport Configuration
|
||
- **Akka.NET built-in reconnection** with explicitly configured transport heartbeat interval and failure detection threshold.
|
||
- No custom reconnection logic — framework handles it.
|
||
- Settings explicitly documented rather than relying on framework defaults, for predictability in a SCADA context.
|
||
|
||
### Connection Failure Behavior
|
||
- **In-flight messages get a timeout error** — caller retries manually. No buffering at central. Consistent with existing design principle.
|
||
- Automatic retry rejected due to risk of duplicate processing (e.g., site may have applied a deployment before the connection dropped).
|
||
|
||
### Message Ordering
|
||
- **Per-site ordering guaranteed** — relies on Akka.NET's built-in per-sender/per-receiver ordering. No custom sequencing logic needed.
|
||
|
||
### Debug Stream Interruption
|
||
- **Stream dies on any disconnect** (failover or network blip). Engineer reopens the debug view manually.
|
||
- Auto-resume rejected — adds complexity for a transient diagnostic tool.
|
||
|
||
## Affected Documents
|
||
|
||
| Document | Change |
|
||
|----------|--------|
|
||
| `docs/requirements/Component-Communication.md` | Added 4 new sections: Message Timeouts, Transport Configuration, Message Ordering, Connection Failure Behavior |
|
||
|
||
## Alternatives Considered
|
||
|
||
- **Global timeout for all patterns**: Rejected — deployment involves compilation and needs more time than a simple query.
|
||
- **Default Akka.NET transport settings**: Rejected — relying on undocumented defaults is risky for SCADA; explicit configuration ensures predictable behavior.
|
||
- **Automatic retry of in-flight messages**: Rejected — risks duplicate processing and contradicts the no-buffering-at-central principle.
|
||
- **No ordering guarantee**: Rejected — Akka.NET provides this for free; the design already implicitly relies on it.
|
||
- **Auto-resume debug streams on reconnection**: Rejected — adds state tracking complexity for a transient diagnostic feature.
|