scadaproj/components/audit/current-state/scadabridge/CURRENT-STATE.md

Audit — current state: ScadaBridge

Repo: ~/Desktop/ScadaBridge. Stack: .NET 10, Akka.NET; solution ZB.MOM.WW.ScadaBridge.slnx. Audit code centers on the dedicated ZB.MOM.WW.ScadaBridge.AuditLog project, with the shared record + seams living in ZB.MOM.WW.ScadaBridge.Commons. All paths relative to repo root. Verified 2026-06-01.

By far the largest audit implementation in the family — a full who-did-what pipeline across a site SQLite hot-path and a central MS SQL store, with forwarding, reconciliation, purge, partition maintenance, redaction, CLI export, hash-chain verify (v1 stub), and a Blazor UI. Key finding: ScadaBridge is already at the target. It already has an IAuditWriter best-effort seam (near-identical to the canonical contract) and an IAuditPayloadFilter redaction seam (= the library's IAuditRedactor, just renamed). Adoption is align, don't replace — mostly naming alignment; the enormous transport/storage/CLI/UI stays bespoke.

1. How it works today

The record — AuditEvent (~25 fields)

src/ZB.MOM.WW.ScadaBridge.Commons/Entities/Audit/AuditEvent.cs:22 — a sealed record, append-only, "single source of truth for AuditLog (#23) rows." Far richer than the canonical 10-field event. Notable fields:

• Identity / correlation: EventId (idempotency key, :25), CorrelationId (per-op lifecycle, :68), ExecutionId (per-run, :75), ParentExecutionId (spawner link, :82).
• Classification: Channel (:62), Kind (:65), Status (:109) — the domain enums (below).
• Provenance: SourceSiteId (:85), SourceNode (:94, stamped from INodeIdentityProvider), SourceInstanceId (:97), SourceScript (:100), Actor (:103), Target (:106).
• Outcome detail: HttpStatus (:112), DurationMs (:115), ErrorMessage (:118), ErrorDetail (:121).
• Payload: RequestSummary / ResponseSummary (truncated+redacted, :124/:127), PayloadTruncated (:130), Extra (free-form JSON, :133).
• Lifecycle plumbing: IngestedAtUtc (null on site, stamped at central ingest, :52), ForwardState (site-only, null on central, :136).

UTC-forcing init-setters. OccurredAtUtc (:39) and IngestedAtUtc (:52) keep a backing field and call DateTime.SpecifyKind(value, DateTimeKind.Utc) on assignment, so a value built from a literal or rehydrated from a SQL Server datetime2 column (which strips Kind on the wire) cannot leak downstream as Unspecified/local. The record uses DateTime (not DateTimeOffset) deliberately, to match the partitioned datetime2 column shape (:9-21).

Domain vocabulary — four enums

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Enums/:

• AuditChannel.cs:7 — trust boundary crossed: ApiOutbound, DbOutbound, Notification, ApiInbound.
• AuditKind.cs:8 — specific event within a channel: ApiCall, ApiCallCached, DbWrite, DbWriteCached, NotifySend, NotifyDeliver, InboundRequest, InboundAuthFailure, CachedSubmit, CachedResolve. Cached variants emit multiple rows per operation.
• AuditStatus.cs:8 — lifecycle status of the row: Submitted, Forwarded, Attempted, Delivered, Failed, Parked, Discarded, Skipped.
• AuditForwardState.cs:9 — site-local forwarding state (central rows leave null): Pending, Forwarded, Reconciled. The site retention purge MUST NOT drop a Pending row.

The writer seam — IAuditWriter (best-effort, never aborts the action)

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IAuditWriter.cs:10 — boundary-side abstraction: Task WriteAsync(AuditEvent evt, CancellationToken ct = default) (:18). The contract is explicit and matches the canonical seam almost word-for-word: "Failures must NEVER abort the user-facing action" (:8), best-effort, "implementations must swallow/log internal failures rather than propagating them to the calling boundary code" (:13-14).

The redaction seam — IAuditPayloadFilter (pure, never throws)

src/ZB.MOM.WW.ScadaBridge.AuditLog/Payload/IAuditPayloadFilter.cs:22 — AuditEvent Apply( AuditEvent rawEvent) (:30). Filters an event between construction and persistence: truncates oversized payloads, redacts headers/body/SQL params, sets PayloadTruncated. Pure function returning a filtered COPY via with expressions, and MUST NOT throw — on internal failure it over-redacts and increments the AuditRedactionFailure health metric (:11-20, :26-28). This is exactly the canonical IAuditRedactor under a different name. Two implementations: DefaultAuditPayloadFilter.cs:56 (full truncation + header/body/SQL redaction with live options) and SafeDefaultAuditPayloadFilter.cs:19 (always-safe fallback — header-only redaction, over-redacts on parse failure, :42-59).

Transport / storage / pipeline — stays per-project

The ZB.MOM.WW.ScadaBridge.AuditLog project is split into Site/, Central/, Payload/, and Configuration/. This is the bespoke half and is not a candidate for extraction; cited here only to show the scale around the common core:

• Site hot-path: Site/SqliteAuditWriter.cs:32 (IAuditWriter over an owned SqliteConnection fed by a bounded Channel<T> drained on a background task, so script-thread callers never block on disk I/O; first-write-wins on duplicate EventId). Site/FallbackAuditWriter.cs:28 composes the SQLite writer with a drop-oldest RingBufferFallback so a primary failure never bubbles out. Site/Telemetry/ forwards rows to central over Akka ClusterClient.
• Central ingest/store: Central/CentralAuditWriter.cs:40 (ICentralAuditWriter, direct MS SQL write for central-originated events, per-call EF scope, idempotent InsertIfNotExistsAsync, swallows every exception per "alog.md §13"). Central/AuditLogIngestActor.cs:46 batches site telemetry; Central/SiteAuditReconciliationActor.cs:68 periodically pulls to catch dropped forwards; Central/AuditLogPurgeActor.cs:58 enforces retention; Central/AuditLogPartitionMaintenanceService.cs:55 manages the partitioned table.
• CLI: CLI/Commands/AuditCommands.cs:12 builds export (:137, formats csv/jsonl/parquet) and verify-chain (:226). Hash-chain verify is currently a v1 no-op stub — CLI/Commands/AuditVerifyChainHelpers.cs:6-10 ("v1 is a no-op").
• UI: Blazor pages under CentralUI/Components/Pages/Audit/ (e.g. AuditLogPage.razor:1, gated by [Authorize(Policy = AuthorizationPolicies.OperationalAudit)]) plus drill-down components in CentralUI/Components/Audit/.
• Wiring: AuditLog/ServiceCollectionExtensions.cs:59 AddAuditLog(...), :316 AddAuditLogCentralMaintenance(...).

2. Mapping to the canonical record

Target (ZB.MOM.WW.Audit, being built): record AuditEvent { Guid EventId; DateTimeOffset OccurredAtUtc; string Actor; string Action; AuditOutcome Outcome; string? Category; string? Target; string? SourceNode; Guid? CorrelationId; string? DetailsJson; }. ScadaBridge's record is a strict superset — the canonical fields map directly; the rich extras collapse into DetailsJson.

Canonical field	ScadaBridge source	Notes
EventId (Guid)	AuditEvent.EventId	Direct; same idempotency-key role.
OccurredAtUtc (DateTimeOffset)	AuditEvent.OccurredAtUtc (DateTime, UTC-forced)	Type bridge DateTime(Utc)↔DateTimeOffset; semantics identical.
Actor (string)	AuditEvent.Actor (nullable)	Direct; ScadaBridge allows null (system-originated rows).
Action (string)	AuditEvent.Kind (+Channel)	Derive a stable action string, e.g. {Channel}.{Kind} (ApiOutbound.ApiCall).
Outcome (Success/Failure/Denied)	AuditEvent.Status	Delivered→Success; Failed/Parked/Discarded→Failure; InboundAuthFailure(Kind)→Denied; in-flight Submitted/Forwarded/Attempted collapse to the last-known terminal state when projecting.
Category (string?)	AuditEvent.Channel	The coarse bucket; pairs with Action above.
Target (string?)	AuditEvent.Target	Direct.
SourceNode (string?)	AuditEvent.SourceNode	Direct (node-a/central-b/…).
CorrelationId (Guid?)	AuditEvent.CorrelationId	Direct (per-op lifecycle id).
DetailsJson (string?)	ExecutionId, ParentExecutionId, SourceSiteId, SourceInstanceId, SourceScript, HttpStatus, DurationMs, ErrorMessage, ErrorDetail, RequestSummary, ResponseSummary, PayloadTruncated, Extra, IngestedAtUtc, ForwardState	The ~15 rich/plumbing fields serialize into the canonical DetailsJson extension.

The canonical record is a lossy projection of ScadaBridge's — fine for cross-project reporting, but ScadaBridge keeps its full record as the storage shape (the partitioned SQL schema, forwarding state, and reconciliation all depend on the extra columns).

3. Adoption plan → ZB.MOM.WW.Audit

Posture: align, don't replace. ScadaBridge is the reference implementation the shared library is being extracted from; it already has both seams. Adoption is mostly renaming and contract-confirmation, with a deliberately small touched surface and a large blast radius if done carelessly. Priority: LOW. Blast radius: HIGH.

Align (small, naming-level):

• Rename the redaction seam to match the contract. IAuditPayloadFilter → adopt ZB.MOM.WW.Audit.IAuditRedactor (AuditEvent Apply(AuditEvent) — identical signature and pure/never-throws contract). Either alias IAuditPayloadFilter : IAuditRedactor during transition or rename outright; DefaultAuditPayloadFilter / SafeDefaultAuditPayloadFilter implement it unchanged. See ../../shared-contract/.
• Confirm the writer contract matches. IAuditWriter.WriteAsync(AuditEvent, CancellationToken = default) is already byte-for-byte the canonical signature, and the "never abort the user-facing action" wording matches. The only delta is the record type: the library's IAuditWriter is typed on the canonical 10-field AuditEvent, while ScadaBridge's is typed on its ~25-field record. Resolve by either (a) keeping ScadaBridge's writer on its own rich record and adopting only the library's interface name + outcome enum, or (b) having the shared seam be generic over the event type. Recommended: (a) — adopt the canonical AuditOutcome enum and the interface naming, but keep the bespoke AuditEvent as ScadaBridge's storage record, since the whole transport/partition/forwarding layer is built on its extra columns. (Best-practice fit: this is the minimal-coupling option — share the contract, not the schema.)

Keep bespoke (the large, untouched majority):

• The entire Site/ (SQLite hot-path + ring-buffer fallback + telemetry forwarder) and Central/ (ingest / reconcile / purge / partition maintenance) pipeline.
• The AuditEvent rich record itself, the four domain enums (AuditChannel/AuditKind/ AuditStatus/AuditForwardState), CLI export/verify-chain, and the Blazor audit UI.
• The redaction policy (DefaultAuditPayloadFilter options, per-target overrides) — only the interface name is shared, not the implementation.

Net: ScadaBridge converges by renaming one interface and adopting the canonical AuditOutcome enum + the Kind/Channel→Action/Category and …→DetailsJson projection for any cross-project reporting. No transport, storage, CLI, or UI is replaced. Sequencing and the cross-project gap list live in ../../GAPS.md; the canonical target is ../../spec/SPEC.md.