Merge master (7feffc96) into remed/lane-G1

Refs #743 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 16:22:24 -04:00
parent f51055b509 7feffc963a
commit b943f48e01
171 changed files with 15356 additions and 3063 deletions
@@ -512,16 +512,16 @@ same pass (a UNS reference variable, say) are visible through the index with no

 ⚠️ **The value fan is now a single message.** It sends one
 `DriverInstanceActor.AttributeValueBatchPublished` carrying one item per RawPath, where it previously sent
-one `AttributeValuePublished` per ref — 5 000 messages onto the mux that also carries the node's steady
+one per-value message per ref — 5 000 messages onto the mux that also carries the node's steady
 value ingress, every time one driver flapped. Delivery is unchanged: the mux filters the batch per item
 against the same registered-interest map the per-value receive consulted, so only the framing moved. The
 **alarm** fan is indexed but deliberately not batched — one driver ref can back several condition NodeIds,
 so it still emits one `AlarmQualityUpdate` per condition.

-**Consequence worth knowing: `AttributeValuePublished` now has no production sender at all.** This fan was
-its last one — everything on the subscription path was already wrapped in `AttributeValueBatchPublished`.
-`DependencyMuxActor` still registers the per-value receive, but in production it is dead code; it stays
-for tests and direct senders.
+**Consequence: the per-value `AttributeValuePublished` record is deleted.** This fan was its last
+production sender (everything on the subscription path was already wrapped in
+`AttributeValueBatchPublished`), so the record and `DependencyMuxActor`'s per-value receive were removed
+(2026-10-22). A single value is a one-item batch; tests build one with `ValuePublishes.Single`.

 #### The third fan: the value nodes (archreview 03/S15)

@@ -39,8 +39,8 @@ This was not always true. Until #519 the publish path projected the driver's `ui
 `Good`/`Uncertain`/`Bad` enum in `DriverInstanceActor`, and `OtOpcUaNodeManager` re-expanded `Bad` to
 a bare `StatusCodes.Bad` (`0x80000000`). Every driver's diagnostic intent survived in logs only —
 including the 16 status constants #497 had just corrected across six drivers. The value path now
-carries the raw `uint` end to end (`AttributeValuePublished` → `AttributeValueUpdate` →
-`IOpcUaAddressSpaceSink.WriteValue`), and severity classification is a helper
+carries the raw `uint` end to end (`AttributeValueBatchPublished` → `AttributeValueBatchUpdate` →
+`IOpcUaAddressSpaceSink.WriteValues`), and severity classification is a helper
 (`OpcUaStatus.IsGood`/`IsUncertain`/`IsBad`) rather than a lossy projection.

 **Writing a status code in engine code:** use a named constant on
@@ -198,10 +198,32 @@ scripted-alarm predicates) runs scripts through the shared `ScriptRunGuard`:
  2 s default) quarantines immediately, through the same path (Error log, metric
  `reason=stuck`, Bad). A short overrun (a young orphan) stays a plain refusal and
  the script resumes once the orphan completes.
+- **Cooperative cancellation (`ctx.CancellationToken`).** The guard cancels the run
+  token when a run times out, and scripts see it as `ctx.CancellationToken`. A
+  long-running loop that polls `ctx.CancellationToken.IsCancellationRequested` (or calls
+  `ctx.CancellationToken.ThrowIfCancellationRequested()`) ends its own abandoned run
+  and frees the slot, instead of holding a pool thread until it returns. A script that
+  ignores the token is still an orphan. The editor completes the member, and
+  `CancellationToken` is on the sandbox allow-list.
 - **Allocation budget.** A single run allocating more than
  `Scripting:MaxAllocBytesPerRun` (64 MB) is quarantined. This is sampled after the
  run returns, so a run that OOMs the process first is not stopped — that needs an
  out-of-process runner.
+- **Configuration keys and their ranges.** All three knobs are node-wide (the
+  `Scripting` appsettings section, shared by virtual tags, Calculation tags and
+  scripted alarms) and are clamped when bound, with one startup Warning per
+  clamped value:
+
+  | Key | Default | Range after the clamp |
+  |---|---|---|
+  | `Scripting:MaxAllocBytesPerRun` | `67108864` (64 MB) | `0` (or negative) disables the budget; a positive value below `1048576` (1 MB) becomes 1 MB |
+  | `Scripting:QuarantineAfterConsecutiveTimeouts` | `3` | `1`–`1000` |
+  | `Scripting:StuckOrphanQuarantineFactor` | `10` | `0` (or negative) disables the rule; above `1000` becomes `1000`; `NaN` becomes the default |
+
+  A Calculation driver may override `maxAllocBytesPerRun` and
+  `quarantineAfterConsecutiveTimeouts` in its own driver config. Those keys are
+  layered on the node values and clamped to the same ranges, and an out-of-range
+  value logs a Warning naming the driver. The stuck factor has no per-driver key.
 - **Lifting.** A quarantine lifts when the script source changes or on redeploy,
  never by itself.
 - **Script-log rate limit.** The cluster-wide script-log fan-out admits 20 entries
@@ -243,7 +265,7 @@ prefix. The concrete implementation `ScriptTagCatalog` reads `Tag` +
 | Virtual tag | Leaf `Name` (best-effort) |

 **Why only resolvable keys?** The live runtime resolves a `ctx.GetTag("X")`
-literal against `DriverInstanceActor.AttributeValuePublished.FullReference`,
+literal against `DriverInstanceActor.AttributeValueItem.FullReference`,
 which is the `FullName` field from `Tag.TagConfig`
 (see `ScriptTagCatalog.ExtractFullNameFromTagConfig` + `EquipmentNodeWalker.ExtractFullName`).
 The former UNS-path cascade engine (`Core.VirtualTags.VirtualTagEngine`, keyed by the
@@ -93,7 +93,7 @@ Virtual-tag nodes are materialised by `AddressSpaceApplier` and fed by `VirtualT

 `ITagUpstreamSource` and `IHistoryWriter` are the two ports value consumers require from their host. Both live in `Core.VirtualTags`. In the v2 actor system:

- **Upstream-tag feed.** `DependencyMuxActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs`) routes `DriverInstanceActor.AttributeValuePublished` events to the `VirtualTagActor` instances that declared interest in those tag refs. Each `VirtualTagActor` holds the in-memory per-tag dependency map; the `IVirtualTagEvaluator` (`RoslynVirtualTagEvaluator`) receives the dependency snapshot synchronously on the actor message thread. Reads of never-pushed dependency refs return `null` values in the dependency snapshot.
+- **Upstream-tag feed.** `DependencyMuxActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs`) routes the items of each `DriverInstanceActor.AttributeValueBatchPublished` to the `VirtualTagActor` instances that declared interest in those tag refs. Each `VirtualTagActor` holds the in-memory per-tag dependency map; the `IVirtualTagEvaluator` (`RoslynVirtualTagEvaluator`) receives the dependency snapshot synchronously on the actor message thread. Reads of never-pushed dependency refs return `null` values in the dependency snapshot.
 - **`IHistoryWriter`** — the equipment-namespace path threads `Historize` end-to-end and `VirtualTagHostActor` invokes the injected writer on historized results (H5); the writer is resolved through `DriverHostActor` DI with a `NullHistoryWriter` default. No *durable* writer ships on this seam — durable continuous historization now flows through the separate `ContinuousHistorizationRecorder` → HistorianGateway `WriteLiveValues` path (see the `IHistoryWriter` section above and [Historian.md](Historian.md)).

 ## Composition
@@ -104,7 +104,7 @@ In the v2 actor system, virtual-tag engine composition is owned by the driver-ro

 - `AddressSpaceComposer.Compose` emits `DriverInstancePlan` / `ScriptedAlarmPlan` records; the driver-role `DriverHostActor` spawns one `VirtualTagActor` per virtual-tag expression and one `ScriptedAlarmActor` per scripted alarm.
 - `RoslynVirtualTagEvaluator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs`) is injected into each `VirtualTagActor` as its `IVirtualTagEvaluator`. It holds a per-source `CompiledScriptCache` keyed by script source and compiles on first use.
- `DependencyMuxActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs`) receives every `DriverInstanceActor.AttributeValuePublished` event and routes it to the `VirtualTagActor` instances that registered interest in that tag ref.
+- `DependencyMuxActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs`) receives every `DriverInstanceActor.AttributeValueBatchPublished` and routes each item to the `VirtualTagActor` instances that registered interest in that tag ref.

 `ITagUpstreamSource` and `IHistoryWriter` remain available as `Core.VirtualTags` ports.

@@ -125,7 +125,7 @@ In the v2 actor system, virtual-tag engine composition is owned by the driver-ro
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/ITagUpstreamSource.cs` — driver-tag read + subscribe port
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/IHistoryWriter.cs` — historize sink port + `NullHistoryWriter`
 - `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs` — actor that receives `DependencyValueChanged` from the mux and invokes `IVirtualTagEvaluator` per expression
- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs` — routes `DriverInstanceActor.AttributeValuePublished` to interested `VirtualTagActor` subscribers
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs` — routes `DriverInstanceActor.AttributeValueBatchPublished` items to interested `VirtualTagActor` subscribers
 - `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs` — production `IVirtualTagEvaluator` binding; holds a per-source `CompiledScriptCache`
 - `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/AddressSpaceComposer.cs` — pure data composer: config-DB entities → `AddressSpaceComposition` (UNS topology + raw subtree + driver/alarm plans)
 - `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/AddressSpaceApplier.cs` — applies the composed plan into the SDK node manager
@@ -88,6 +88,9 @@ After the handshake, Test Connect reads 2 bytes from `MB0`. A CPU with PUT/GET d
 default) completes the handshake but denies every read, so the probe fails with an actionable "enable
 PUT/GET communication" message instead of a false green tick. A CPU that merely rejects that address (no
 `MB0`) still passes — the connection is fine; any other read fault fails the probe with its message.
+Both are recognised in the bare-`Exception` shape S7.Net's read path really raises. The handshake and
+test read are bounded by the config's `timeoutMs` (the driver's own per-operation timeout), capped by the
+Test Connect timeout — before R07:H7 the config value was ignored.

 ## Address forms

@@ -103,9 +106,18 @@ Addresses use Siemens TIA-Portal / STEP 7 Classic syntax, parsed by
 | Timer | `T0` / `T15` | Timer area (read-only — see Wide types section) |
 | Counter | `C0` / `C10` | Counter area (read-only — see Wide types section) |

-Parsing is strict and runs once at `InitializeAsync` so a config typo fails fast
-at load instead of surfacing as `BadInternalError` on every read. Bit offsets
-must be 0-7, byte offsets non-negative, DB numbers >= 1.
+Parsing is strict. Bit offsets must be 0-7, byte offsets non-negative, DB numbers >= 1.
+
+**Tag shape rules are judged per tag, at every gate** (`S7TagShapeRules`, called by
+`S7TagDefinitionFactory.FromTagConfig`): the AdminUI editor refuses the tag, the deploy gate
+(`Inspect`) warns, and the driver's init **skips** it (reported through `ISkippedTagReporter`; it reads
+`BadNodeIdUnknown`) while every other tag keeps working. Refused: an address that does not parse, a
+wide/structured type that is an array or is not byte-addressed (`DBB`/`MB`/`IB`/`QB`), a narrow type at the
+wrong access width (`Int32` on `DBW0`, `Bool` on `DBB0`...), a Timer not typed `Float64` or a Counter not typed
+`Int32`, a writable or array Timer/Counter, a writable `Bool` array, and a `Bool` array that does not start
+at bit 0 (a Bool array reads bit 0 of each byte, so `DB1.DBX0.3` used to silently return bit 0 of bytes
+0..n). These used to be init guards that THREW, so one typo faulted every tag on the PLC and the actor
+retried the same init every 10 s forever (R07:H3).

 ## Data types

@@ -277,7 +289,7 @@ AdminUI `/hosts` page (Gitea #640). See `docs/Telemetry.md` ("Driver diagnostics
 | `IWritable` | `WriteAsync` → `S7.Net.Plc.WriteAsync` | Read-only tags (`Writable=false`) return `BadNotWritable` |
 | `ITagDiscovery` | `DiscoverAsync` | Emits a flat `S7/` folder of the configured tags — no live browse |
 | `ISubscribable` | per-tag poll loop with capped exponential backoff | S7 has no push model; floor is 100 ms (the CPU services the comms mailbox once per scan) |
-| `IHostConnectivityProbe` | periodic `S7.Net.Plc.ReadStatusAsync` (CPU-status PDU) | `host:port` host key; `Running`/`Stopped` transitions raise `OnHostStatusChanged` |
+| `IHostConnectivityProbe` | periodic `S7.Net.Plc.ReadStatusAsync` (CPU-status PDU) | `host:port` host key; `Running`/`Stopped` transitions raise `OnHostStatusChanged`. A tick that finds the gate held past the probe deadline (a long read pass) gives **no verdict** — it no longer reports `Stopped` for a connection that is busy, not lost (R07:H7) |

 ### Single-connection policy

@@ -302,8 +314,9 @@ Portal under *Protection & Security* for the CPU.
 | Tag not in config | `BadNodeIdUnknown` | unchanged |
 | Read-only tag written | `BadNotWritable` | unchanged |
 | Unimplemented data type | `BadNotSupported` | unchanged |
-| PUT/GET denied | `BadNotSupported` | `Faulted` (config alert) |
-| CPU / hardware fault | `BadDeviceFailure` | `Degraded` |
+| PUT/GET denied | `BadNotSupported` | `Faulted` (config alert) — also counts as *answered*, advances `LastSuccessfulRead` (no watchdog reconnect loop) |
+| CPU refusal of the item (object does not exist, address out of range, type inconsistent, hardware fault) | `BadDeviceFailure` | unchanged — counts as *answered*, advances `LastSuccessfulRead`; one Warning per tag |
+| Other device-layer fault (`PlcException` that is neither a refusal nor connection-fatal) | `BadDeviceFailure` | `Degraded` |
 | Socket / timeout | `BadCommunicationError` | `Degraded` |
 | Reconnect suppressed (backoff window) | `BadCommunicationError` | `Degraded` |
 | Array write of the wrong shape / length / element type | `BadTypeMismatch` | unchanged |
@@ -314,7 +327,36 @@ accumulate their outcomes and write health once (`Healthy < Degraded < Faulted`)
 `Faulted` item is not erased by a later `Degraded` or successful sibling. The write-side `Faulted` is
 **sticky against reads**: a clean read pass (reads often work against a write-protected CPU) leaves
 `Faulted` in place and only advances `LastSuccessfulRead`; the next write that succeeds clears it. A
-transient `Degraded` write failure is still cleared by a clean read, as before.
+transient `Degraded` write failure is cleared by a clean read, or by the next write batch the CPU
+answers without a failure.
+
+**A refusal is an answer (R07:H4).** S7.Net's read paths raise the CPU's item error as a bare
+`Exception` ("Received error from PLC: Object does not exist." — live-probed on the snap7 fixture), its
+write paths as a `PlcException(WriteData)`; both are classified over the whole exception chain, and the
+access-denied text inside either (S7.Net's exact "Accessing object not allowed", and never when the chain
+also carries a transport fault) is the `Faulted` alert — which is ALSO an answer: it advances
+`LastSuccessfulRead`, so a factory-default CPU with PUT/GET disabled stays `Faulted` instead of being
+reconnected by the comms-loss watchdog every 90 s. A multi-var chunk that falls back per tag memoises the
+members refused on their own, like a refused span. A refusal is deterministic, so it neither
+degrades health nor reopens the connection, and because it proves the CPU is reachable it advances
+`LastSuccessfulRead` and restores `Healthy` after an earlier comms fault. Before this, a driver whose
+every tag was refused (a wrong DB number) sat `Degraded` with a frozen timestamp and the comms-loss
+watchdog reconnected it every 90 s against a perfectly reachable PLC.
+
+**A dead handle ends the pass's wire traffic (R07:P1).** Once a read pass or write batch marks the
+connection dead (a wire op blew its deadline on a frozen-but-established peer, a socket dropped), the
+remaining spans / multi-var chunks / tags / writes of that pass are stamped `BadCommunicationError`
+without I/O; the next call reopens. A multi-var chunk that dies on a transport loss no longer falls back
+to one doomed per-tag read per member. Without this an op that ignores its cancellation token would cost
+one full deadline per remaining item under the gate, and `Degraded` (and so the comms-loss watchdog's
+clock) only became visible after the whole pass.
+
+**A refused span falls back per member (R07:P2).** A grouped block read covers the union of its members'
+ranges, so one member the CPU refuses (running past the DB's real end, an over-declared `stringLength`)
+used to make every neighbour in the block Bad on every poll. When the CPU refuses a multi-member span the
+driver re-reads its members one at a time for that pass and remembers which tags must not be grouped —
+the members refused on their own, or every member when none was — so later passes group only the rest.
+The memo lasts until the next initialize. A span failure that is not a refusal still stamps every member.

 **Connect backoff.** A dead PLC costs one connect attempt per backoff window (1 s doubling to a 30 s
 cap), not one per read / poll tick / probe tick: inside the window `EnsureConnectedAsync` fails fast
@@ -359,7 +401,7 @@ normal dev (the S7 sim is on the shared Docker host but currently offline).
 **Array writes (S7-016)** — a writable `Byte` / `Int16` / `UInt16` / `Int32` / `UInt32` / `Float32` array
 is written as ONE contiguous `WriteBytesAsync` of `count x element-bytes` (the inverse of the read
 decode), and the value must be an array of exactly `arrayLength` elements (else `BadTypeMismatch`, no
-health impact). **Writable `Bool` arrays are refused at init** (`NotSupportedException`): the array
+health impact). **Writable `Bool` arrays are refused per tag** (see the tag shape rules above): the array
 read is byte-granular, so a matching write would overwrite the 7 neighbouring bits of every byte it
 touches, and a safe bit-packed write needs read-modify-write. Mark Bool arrays `writable: false`. A `null` array element is rejected (`BadTypeMismatch`, nothing written)
 rather than coerced to 0. An array write larger than one PDU is split by S7.Net into several writes and is