diff --git a/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md b/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md
new file mode 100644
index 0000000..57fd762
--- /dev/null
+++ b/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md
@@ -0,0 +1,974 @@
+# Audit Normalization Component + ZB.MOM.WW.Audit Shared Library — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
+
+**Goal:** Normalize the "audit" cross-cutting concern across the three sister repos (OtOpcUa, MxAccessGateway, ScadaBridge) under `components/audit/`, then build a thin, tested, packed `ZB.MOM.WW.Audit` shared library that extracts the genuinely-common core: a canonical `AuditEvent` record, an `AuditOutcome` enum, a best-effort `IAuditWriter` seam, an `ILogRedactor`-aligned `IAuditRedactor` seam, and a handful of dependency-light helpers.
+
+**Architecture:** Spec-first. Phase A writes the normalization docs (the spec drives the API). Phase B builds the single NuGet package, strictly TDD, one type per task. Phase C registers the component in the workspace indexes. **No sister-repo adoption this round** — adoption is captured in `GAPS.md` exactly where Auth/Theme/Health adoption sits today. Transport/storage (Akka / SQLite-hot-path+central-SQL / SQLite) stays per-project; only the record + two seams are shared.
+
+**Tech Stack:** .NET 10, C# (file-scoped namespaces, `sealed record`, nullable enabled, central package management), xUnit + coverlet, `dotnet pack`. The library's only non-BCL dependency is `Microsoft.Extensions.DependencyInjection.Abstractions` (for the `AddZbAudit` extension). Design doc: [`docs/plans/2026-06-01-audit-component-design.md`](2026-06-01-audit-component-design.md).
+
+**Conventions mirrored from `ZB.MOM.WW.Auth/`** (read these for reference): `Directory.Build.props` (net10.0, `Version` 0.1.0, central package mgmt), `Directory.Packages.props`, `.slnx` solution, `build/pack.sh` (`dotnet pack -c Release -o ./artifacts`), per-package pack metadata (`IsPackable`/`PackageId`/`Authors=ZB.MOM.WW`/`Description`/`PackageProjectUrl`/`RepositoryUrl`), test csproj (`IsPackable=false`, ``, coverlet collector). Repo URL: `https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit`.
+
+---
+
+## Phase A — `components/audit/` normalization docs (spec-first)
+
+> Doc tasks: no TDD. Each task's "verification" is the file exists, cross-links resolve, and the content matches the cited code. Tasks 0–2 are independent (different sister repos) and dispatchable in parallel. Capture **real `file:line` refs** — re-verify against current code, do not trust this plan's line numbers blindly.
+
+### Task 0: Current-state — OtOpcUa
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 1, Task 2
+
+**Files:**
+- Create: `components/audit/current-state/otopcua/CURRENT-STATE.md`
+
+**Source to read (code-verify, capture `file:line`):**
+- `~/Desktop/OtOpcUa/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Audit/AuditEvent.cs` — record (`EventId, Category, Action, Actor, OccurredAtUtc, DetailsJson, SourceNode, CorrelationId`).
+- `~/Desktop/OtOpcUa/src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/ConfigAuditLog.cs` — EF entity + filtered-unique `EventId` index.
+- `~/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/Audit/AuditWriterActor.cs` — cluster-singleton, batch 500 / 5s flush, two-layer dedup.
+- `~/Desktop/OtOpcUa/tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests/AuditWriterActorTests.cs`; `~/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Clusters/ClusterAudit.razor`.
+
+**Step 1:** Write the doc with sections: *How it works today* (record shape, transport = Akka broadcast → singleton, storage = `ConfigAuditLog`, dedup/idempotency, scope = config writes + authz checks), *Mapping to the canonical record* (per the design's mapping table — `Action`/`Category`/`SourceNode`/`CorrelationId` map directly; `Outcome` is derived from the action vocabulary; rich fields → `DetailsJson`), and an *Adoption plan* (`AuditEvent`→canonical record; `AuditWriterActor : IAuditWriter`; `ConfigAuditLog` mapping — medium effort).
+
+**Step 2:** Verify every `file:line` ref by opening the cited file. Fix any drift.
+
+**Step 3: Commit**
+```bash
+git add components/audit/current-state/otopcua/CURRENT-STATE.md
+git commit -m "docs(audit): current-state OtOpcUa"
+```
+
+### Task 1: Current-state — MxAccessGateway
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 0, Task 2
+
+**Files:**
+- Create: `components/audit/current-state/mxaccessgw/CURRENT-STATE.md`
+
+**Source to read (code-verify, capture `file:line`):**
+- `~/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyAuditStore.cs` (`AppendAsync` + `ListRecentAsync`).
+- `.../ApiKeyAuditRecord.cs` (`AuditId, KeyId, EventType, RemoteAddress, CreatedUtc, Details`), `.../ApiKeyAuditEntry.cs`, `.../SqliteApiKeyAuditStore.cs`.
+
+**Step 1:** Write the doc: *How it works today* (narrowest of the three — API-key auth events/denials only, SQLite append + list-recent, no separate redaction seam — scrubbing is in the store), *Mapping to canonical* (`KeyId`→`Actor`, `EventType`→`Action`, `CreatedUtc`→`OccurredAtUtc`, denials→`Outcome.Denied`, `Category="ApiKey"`, `RemoteAddress`→`SourceNode`, `Details`→`DetailsJson`; new `EventId` Guid needed), *Adoption plan* (map `IApiKeyAuditStore`/`ApiKeyAuditRecord` → `IAuditWriter`/`AuditEvent` — low effort, but **coordinate**: the parallel health/observability session is already editing this repo for MEL→Serilog).
+
+**Step 2:** Verify refs.
+
+**Step 3: Commit**
+```bash
+git add components/audit/current-state/mxaccessgw/CURRENT-STATE.md
+git commit -m "docs(audit): current-state MxAccessGateway"
+```
+
+### Task 2: Current-state — ScadaBridge
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 0, Task 1
+
+**Files:**
+- Create: `components/audit/current-state/scadabridge/CURRENT-STATE.md`
+
+**Source to read (code-verify, capture `file:line`):**
+- `~/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Commons/Entities/Audit/AuditEvent.cs` (~25 fields, UTC-forcing init-setters).
+- `.../Commons/Interfaces/Services/IAuditWriter.cs` (best-effort: "Failures must NEVER abort the user-facing action").
+- `~/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.AuditLog/Payload/IAuditPayloadFilter.cs` (pure, never-throws, over-redacts).
+- The `ZB.MOM.WW.ScadaBridge.AuditLog/` Site (SQLite hot-path) + Central (MS SQL ingest/reconcile/purge/partition-maintenance) tree; `Commons/Types/Enums/{AuditChannel,AuditKind,AuditStatus,AuditForwardState}.cs`.
+
+**Step 1:** Write the doc: *How it works today* (the largest implementation — full who-did-what across site+central, hash-chain verify, CLI + UI + export). **State the key finding plainly: ScadaBridge is already at the target** — its `IAuditWriter` and `IAuditPayloadFilter` contracts are near-identical to what the library extracts. *Mapping to canonical* (`Kind`(+`Channel`)→`Action`/`Category` strings, `Status`→`Outcome`, rich fields → `DetailsJson`). *Adoption plan*: "align, don't replace" — rename `IAuditPayloadFilter`→`IAuditRedactor`, keep its `IAuditWriter`. Large surface, mostly naming alignment; low priority / high blast-radius.
+
+**Step 2:** Verify refs.
+
+**Step 3: Commit**
+```bash
+git add components/audit/current-state/scadabridge/CURRENT-STATE.md
+git commit -m "docs(audit): current-state ScadaBridge"
+```
+
+### Task 3: SPEC.md + EVENT-MODEL.md
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (synthesizes Tasks 0–2)
+
+**Files:**
+- Create: `components/audit/spec/SPEC.md`
+- Create: `components/audit/spec/EVENT-MODEL.md`
+
+**Step 1:** Write `SPEC.md` — the ONE normalized target. Open with **Section 0: Normalized vs left-per-project** (normalized = the canonical record + `Outcome` + the two seams; left-per-project = transport/storage, domain vocab `Channel`/`Kind`/`Status`/`ForwardState` + OtOpcUa event-types, query/CLI/UI, each app's redaction *policy*). Then: the best-effort writer contract, the never-throw redactor contract, and the "audit closes the loop on Auth" hinge (`Actor` SHOULD be the `ZB.MOM.WW.Auth` principal; kept as a string in the contract).
+
+**Step 2:** Write `EVENT-MODEL.md` (the reference doc, mirroring auth's `CANONICAL-ROLES.md` / theme's `DESIGN-TOKENS.md`): the field-by-field canonical record (required core + optional + `DetailsJson`), the `AuditOutcome` definition (`Success | Failure | Denied`) with which app states map to each, and the full per-project mapping table from the design doc.
+
+**Step 3: Commit**
+```bash
+git add components/audit/spec/SPEC.md components/audit/spec/EVENT-MODEL.md
+git commit -m "docs(audit): spec + event-model"
+```
+
+### Task 4: shared-contract/ZB.MOM.WW.Audit.md
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (blocked by Task 3)
+
+**Files:**
+- Create: `components/audit/shared-contract/ZB.MOM.WW.Audit.md`
+
+**Step 1:** Document the proposed public API *on paper* (this is the contract Phase B implements): the single package `ZB.MOM.WW.Audit`; the `AuditEvent` record + `AuditOutcome` enum signatures; `IAuditWriter` and `IAuditRedactor` interfaces with their hard contracts; the shipped helpers (`NullAuditRedactor`, `TruncatingAuditRedactor` + options, `NoOpAuditWriter`, `CompositeAuditWriter`, `RedactingAuditWriter`); `AddZbAudit`. State the single dependency (`Microsoft.Extensions.DependencyInjection.Abstractions`) and the "aligned-but-independent" relationship to Telemetry's `ILogRedactor`.
+
+**Step 2: Commit**
+```bash
+git add components/audit/shared-contract/ZB.MOM.WW.Audit.md
+git commit -m "docs(audit): shared-contract ZB.MOM.WW.Audit"
+```
+
+### Task 5: README.md + GAPS.md
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (blocked by Tasks 3, 4)
+
+**Files:**
+- Create: `components/audit/README.md`
+- Create: `components/audit/GAPS.md`
+
+**Step 1:** `README.md` — overview + per-project status table linking into the spec/current-state/shared-contract docs (match auth's/ui-theme's README shape).
+
+**Step 2:** `GAPS.md` — per-project divergences vs `SPEC.md` + the adoption/extraction backlog with priority/effort/risk: ScadaBridge "align, don't replace" (low priority, high blast-radius); MxGateway map onto seam (low effort, **coordinate** — shared repo with the other session); OtOpcUa record+actor migration (medium); cross-cutting `Outcome` normalization, `Actor`=Auth-principal, `IAuditRedactor` naming aligned with `ILogRedactor`. Note adoption is deferred (not built this round).
+
+**Step 3: Commit**
+```bash
+git add components/audit/README.md components/audit/GAPS.md
+git commit -m "docs(audit): README + GAPS adoption backlog"
+```
+
+---
+
+## Phase B — `ZB.MOM.WW.Audit` library (TDD)
+
+> All Phase B tasks blocked by Task 4 (the API on paper). Build from `~/Desktop/scadaproj/ZB.MOM.WW.Audit/`. Run tests with `dotnet test` from that root.
+
+### Task 6: Scaffold the library + test project + solution
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (blocked by Task 4)
+
+**Files:**
+- Create: `ZB.MOM.WW.Audit/Directory.Build.props`
+- Create: `ZB.MOM.WW.Audit/Directory.Packages.props`
+- Create: `ZB.MOM.WW.Audit/ZB.MOM.WW.Audit.slnx`
+- Create: `ZB.MOM.WW.Audit/src/ZB.MOM.WW.Audit/ZB.MOM.WW.Audit.csproj`
+- Create: `ZB.MOM.WW.Audit/tests/ZB.MOM.WW.Audit.Tests/ZB.MOM.WW.Audit.Tests.csproj`
+- Create: `ZB.MOM.WW.Audit/build/pack.sh`
+- Create: `ZB.MOM.WW.Audit/README.md`
+
+**Step 1: `Directory.Build.props`** (copy auth's):
+```xml
+
+
+ net10.0
+ enable
+ enable
+ latest
+ 0.1.0
+ true
+
+
+```
+
+**Step 2: `Directory.Packages.props`:**
+```xml
+
+
+ true
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Step 3: `src/ZB.MOM.WW.Audit/ZB.MOM.WW.Audit.csproj`:**
+```xml
+
+
+ net10.0
+ enable
+ enable
+
+
+ true
+ ZB.MOM.WW.Audit
+ ZB.MOM.WW
+ Canonical audit event model + best-effort writer and redactor seams for the ZB.MOM.WW SCADA family.
+ https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit
+ https://gitea.dohertylan.com/dohertj2/zb-mom-ww-audit
+
+
+
+
+
+```
+
+**Step 4: `tests/ZB.MOM.WW.Audit.Tests/ZB.MOM.WW.Audit.Tests.csproj`:**
+```xml
+
+
+ false
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Step 5: `ZB.MOM.WW.Audit.slnx`:**
+```xml
+
+
+
+
+
+
+
+
+```
+
+**Step 6: `build/pack.sh`** (`chmod +x` it):
+```bash
+#!/usr/bin/env bash
+# pack.sh — produce the ZB.MOM.WW.Audit NuGet package into ./artifacts.
+set -euo pipefail
+dotnet pack -c Release -o ./artifacts
+```
+
+**Step 7: `README.md`** — package overview + consumer matrix (all three apps; adoption deferred) + versioning note, mirroring auth's README shape.
+
+**Step 8: Verify it builds (empty but valid):**
+Run: `cd ~/Desktop/scadaproj/ZB.MOM.WW.Audit && dotnet build ZB.MOM.WW.Audit.slnx`
+Expected: Build succeeded (0 errors).
+
+**Step 9: Commit**
+```bash
+cd ~/Desktop/scadaproj/ZB.MOM.WW.Audit
+git init -q 2>/dev/null || true
+git add -A && git commit -m "chore(audit): scaffold ZB.MOM.WW.Audit solution"
+```
+> Note: this library is its own nested git repo (like `ZB.MOM.WW.Auth/`). Commit from inside `ZB.MOM.WW.Audit/`.
+
+### Task 7: AuditEvent record + AuditOutcome enum + the two seam interfaces
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (blocked by Task 6)
+
+> High-risk: this is the data contract every consumer maps onto. The interfaces are trivial (no behaviour) and are defined here so the helpers can compile; the record is TDD'd.
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/AuditOutcome.cs`
+- Create: `src/ZB.MOM.WW.Audit/AuditEvent.cs`
+- Create: `src/ZB.MOM.WW.Audit/IAuditWriter.cs`
+- Create: `src/ZB.MOM.WW.Audit/IAuditRedactor.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/AuditEventTests.cs`
+
+**Step 1: Write the failing tests** (`AuditEventTests.cs`):
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class AuditEventTests
+{
+ private static AuditEvent Minimal() => new()
+ {
+ EventId = Guid.NewGuid(),
+ OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "alice",
+ Action = "ConfigPublished",
+ Outcome = AuditOutcome.Success,
+ };
+
+ [Fact]
+ public void Required_core_fields_round_trip()
+ {
+ var id = Guid.NewGuid();
+ var evt = Minimal() with { EventId = id, Actor = "svc", Action = "ApiCall", Outcome = AuditOutcome.Denied };
+ Assert.Equal(id, evt.EventId);
+ Assert.Equal("svc", evt.Actor);
+ Assert.Equal("ApiCall", evt.Action);
+ Assert.Equal(AuditOutcome.Denied, evt.Outcome);
+ }
+
+ [Fact]
+ public void OccurredAtUtc_is_normalized_to_utc()
+ {
+ var local = new DateTimeOffset(2026, 6, 1, 12, 0, 0, TimeSpan.FromHours(5));
+ var evt = Minimal() with { OccurredAtUtc = local };
+ Assert.Equal(TimeSpan.Zero, evt.OccurredAtUtc.Offset);
+ Assert.Equal(local.UtcDateTime, evt.OccurredAtUtc.UtcDateTime);
+ }
+
+ [Fact]
+ public void Optional_fields_default_to_null()
+ {
+ var evt = Minimal();
+ Assert.Null(evt.Category);
+ Assert.Null(evt.Target);
+ Assert.Null(evt.SourceNode);
+ Assert.Null(evt.CorrelationId);
+ Assert.Null(evt.DetailsJson);
+ }
+
+ [Fact]
+ public void Records_with_same_values_are_equal()
+ {
+ var id = Guid.NewGuid();
+ var when = DateTimeOffset.UtcNow;
+ AuditEvent Make() => new() { EventId = id, OccurredAtUtc = when, Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+ Assert.Equal(Make(), Make());
+ }
+}
+```
+
+**Step 2: Run to verify failure**
+Run: `cd ~/Desktop/scadaproj/ZB.MOM.WW.Audit && dotnet test`
+Expected: FAIL — `AuditEvent`/`AuditOutcome` do not exist (compile error).
+
+**Step 3: Implement.** `AuditOutcome.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Normalized outcome of an audited action.
+public enum AuditOutcome
+{
+ /// The action completed successfully.
+ Success,
+ /// The action failed due to an error.
+ Failure,
+ /// The action was rejected by authentication/authorization.
+ Denied,
+}
+```
+`AuditEvent.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+///
+/// Canonical, transport-agnostic audit record — who did what, when, with what outcome.
+/// Required core + optional common fields + a extension bag. Each
+/// sister app maps its own record onto this; domain vocabularies (channels/kinds/event-types)
+/// map into // and are not
+/// modelled here. See scadaproj/components/audit/spec/EVENT-MODEL.md.
+///
+public sealed record AuditEvent
+{
+ /// Idempotency key uniquely identifying this audit event.
+ public required Guid EventId { get; init; }
+
+ /// When the audited action occurred. Normalized to UTC on assignment.
+ public required DateTimeOffset OccurredAtUtc
+ {
+ get => _occurredAtUtc;
+ init => _occurredAtUtc = value.ToUniversalTime();
+ }
+ private readonly DateTimeOffset _occurredAtUtc;
+
+ /// Who performed the action (identity string; the ZB.MOM.WW.Auth principal at adoption).
+ public required string Actor { get; init; }
+
+ /// What was done — a verb/event-type string.
+ public required string Action { get; init; }
+
+ /// Normalized outcome.
+ public required AuditOutcome Outcome { get; init; }
+
+ /// Optional subsystem/grouping for the action.
+ public string? Category { get; init; }
+
+ /// Optional target of the action (resource/method/connection).
+ public string? Target { get; init; }
+
+ /// Optional node that emitted the event.
+ public string? SourceNode { get; init; }
+
+ /// Optional correlation id joining this row to its originating request/workflow.
+ public Guid? CorrelationId { get; init; }
+
+ /// Optional JSON extension carrying project-specific fields.
+ public string? DetailsJson { get; init; }
+}
+```
+`IAuditWriter.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+///
+/// Best-effort sink for s. Implementations MUST swallow/log internal
+/// failures rather than propagating them — a failed audit write must never abort the
+/// user-facing action that produced it.
+///
+public interface IAuditWriter
+{
+ /// Persist an audit event. Best-effort; must not throw to the caller.
+ Task WriteAsync(AuditEvent evt, CancellationToken ct = default);
+}
+```
+`IAuditRedactor.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+///
+/// Filters an between construction and persistence — truncates oversized
+/// fields and scrubs sensitive content. Pure function: returns a filtered COPY and MUST NOT throw
+/// (over-redact on internal failure). Shaped to mirror Telemetry's ILogRedactor so a future
+/// ZB.MOM.WW.Hosting aggregator can wire both consistently; intentionally has no dependency on it.
+///
+public interface IAuditRedactor
+{
+ /// Apply the configured truncation/redaction policy and return a filtered copy.
+ AuditEvent Apply(AuditEvent rawEvent);
+}
+```
+
+**Step 4: Run to verify pass**
+Run: `dotnet test`
+Expected: PASS (4 tests).
+
+**Step 5: Commit** (from `ZB.MOM.WW.Audit/`):
+```bash
+git add -A && git commit -m "feat(audit): AuditEvent record + AuditOutcome + writer/redactor seams"
+```
+
+### Task 8: NullAuditRedactor
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 9, Task 10, Task 11, Task 12
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/NullAuditRedactor.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/NullAuditRedactorTests.cs`
+
+**Step 1: Failing test:**
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class NullAuditRedactorTests
+{
+ [Fact]
+ public void Apply_returns_input_unchanged()
+ {
+ var evt = new AuditEvent { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "a", Action = "x", Outcome = AuditOutcome.Success, DetailsJson = "{\"k\":1}" };
+ Assert.Same(evt, NullAuditRedactor.Instance.Apply(evt));
+ }
+}
+```
+
+**Step 2: Run — FAIL** (`NullAuditRedactor` not defined). `dotnet test`.
+
+**Step 3: Implement:**
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Identity redactor — returns the event unchanged. The default when no policy is configured.
+public sealed class NullAuditRedactor : IAuditRedactor
+{
+ /// Shared singleton instance.
+ public static readonly NullAuditRedactor Instance = new();
+ private NullAuditRedactor() { }
+
+ ///
+ public AuditEvent Apply(AuditEvent rawEvent) => rawEvent;
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): NullAuditRedactor"`
+
+### Task 9: TruncatingAuditRedactor + options
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 8, Task 10, Task 11, Task 12
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/TruncatingAuditRedactorOptions.cs`
+- Create: `src/ZB.MOM.WW.Audit/TruncatingAuditRedactor.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/TruncatingAuditRedactorTests.cs`
+
+**Step 1: Failing tests:**
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class TruncatingAuditRedactorTests
+{
+ private static AuditEvent Evt(string? details, string? target = null) => new()
+ {
+ EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "a", Action = "x", Outcome = AuditOutcome.Success,
+ DetailsJson = details, Target = target,
+ };
+
+ [Fact]
+ public void Short_values_pass_through_unchanged()
+ {
+ var r = new TruncatingAuditRedactor(new() { MaxDetailsJsonLength = 100 });
+ var evt = Evt("small");
+ Assert.Equal("small", r.Apply(evt).DetailsJson);
+ }
+
+ [Fact]
+ public void Oversized_details_are_truncated_with_marker()
+ {
+ var opts = new TruncatingAuditRedactorOptions { MaxDetailsJsonLength = 10, TruncationMarker = "~" };
+ var r = new TruncatingAuditRedactor(opts);
+ var result = r.Apply(Evt(new string('x', 50)));
+ Assert.Equal(10, result.DetailsJson!.Length);
+ Assert.EndsWith("~", result.DetailsJson);
+ }
+
+ [Fact]
+ public void Oversized_target_is_truncated()
+ {
+ var r = new TruncatingAuditRedactor(new() { MaxTargetLength = 5, TruncationMarker = "" });
+ var result = r.Apply(Evt(null, target: "abcdefghij"));
+ Assert.Equal(5, result.Target!.Length);
+ }
+
+ [Fact]
+ public void Null_fields_are_left_null()
+ {
+ var r = new TruncatingAuditRedactor();
+ var result = r.Apply(Evt(null));
+ Assert.Null(result.DetailsJson);
+ Assert.Null(result.Target);
+ }
+}
+```
+
+**Step 2: Run — FAIL.** `dotnet test`.
+
+**Step 3: Implement.** `TruncatingAuditRedactorOptions.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Caps for .
+public sealed class TruncatingAuditRedactorOptions
+{
+ /// Max length of before truncation. Default 4096.
+ public int MaxDetailsJsonLength { get; set; } = 4096;
+ /// Max length of before truncation. Default 512.
+ public int MaxTargetLength { get; set; } = 512;
+ /// Marker appended to a truncated value. Default "…[truncated]".
+ public string TruncationMarker { get; set; } = "…[truncated]";
+}
+```
+`TruncatingAuditRedactor.cs`:
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+///
+/// Redactor that caps oversized and .
+/// Never throws — over-redacts (drops DetailsJson) on internal failure. The secret-field policy
+/// (which fields are sensitive) stays per-project; compose this with a project redactor as needed.
+///
+public sealed class TruncatingAuditRedactor : IAuditRedactor
+{
+ private readonly TruncatingAuditRedactorOptions _options;
+
+ /// Creates the redactor with the given options (defaults when null).
+ public TruncatingAuditRedactor(TruncatingAuditRedactorOptions? options = null)
+ => _options = options ?? new TruncatingAuditRedactorOptions();
+
+ ///
+ public AuditEvent Apply(AuditEvent rawEvent)
+ {
+ try
+ {
+ return rawEvent with
+ {
+ Target = Truncate(rawEvent.Target, _options.MaxTargetLength),
+ DetailsJson = Truncate(rawEvent.DetailsJson, _options.MaxDetailsJsonLength),
+ };
+ }
+ catch
+ {
+ // Hard contract: never throw. Over-redact on internal failure.
+ return rawEvent with { DetailsJson = null };
+ }
+ }
+
+ private string? Truncate(string? value, int max)
+ {
+ if (value is null || value.Length <= max) return value;
+ var marker = _options.TruncationMarker;
+ if (marker.Length >= max) return marker[..max];
+ return string.Concat(value.AsSpan(0, max - marker.Length), marker);
+ }
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): TruncatingAuditRedactor + options"`
+
+### Task 10: NoOpAuditWriter
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 8, Task 9, Task 11, Task 12
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/NoOpAuditWriter.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/NoOpAuditWriterTests.cs`
+
+**Step 1: Failing test:**
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class NoOpAuditWriterTests
+{
+ [Fact]
+ public async Task WriteAsync_completes_without_error()
+ {
+ var evt = new AuditEvent { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+ await NoOpAuditWriter.Instance.WriteAsync(evt);
+ }
+}
+```
+
+**Step 2: Run — FAIL.** `dotnet test`.
+
+**Step 3: Implement:**
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Writer that discards events. Default when audit is disabled, and useful in tests.
+public sealed class NoOpAuditWriter : IAuditWriter
+{
+ /// Shared singleton instance.
+ public static readonly NoOpAuditWriter Instance = new();
+ private NoOpAuditWriter() { }
+
+ ///
+ public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) => Task.CompletedTask;
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): NoOpAuditWriter"`
+
+### Task 11: CompositeAuditWriter
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 8, Task 9, Task 10, Task 12
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/CompositeAuditWriter.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/CompositeAuditWriterTests.cs`
+
+**Step 1: Failing tests** (include a recording + a throwing fake writer):
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class CompositeAuditWriterTests
+{
+ private sealed class RecordingWriter : IAuditWriter
+ {
+ public int Count;
+ public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) { Count++; return Task.CompletedTask; }
+ }
+ private sealed class ThrowingWriter : IAuditWriter
+ {
+ public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) => throw new InvalidOperationException("boom");
+ }
+
+ private static AuditEvent Evt() => new() { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "a", Action = "x", Outcome = AuditOutcome.Success };
+
+ [Fact]
+ public async Task Fans_out_to_all_writers()
+ {
+ var a = new RecordingWriter(); var b = new RecordingWriter();
+ await new CompositeAuditWriter(new IAuditWriter[] { a, b }).WriteAsync(Evt());
+ Assert.Equal(1, a.Count);
+ Assert.Equal(1, b.Count);
+ }
+
+ [Fact]
+ public async Task One_failing_writer_does_not_stop_the_others()
+ {
+ var after = new RecordingWriter();
+ var sut = new CompositeAuditWriter(new IAuditWriter[] { new ThrowingWriter(), after });
+ await sut.WriteAsync(Evt()); // must not throw
+ Assert.Equal(1, after.Count);
+ }
+}
+```
+
+**Step 2: Run — FAIL.** `dotnet test`.
+
+**Step 3: Implement:**
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Fans an event out to several writers. Best-effort: a failing writer does not stop the others.
+public sealed class CompositeAuditWriter : IAuditWriter
+{
+ private readonly IReadOnlyList _inner;
+
+ /// Creates a composite over the given writers.
+ public CompositeAuditWriter(IEnumerable inner)
+ {
+ ArgumentNullException.ThrowIfNull(inner);
+ _inner = inner.ToArray();
+ }
+
+ ///
+ public async Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
+ {
+ foreach (var writer in _inner)
+ {
+ try { await writer.WriteAsync(evt, ct).ConfigureAwait(false); }
+ catch { /* best-effort seam: a failing writer must not stop the others or the caller */ }
+ }
+ }
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): CompositeAuditWriter"`
+
+### Task 12: RedactingAuditWriter
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 8, Task 9, Task 10, Task 11
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/RedactingAuditWriter.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/RedactingAuditWriterTests.cs`
+
+**Step 1: Failing tests** (verify the *redacted* event reaches the inner writer):
+```csharp
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class RedactingAuditWriterTests
+{
+ private sealed class CapturingWriter : IAuditWriter
+ {
+ public AuditEvent? Last;
+ public Task WriteAsync(AuditEvent evt, CancellationToken ct = default) { Last = evt; return Task.CompletedTask; }
+ }
+ private sealed class StampRedactor : IAuditRedactor
+ {
+ public AuditEvent Apply(AuditEvent rawEvent) => rawEvent with { DetailsJson = "redacted" };
+ }
+
+ private static AuditEvent Evt() => new() { EventId = Guid.NewGuid(), OccurredAtUtc = DateTimeOffset.UtcNow,
+ Actor = "a", Action = "x", Outcome = AuditOutcome.Success, DetailsJson = "secret" };
+
+ [Fact]
+ public async Task Inner_writer_receives_the_redacted_event()
+ {
+ var inner = new CapturingWriter();
+ var sut = new RedactingAuditWriter(new StampRedactor(), inner);
+ await sut.WriteAsync(Evt());
+ Assert.Equal("redacted", inner.Last!.DetailsJson);
+ }
+}
+```
+
+**Step 2: Run — FAIL.** `dotnet test`.
+
+**Step 3: Implement:**
+```csharp
+namespace ZB.MOM.WW.Audit;
+
+/// Decorator: applies an , then delegates to an inner .
+public sealed class RedactingAuditWriter : IAuditWriter
+{
+ private readonly IAuditRedactor _redactor;
+ private readonly IAuditWriter _inner;
+
+ /// Creates the decorator around using .
+ public RedactingAuditWriter(IAuditRedactor redactor, IAuditWriter inner)
+ {
+ ArgumentNullException.ThrowIfNull(redactor);
+ ArgumentNullException.ThrowIfNull(inner);
+ _redactor = redactor;
+ _inner = inner;
+ }
+
+ ///
+ public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
+ => _inner.WriteAsync(_redactor.Apply(evt), ct);
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): RedactingAuditWriter decorator"`
+
+### Task 13: AddZbAudit DI extension
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (blocked by Tasks 8, 10)
+
+**Files:**
+- Create: `src/ZB.MOM.WW.Audit/AuditServiceCollectionExtensions.cs`
+- Test: `tests/ZB.MOM.WW.Audit.Tests/AuditServiceCollectionExtensionsTests.cs`
+
+**Step 1: Failing tests:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ZB.MOM.WW.Audit.Tests;
+
+public class AuditServiceCollectionExtensionsTests
+{
+ [Fact]
+ public void Registers_null_redactor_and_noop_writer_by_default()
+ {
+ var sp = new ServiceCollection().AddZbAudit().BuildServiceProvider();
+ Assert.IsType(sp.GetRequiredService());
+ Assert.IsType(sp.GetRequiredService());
+ }
+
+ [Fact]
+ public void Does_not_override_a_preregistered_writer()
+ {
+ var services = new ServiceCollection();
+ services.AddSingleton(new CompositeAuditWriter(System.Array.Empty()));
+ var sp = services.AddZbAudit().BuildServiceProvider();
+ Assert.IsType(sp.GetRequiredService());
+ }
+}
+```
+
+**Step 2: Run — FAIL.** `dotnet test`.
+
+**Step 3: Implement:**
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+
+namespace ZB.MOM.WW.Audit;
+
+/// DI helpers for ZB.MOM.WW.Audit.
+public static class AuditServiceCollectionExtensions
+{
+ ///
+ /// Registers safe defaults — and —
+ /// using TryAdd so a consumer that has already registered a real writer/redactor wins. Consumers
+ /// compose / around their own sink.
+ ///
+ public static IServiceCollection AddZbAudit(this IServiceCollection services)
+ {
+ ArgumentNullException.ThrowIfNull(services);
+ services.TryAddSingleton(NullAuditRedactor.Instance);
+ services.TryAddSingleton(NoOpAuditWriter.Instance);
+ return services;
+ }
+}
+```
+
+**Step 4: Run — PASS.** `dotnet test`.
+
+**Step 5: Commit:** `git add -A && git commit -m "feat(audit): AddZbAudit DI extension with safe defaults"`
+
+### Task 14: Full test run + dotnet pack @ 0.1.0
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** none (blocked by Task 13)
+
+**Files:** none (verification only)
+
+**Step 1: Full green test run**
+Run: `cd ~/Desktop/scadaproj/ZB.MOM.WW.Audit && dotnet test ZB.MOM.WW.Audit.slnx`
+Expected: all tests PASS (~18–20 across the type tests).
+
+**Step 2: Pack**
+Run: `./build/pack.sh`
+Expected: `./artifacts/ZB.MOM.WW.Audit.0.1.0.nupkg` produced (exactly 1 nupkg). Confirm:
+`ls artifacts/*.nupkg` → one file ending `0.1.0.nupkg`.
+
+**Step 3: Commit** (artifacts are typically gitignored; commit any `.gitignore`/README touch-ups only)
+```bash
+git add -A && git commit -m "chore(audit): verify dotnet test green + pack @ 0.1.0" --allow-empty
+```
+
+---
+
+## Phase C — Register the component
+
+### Task 15: Index/registry updates + GAPS cross-check
+
+**Classification:** small
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (blocked by Task 14)
+
+> These edits are in the **outer `scadaproj` repo** (not the nested library repo). Commit from `~/Desktop/scadaproj`.
+
+**Files:**
+- Modify: `components/README.md` (registry table — add `audit/` row, status Draft)
+- Modify: `CLAUDE.md` (Component normalization table — add Audit row with links + a short paragraph mirroring the Auth/UI-Theme write-ups)
+- Modify: `upcoming.md` (mark Audit #3 done; note logging stays with Telemetry.Serilog)
+- Modify: `components/audit/GAPS.md` (cross-check against the shipped library API)
+
+**Step 1:** Add to `components/README.md` registry:
+```markdown
+| Audit (event model / writer / redaction) | Draft | OtOpcUa, MxAccessGateway, ScadaBridge | Path to shared code (`ZB.MOM.WW.Audit`) | [`audit/`](audit/) |
+```
+
+**Step 2:** Add the Audit row to the `CLAUDE.md` Component-normalization table + a paragraph: built lib at `ZB.MOM.WW.Audit/` (1 package, ~18–20 tests, `dotnet pack` → 1 nupkg @ 0.1.0); common ground = canonical `AuditEvent` + `Outcome` + `IAuditWriter`/`IAuditRedactor` seams; left per-project = transport/storage + domain vocab; **not yet adopted** (tracked in `components/audit/GAPS.md`); closes the loop on Auth (`Actor` = principal).
+
+**Step 3:** In `upcoming.md`, mark the Audit recommendation (#3) as done with a pointer to `components/audit/` + `ZB.MOM.WW.Audit/`; add a one-line note that "Logging" (Tier 2) is being delivered as `ZB.MOM.WW.Telemetry.Serilog` by the health/observability pass, not as a standalone lib.
+
+**Step 4:** Re-read `components/audit/GAPS.md` against the final shipped API; fix any drift (type/method names).
+
+**Step 5:** Verify all new cross-links resolve (the README/CLAUDE links point at files that exist).
+
+**Step 6: Commit**
+```bash
+cd ~/Desktop/scadaproj
+git add components/README.md CLAUDE.md upcoming.md components/audit/GAPS.md
+git commit -m "docs(audit): register component in indexes + GAPS cross-check"
+```
+
+---
+
+## Done criteria (evidence, not assertions)
+
+- `components/audit/` complete: README, SPEC, EVENT-MODEL, shared-contract, 3 code-verified current-state docs (each with an Adoption plan), GAPS.
+- `ZB.MOM.WW.Audit/`: `dotnet test ZB.MOM.WW.Audit.slnx` green; `./build/pack.sh` → exactly **1 nupkg @ 0.1.0**.
+- Indexes updated: `components/README.md`, `CLAUDE.md`, `upcoming.md` (#3 done), GAPS cross-checked.
+- **No sister-repo code changed** — adoption deferred to `GAPS.md`.
diff --git a/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md.tasks.json b/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md.tasks.json
new file mode 100644
index 0000000..5050c2e
--- /dev/null
+++ b/docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md.tasks.json
@@ -0,0 +1,22 @@
+{
+ "planPath": "docs/plans/2026-06-01-zb-mom-ww-audit-shared-library.md",
+ "tasks": [
+ {"id": 0, "subject": "Task 0: Current-state — OtOpcUa", "status": "pending"},
+ {"id": 1, "subject": "Task 1: Current-state — MxAccessGateway", "status": "pending"},
+ {"id": 2, "subject": "Task 2: Current-state — ScadaBridge", "status": "pending"},
+ {"id": 3, "subject": "Task 3: SPEC.md + EVENT-MODEL.md", "status": "pending", "blockedBy": [0, 1, 2]},
+ {"id": 4, "subject": "Task 4: shared-contract/ZB.MOM.WW.Audit.md", "status": "pending", "blockedBy": [3]},
+ {"id": 5, "subject": "Task 5: components/audit/README.md + GAPS.md", "status": "pending", "blockedBy": [3, 4]},
+ {"id": 6, "subject": "Task 6: Scaffold the library + test project + solution", "status": "pending", "blockedBy": [4]},
+ {"id": 7, "subject": "Task 7: AuditEvent record + AuditOutcome enum + seam interfaces", "status": "pending", "blockedBy": [6]},
+ {"id": 8, "subject": "Task 8: NullAuditRedactor", "status": "pending", "blockedBy": [7]},
+ {"id": 9, "subject": "Task 9: TruncatingAuditRedactor + options", "status": "pending", "blockedBy": [7]},
+ {"id": 10, "subject": "Task 10: NoOpAuditWriter", "status": "pending", "blockedBy": [7]},
+ {"id": 11, "subject": "Task 11: CompositeAuditWriter", "status": "pending", "blockedBy": [7]},
+ {"id": 12, "subject": "Task 12: RedactingAuditWriter", "status": "pending", "blockedBy": [7]},
+ {"id": 13, "subject": "Task 13: AddZbAudit DI extension", "status": "pending", "blockedBy": [8, 10]},
+ {"id": 14, "subject": "Task 14: Full test run + dotnet pack @ 0.1.0", "status": "pending", "blockedBy": [13]},
+ {"id": 15, "subject": "Task 15: Index/registry updates + GAPS cross-check", "status": "pending", "blockedBy": [14]}
+ ],
+ "lastUpdated": "2026-06-01"
+}