3 Commits

Author	SHA1	Message	Date
Joseph Doherty	00a804e6d9	guard(di): captive-dependency tripwires — scope validation + an actor field scan ... Register row 50. Row 45 (fixed 9e769735) was a live captive dependency — NotificationOutboxActor cached delivery adapters resolved from an actor-lifetime IServiceScope, so MaxParallelDeliveries concurrent deliveries shared one EF DbContext and central-b logged EF's "second operation was started on this context instance" continuously. Actors take the ROOT IServiceProvider rather than typed services, which is invisible to build-time analysis, so the bug class had no mechanical guard at all. This adds both of the register's mitigations; neither subsumes the other. 1. ValidateScopes + ValidateOnBuild in Development, on BOTH branches, via ServiceProviderValidation.Configure. WebApplication.CreateBuilder already sets both flags to IsDevelopment(), so on paper this restates a default — it is written out because that default is silent (a future move off CreateBuilder drops it with no diagnostic) and because this host carries three environment-ish signals (SCADABRIDGE_CONFIG, DOTNET_ENVIRONMENT, ASPNETCORE_ENVIRONMENT), so "is this node in Development" is not obvious at the call site. Production stays unvalidated deliberately: a validation failure is fail-closed, and CI now proves what a production node will not check. This surfaced two REAL latent violations on the SITE role — not captive dependencies but unconstructible descriptors, which fail ValidateOnBuild for the entire graph and are therefore what kept the site branch from being validatable at all (SiteHealthEndpointTests had pinned UseEnvironment ("Production") to work around exactly this): - ReconcileService (scoped, needs the central-only IDeploymentManagerRepository) moved out of the shared AddCommunication() into a new AddCentralCommunication(). - AuditLogKpiSampleSource (scoped IKpiSampleSource, needs the central-only IAuditLogRepository) moved out of the shared AddAuditLog() into a new AddAuditLogCentralKpi(). Both were registered on sites under the argument "harmless — only the central actor ever resolves it". True of the runtime, false of the container: a registration nothing can build is what stops the validator being usable, and it masks whatever real defect the validator would have found. Both are now central-only and SiteHealthEndpointTests boots the site branch validated again. 2. CaptiveDependencyGuard: a reflection scan over every actor class in the shipped assemblies (28 today; the reference graph is walked from the Host assembly because referenced assemblies load lazily). Fails on any instance field — auto- property backing fields included, they are ordinary private fields — typed as IServiceScope, as a DbContext, or as a service the REAL composition roots register Scoped. The scoped set is derived from the built Central and Site containers rather than hand-listed, so a lifetime change automatically re-scopes the check. IServiceProvider / IServiceScopeFactory fields are explicitly allowed: that IS the correct per-operation-scope pattern. No live violation exists — every actor opens a scope per operation. Two fields are allowlisted with their safety argument rather than exempted silently: AuditLogIngestActor._injectedRepository and SiteCallAuditActor._injectedRepository are scoped repository types assigned ONLY by explicitly test-mode constructors, null under production wiring (AkkaHostedService uses the IServiceProvider overload in both cases), and SiteCallAuditActor additionally wraps its injected instance in a SerializedRepository. The shape is one constructor call away from being row 45 again, so it is recorded, not dismissed. Tests: 10 new. Six permanent self-tests of the guard, including positive controls that reproduce the pre-row-45 shape (an actor caching a scoped service, an IServiceScope, a DbContext, and a scoped auto-property) and a negative control for the allowed root-provider pattern — a reflection guard that matches nothing passes just as green as one that works. Plus an actor-count floor with cross-assembly spot-checks, an allowlist-staleness test that fails any entry no longer matching a flagged field, and the two per-role scans. Verified non-vacuous by emptying the allowlist: the Central scan then names both real fields. Two composition-root build tests force both validation flags on per role regardless of environment. Doc: REQ-HOST-11 in Component-Host.md records all three rules and their guards.	2026-08-15 11:58:40 -04:00
Joseph Doherty	2e4e41a8f7	fix(auditlog): site audit DB onto the data volume; required path + soft flush ... Closes WP1.2 of the arch-review remediation plan (finding #2, High): SqliteAuditWriterOptions.DatabasePath defaulted to CWD-relative "auditlog.db", which on the docker rig resolves onto the container's ephemeral overlayfs (not the mounted /app/data volume), silently discarding the pending audit forward-state backlog on every recreate; nothing in docker/ or docker-env2/ overrode it; FlushIntervalMs was validated but never read by the writer loop (one commit per event even at trickle rate); and no PRAGMA synchronous was set (SQLite's FULL default fsyncs every commit). - DatabasePath now has no default (mirrors ZB.MOM.WW.LocalDb's LocalDbOptions.Path) and is required pre-host for Site nodes only, via a new StartupValidator raw-config check (top-level "AuditLog:SiteWriter:DatabasePath", NOT nested under ScadaBridge: AddAuditLog binds that section off the configuration root). SqliteAuditWriterOptionsValidator deliberately does NOT check DatabasePath itself, because AddAuditLog runs its ValidateOnStart on both Central and Site composition roots but only Site nodes ever resolve the writer — checking it there would fail Central's boot too. - All 8 site-node appsettings under docker/ and docker-env2/ now set AuditLog:SiteWriter:DatabasePath to /app/data/auditlog.db (mounted volume, survives container recreate, same convention as LocalDb:Path); the local-dev base appsettings.Site.json sets ./data/auditlog.db to match. - The writer loop now honors FlushIntervalMs: after draining the immediately available burst, it keeps the transaction open (bounded by FlushIntervalMs from the first event) waiting for more trickle-rate events before committing, instead of flushing (and fsyncing) per event. - PRAGMA synchronous = NORMAL on the write connection — audit is best-effort by design (CLAUDE.md: "Audit-write failure NEVER aborts the user-facing action"), so NORMAL's narrower power-loss window is an acceptable trade for far fewer fsyncs; WAL mode still guarantees no corruption. - Tests: StartupValidator site-required/blank/central-exempt cases; writer trickle-load single-transaction coalescing + beyond-interval separate-transaction regression (new FlushCountForTests seam); options-validator doc updates reflecting the moved responsibility. Full suite runs green: AuditLog.Tests 368/368, Host.Tests 480/480. One-time migration note: the existing container-local auditlog.db (wherever it landed under CWD) is abandoned by this change, not migrated — already-forwarded rows are safe centrally (AuditLog is the durable copy), and any still-Pending rows on the abandoned path are lost once. This is the exact bug being fixed, not a new loss: those rows were already living outside the mounted volume and would not have survived the next container recreate regardless. Cross-reference docs/known-issues/2026-07-20-cached-telemetry-drain-hot-loop.md, which this placement bug caused.	2026-08-14 20:13:31 -04:00
Joseph Doherty	47850c0f53	feat(health): serve MapZbHealth on site nodes ... Site nodes served no health surface at all — gRPC on the HTTP/2-only listener and /metrics on the HTTP/1.1 one — so nothing outside the cluster could ask a site node whether it was ready or which half of the pair was active. The family overview dashboard probes every instance the same way, and this is the one gap. Three checks, registered in SiteServiceRegistration.Configure (not Program.cs, so the composition-root tests that build this graph actually cover them) and mapped by app.MapZbHealth() on the site's HTTP/1.1 listener (default :8084) alongside /metrics: akka-cluster [Ready] the shared AkkaClusterHealthCheck. Also carries the cluster-view data (leader/memberCount/...) the dashboard reads, free with ZB.MOM.WW.Health 0.2.0. localdb [Ready] NEW SiteLocalDbHealthCheck — SELECT 1 through the registered ILocalDb. Site has no EF context; central's DatabaseHealthCheck<ScadaBridgeDbContext> is central-only. Replication state rides along as data ENRICHMENT only: replication is default-OFF, so failing on it would mark every correctly-configured node unready. active-node [Active] NEW SitePairActiveNodeHealthCheck, delegating to IClusterNodeProvider.SelfIsPrimary. Deliberately NOT central's OldestNodeActiveHealthCheck: that one calls SelfIsOldest(cluster) with no role argument and would compute "oldest" across the wrong member set on a mesh carrying more than one site. Anonymous, as central's are: the site pipeline runs no authentication middleware and has no FallbackPolicy, so nothing extra was needed. Also bumps ZB.MOM.WW.Health* 0.1.0 -> 0.2.0 (central gains data.leader for free). Tests: SiteHealthCheckTests builds the REAL site container and activates every registration through its factory (exact-set names, one tier tag each, resolved types, central-only checks absent behind a positive control) plus behaviour for both new checks. SiteHealthEndpointTests boots the real site Program over WebApplicationFactory and proves the endpoints are MAPPED — without it, deleting MapZbHealth would leave every registration test green while site nodes 404'd. Prereq for scadaproj docs/plans/2026-07-22-overview-dashboard-impl-plan.md Phase 1.	2026-07-24 05:54:30 -04:00