docs(code-review): re-review 17 changed modules at 1f9de8a2 — 8 new findings

Re-reviewed the modules whose source changed since the last review baseline
(full-review remediation fd618cf1 + InboundAPI Database-helper fixes b3c90143),
focused on whether the fixes are sound and regression-free. 9 of 17 modules
clean; 8 new findings (0 Critical, 0 High, 4 Medium, 4 Low), all code-verified
by the orchestrator before recording:

- DataConnectionLayer-029 (Med): DCL-023's unsubscribe-clears-in-flight reopens a
  double-subscribe window that leaks an orphaned alarm feed; the alarm completion
  handler overwrites the subscription id without the tag-path guard at line 908.
- InboundAPI-031 (Med): WaitForAttribute's 5s grace backstop is tighter than the
  CommunicationService Ask's timeout+IntegrationTimeout (30s) round-trip slack, so
  a slow-but-valid timed-out 'false' arriving in the 5-30s window is cancelled into
  an unhandled OperationCanceledException/500 (contradicts spec 6 + its own comment).
- SiteRuntime-032 (Med): SiteRuntime-029's wasPresent guard skips the deployed-count
  decrement when deleting a DISABLED instance (absent from both maps), drifting the
  health-dashboard tally; self-heals on singleton restart (observational, hence Med).
- StoreAndForward-028 (Med): StoreAndForward-025 resets the register-guard but not
  _bufferedCount, so a same-instance Stop->Start re-seeds the depth gauge to ~2N.
- AuditLog-017, CentralUI-037, ScriptAnalysis-009, SiteRuntime-033 (Low): a
  test-coverage gap plus stale doc-comments/spec following the remediation.

Header commit/date bumped to 1f9de8a2 / 2026-06-24 on all 17 modules; README
regenerated (8 pending / 576 total).
This commit is contained in:
Joseph Doherty
2026-06-24 09:20:03 -04:00
parent 1f9de8a2b5
commit c42bb48585
18 changed files with 635 additions and 66 deletions
+24 -2
View File
@@ -5,9 +5,9 @@
| Module | `src/ZB.MOM.WW.ScadaBridge.TemplateEngine` |
| Design doc | `docs/requirements/Component-TemplateEngine.md` |
| Status | Reviewed |
| Last reviewed | 2026-06-20 |
| Last reviewed | 2026-06-24 |
| Reviewer | claude-agent |
| Commit reviewed | `4307c381` |
| Commit reviewed | `1f9de8a2` |
| Open findings | 0 |
## Summary
@@ -1388,3 +1388,25 @@ and add a legacy-array test asserting names are returned.
Resolved 2026-06-20 (commit `fd618cf1`): deleted the dead, misnamed `SemanticValidator.ParseParameterDefinitions` (no production caller per grep; its only references were two tests, which asserted the buggy type-not-name output). Tests removed.
## Re-review — 2026-06-24 (commit `1f9de8a2`)
Focused re-review of the changes since the prior review — verifying the code-review remediation + feature fixes are sound and regression-free. Reviewed by a per-module workflow agent; findings code-verified by the orchestrator.
**Changes reviewed:** Two changes since 4307c381. (1) TemplateFolderService.cs: each of the five folder mutators (Create/Rename/Move/Reorder/Delete) now issues a second SaveChangesAsync after auditService.LogAsync, so the audit row staged on the EF change tracker is actually persisted instead of being discarded when the ManagementActor's DI scope is disposed. (2) SemanticValidator.cs: the unused internal ParseParameterDefinitions(string?) helper was deleted along with its two unit tests; the matching call-order tests for folder audit persistence were added.
**Verdict:** Both deltas are correct, minimal, and regression-free. The audit-persistence fix closes a real defect: AuditService.LogAsync only stages an AuditLogEntry on the change tracker (it explicitly documents that the caller must SaveChanges), so before this change folder-mutation audit rows were never flushed — violating the design doc's "all template changes are audit logged" requirement. The fix mirrors the established, deliberate TemplateService pattern (save entity to populate the key, log, then save the staged audit row) and is covered by new call-order tests asserting a save follows the log. The ParseParameterDefinitions removal is genuinely dead code (no remaining references in src or tests, no design-doc footprint, System.Text.Json still used elsewhere so no orphaned using). Project builds with zero warnings; all 88 TemplateFolderService + SemanticValidator tests pass. No new issues found.
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | Second SaveChangesAsync correctly flushes the staged audit row (LogAsync only stages, per AuditService.cs:59-61). For Rename/Move/Reorder/Delete the entity id is already known so the audit entityId is correct. No issues found. |
| 2 | Akka.NET conventions | ☑ | No actor code touched; TemplateFolderService is a plain async service invoked from within a ManagementActor DI scope. No Tell/Ask, supervision, or closure-capture concerns in the delta. |
| 3 | Concurrency & thread safety | ☑ | No shared mutable state introduced; per-request scoped DbContext, sequential awaits. No issues found. |
| 4 | Error handling & resilience | ☑ | The added saves are non-atomic with the entity save (separate transaction), matching the accepted TemplateService trade-off; audit-as-best-effort is consistent with system design. No issues found. |
| 5 | Security | ☑ | No secrets, no injection surface; audit serialization handles cycles/depth in AuditService. No change to security posture. |
| 6 | Performance & resource management | ☑ | One extra round-trip SaveChangesAsync per folder mutation — negligible for low-frequency admin operations and required for correctness. No leaks (no IDisposable introduced). |
| 7 | Design-document adherence | ☑ | Fix realizes Component-TemplateEngine.md:218 'all template changes are audit logged'. ParseParameterDefinitions removal drops no documented capability. |
| 8 | Code organization & conventions | ☑ | Mirrors TemplateService pattern exactly; dead-code removal leaves no orphaned usings (build has 0 warnings). Clean. |
| 9 | Testing coverage | ☑ | New tests assert a SaveChangesAsync follows LogAsync for all five mutators plus Times.Exactly(2) save counts; obsolete ParseParameterDefinitions tests removed. 88 tests pass. |
| 10 | Documentation & comments | ☑ | Each added save has an accurate explanatory comment cross-referencing CreateFolderAsync/TemplateService and the DI-scope-disposal rationale. XML doc on the removed method went with it. |
_No new findings — the changes in this module are clean._