lmxopcua/docs/plans/2026-08-05-skipped-tag-visibility-live-gate.md

Live gate — skipped-tag visibility (Gitea #541)

Date: 2026-08-05 Rig: local docker-dev/ (OrbStack), MAIN pair central-1 / central-2, AdminUI http://localhost:9200 Build under test: fix/541-skipped-tag-visibility Result: PASS. The gate found one defect unit tests did not (§4). Round two on 2026-08-06 closed the two items round one left unproven and corrected a wrong claim about the rig's topology (§6).

What needed proving

The unit suites pin the ledger semantics, the publish fingerprint, the proto round-trip and the view-model. None of them prove the thing an operator actually depends on: that the Tags column on /hosts renders the right cell, in the right colour, with actionable detail, against a driver that is genuinely skipping tags on a real deployment.

Method

The rig already carried eleven driver instances. Three of the thirteen tags on the pymodbus Modbus driver had their TagConfig.region rewritten to NoSuchRegion — the realistic shape of a bad blob — then MAIN was redeployed via POST /api/deployments. Backup of the original thirteen blobs taken first; all three restored and redeployed at the end (§5).

Results

Driver logs confirmed the skips reached the driver:

[WRN] Modbus tag config did not map to a definition; skipping. Driver=MAIN-modbus RawPath=pymodbus/plc/Probe3
[WRN] Modbus tag config did not map to a definition; skipping. Driver=MAIN-modbus RawPath=pymodbus/plc/Probe4
[WRN] Modbus tag config did not map to a definition; skipping. Driver=MAIN-modbus RawPath=pymodbus/plc/Probe5

/hosts then rendered — note every other column on the pymodbus row reads perfectly healthy, which is the entire point:

Driver	Status	Errors/5 min	Last error	Last read	Tags	Chip
pymodbus	HEALTHY	0	—	advancing	3 / 13 SKIPPED	chip-warn (amber)
sql-oracle-fixture	HEALTHY	0	—	advancing	1 / 1 SKIPPED	chip-bad (red)
sql-postgres-fixture	HEALTHY	0	—	advancing	1 / 1 SKIPPED	chip-bad (red)
gate-modbus-renamed	HEALTHY	0	—	advancing	1 / 1 SKIPPED	chip-bad (red)
abcip-browse	HEALTHY	0	—	advancing	5 tags	none
adsfa (Calculation)	HEALTHY	0	—	—	0 tags	none
opcua1	FAULTED	1	(config error)	—	—	none
rtu-gate	FAULTED	1	Connection refused	—	—	none

Tooltip on the amber chip, verbatim:

3 of 13 authored tag(s) are not being polled. They report BadNodeIdUnknown and the driver's state does not reflect them. pymodbus/plc/Probe3: TagConfig did not map to a definition · pymodbus/plc/Probe4: … · pymodbus/plc/Probe5: …

and on a red one:

This driver is polling NONE of its 1 authored tag(s). …

Three of the four skipping drivers were not planted. sql-oracle-fixture, sql-postgres-fixture and gate-modbus-renamed were already misconfigured on this rig and had been silently skipping their tags for an unknown length of time, each reporting Healthy with zero errors. The column surfaced them on its first run — an unplanned but fairly direct demonstration of the defect being real rather than theoretical.

Restoring the three blobs and redeploying returned pymodbus to 13 tags with no chip, which also exercises the clear-on-clean-rebuild path live.

4. Defect the gate found — 0 tags on a driver that never built a table

The first pass rendered 0 tags for opcua1 and rtu-gate. Both are FAULTED, both have two authored tags in the ConfigDb, and neither ever completed InitializeAsync — so their ledgers had never committed and Snapshot() returned SkippedTagReport.Empty.

A zero report is a positive claim — "this driver skipped nothing" — and making it on behalf of a driver that never got as far as looking is precisely the quiet inaccuracy #541 exists to remove. Not caught by unit tests because every one of them drove a driver through a completed build first.

Fixed by making ISkippedTagReporter.GetSkippedTags() and SkippedTagLedger.Snapshot() return null until the first committed build, so the column shows the same em-dash it already used for a driver that cannot report at all. Both are no answer; neither is nothing skipped. Pinned by three new SkippedTagLedgerTests cases plus a corrected FOCAS assertion. Re-gated on a rebuilt image: both faulted drivers now render —, while adsfa — which genuinely has zero authored tags and did build — correctly still renders 0 tags. That pair is the discriminating case.

5. Rig left as found

The three pymodbus blobs were restored from the pre-change backup and MAIN redeployed; /hosts shows 13 tags. The three pre-existing skipping drivers were left exactly as they were — they are the rig's own configuration, not this gate's.

6. Round two (2026-08-06) — truncation note + the central proto path

Both items round one left unproven were closed by one setup, chosen so that a single observation settles both. One correction first: round one recorded "the rig's central pair is fused admin+driver, so the snapshot never crossed the Phase 5 gRPC telemetry stream." That was wrong about the rig. All six ClusterNode rows carry GrpcPort 4056, every node runs Telemetry__Mode=Grpc, and central dials all six — the two Telemetry stream to node … lines seen in round one were startup failure warnings, not the dial set.

Setup. 25 tags with region: NoSuchRegion added to sa-modbus2 on SITE-A, joining its one good tag (26 total), then SITE-A deployed. SITE-A is the discriminator: Phase 6 partitioned it into its own Akka mesh, so central's MEMBERS panel lists only central-1:4053 and central-2:4053. DistributedPubSub fans out within one mesh's mediator and does not federate, and the single akka.tcp://otopcua@site-a-1 reference in central's log is the ClusterClient receptionist — a point-to-point command path, not gossip. So a SITE-A driver's health can reach central's /hosts by exactly one route: TelemetryProtoMapNode → gRPC TelemetryStreamService/Subscribe → TelemetryProtoMapCentral.

Result — 25 skipped of 26 authored:

Fact	Observed
Chip	25 / 26 SKIPPED, chip-warn
Driver status	HEALTHY, 0 errors (as ever)
Sample entries in tooltip	20 (= SkippedTagLedger.MaxSample)
Truncation note	(+5 more not shown)
Skips logged on site-a-1	25

That proves the truncation note, and simultaneously proves the proto path: the counts and all 20 sample entries with their RawPath + reason survived the wire.

Positive control, doubling as the cap boundary. Five of the 25 broken tags were deleted and SITE-A redeployed. Central's page tracked the change made only on the site node — 20 / 21 SKIPPED, sample still 20, and no truncation note, correct at exactly MaxSample (the off-by-one that would have read "+0 more not shown"). A live-updating view of a node with no gossip path is conclusive.

Rig restored: all 25 test tags deleted, SITE-A redeployed, sa-modbus2 back to 1 tag; the deployment revision hash returned to the pre-test 6178a8f3….

Still not proven live

Nothing outstanding from the original two. Remaining unit-only coverage is the ledger's concurrency guard (a torn read under a real init/publish interleaving) — inherently hard to force on a rig, and the lock makes it a code-inspection matter rather than an observational one.