Drop the "not yet implemented / BadNotSupported" stale note from all three
S7 CLI --type option descriptions (ReadCommand, WriteCommand, SubscribeCommand)
and replace with accurate help listing the full supported type set, byte-anchored
addressing for wide types, and Timer/Counter read-only status.
docs/v2/driver-specs.md §5: add Supported Data Types table, Byte-Anchored
Addressing table (DBB/MB/IB/QB + examples), Timer/Counter read section with
the Counter-BCD known-limitation, and Deferrals list.
docs/drivers/S7.md: expand Data types to a full table, add "Wide types &
Timer/Counter" section (byte-anchored addressing, Timer/Counter read-only,
Counter BCD known-limitation, deferrals), update Address forms table and
1-D array Deferrals note.
Records T17-T22 as shipped: RoleCarryingUserIdentity, Part 9 method handlers gated on AlarmAck
role, alarm-commands DPS topic, ScriptedAlarmHostActor dispatch, WriteAlarmCondition delta-gate,
AdminUI /alerts Acknowledge/Shelve/Unshelve buttons via AdminOperationsActor singleton, and
Client.CLI ack/confirm/shelve commands. Corrects stale "Not started" / "Partial" entries in
phase-7-status.md (Stream G OPC UA method binding row and C.6 row and Gap 1 body) and adds
the alarm-commands topic to Runtime.md. Removes untracked scratch files resume.md and pending.md.
docker-dev un-stubbed → binds zb-shared-glauth on 10.100.0.35:3893 (dc=zb,dc=local)
via cn=serviceaccount; sign in multi-role/password (group→role seeded by
seed-clusters.sql). Per-VM C:\publish\glauth + base DNs dc=lmxopcua/dc=otopcua
obsolete. Source of truth: scadaproj/infra/glauth/.
Four new docs at docs/v2/ giving a single-page tour of each v2 piece:
- Architecture-v2.md: top-level mental model (fused Host + roles + cluster + live-edit)
- Cluster.md: AkkaClusterOptions + IClusterRoleInfo + WithOtOpcUaClusterBootstrap
- ControlPlane.md: 5 admin singletons + DPS topics + deploy flow + failover recovery
- Runtime.md: per-node actor tree + state machines + engine-wiring follow-up map
Each links back to the design doc for depth. Architecture-v2 cross-references
the other three + ServiceHosting + Redundancy + security.
Five doc-content updates after this session's code-review resolution
sweep. No code touched; pure documentation drift correction.
1. docs/reqs/HighLevelReqs.md (HLR-007 — Service Hosting):
Refreshed the deployment description from "three cooperating
processes (Server, Admin, Galaxy.Host)" to "two cooperating
Windows services (Server, Admin)". The legacy x86 TopShelf
Galaxy.Host process was retired in PR 7.2 (2026-04-30); Galaxy
access now flows through the in-process Tier-A GalaxyDriver
talking gRPC to the sibling mxaccessgw gateway. Also called out
decision #30 (AddWindowsService replacing TopShelf) inline.
2. docs/VirtualTags.md:
- Line 9: "compiled via Microsoft.CodeAnalysis.CSharp.Scripting"
replaced with the current pipeline (Microsoft.CodeAnalysis.CSharp
regular compiler — Core.Scripting-008 / -016 retired the
CSharpScript/ScriptRunner path).
- Line 39: orphan-thread leak description rewritten. The
CSharp.Scripting-era "underlying ScriptRunner keeps running on
its thread-pool thread until the Roslyn runtime returns" is no
longer accurate — the new pipeline binds the script as a
regular C# Func<> delegate, so the leak is now "synchronous
CPU-bound work on a pool thread" (same operator-visible
effect, different mechanism).
3. docs/v2/plan.md decision #29 ("Galaxy Host is a separate Windows
service"):
Annotated both the decision body and the decision-log table row
with "Reversed PR 7.2, 2026-04-30" + a one-line summary of the
replacement architecture. The original reasoning is preserved as
audit trail per the decision-log convention.
4. docs/v2/implementation/phase-7-scripting-and-alarming.md A.1:
Added an Implementation note describing the
Core.Scripting-008 / -016 supersession of the original
CSharpScript pipeline. The historical record stays; the note
points future readers at docs/VirtualTags.md "Compile cache"
for the current contract.
5. docs/plans/alarms-over-gateway.md "Files" section under client
regeneration:
Updated the .NET regeneration instructions to point at the new
ZB.MOM.WW.MxGateway.Contracts.csproj path. The old
clients/dotnet/MxGateway.Client.csproj no longer exists in the
sibling repo (restructure after this plan was written) and the
vendored-binaries situation in
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/libs/ is called out
so a reader following the plan won't chase a deleted path.
Verification: grep against docs/ for the pre-fix wordings ("three
cooperating processes", "Galaxy.Host (TopShelf)", "ScriptRunner",
the wrong BadDeviceFailure hex code 0x80550000) returns no hits.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Core.Scripting-012 (High, Security) resolution.
The Core.Scripting-008 rewrite broadened the BCL references list from a
narrow allow-list to the full System.* + netstandard +
Microsoft.Win32.Registry set, delegating the security gate entirely to
ForbiddenTypeAnalyzer. Three categories of dangerous BCL types were
reachable from script source without a deny-list entry:
- System.Threading.ThreadPool — QueueUserWorkItem re-introduces the
background-fanout threat Core.Scripting-003 closed against
System.Threading.Tasks.
- System.Threading.Timer — schedules unbounded callback work that
outlives the per-evaluation timeout.
- System.Runtime.Loader.AssemblyLoadContext — loads arbitrary DLLs.
Defense-in-depth gap; invocation needs reflection (already denied)
but the load itself was reachable.
Fix:
- Added 'System.Runtime.Loader' to ForbiddenNamespacePrefixes
(preferred over type-granular per the recommendation so future BCL
additions to that namespace are denied by default).
- Added 'System.Threading.ThreadPool' and 'System.Threading.Timer'
to ForbiddenFullTypeNames — both live in System.Threading shared
with allowed primitives so they must be type-granular.
Regression tests added to ScriptSandboxTests:
Rejects_ThreadPool_QueueUserWorkItem_at_compile
Rejects_Timer_new_at_compile
Rejects_AssemblyLoadContext_at_compile
Docs:
docs/v2/implementation/phase-7-scripting-and-alarming.md decision #6
and the Sandbox-escape compliance-check row both updated to enumerate
the new entries per the Core.Scripting-009 doc-sync convention.
Two lower-impact suggestions from the finding's recommendation
(System.Console, CultureInfo.DefaultThreadCurrentCulture) were
intentionally not addressed and are recorded as accepted minor risks
in the resolution.
Verification: Core.Scripting.Tests 107/107 (was 104 + 3 new rejection
tests).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The task-galaxy-e2e branch was merged + deleted; the durable reference
is PR #205 alone. Tidies a dangling pointer that future readers might
chase looking for a branch that no longer exists.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Core.ScriptedAlarms-009 resolution: replace the per-call Dictionary +
AlarmPredicateContext allocation with a per-alarm reusable AlarmScratch
held in _scratchByAlarmId, refilled in place under _evalGate on each
evaluation. The hot path no longer allocates per upstream tag change.
Why this matters:
On a busy line where many tags feeding many alarms change frequently,
the old BuildReadCache allocated a fresh dictionary + context on every
predicate evaluation — a steady stream of short-lived allocations the
GC eventually has to reclaim. With the reuse, the dictionary and
context are allocated once per alarm (on first evaluation) and refilled
in place across every subsequent re-eval.
Implementation:
- New private AlarmScratch class holds the reusable
Dictionary<string, DataValueSnapshot> read cache (pre-sized to the
alarm's Inputs.Count) and the AlarmPredicateContext that wraps it by
reference. The context observes refilled values without being
re-created.
- ConcurrentDictionary<string, AlarmScratch> _scratchByAlarmId on the
engine, cleared in LoadAsync alongside _alarms so a config-publish
drops the prior generation's scratch (Inputs / Logger may change).
- EvaluatePredicateToStateAsync looks up scratch via GetOrAdd, calls
the new RefillReadCache(Dictionary, IReadOnlySet) helper to clear +
repopulate the dictionary in place, then runs the predicate against
the reused context.
- BuildReadCache removed.
Safety:
Reuse is serialised under _evalGate which guarantees no two threads
ever observe the same scratch in a half-refilled state. The
AlarmPredicateContext is bound to the scratch dictionary by reference,
so the predicate's ctx.GetTag(path) sees the freshly-refilled values
rather than a stale snapshot.
Verification:
- All 66 ScriptedAlarms tests pass (was 63 — three new regression tests
locking the reuse contract).
- All 56 VirtualTags tests still pass (unchanged).
- All 104 Core.Scripting tests still pass (unchanged).
New tests in ScriptedAlarmEngineTests:
- Reevaluation_reuses_the_same_read_cache_dictionary — asserts
ReferenceEquals(scratch_before, scratch_after) across two
evaluations of the same alarm.
- Reevaluation_reuses_the_same_predicate_context — same, for the
context.
- LoadAsync_drops_the_prior_generations_scratch — asserts a config
publish wipes the prior scratch (so a stale Logger / Inputs can't
leak into the new generation).
Internal test hooks TryGetScratchReadCacheForTest /
TryGetScratchContextForTest added via the existing
InternalsVisibleTo for the tests project. Kept internal — not part of
the public engine surface.
Docs:
- docs/v2/Galaxy.Performance.md "Scripted-alarm engine" section
rewritten as "hot-path allocation reuse" documenting the new
contract + reuse safety reasoning + the three regression tests.
- code-reviews/Core.ScriptedAlarms/findings.md -009 flipped
Won't Fix → Resolved.
- code-reviews/README.md regenerated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Driver.Modbus.Addressing-006: broaden the catch in TryParseFamilyNative
so a future helper throwing a non-Argument/Overflow type still satisfies
the try-parse contract.
- Driver.Modbus.Addressing-007: document that the address grammar does
not carry ModbusStringByteOrder (the structured-tag path does);
add a 'Grammar scope' bullet to docs/v2/dl205.md.
- Driver.Modbus.Addressing-009: reword the ModbusModiconAddress comments
so they don't imply a leading-digit invariant the parser doesn't
enforce.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Core.Scripting-005: DependencyExtractor.HandleTagCall now recognises
raw-string literal paths by checking the StringLiteralExpression node
kind instead of the legacy StringLiteralToken kind.
- Core.Scripting-006: scope CompiledScriptCache failed-compile eviction
with TryRemove(KeyValuePair) so a racing retry entry is not evicted.
- Core.Scripting-008: document the per-publish assembly accretion as an
accepted limitation in docs/VirtualTags.md.
- Core.Scripting-009: enumerate the authoritative deny-list (namespace
prefixes + type-granular denies) in the Phase 7 decision-#6 entry to
match ForbiddenTypeAnalyzer.
- Core.Scripting-011: pin ScriptSandbox.Build, ScriptContext.Deadband
boundary semantics, and end-to-end factory + companion-sink
integration.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Core.ScriptedAlarms-003: emit OnEvent OUTSIDE _evalGate by collecting
pending emissions during the gate-held section and flushing them after
release; eliminates re-entrancy deadlock the docs already promised.
- Core.ScriptedAlarms-006: track every fire-and-forget Reevaluate /
ShelvingCheck task in _inFlight; Dispose drains the set so the engine
no longer races store writes against teardown.
- Core.ScriptedAlarms-008: store comments as ImmutableList<AlarmComment>
so AppendComment is O(log n) instead of O(n).
- Core.ScriptedAlarms-010: document the deliberate input-quality
asymmetry (Uncertain drives the predicate, renders {?} in the message)
in docs/ScriptedAlarms.md and on MessageTemplate.Resolve remarks.
- Core.ScriptedAlarms-011: propagate the no-op reason through
TransitionResult.NoOp(state, reason) and log it from
ScriptedAlarmEngine.ApplyAsync.
- Core.ScriptedAlarms-009 (Won't Fix per recommendation): documented the
per-evaluation dictionary allocation in docs/v2/Galaxy.Performance.md
with a mitigation path if a future soak surfaces pressure.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
RouteScriptedAlarmMethodCalls now handles ConditionType.AddComment
alongside Acknowledge/Confirm, dispatching to engine.AddCommentAsync.
An empty comment is rejected by the Part 9 state machine and surfaced
as BadInvalidArgument. MapCallOperation gates AddComment at the
AlarmAcknowledge tier — there is no dedicated AddComment permission bit.
Closes phase-7-status.md Gap 1: all Part 9 alarm methods now route to
the engine. Adds 3 unit tests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
OneShotShelve / TimedShelve / Unshelve now reach the ScriptedAlarmEngine.
Scripted-alarm condition nodes get a ShelvedStateMachine subtree created
before alarm.Create so the stack wires each shelve method's dispatch
handler; AlarmConditionState.OnShelve / OnTimedUnshelve route to the
engine and mirror the result onto the OPC UA node via SetShelvingState.
The three per-instance shelve method NodeIds are indexed so the Call gate
resolves them to OpcUaOperation.AlarmShelve instead of falling through to
generic Call. Engine dispatch is split into the node-free InvokeEngineShelve
so the routing decision is unit-testable.
Adds 9 unit tests; updates phase-7-status.md Gap 1 (only AddComment remains
unwired) and the #24 entry in looseends.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audits every Phase 7 plan stream (A-H) against the repo, confirms the
exit gate is fully closed, and records the five genuine remaining gaps:
OPC UA method-call dispatch for alarm Ack/Confirm/Shelve, the
/virtual-tags and /scripted-alarms Admin UI tabs, the script log viewer,
and the missing production IHistoryWriter for virtual-tag historization.
Also notes that docs/v2/v2-release-readiness.md carries a stale "out of
scope" label — Phase 7 shipped completely after that doc was last updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every item in lmx-followups.md was marked DONE and rooted in the
retired GalaxyProxyDriver / OtOpcUaGalaxyHost named-pipe architecture
deleted in PR 7.2. No live or unique content remains: v2-release-readiness.md
is the canonical open-work tracker. Remove the file and drop the
now-dead link from docs/README.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrite src/ and tests/ project paths in docs, CLAUDE.md, README.md, and
test-fixture READMEs to the new module-folder layout (Core/Server/Drivers/
Client/Tooling). References to retired v1 projects (Galaxy.Host/Proxy/Shared,
the legacy monolithic test projects) are left untouched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Seventeenth PR of the alarms-over-gateway epic
(docs/plans/alarms-over-gateway.md). Lands the script that the
plan calls for in Track D — the actual smoke-run validation
on the dev rig (publish, restart, fire alarms, capture artifacts)
remains operator work; this PR ships the automation that the
operator drives.
scripts/install/Refresh-Services.ps1 — single-shot refresh
script. Designed to run elevated on the deploy host
(DESKTOP-6JL3KKO today; production uses a separate runbook).
The script:
- Stops services in reverse-dependency order (OtOpcUa →
OtOpcUaWonderwareHistorian → MxAccessGw) and force-kills any
residual processes (avoids the publish-time MSB3027 file-lock
the original install script hit).
- Snapshots existing C:\publish trees to
C:\publish\.backup-YYYY-MM-DD-HHMMSS\ for rollback (skip with
-SkipBackup).
- Builds + copies mxaccessgw worker (x86 net48) + server (net10.0)
binaries from the sibling repo.
- Publishes OtOpcUa Server + Wonderware historian sidecar from
this repo.
- Ensures OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED=true is set on
the historian service env block (PR C.2 toggle).
- Starts services in forward-dependency order with the
inter-service waits the original install used.
- Smoke-verifies (service status, listening ports 5120 / 4840
/ 4841, recent log tails).
Supports -WhatIf for dry-run inspection without touching the
running services.
docs/v2/dev-environment.md — new "Service Refresh —
Refresh-Services.ps1" section between Credential Management
and Test Data Seed. Cross-references the plan's Track D
functional verification scenarios.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- docs/drivers/FOCAS.md and docs/v2/implementation/focas-wire-protocol.md
pointed at focas-deployment.md and focas-simulator-plan.md, both of
which were untracked drafts that have since been removed. Drop the
refs (the wire-protocol companion now stands on its own; deployment
guidance lives inline in the FOCAS driver doc).
- Link the orphan v2 design docs from docs/README.md (multi-host
dispatch, v2 release readiness, the historical lmx-followups tracker)
and from modbus-test-plan.md (s7.md, mitsubishi.md per-family quirk
catalogs, sibling to dl205.md).
Surfaced by the doc audit; no content changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- gr/ folder moved to sibling repo at C:\Users\dohertj2\Desktop\graccess\gr;
the SQL queries + DDL captures belong with the graccess CLI work, not
with the OPC UA server. PR 7.2 retired direct Galaxy-DB access from this
repo (mxaccessgw owns those queries server-side now).
- Drop the now-obsolete "Galaxy Repository Database" section in CLAUDE.md
for the same reason — server no longer queries the DB directly.
- Delete root scratch files surfaced by the doc audit (runtimestatus.md,
service_info.md) — abandoned plan + operational scratch.
- Delete docs/v2/implementation/pr-{1,2,4}-body.md — ephemeral PR-body
snapshots from the v2-mxgw rollout.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Audit (three parallel agent passes) found 43 markdown files carrying
stale references to the deleted Galaxy.Host/Proxy/Shared projects
after the v2-mxgw merge. This commit lands the prioritized fixes.
Track 1 — high-traffic in-place rewrites (3 files, ~454 lines deleted)
- README.md (202 → 91 lines): drops .NET 4.8 / x86 / TopShelf install
text; leads with the multi-driver .NET 10 server identity and points
at scripts/install/Install-Services.ps1 and the parity rig.
- docs/v2/driver-specs.md §1 Galaxy (~289 → ~66 lines): replaces the
Tier-C out-of-process spec with a Tier-A in-process description
matching the current GalaxyDriver code, with the four-section
GalaxyDriverOptions JSON shape pulled verbatim from
Config/GalaxyDriverOptions.cs.
- docs/drivers/Galaxy.md (211 → 92 lines): full rewrite around the
current Browse/Runtime/Health/Config sub-folders.
Track 2 — historical banners (5 files)
- lmx_mxgw.md, lmx_mxgw_impl.md, lmx_backend.md,
docs/v2/Galaxy.ParityMatrix.md,
docs/v2/implementation/phase-2-galaxy-out-of-process.md each get a
"✅ Completed 2026-04-30 — historical record" banner block. lmx_mxgw.md
also fixes two dead links (`docs/Galaxy.Driver.md` and
`docs/v2/Galaxy.Driver.md`) → `docs/drivers/Galaxy.md`.
Track 3 — v1 archive sweep (10 git mv + 1 new index + 2 in-place scrubs)
- Moved 10 v1 docs under docs/v1/ preserving subpath structure:
AlarmTracking, Configuration, DataTypeMapping, HistoricalDataAccess,
Subscriptions (top-level); drivers/Galaxy-Repository,
drivers/Galaxy-Test-Fixture; reqs/GalaxyRepositoryReqs,
reqs/MxAccessClientReqs, reqs/ServiceHostReqs.
- New docs/v1/README.md is the shared archive banner + per-file table.
- docs/README.md repointed to the v1 paths and updated to reflect the
v2 two-process deploy shape (Server + Admin + optional
OtOpcUaWonderwareHistorian).
- docs/v2/Galaxy.ParityRig.md got a historical banner + four inline
scrubs marking the OtOpcUaGalaxyHost service / Driver.Galaxy.Host
EXE / Driver.Galaxy.ParityTests project as deleted-in-PR-7.2.
The repo's live-reading surface (README + CLAUDE.md + docs/v2/) now
describes only the post-PR-7.2 architecture. v1 docs are preserved as
a labelled archive under docs/v1/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the v2-mxgw migration's housekeeping debt now that PR 7.2 has
retired the legacy projects + service.
Repo docs:
- CLAUDE.md: rewrote the Galaxy section + reference-impl + MXAccess
documentation pointers; replaced .NET 4.8 x86 / COM apartment
constraints with .NET 10 AnyCPU + a pointer to the gateway. Dropped
the "Service hosting (Galaxy.Host)" library-preferences row.
- docs/ServiceHosting.md: rewrote (was 156 lines of Galaxy.Host pipe
IPC details). Now reflects the v2 process shape: OtOpcUa.Server +
OtOpcUa.Admin + optional OtOpcUaWonderwareHistorian, with Galaxy
access via the in-process driver → mxaccessgw.
- docs/v2/dev-environment.md: scrubbed four Galaxy.Host references
(TwinCAT/Galaxy.Host shared-host note; .NET 4.8 SDK row; install
step #2; risks table). The .NET 4.8 SDK is now correctly framed as
"optional, only needed when building the mxaccessgw worker".
- mxaccess_documentation.md: deleted from the repo root (obsolete; the
gateway repo is the canonical MxAccess API doc).
Memory housekeeping (under ~/.claude/projects/.../memory/):
- Retired: project_galaxy_host_service.md,
project_galaxy_host_installed.md, reference_impl.md (the LmxProxy
Host MXAccess reference is no longer the design pattern this repo
uses).
- Revised: project_overview.md (now describes the .NET 10 + mxaccessgw
shape), project_aveva_platform_installed.md (AVEVA still required
on the dev box but consumed by the gateway worker, not by anything
here), project_galaxy_via_mxgateway.md (post-7.2 state — flagged as
the only Galaxy backend), project_server_history_alarm_subsystems.md
(per-driver fallbacks retired in PR 7.2).
- MEMORY.md index updated to match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The parity matrix gate is the precondition for retiring the legacy
Galaxy projects. The 24h × 50k soak run and 2-week production pilot
were sketched in early planning as additional safety nets but aren't
operationally applicable for this deployment — there's no separate
production fleet to pilot against, and the soak harness's value is as
ongoing diagnostic infrastructure (still shipped in PR 6.4) rather
than a one-shot release gate.
PR 7.2's only remaining precondition is the matrix being fully green
or carrying documented accepted-deltas — verified 2026-04-30 on the
dev rig: 14 passed / 1 skipped / 0 failed.
Affected:
- docs/v2/Galaxy.ParityMatrix.md "Outstanding deltas" — flips to
"PR 7.2 is unblocked"
- docs/v2/Galaxy.ParityRig.md "After the rig is green" — drops the
three-step soak+pilot flow, keeps only the matrix-doc bookkeeping
follow-up
- lmx_mxgw_impl.md PR 7.2 "Depends on" — replaces "fully soaked"
with the matrix-green precondition + the verification date
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
End-to-end run on the live ZB galaxy with mxaccessgw on
http://localhost:5120: 14 passed / 1 skipped / 0 failed in 18m53s.
PR 7.2's matrix-gate condition met. Three resolution patches in this
commit; the matrix doc records the new state.
1. Discoverer: defensive `[]` array-suffix strip
----------------------------------------------------
The gw's GalaxyRepository.cs:173-175 appends `[]` to
array-typed full_tag_reference values, but MxAccess COM
IInstance.AddItem doesn't accept `[]`-suffixed addresses.
GalaxyDiscoverer.StripArraySuffix removes the suffix client-side
so SubscribeBulk / Read / Write paths see the canonical form.
Tracked in mxaccessgw/requirements-array-suffix-fix.md; this
workaround is removed when the gw fix lands.
2. WriteByClassification: pin status class, not exact code
---------------------------------------------------------
Legacy MxAccessGalaxyBackend.WriteValuesAsync flat-maps every
failure to BadInternalError (0x80020000); mxgw's
GatewayGalaxyDataWriter.TranslateReply uses
MxStatusProxy.RawDetectedBy to distinguish gw-layer faults
(BadCommunicationError, 0x80050000) from MxAccess HRESULT
faults. Both yield Bad-status — the parity invariant is the
status class (Good/Uncertain/Bad), not the exact code. Both
write tests now use AssertStatusClassMatches; legacy mapping
retires alongside GalaxyProxyDriver in PR 7.2.
3. BrowseAndReadParity Read scenario: drop CLR-type assertion
------------------------------------------------------------
Legacy returns the raw VARIANT (e.g. byte[]) for an attribute
that hasn't received its first value cycle from MxAccess yet,
while mxgw returns the typed value (Single, Int32, etc.). Once
a real value is written or scanned, both converge. Pinning
CLR-type equality across the uninitialized window adds noise
without a real parity invariant — the StatusCode-class
assertion already covers the "did the read succeed" question.
The test still pins StatusCode-class parity per scenario.
4. Galaxy.ParityMatrix.md — first-rig results captured
-----------------------------------------------------
Per-row status flipped from "n/a unverified" to actual
green / yellow / deferred outcomes from this run. Four new
accepted-deltas added (read-value CLR type, write-status code
mapping, single-platform ScanState scope, gw `[]` suffix
workaround), bringing the total to nine. Outstanding deltas
section flipped to "none as of 2026-04-30."
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the placeholder "configure an API key per gateway.md" with
the actual commands that worked end-to-end on this dev box:
- Build both halves (Worker x86 net48, Server net10)
- apikey init-db + apikey create-key with the seven scopes the parity
test exercises (session:*, invoke:*, events:read, metadata:read)
- Three env-var overrides at server startup — capturing real lessons
learned standing the rig up:
* Kestrel__Endpoints__Http__Url = http://localhost:5120
* Kestrel__Endpoints__Http__Protocols = Http2 (gRPC needs h2c on
plain HTTP — without this flag the client gets HTTP_1_1_REQUIRED)
* MxGateway__Worker__ExecutablePath = absolute path to the built
worker (appsettings.json's relative path drops \net48 and the
server can't resolve it)
- Note that workers spawn lazily on first OpenSession, not at server
startup — so port-listening is necessary but not sufficient
evidence the gateway is healthy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Calls out the single-platform constraint on this dev box and the
graccess-cli at C:\Users\dohertj2\Desktop\graccess as the way to
configure the rest of the parity-rig Galaxy shape:
- ScanState probe parity (multi-platform) is deferred to a customer
rig — not feasible on this dev box. PR 7.2 gate accepts
"n/a, deferred" on those rows because PR 4.7's unit tests already
pin the state-decoder + member-tracking logic.
- Per-row provisioning recipes for the five ⚙-scriptable rows:
FreeAccess/Operate UDA, Configure/Tune UDA, value-change source
(recommend external write-loop over template surgery), $Alarm*
extension, History extension. All against a reserved
OtOpcUaParityTest sandbox UDO so plant-relevant objects stay
untouched.
- Trailing deploy + Galaxy.Host restart so MxAccess picks up the
change before re-running the matrix.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walks through standing up both Galaxy backends side-by-side against a
single live Galaxy:
- Conceptual layout (two MxAccess sessions on distinct ClientNames so
they don't evict each other)
- What's already on the dev box (AVEVA + OtOpcUaGalaxyHost service)
- mxaccessgw build + run + config (API key, ClientName)
- The three OTOPCUA_PARITY_* env vars the harness reads
- HarnessShapeTests as the two-line truth-teller for "did both halves
resolve"
- Galaxy-shape coverage matrix mapping each scenario to what's needed
for it to assert (rather than skip)
- Soak run recipes, including the compressed-tag fallback when the dev
Galaxy doesn't have 50k attributes
- Troubleshooting for the four common SkipReasons
- Three further gates before PR 7.2 lands (matrix green, soak data,
pilot flip)
Explicitly drops the stale "use a non-elevated shell" precondition —
the legacy Galaxy.Host pipe ACL accepts elevated and non-elevated
dohertj2 alike (resolved 2026-04-24).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents the four perf surfaces shipped in Phase 6:
- Tracing surface (PR 6.1) — table of every span the driver emits +
rationale for stream-level (not per-event) coverage.
- Metrics surface (PR 6.2) — three EventPump counters, tagging
scheme, the bounded-channel design, and the
received = dispatched + dropped + in-flight invariant.
- Buffered update interval (PR 6.3) — how MxAccess.PublishingIntervalMs
flows through both subscribe paths and what's still pending on the
gw side (typed SetBufferedUpdateInterval helper).
- Soak scenario (PR 6.4) — env-var-gated 24h × 50k validation with
the CI-compressed override recipe.
- Tuned defaults (PR 6.5) — table of every default with source +
notes; rows marked "unchanged" carry the explicit "no live data
argues for changing this" caveat.
Closes with a "where to look first when something's slow" runbook
section so on-call doesn't have to re-derive the trace+metric
correlation map from primary docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tabular scenario × result map for the seven Phase 5 parity scenarios
(BrowseAndRead, Subscribe, Write, Alarm, History, Reconnect, ScanState).
Each row records the assertion strength (green strict, yellow soft) and
flags accepted-delta cases:
- Transport-entry host name divergence (legacy = Galaxy.Host process,
mxgw = MxAccess.ClientName)
- Reconnect latency cadence — different paths, both correct for their
own session shape
- Sampled-read value drift (we pin StatusCode + type, not value)
- Event-rate ±50% tolerance over a 3s window
- Per-driver IHistoryProvider absence (architectural pin from PR 1.3)
Phase 7 (PR 7.1) consumes this matrix as the default-flip gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Auto-prohibited ranges (#148) were previously visible only through an
internal AutoProhibitedRangeCount accessor used by tests. Production
operators had no way to see what the planner had learned without pulling
logs or inspecting driver state.
Changes:
- New public record `ModbusAutoProhibition(UnitId, Region, StartAddress,
EndAddress, LastProbedUtc, BisectionPending)` — operator-facing snapshot
shape. Lives in the addressing assembly's logical namespace alongside
the other public types.
- `ModbusDriver.GetAutoProhibitedRanges()` returns
`IReadOnlyList<ModbusAutoProhibition>` — a copy of the live prohibition
map. Lock-protected snapshot so consumers don't race with the re-probe
loop.
- RecordAutoProhibition tracks first-fire vs re-fire via the dictionary
insert path, leaving a hook to add structured logging once an ILogger
is plumbed through (currently elided to keep the constructor minimal
for testability — a future change can wire ILogger and emit a single
warning per first-fire).
Tests (1 new, additive to the 6 in ModbusCoalescingAutoRecoveryTests):
- GetAutoProhibitedRanges_Surfaces_Operator_Visible_Snapshot — confirms
the snapshot shape: empty before any failure, populated with correct
UnitId/Region/Start/End/BisectionPending after a failed coalesced read,
LastProbedUtc within the recent past.
Docs:
- docs/v2/modbus-addressing.md — new "Coalescing auto-recovery" subsection
consolidates the #148/#150/#151/#152 surface in one place. Documents
the diagnostic accessor + flags the in-process consumption pattern
(Server health endpoints today; Admin UI when an RPC channel exists).
239 + 1 = 240 unit tests green.
Caveat: the Admin UI surfacing (table render, "clear all prohibitions"
button) is intentionally NOT shipped here. Admin can't reach a live
ModbusDriver instance without a driver-diagnostics RPC channel that
doesn't exist yet — that's a larger architectural piece. For now the
data is queryable in-process by the Server's health endpoints; once an
RPC channel lands, Admin can wire the existing GetAutoProhibitedRanges
into a Blazor table without further driver changes.
Web verification (2026-04-25) against current vendor docs surfaced concrete
grammar conflicts in the v1 suffix grammar shipped in #137. Hard cutover
before the Admin UI rolls out widely so users don't paste `:I` from a
Wonderware spreadsheet and silently get wrong-typed reads.
Sources:
- Wonderware DASMBTCP user guide
https://cdn.logic-control.com/media/DASMBTCP.pdf
- Ignition Modbus addressing (8.1)
https://www.docs.inductiveautomation.com/docs/8.1/ignition-modules/opc-ua/opc-ua-drivers/modbus/modbus-addressing
Type-code changes:
| Code | Pre-#146 | Post-#146 | Vendor reference |
|--------|----------|------------|------------------------------|
| `:S` | (n/a) | Int16 | Wonderware DASMBTCP `S` |
| `:US` | (n/a) | UInt16 | Ignition `HRUS` |
| `:I` | Int16 | **Int32** | Wonderware `I` + Ignition `HRI` |
| `:UI` | UInt16 | **UInt32** | Ignition `HRUI` |
| `:I_64` | (n/a) | Int64 | Ignition `HRI_64` |
| `:UI_64` | (n/a) | UInt64 | Ignition `HRUI_64` |
| `:BCD_32`| (n/a) | BCD32 | Ignition `HRBCD_32` |
Codes REMOVED (no clear vendor precedent + conflict with the new mapping):
`:DI`, `:L`, `:UDI`, `:UL`, `:LI`, `:ULI`, `:LBCD`. Pre-#146 configs that
use them get an "Unknown type code" diagnostic at parse time so users get
a fast surface-level error rather than silent wrong-typed reads.
Codes UNCHANGED (already vendor-aligned): `:BOOL`, `:F`, `:D`, `:BCD`,
`:STR<n>`. Modicon 5/6-digit + mnemonic regions (HR/IR/C/DI) + bit suffix
`.N` are also unchanged.
Defaults:
- Coils / DiscreteInputs → `BOOL` (unchanged)
- HoldingRegisters / InputRegisters with no explicit type → Int16 (matches
Ignition's bare `HR` default)
Byte-order mnemonics (`:ABCD` / `:CDAB` / `:BADC` / `:DCBA`) are kept but
documented as OtOpcUa-specific — they aren't in any major vendor's per-tag
address string. Ignition uses a `-R` suffix per prefix; Wonderware
configures word-order at the topic level.
Tests:
- 12 Type_Codes_Parse rows updated to assert the new mappings.
- New Removed_Aliases_Are_Rejected (×7) confirms each pre-#146 alias now
fails fast with "Unknown type code".
- Worked_Example_Int16_Array uses the new `:S` code.
- New Worked_Example_Int32_Array_Via_I_Code documents the `:I = Int32`
vendor-alignment intent so a future "fix" doesn't accidentally regress.
- Unknown_Type_Code_Rejected_With_Catalog updated to match the new error
message ("Valid: BOOL, S, US, I, ...").
Docs:
- docs/v2/modbus-addressing.md — table replaced with the post-#146 codes,
each row cites its Wonderware / Ignition reference. New "Codes removed
in #146" subsection documents the cutover.
- docs/Driver.Modbus.Cli.md — example grammar list updated; explicit
type-code reminder appended.
114 addressing tests + 231 driver tests still green. Solution build clean.
Closes the docs/e2e end of the Modbus addressing line shipped across
#136-#145.
Docs:
- docs/v2/modbus-addressing.md (new) — full grammar reference.
Region+offset (Modicon 5-digit / 6-digit / mnemonic), bit suffix,
type codes (BOOL / I / UI / DI / UDI / LI / ULI / F / D / BCD / LBCD /
STR<n>), all four byte-order mnemonics (ABCD / CDAB / BADC / DCBA),
array-count semantics, family-native syntax (DL205 V/Y/C/X/SP and
MELSEC D/M/X/Y with hex-vs-octal sub-family selection), driver-instance
options (KeepAlive / Reconnect / IdleDisconnect, MaxCoilsPerRead and
FC15/16 forcing, Deadband + WriteOnChangeOnly, MaxReadGap +
CoalesceProhibited, multi-unit IPerCallHostResolver). Includes a worked
JSON DTO example mixing AddressString + structured tag forms.
- docs/Driver.Modbus.Cli.md — appended a "v2 addressing grammar" section
pointing users at the full reference, with quick-reference examples.
- Vendor-compatibility caveat documented: type codes and byte-order
mnemonics were synthesised from training-era vendor docs (Wonderware
DASMBTCP, Kepware KEPServerEX, Ignition, Matrikon, OAS) and should be
verified against current vendor manuals before locking for production.
E2E tests (4 new AddressingGrammarTests in IntegrationTests):
- Modicon 5-digit and 6-digit forms map to identical wire offsets.
- Float32 + WordSwap (CDAB) round-trips end-to-end through the
pymodbus simulator.
- Int16[5] array round-trips as a typed short[] surface.
- Block-read coalescing produces a wire-acceptable PDU when MaxReadGap=5
bridges three nearby tags.
All tests skip gracefully when the pymodbus simulator at localhost:5020
is unreachable (matches the existing ModbusSimulatorFixture pattern).
Final test count across the Modbus addressing surface:
- 107 ModbusAddressing.Tests (parser + family + Modicon)
- 231 Driver.Modbus.Tests (driver, byte order, array, multi-unit, coalescing,
protocol, subscribe, connection options)
- 110 Admin.Tests (incl. ModbusOptionsViewModel defaults pinning)
- 4 new AddressingGrammar integration tests (skip when sim down)
The Phase 6.2 evaluator was wired but received no input in production:
RoleBasedIdentity (the IUserIdentity our LDAP path produces) implemented
IRoleBearer but not ILdapGroupsBearer, so AuthorizationGate.BuildSessionState
always returned null and the gate lax-mode-allowed every request. UserAuthResult
also never carried the resolved LDAP groups, only the role-mapped strings.
Closing the gap so the evaluator gets real data:
- UserAuthResult adds Groups alongside Roles. LdapUserAuthenticator now
surfaces the raw RDN values (ReadOnly / WriteOperate / ...) it already
collected during the directory query. Roles stay separate per decision #150
(control-plane Admin role mapping vs data-plane NodeAcl key).
- RoleBasedIdentity implements ILdapGroupsBearer so AuthorizationGate sees
the groups via the same seam unit tests already use.
ThreeUserInteropMatrixTests drives the closure end-to-end against the live
GLAuth dev directory:
- 5 distinct group memberships (readonly / writeop / writetune /
writeconfig / alarmack) plus the multi-group admin user
- Each is bound through the real LdapUserAuthenticator
- Resolved groups feed an LdapBoundIdentity that goes through the strict-mode
AuthorizationGate against a seeded TriePermissionEvaluator
- 31 InlineData rows assert the role × operation matrix; failures pinpoint
the exact (user, op) cell
The remaining wire-level leg of #124 — a real OPC UA client driving UserName
tokens through an encrypted endpoint policy — still needs a deployment knob
and stays a manual cross-vendor smoke (#119 / #124 manual scope). The doc
audit note in admin-ui-phase-6-status.md is updated to reflect what's now
auto'd vs what stays manual.
33/33 new tests pass against live GLAuth; existing 270 non-LiveLdap tests
in Server.Tests still pass; Core.Tests 205/205, Admin.Tests 109/109. The 7
integration-test failures observed during this run pre-exist this commit
(NodeId-scheme regression from #134) and are tracked separately as #135.
Task-by-task audit of the Admin UI quartet shows every page listed in
the task descriptions is already built, routed, DI-wired, SignalR-live,
and covered by Admin.Tests (112/112 green):
- #128 /hosts — Hosts.razor 233 LOC with ConsecutiveFailures +
LastCircuitBreakerOpenUtc + Stale/Faulted/Running cards
- #129 RoleGrants + AclsTab + Probe — RoleGrants.razor (192 LOC),
AclsTab.razor (279 LOC) with the embedded Probe form at line 38
- #130 RedundancyTab — RedundancyTab.razor 175 LOC with peer
reachability / ServiceLevel / apply-lease / failover button
- #131 Draft/Publish/Diff/Identification — DraftEditor (105 LOC) +
Generations (73 LOC) + DiffViewer (87 LOC) + IdentificationFields
(49 LOC), all wired to GenerationService / DraftValidationService
Shipping docs/v2/implementation/admin-ui-phase-6-status.md as the
canonical reference. Each task's required features are listed with the
exact file / LOC / routing + DI injection so future auditors don't
need to re-derive the status.
No code change in this commit — doc-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Task #127 / decision #144. The resilience infrastructure for per-PLC
circuit breakers is shipped and fully tested — the task description's
"current pipeline keys on DriverInstanceId only" was stale. The actual
state:
- `DriverResiliencePipelineBuilder` keys on
`(DriverInstanceId, HostName, DriverCapability)`.
- `CapabilityInvoker.ExecuteAsync` takes `hostName` per call.
- `IPerCallHostResolver` is the driver-side hook; AB CIP implements it.
- `PerCallHostResolverDispatchTests.DeadPlc_DoesNotOpenBreaker_For_HealthyPlc_With_Resolver`
proves the end-to-end isolation.
Remaining work is per-driver adoption, not shared infrastructure:
- AB CIP: live + tested
- Galaxy / FOCAS / OPC UA Client / AB Legacy: 1 device per instance by
design, trivially isolated
- Modbus / S7 / TwinCAT: single-device today; multi-device refactor is
per-driver surgery (Device row + options + resolver + transport
fan-out), not a shared-infra change
Shipping docs/v2/multi-host-dispatch.md as the canonical reference:
contract + driver-author checklist + current fleet-wide status table.
Future driver authors follow the AB CIP template.
No code change in this commit — doc-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The runbook shipped at phase-7 close (2026-04-20) described the original
`Doubled = Source × 2` virtual tag, Float64 seed, and flat TagId-shaped
NodeIds. Four commits later the wiring has moved:
- Seed now targets `TestMachine_001.TestHistoryValue` (Int32, writable,
historized) — no placeholder to fill in for the dev box.
- VirtualTag is `MachineStatus` (Boolean, `Source > 0`, historized).
- NodeIds are path-based per OPC UA Part 3 §5.2.2
(`{driverId}/{folder-path}/{browseName}`).
- Seed inserts the ClusterNodeCredential row — without it the Server
bootstrap fails `Unauthorized: caller X is not bound to NodeId`.
Changes:
1. Step 3 — replace "edit the placeholder" instructions with the ZB
Galaxy-Repository query that finds writable historized attributes
(dpc CTE + HistoryExtension EXISTS + `security_classification > 0`).
2. New step 4a — LDAP + `SecurityProfile = Basic256Sha256-Sign` recipe
for the reverse-bridge + alarm-fires stages. Anonymous sessions are
denied writes against `Operate`-classified attributes (PR 26 gate);
`writeop / writeop123` against the dev-box GLAuth clears it.
3. Step 6 validation commands updated to the new NodeIds + reference
the path-based scheme's Part-3 rationale.
4. Drive-the-alarm snippet now calls `otopcua-cli write … -U writeop`
so operators see the explicit auth step.
5. Acceptance checklist updated for the new tag names + the
test-galaxy.ps1 `-Username` invocation.
6. Added a 2026-04-24 second-run evidence section alongside the original
— documents the 3/7 anonymous ceiling and what's needed to reach 7/7.
No code or seed changes in this commit — doc-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three root-cause fixes to get an elevated dev-box shell past session open
through to real MXAccess reads:
1. PipeAcl — drop BUILTIN\Administrators deny ACE. UAC's filtered token
carries the Admins SID as deny-only, so the deny fired even from
non-elevated admin-account shells. The per-connection SID check in
PipeServer.VerifyCaller remains the real authorization boundary.
2. PipeServer — swap the Hello-read / VerifyCaller order. ImpersonateNamedPipeClient
returns ERROR_CANNOT_IMPERSONATE until at least one frame has been read
from the pipe; reading Hello first satisfies that rule. Previously the
ACL deny-first path masked this race — removing the deny ACE exposed it.
3. GalaxyIpcClient — add a background reader + single pending-response
slot. A RuntimeStatusChange event between OpenSessionRequest and
OpenSessionResponse used to satisfy the caller's single ReadFrameAsync
and fail CallAsync with "Expected OpenSessionResponse, got
RuntimeStatusChange". The reader now routes response kinds (and
ErrorResponse) to the pending TCS and everything else to a handler the
driver registers in InitializeAsync. The Proxy was already set up to
raise managed events from RaiseDataChange / RaiseAlarmEvent /
OnHostConnectivityUpdate — those helpers had no caller until now.
4. RedundancyPublisherHostedService — swallow BadServerHalted while
polling host.Server.CurrentInstance. StandardServer throws that code
during startup rather than returning null, so the first poll attempt
crashed the BackgroundService (and the host) before OnServerStarted
ran. This race was latent behind the Galaxy init failure above.
Updates docs that described the Admins deny ACE + mandatory non-elevated
shells, and drops the admin-skip guards from every Galaxy integration +
E2E fixture that had them (IpcHandshakeIntegrationTests, EndToEndIpcTests,
ParityFixture, LiveStackFixture, HostSubprocessParityTests).
Adds GalaxyIpcClientRoutingTests covering the router's
request/response match, ErrorResponse, event-between-call, idle event,
and peer-close paths.
Verified live on the dev box against the p7-smoke cluster (gen 6):
driver registered=1 failedInit=0, Phase 7 bridge subscribed, OPC UA
server up on 4840, MXAccess read round-trip returns real data with
Status=0x00000000.
Task #112 — partial: Galaxy live stack is functional end-to-end. The
supplied test-galaxy.ps1 script still fails because the UNS walker
encodes TagConfig JSON as the tag's NodeId instead of the seeded TagId
(pre-existing; separate issue from this commit).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #133 — the "authz gate is inert in production" blocker
surfaced during task #123. Before this commit, every ACL check on the
six dispatch surfaces (Read, Write, HistoryRead, Browse,
CreateMonitoredItems, Call) short-circuited to allow because Program.cs
constructed OpcUaApplicationHost without passing authzGate or
scopeResolver.
New pieces:
- `AuthorizationOptions` — bound to `Node:Authorization` in
appsettings.json. `Enabled` (default false) is the master switch;
`StrictMode` (default false) controls the anonymous / no-LDAP-groups
fallback behaviour.
- `AuthorizationBootstrap` — singleton service that loads `NodeAcl`
rows for the published generation, builds a `PermissionTrieCache` +
`AuthorizationGate`, merges every registered driver's
`EquipmentNamespaceContent` through `ScopePathIndexBuilder` into one
full-path `NodeScopeResolver`. Returns `(null, null)` when disabled
or when no generation is Published yet.
- `DriverEquipmentContentRegistry.Snapshot()` — new method returning a
defensive copy of the driver → content map so the bootstrap can
iterate without holding the lock.
- `OpcUaApplicationHost.SetAuthorization(gate, resolver)` — late-bind
method matching the existing `SetPhase7Sources` pattern. Must run
before `StartAsync`; rejects post-start rebinding with
InvalidOperationException.
- `OpcUaServerService.ExecuteAsync` calls `AuthorizationBootstrap.BuildAsync`
after `PopulateEquipmentContentAsync` and before `applicationHost.StartAsync`,
in the same window that `SetPhase7Sources` runs.
Behaviour change
- Default (Enabled=false): no behaviour change — the gate stays null,
all six dispatch surfaces run unchanged. Safe for any existing
deployment on upgrade.
- Enabled=true with StrictMode=false: identities carrying LDAP groups
are evaluated against the trie; anonymous / no-groups identities
pass through (v1 legacy-client compatibility).
- Enabled=true with StrictMode=true: everything evaluates. Anonymous
or no-groups identities are denied.
Follow-up not covered here: rebind the gate+resolver on generation
refresh (the `GenerationRefreshHostedService` that shipped earlier in
this session). Today the gate only reflects the bootstrap generation
— operators publishing new ACL changes need a process restart to see
them. Matches the current driver-hot-reload limitation and is tracked
in the existing 6.3 follow-up bullet.
Docs: v2-release-readiness.md Phase 6.2 Stream C.12 bullet flipped to
Closed with operator-facing config pointer (`Node:Authorization:Enabled`).
All 283/283 Server.Tests still pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #123 (partial — builder semantics unit-tested; production
wiring is the new task #133).
ScopePathIndexBuilder + NodeScopeResolver indexed mode already exist —
they produce a full Cluster → Namespace → UnsArea → UnsLine → Equipment
→ Tag scope from the published generation's config rows. What was
missing: unit coverage of the Build semantics (the only consumers were
compile-time references) + explicit acknowledgement in the readiness
doc that the gate/resolver aren't yet wired into Program.cs.
Tests — 6 cases in ScopePathIndexBuilderTests.cs:
- Well-formed content emits full hierarchy.
- Tags with null EquipmentId skipped (SystemPlatform-namespace fallback).
- Tags with broken Equipment FK skipped (publish-time validation
should have caught; builder is defensive).
- Equipment with broken Line FK skipped.
- Duplicate TagConfig throws InvalidOperationException.
- Resolver with index returns full-path scope; un-indexed ref falls
through to cluster-only scope (pre-ADR-001 behaviour preserved).
Server.Tests 277 → 283.
Critical follow-up (task #133): Program.cs still constructs
OpcUaApplicationHost WITHOUT authzGate or scopeResolver, so all six
dispatch-layer gates (Read, Write, HistoryRead, Browse,
CreateMonitoredItems, Call) are currently inert in production. Wiring
them up — load NodeAcl + EquipmentNamespaceContent at bootstrap,
construct gate + resolver, pass into OpcUaApplicationHost, rebind on
generation refresh — is the last Phase 6.2 GA blocker.
Docs: v2-release-readiness.md Phase 6.2 Stream C hardening list marks
the scope-resolution bullet struck-through with a close-out note that
calls out the gate-inert-in-production gap + task #133.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #122 (Acknowledge + Confirm + generic Call — Shelve stays as
a follow-up pending per-instance method-NodeId resolution).
Before this commit any session with a connected channel could invoke
method nodes on driver-materialized equipment — including alarm
Acknowledge / Confirm. Combined with the Browse + CreateMonitoredItems
gates that landed earlier in Stream C, this was the last service-layer
entry point where a session could still affect state without passing
the authz trie.
Implementation on DriverNodeManager:
- `Call` override — pre-iterates methodsToCall, gates each through
AuthorizationGate with the operation kind returned by
MapCallOperation. Denied calls get errors[i] = BadUserAccessDenied
before delegating to base.Call.
- `MapCallOperation(NodeId methodId)` — maps well-known Part 9 method
NodeIds to dedicated operation kinds:
MethodIds.AcknowledgeableConditionType_Acknowledge →
OpcUaOperation.AlarmAcknowledge
MethodIds.AcknowledgeableConditionType_Confirm →
OpcUaOperation.AlarmConfirm
everything else → OpcUaOperation.Call
Lets the ACL distinguish "can acknowledge alarms" from "can invoke
arbitrary methods" without conflating the two roles.
- Shelve dispatch paths through per-instance ShelvedStateMachine methods
with dynamic NodeIds that can't be constant-matched — falls through
to generic Call. Fine-grained OpcUaOperation.AlarmShelve is a follow-
up when the method-invocation path grows a "method-role" annotation.
Extracted GateCallMethodRequests + MapCallOperation as static internal
for unit-testability. 8 new tests (MapCallOperation Acknowledge /
Confirm / generic; gate-null no-op, denied-Acknowledge, allowed-
Acknowledge, mixed-batch, pre-populated-error-preserved).
Server.Tests 269 → 277.
Known follow-ups:
- Shelve per-operation gating (see above).
- TranslateBrowsePathsToNodeIds gating (Browse follow-up from #120).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #121 (partial — creation-time gate; decision #153 per-item
revocation stamp is a follow-up).
Before this commit a session could subscribe to any node via
CreateMonitoredItems, even nodes where Read was denied — the
subscription would surface BadUserAccessDenied on each data-change
read, but the client saw a successful CreateMonitoredItems response
and held the subscription open, wasting resources and leaking the
address-space shape through the item metadata.
New override on DriverNodeManager.CreateMonitoredItems:
- Pre-iterates itemsToCreate, gates each through AuthorizationGate with
OpcUaOperation.CreateMonitoredItems at the target node's scope.
- For denied slots: sets errors[i] = new ServiceResult(
StatusCodes.BadUserAccessDenied). The OPC Foundation base stack
honours pre-populated non-success errors and skips item creation for
those slots — the subscription never holds a handle to a denied
node.
- Preserves prior errors (e.g. BadNodeIdUnknown) — first diagnosis wins.
- Non-string-identifier references (stack-synthesized numeric ids)
bypass the gate.
Extracted the pure filter logic into
GateMonitoredItemCreateRequests(items, errors, identity, gate,
scopeResolver) — static internal, unit-testable without the OPC UA
server stack.
Tests — 6 new in MonitoredItemGatingTests.cs (gate-null no-op,
denied-gets-BadUserAccessDenied, allowed-passes, mixed-batch-denies-
per-item, pre-populated-error-preserved, numeric-id-bypass). Server.Tests
263 → 269.
Known follow-ups:
- Per-item (AuthGenerationId, MembershipVersion) stamp (decision #153)
for detecting revocation mid-subscription — needs subscription-layer
plumbing.
- TransferSubscriptions not yet wired (same pattern, smaller scope).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #120 (partial — strict point-check; ancestor-visibility
implication is a follow-up).
Before this commit DriverNodeManager exposed every materialized node to
every browsing session regardless of the user's ACL. Read + Write +
HistoryRead were already gated through AuthorizationGate in Phase 6.2
Stream C core; Browse was the one surface where the session could still
enumerate nodes it had no permission to touch, discovering structure
even when reads failed with BadUserAccessDenied.
Implementation
- New `Browse` override on DriverNodeManager that calls base.Browse
first (lets the stack populate the reference list normally), then
post-filters the IList<ReferenceDescription> so denied nodes are
removed silently. OPC UA convention: Browse filtering is invisible to
the client; no BadUserAccessDenied surfaces.
- Extracted the filter loop into the static internal
`FilterBrowseReferences(references, userIdentity, gate, scopeResolver)`
so the policy is unit-testable without standing up the full OPC UA
server stack.
- Non-string NodeId identifiers (stack-synthesized standard-type
references with numeric identifiers) bypass the gate — only driver-
materialized nodes key into the authz trie.
- When AuthorizationGate or NodeScopeResolver is null, the filter is a
no-op — preserves the pre-Phase-6.2 dispatch path for integration
tests that construct DriverNodeManager without authz.
Tests — 6 new in BrowseGatingTests.cs (gate-null no-op, empty-list
no-op, denied-removed, allowed-passes-through, numeric-id bypass,
lax-mode null-identity keeps references). Server.Tests 257 → 263.
Known follow-up (tracked implicitly under #120 re-scope):
- Ancestor-visibility implication (acl-design.md §Browse line 111): a
user with Read at `Line/Tag` should be able to Browse `Line` even
without an explicit Browse grant. Current filter does a strict
point-check. Proper fix needs TriePermissionEvaluator to expose a
"subtree-has-any-grant" query.
- TranslateBrowsePathsToNodeIds not yet filtered (same extension
pattern; small follow-up).
Docs: v2-release-readiness.md Phase 6.2 Stream C hardening list marks
the Browse bullet struck-through with "Partial" close-out note.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes tasks #132 + #118 (GA hardening backlog).
Before this commit, the Server only observed the generation in force at
process start (SealedBootstrap). Peer-published generations accumulated
in the shared config DB while the running node kept serving the
generation it had sealed on boot. Two consequences:
1. Operator role-swaps required a process restart — Admin publishes a
new generation, but the Server's RedundancyCoordinator never re-read
the topology.
2. ApplyLeaseRegistry had no apply to wrap. ServiceLevelBand sat at
PrimaryHealthy (255) during every publish because nothing opened a
lease; PrimaryMidApply (200) was effectively dead code.
New GenerationRefreshHostedService (src/.../Server/Hosting/):
- Polls sp_GetCurrentGenerationForCluster every 5s (tunable).
- On change: opens leases.BeginApplyLease(newGenerationId, Guid.NewGuid()),
calls coordinator.RefreshAsync inside the `await using`, releases on
scope exit (success / exception / cancellation via IAsyncDisposable).
- Diagnostic properties: LastAppliedGenerationId, TickCount, RefreshCount.
- Delegate-injected currentGenerationQuery for test drive-through; real
path is the private static DefaultQueryCurrentGenerationAsync.
- Registered as HostedService in Program.cs alongside the Phase 6.3
redundancy / peer-probe stack.
Scope intentionally narrow: only the coordinator refreshes today. Driver
re-init, virtual-tag re-bind, script-engine reload remain as follow-up
wiring. The lease wrap is the right seam for those subscribers to hook
once they grow hot-reload support — the doc comments say so.
Tests
- 5 new unit tests in GenerationRefreshHostedServiceTests (first-apply,
identity no-op, change-triggers-refresh, null-generation-is-no-op,
lease-is-released-on-exit). Stub generation-query delegate; real
coordinator backed by EF InMemory DB.
- Server.Tests total 252 → 257.
Docs
- v2-release-readiness.md Phase 6.3 follow-ups list marks the
sp_PublishGeneration lease wrap bullet struck-through with close-out
note.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes task #116 (GA hardening backlog). Before this commit the
RedundancyStatePublisher saw PeerReachability.Unknown for every peer
because the tracker had no writers — every healthy peer got
degraded to the Isolated-Primary band (230) even when fully reachable.
Not release-blocking (safe default), but not the full non-transparent-
redundancy UX either.
Two-layer probe model per docs/v2/implementation/phase-6-3-redundancy-runtime.md
§Stream B:
- PeerHttpProbeLoop (Stream B.1) — fast-fail layer at 2 s / 1 s timeout.
Hits each peer's http://{Host}:{DashboardPort}/healthz via an injected
IHttpClientFactory. Writes the HTTP bit of PeerReachability while
preserving the UA bit from the last UA probe so a transient HTTP blip
doesn't clobber the authoritative UA reading.
- PeerUaProbeLoop (Stream B.2) — authoritative layer at 10 s / 5 s
timeout. Calls DiscoveryClient.GetEndpoints against opc.tcp://{Host}:
{OpcUaPort} — cheap compared to a full Session.Create, no cert trust
required. Short-circuits when the HTTP probe last reported the peer
unhealthy (no wasted handshakes on a known-dead endpoint), clearing
the stale UaHealthy bit in that case.
Both inherit from BackgroundService, follow the tick/delay/catch pattern
RedundancyPublisherHostedService + ResilienceStatusPublisherHostedService
established, and expose TickAsync() as internal for test drive-through.
New PeerProbeOptions class carries the four intervals/timeouts so
operators can tune cadence per site. Registered as singleton in Program.cs;
HTTP client registered by name so the OtOpcUa handler chain
(Serilog enrichers, potential future OpenTelemetry instrumentation) isn't
bypassed.
Tests — 9 new unit tests across PeerHttpProbeLoopTests (5) and
PeerUaProbeLoopTests (4). All pass. Server.Tests total 243 → 252.
Full solution build clean.
Docs: v2-release-readiness.md Phase 6.3 follow-ups list marks the
peer-probe bullet struck-through with a close-out note.
Still deferred in Phase 6.3:
- OPC UA variable-node binding (task #117 — ServiceLevel + ServerUriArray)
- sp_PublishGeneration lease wrap (task #118)
- Client interop matrix (task #119)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Joseph Doherty