docs: site artifact revision, pending-updates indicator, rail scroll pane

Claude-Session: https://claude.ai/code/session_01Y5ef34iUUMjmwnMpL9xgmB
2026-09-14 14:01:07 -04:00
parent c724ed6ee2
commit d8979664f1
6 changed files with 123 additions and 2 deletions
@@ -138,6 +138,7 @@ spec for each is `docs/requirements/Component-<Name>.md`, and `README.md` carrie
 - Deployment identity: unique deployment ID + revision hash for idempotency.
 - Per-instance operation lock covers all mutating commands (deploy, disable, enable, delete).
 - **Bulk site deployment (`DeploymentService.DeploySiteAsync`, arch-review WP2.5)** redeploys every out-of-date instance at a site through one flatten session (a template chain shared by N instances is walked once) in three phases — serial Prepare, bounded-parallel Send (`SiteDeploymentMaxParallelism`, default 4), serial Finalize — still **not all-or-nothing**: any one instance's failure doesn't block the rest. **Disabled instances are SKIPPED by bulk deploy as of 2026-08-19 (arch-review P7-2)** — they are reported in the summary's additive `SkippedInstances` list, never flattened/sent/re-enabled (single-instance deploy remains the explicit operator path that deploys+enables a Disabled instance); **Up-to-date instances are ALSO skipped as of 2026-08-20 (arch-review P7-6)** — a redeploy is not idempotent at the site (it resets static overrides and clears native alarm state), so `DeploySiteAsync` pre-filters through `IStaleInstanceProbe` (trustworthy since P7-4 fixed its memo timing) and reports unchanged instances in `SkippedInstances` with reason `up-to-date`; the filter is conservative (every uncertainty deploys: missing snapshot, `ShouldQuerySiteBeforeRedeploy`, null/faulting probe). Additive `MgmtDeploySiteCommand.Force` / CLI `deploy site --force` restores the unconditional push for what central cannot see (restored volume, rebuilt node) — **Disabled still wins under `--force`**. Also P7-5: the three phases share one scoped DbContext and a failed `SaveChanges` leaves the entity tracked, so one permanent failure used to cascade to every later instance and strand records `InProgress`; `MarkDeploymentFailedAsync` now detaches pending changes and retries the `Failed` write once on the clean tracker; Prepare's per-instance reconcile also runs under a short `SiteDeploymentReconcileTimeout` (5s) with a once-per-batch unreachable-site circuit-breaker, so a down site no longer costs 30s × N serial before the first send (P7-3). The `PendingDeployment` staging row (5-minute TTL) is written per-instance immediately before that instance's round-trip in the Send phase, not upfront in Prepare, so a large batch's tail instances don't have their TTL clock already half-spent by the time they're reached.
 - **Site artifact revision + fleet-wide pending-updates indicator (2026-09-14, `docs/plans/2026-09-14-pending-updates-design.md`).** `Site.ArtifactRevisionHash`/`ArtifactsDeployedAt` (migration `AddSiteArtifactRevision`) are stamped by `ArtifactDeploymentService` only on a site whose artifact deploy succeeds, so a redeployed fleet's artifacts are trackable per site the same way instance staleness already is. `PendingUpdatesEvaluator` combines that with `DeploymentService.GetInstanceStalenessAsync` (one shared `FlattenSession` for the whole fleet) into a `PendingUpdatesSnapshot`, held behind a process-wide singleton `IPendingUpdatesCache` (`ScadaBridge:DeploymentManager:PendingUpdatesCacheTtl`, default 60s) so N Blazor circuits cost one fleet flatten per TTL, not one each. Surfaces: the Sites page's per-site **Artifacts** badge (`Current`/`Out of date`/`Never deployed`) + instance-staleness line + header **Re-check**, and a rail-footer **pending updates** indicator (Deployer/Administrator only, 30s poll, site-scoped). **Upgrade consequence:** every site reads *Never deployed* until one artifact deploy runs post-upgrade — deliberate, not a bug. Also shipped: the rail nav now sits in its own scroll pane (`NavMenu`'s `.rail-scroll` + `site.css`) so a long nav can't push the footer/indicator off-screen; the `ZB.MOM.WW.Theme` kit itself is untouched (register row 123 proposes upstreaming it).
 - **Create Instance picks its template from the Templates folder tree** (2026-08-21): the flat `<select>` is gone. The Template field is a read-only folder-qualified path box (`TemplatePathFormatter`, "Folder / Sub / Name") + a **Choose…** button, both opening `TemplatePickerDialog` — an `IDialogService.ShowAsync` body wrapping the **same shared `TemplateFolderTree`** the Templates page renders, with its own search, expand/collapse-all, templates-only selection and double-click-to-pick. It opens on the current pick via the tree's additive **`RevealKeys`** parameter (ancestors of the named `f:`/`t:` keys start expanded when no `Filter` is active; an active filter's reveal set still wins; callers passing nothing are byte-identical). `InstanceCreate` gained `[SupplyParameterFromQuery] TemplateId`, which the Templates tree's new **Deployer-gated "New Instance…"** context-menu item navigates with; combined with `?siteId=` it populates the Connection Bindings card on first render. **The trap for anyone extending the picker:** in `TreeViewSelectionMode.Single` the inner `TreeView` reads the *singular* `SelectedKey`/`SelectedKeyChanged` pair, but `TemplateFolderTree` forwards only the plural (Checkbox-mode) `SelectedKeys` pair — so a Single-mode caller cannot get a row highlight through the shared tree and must own selection in its own `NodeContent`, as the picker does. Design: `docs/plans/2026-08-21-template-picker-design.md`.
 - **Create Instance binds module groups at creation** (2026-08-21): the create page's Connection Bindings card flattens template+site through the additive `IFlatteningPipeline.PreviewAsync` (an unsaved instance — no validation, no hash, nothing persisted, instance repo never touched) and reuses `BindingGroupBuilder`; `NodeBrowserDialog.SelectableNodeClasses` lets it pick **Object** nodes (default stays Variable-only for every existing caller). Create = `CreateInstanceAsync` → `SetConnectionBindingsAsync` (the existing upsert, no new server surface) → always navigate to Configure with `?created=1&bound=N|&bindError=…`, because the row exists whether or not the second call succeeded. Partial binding is legal: a group missing a connection or an Object is skipped and stays unbound. Design: `docs/plans/2026-08-21-create-instance-bindings-design.md`.
 - Site-side apply is all-or-nothing per instance.
@@ -116,6 +116,9 @@ All 7 fix-now items landed via PLAN-04/05/06/07/08 (verified in review 08 round
 | 120 | **Data-sourced SCALAR writes reach the OPC UA server as String Variants — every non-String node rejects them with BadTypeMismatch (0x80740000)** *(Medium)*. `InstanceActor.HandleSetDataAttribute` / `HandleWriteAttributeBatch` decode only List values before the DCL write ("Scalars are unchanged"), so the codec-encoded string (`"True"`, `"42.5"`) reaches `RealOpcUaClient.WriteValuesAsync`, which wraps it in `new Variant(value)` — a String variant sent to a Boolean/Double node. Found live 2026-09-10 running `docker/seed-handshake-demo.sh` against opc-plc `Motor.Running`/`Pump.Running`/`Motor.Speed` (`SetAttribute('Complete') failed: OPC UA write failed with status: 0x80740000`); the seed was retargeted onto the rig's only two writable String nodes. The MxGateway path is unaffected in practice: prod's Delmia/MES handshakes write the same strings through the gateway today. Fix candidates: (a) decode scalars by declared `DataType` in the InstanceActor before the DCL write — also changes what MxGateway receives, so it needs a gateway-side compatibility check; (b) adapter-local: `RealOpcUaClient` coerces to the node's DataType (it already resolves `DataTypeIds` in `EnrichVariableTypeInfoAsync`), leaving the MxGateway wire untouched — preferred. Pin with a `RealOpcUaClientArrayWriteTests`-style test for a Boolean scalar. | Found live 2026-09-10 during the #36 rig gate | Out of scope for #36 (handshake ordering); touches the production write path and needs the MxGateway compatibility question answered first. | Before any OPC UA-bound template relies on script writes to non-String nodes (none does today — until this gate the rig's script writes to OPC UA were static-only). |
 | 121 | **No source-level `IsMesReportable` on native alarm source bindings** *(Low)*. `TemplateNativeAlarmSource` / `InstanceNativeAlarmSourceOverride` carry no per-alarm MES-relevance flag — "every condition under this binding is reportable" is not expressible, only the 900–999 severity-band convention. | `docs/plans/2026-09-11-mes-reportable-alarm-flag-design.md` | Native alarms have no per-alarm config row, and the design chose not to invent one for this slice. | A native-source machine needs per-alarm MES relevance beyond the severity band. |
 | 122 | **`IsMesReportable` does not ride the wire** *(Low)*. `AlarmStateUpdate` (vendored proto) and `DebugAlarmStateDto` have no `IsMesReportable` field, so central-side surfaces (Debug View live stream, Alarm Summary) always see `false` even though the site-side snapshot stamps the real value. Adding it is additive-only: `AlarmStateUpdate` field 25, `DebugAlarmStateDto` field 20, via a manual `regen-proto.sh` toggle-build-copy-untoggle. | `docs/plans/2026-09-11-mes-reportable-alarm-flag-design.md` | No consumer needed it in this slice — the flag exists to serve `Alarms.MesReportableAsync()` for scripts, not a central UI surface. | Operators ask to see the MES-reportable flag live on Debug View / Alarm Summary. |
 | 123 | **Rail nav scroll pane (`.rail-scroll` + the `#theme-rail > .side-rail { height: 100% }` fill rule) lives in app-local `site.css`/`NavMenu.razor`, not the `ZB.MOM.WW.Theme` kit** *(Low)*. Every other kit consumer (OtOpcUa, MxGateway, HistorianGateway, ignitionoee) has the same unbounded-nav-pushes-the-footer-off-screen shape and would need the identical fix copy-pasted. | `docs/plans/2026-09-14-pending-updates-design.md` §3.5 | Scoped to ScadaBridge for this change; upstreaming into the shared kit is a separate cross-repo release, not a one-app CSS tweak. | A second kit consumer hits the same long-nav clipping and copies the fix instead of consuming it from the kit. |
 | 124 | **No template-graph-watermark short-circuit on the pending-updates fleet flatten** *(Low)*. `PendingUpdatesEvaluator.EvaluateAsync` re-flattens every deployed instance through `DeploymentService.GetInstanceStalenessAsync` on every cache-TTL expiry (`PendingUpdatesCacheTtl`, default 60 s) while any Deployer/Admin circuit is open, even when nothing in the template/instance/artifact graph has changed since the last evaluation. | `docs/plans/2026-09-14-pending-updates-design.md` §3.2 ("Not in scope") | The single-flight TTL cache already bounds the cost to one fleet flatten per TTL fleet-wide (not per viewer); a watermark short-circuit is a further optimization, not a correctness need, and needs a cheap "has anything changed" signal that does not exist yet. | The fleet flatten's cost (instance count x template depth) becomes measurable against `PendingUpdatesCacheTtl` on a large deployment. |
 | 125 | **Pending-updates counts have no Health-dashboard tile or CLI surface** *(Low)*. The aggregate (`PendingUpdatesSnapshot.StaleInstanceCount` / `StaleArtifactSiteCount`) is consumed only by the Central UI Sites page and rail indicator; there is no Health dashboard KPI tile and no `deploy`/`site` CLI command surfacing it — `site list` shows only the raw `artifactRevisionHash`/`artifactsDeployedAt` fields on each site, not whether they are current. | `docs/plans/2026-09-14-pending-updates-design.md` §3.2 ("Not in scope") | Out of scope for the UI-focused ask; the CLI/Health surfaces are a separate consumer of the same `IPendingUpdatesCache`. | An operator wants the pending-updates counts without opening the Central UI (headless monitoring, CLI scripting). |
 ## Resolved (verified against the code 2026-07-10)
 Rows removed from the Deferred table above once confirmed shipped. Kept here for traceability.
@@ -19,6 +19,8 @@ Central cluster only. Sites have no user interface.
  - **The decision.** *Approve* is `Caution` (amber): approving executes a real write to live plant equipment, so it is not a benign primary action, but it is not destroying anything either. *Reject* **keeps** `Destructive` (red): it is terminal and irreversible for the request — the Operator must resubmit — and holding it red is what keeps the two opposite decisions visually distinct. Dropping *Reject* to a neutral button was considered and rejected: it would simply invert the bias, making declining look like the safe default.
  - Colour is never the only signal — the button always carries its verb (see the label contract above), so the mapping is an accessibility affordance, not the meaning.
  - **`DialogSeverity` is an additive overload**, not a replacement: the boolean form remains the signature for the ~34 existing call sites, which are genuinely two-state. Adding a fifth optional parameter to the boolean form instead would have silently un-matched every existing four-argument NSubstitute stub — the row-28 gotcha, where a stub that stops matching returns a null `Task` and the caller NREs with no compile error. Reach for the overload only when `Caution` is what you mean.
 - **Pending updates rail indicator (2026-09-14, `PendingUpdatesIndicator`, design `docs/plans/2026-09-14-pending-updates-design.md`).** A block in the rail footer, placed above the user name (`MainLayout`'s `RailFooter`, `.rail-user`), summarising the fleet-wide `PendingUpdatesSnapshot` from Component-DeploymentManager.md's *Pending-updates aggregate*. Rendered only for a user holding **Deployer or Administrator** — the two roles that can act on it — and hidden for everyone else. States: *Checking for updates…* (first load), *Up to date* (muted, check icon), **Pending updates** with a warning count pill and a breakdown line (`N instances`, linking to `/deployment/topology` for a Deployer; `M sites`, linking to `/admin/sites` for an Administrator, plain text otherwise), or *Updates unavailable* (error styling, tooltip carries the failure message) on a faulted evaluation. A tooltip on the block reads *as of HH:mm UTC*. It polls `IPendingUpdatesCache.GetAsync()` every 30 s through `PollGate` — cheap, since the cache's own 60 s TTL means the fleet is actually re-flattened at most once per TTL fleet-wide, no matter how many circuits (or how often each one) poll it — disposes its timer with the circuit, and renders through `InvokeAsync`. A **site-scoped** user sees counts narrowed to their permitted sites only (`PendingUpdatesSnapshot.ForSites`, the same scope `SiteScopeService` applies to Topology), so the indicator and the Sites page never disagree about which sites a given operator can see.
 - **Rail nav scroll pane (2026-09-14).** `NavMenu.razor` wraps its items in a `<div class="rail-scroll">`; `site.css` (≥ lg only) fills the sticky `100vh` `#theme-rail` (`#theme-rail > .side-rail { height: 100% }`) and makes `.rail-scroll` the flexible, independently-scrolling region (`flex: 1 1 auto; min-height: 0; overflow-y: auto`), so a long expanded nav scrolls under the brand bar instead of pushing the rail footer (and now the pending-updates indicator) off-screen. Below lg the rail is inline and scrolls with the page, unchanged. The `ZB.MOM.WW.Theme` kit itself is untouched — this is app-local CSS/markup layered on top of it (deferred-work register row 123 proposes upstreaming it for the kit's other consumers).
 ## Review hardening (2026-09-09)
@@ -107,6 +109,8 @@ Central cluster only. Sites have no user interface.
 - **Move data connection between sites** (M9/T24): a **Move…** action on a data connection opens `MoveDataConnectionDialog`. The underlying `MoveDataConnectionCommand` guards against: target site does not exist, name collision at the target, any `InstanceConnectionBinding` referencing the connection, and any `InstanceNativeAlarmSourceOverride.ConnectionNameOverride` reference at the source site's templates. Blocked connections display the blocking reason.
 - **Server certificate management** (`/design/connections/{id}/certificates`, Admin role): a per-connection page that lists the contents of the site's OPC UA trusted-peer and rejected certificate stores (Subject / Issuer / Thumbprint / validity / Trusted-or-Rejected status) with a **Remove** action. The page makes clear the store is **node-wide for the site** (shared by every site node), not per data connection — trusting or removing a certificate affects all OPC UA connections at that site. Trust and Remove are central commands relayed to **both** site nodes so the node-local PKI stores stay consistent across failover (see Component-SiteRuntime.md, Component-DataConnectionLayer.md).
 - The site detail page exposes a new **"Audit feed"** tab that hosts the Audit Log page pre-filtered to `Site = <site>` — an in-context view of every operational audit event for that site.
 - **Artifacts badge (2026-09-14, design `docs/plans/2026-09-14-pending-updates-design.md`).** Each site card carries an **Artifacts** badge next to the identifier, one of three states: `Current` (light — the site's `Site.ArtifactRevisionHash` matches what a deploy would send today), `Out of date` (warning, `bi-exclamation-triangle`, tooltip = the last successful deploy's UTC timestamp), or `Never deployed` (secondary — the site has no stamp at all, including every site immediately after the migration that added the columns, until one artifact deploy). Below the badge a muted `N of M instances out of date` line links to `/deployment/topology` whenever the site has any deployed instances, since the same fleet snapshot already carries the count.
 - The page header gains a **Re-check** button (forces a fresh fleet evaluation, disabled while running) and an **"Updates as of HH:mm:ss UTC"** caption next to the page title. The snapshot loads **after** the site list, never blocking it — cards render immediately with a *checking…* placeholder for the badge/line, and a snapshot failure renders **unavailable** on the badge rather than hiding it or failing the page. A successful **Deploy Artifacts** (single-site or all-sites) forces a refresh of the snapshot so the badge flips to `Current` immediately rather than waiting out the cache TTL.
 ### Schema Library (Design Role)
 - A **Schema Library** page (M9/T32, under the Design nav group) provides CRUD for `SharedSchema` entries — named, reusable JSON Schema definitions. Each entry has a name (globally unique) and a JSON Schema body.
@@ -184,7 +188,7 @@ Central cluster only. Sites have no user interface.
 - **Per-site deployment**: A "Deploy Artifacts" button on the Sites admin page allows deploying all artifacts to an individual site.
 - **Deploy all**: A bulk action deploys artifacts to all sites at once.
 - This is a **separate action** from instance deployment — system-wide artifacts are not automatically pushed when definitions change.
- Track per-site deployment status.
+- **Track per-site deployment status**, backed by `Site.ArtifactRevisionHash` / `ArtifactsDeployedAt` (Component-DeploymentManager.md → *Per-site artifact revision*), stamped **only on a successful deploy to that site**. A failed site keeps its previous stamp (or none) and keeps reading out of date on the Sites page; after an upgrade that ships the stamp columns, every site reads *Never deployed* until one artifact deploy runs — see the Artifacts badge above.
 ### Debug View (Deployment Role)
 - Select a deployed instance and open a live debug view — the instance picked through the same shared **`InstancePicker`** combobox as the Flow Debugger, with an `ItemLabel` suffix of `(State)` on each row.
@@ -359,6 +359,7 @@ A CI grep guard (`AuditLogAppendOnlyGuardTests`) fails the build on any `UPDATE`
 - New tables are introduced as their own migration — for example, the `Notifications` table for the Notification Outbox ships as a dedicated EF Core migration that creates the table, its `Type`/`Status` value conversions, and its dispatcher and KPI indexes.
 - The native alarm source tables ship in a dedicated `AddNativeAlarmSources` migration, parallel in shape to the existing `AddInstanceAlarmOverrides` migration: it creates `NativeAlarmSources` and `InstanceNativeAlarmSourceOverrides` with their columns, the `TemplateId` → `Templates` and `InstanceId` → `Instances` cascade-delete foreign keys, and the `(TemplateId, Name)` / `(InstanceId, SourceCanonicalName)` unique indexes.
 - **`20260911135501_AddAlarmMesReportable`** (2026-09-11) adds `TemplateAlarms.IsMesReportable` (`bit`, default `0`) and `InstanceAlarmOverrides.IsMesReportableOverride` (`bit` NULL, null = inherit the template value). No new tables, no index changes — see `docs/plans/2026-09-11-mes-reportable-alarm-flag-design.md`.
 - **`20260914173147_AddSiteArtifactRevision`** (2026-09-14) adds `Sites.ArtifactRevisionHash` (`nvarchar(100)` NULL) and `Sites.ArtifactsDeployedAt` (`datetimeoffset` NULL) — both null on an upgraded row until that site's next successful artifact deploy stamps them. No new tables, no index changes — see `docs/plans/2026-09-14-pending-updates-design.md`.
 - The initial `AuditLog` migration creates the monthly partition function `pf_AuditLog_Month` and partition scheme `ps_AuditLog_Month`, then creates the `AuditLog` table aligned to that scheme on `OccurredAtUtc`, along with the indexes listed under Database Schema. The migration also creates the `scadabridge_audit_writer` and `scadabridge_audit_purger` DB roles with the grants described in Database Roles. The ongoing **partition-maintenance job** that rolls the scheme forward each month (creating the next month's partition ahead of time) and switches out expired partitions is owned by the **Audit Log component** (`AuditLogPurgeActor` and its monthly roll-forward step), not by the Configuration Database component — this component is responsible only for the initial schema, roles, and any EF migrations against the table going forward.
 ### Development Environment
@@ -281,6 +281,56 @@ Component-NotificationService.md). Notification delivery happens on the central
 cluster, so no notification artifact or SMTP credential is ever distributed to
 sites.
 ### Per-site artifact revision (2026-09-14)
 `Site` carries two nullable columns — `ArtifactRevisionHash` (`string?`, max 100)
 and `ArtifactsDeployedAt` (`DateTimeOffset?`) — recording the artifact set last
 successfully deployed to that site (migration `AddSiteArtifactRevision`; see
 Component-ConfigurationDatabase.md). Both are `null` on a site that has never had
 artifacts deployed, including every site immediately after an upgrade that ships
 this migration — a redeploy landed the columns, it did not retroactively stamp
 them, so the Sites page reads every site **Never deployed** until one artifact
 deploy runs. **The two columns are deliberately not transported**: like an
 imported instance landing `NotDeployed`, they are environment-specific runtime
 state and the Transport round-trip guard excludes them by name. An import that
 changes a site's data connections therefore correctly makes the site read out of
 date until artifacts are redeployed there.
 `ArtifactRevisionHashService` computes a deterministic SHA-256 over a canonical
 projection of a per-site `DeployArtifactsCommand` — every artifact class sorted by
 `Name` (ordinal), `DeploymentId`/timestamp excluded (so two deploys of identical
 definitions hash identically), an external system's `MethodDefinitionsJson`
 re-canonicalised with its methods sorted by name, and `TimeSpan` retry intervals
 carried as ticks rather than a formatted string. Internal `Hashable*` records MUST
 declare their properties in alphabetical (ordinal) order — `System.Text.Json`
 serializes in declaration order and does not sort — pinned by a
 `HashableRecords_PropertiesDeclaredAlphabetically` test, mirroring
 `RevisionHashService`'s own determinism contract. Because a data connection's
 configuration is plaintext in memory (the ciphertext is an EF value converter
 applied only at rest), a no-op re-save that merely re-encrypts does not change the
 hash.
 `ArtifactDeploymentService` stamps `ArtifactRevisionHash` + `ArtifactsDeployedAt`
 on the `Site` row **only for a site whose deploy succeeded**, on both the
 all-sites/single-site sweep (`DeployCoreAsync`) and the per-site retry
 (`RetryForSiteAsync`) paths. A failed site keeps its previous stamp (or none), so
 it keeps reading out of date. **Ordering is deliberate**: the
 `SystemArtifactDeploymentRecord` audit row is persisted first, and the stamp is
 applied — and saved — afterward, inside its own try/catch. Stamping first would
 let a stamp-save failure (concurrency conflict, constraint violation) escape
 uncaught through the record's own `SaveChangesAsync` and turn a wholly successful
 deploy into a reported failure; running the record's save first keeps a stamp
 failure best-effort — logged at Warning, deploy still reports success, the site
 simply keeps reading out of date until the next deploy.
 `ArtifactDeploymentService.ComputeCurrentArtifactHashesAsync(sites)` returns
 `siteId → hash` for what a deploy would send *right now* — the global artifact
 queries are hoisted once for the whole batch, mirroring `DeployCoreAsync`'s own
 hoist. A failing per-site data-connection query **aborts the whole batch by
 design**: a partial map would silently report the unqueried sites as up to date,
 so the pending-updates cache instead discards the faulted flight and the UI shows
 the aggregate as unavailable.
 ## Site-Side Apply Atomicity
 Applying a deployment at the site is **all-or-nothing per instance**:
@@ -293,7 +343,67 @@ Applying a deployment at the site is **all-or-nothing per instance**:
 - Cross-site version skew for artifacts (shared scripts, external system definitions, data connection definitions, etc.) is **supported** — sites can temporarily run different artifact versions after a partial deployment.
 - Artifacts are self-contained and site-independent. A site running an older version of shared scripts continues to operate correctly with its current instance configurations.
- The Central UI clearly indicates which sites have pending artifact updates so engineers can remediate.
+- The Central UI clearly indicates which sites have pending artifact updates so engineers can remediate — see *Per-site artifact revision* above and *Pending-updates aggregate* below for the concrete mechanism (the Sites-page Artifacts badge and the rail indicator).
 ## Pending-updates aggregate (2026-09-14)
 `DeploymentService.GetInstanceStalenessAsync(instanceIds)` answers instance
 staleness for a whole batch cheaply enough to run fleet-wide on a cache-TTL
 cadence, agreeing exactly with the per-instance Topology badge
 (`GetDeploymentComparisonAsync`):
 - All the flattens share **one `FlattenSession`** for the batch, so a template
  chain used by N instances is walked once — the same trick `DeploySiteAsync`
  uses.
 - The deployed side is read as the `(InstanceId, RevisionHash)` **projection**
  (`IDeploymentManagerRepository.GetDeployedRevisionHashesAsync`), never the fat
  `ConfigurationJson` for the whole fleet.
 - **Mismatch-only normalisation**: only when the projected hash disagrees with
  the re-flatten is the full `DeployedConfigSnapshot` read and the I-1 List-value
  normalisation applied (see *Deployed vs. Template-Derived State* above) — the
  same normalisation `GetDeploymentComparisonAsync` applies, so the aggregate
  never disagrees with the Topology badge on an old-form List snapshot, without
  paying the fat read fleet-wide.
 - `null` means "could not evaluate" (the instance's flatten failed) — counted as
  **unknown**, never as stale; a fleet-wide read must not manufacture a pending
  update out of a read failure. An instance with no deployed snapshot at all is
  omitted, not counted as unknown.
 - Per-instance failures are **not** logged individually — the whole batch runs at
  most once per cache TTL, so one broken shared template fanning out to N
  instances would otherwise emit N Warning lines every minute forever. A single
  Warning summarises the batch's failure count instead; per-instance detail stays
  at Debug.
 `PendingUpdatesEvaluator` (scoped) combines that with
 `ArtifactDeploymentService.ComputeCurrentArtifactHashesAsync` into one
 `PendingUpdatesSnapshot`: `ComputedAt`, plus per-site `SitePendingUpdates`
 (`ArtifactState` — `NeverDeployed` / `Current` / `OutOfDate` —,
 `ArtifactsDeployedAt`, `DeployedInstanceCount`, `StaleInstanceCount`,
 `UnknownInstanceCount`) and fleet totals `StaleInstanceCount` /
 `StaleArtifactSiteCount`. Only instances with a deployed snapshot (`State !=
 NotDeployed`, the same gate Topology uses) are evaluated. **`NeverDeployed` is
 deliberately not a pending update** — a freshly-created site the operator has not
 gotten to yet has nothing drifted, so it is surfaced on the Sites page but never
 counted toward the fleet totals or the rail indicator's badge count. Nothing in
 the evaluator swallows an exception: a faulted evaluation propagates so the
 cache's single-flight memo discards the flight and the Central UI renders the
 aggregate as unavailable, rather than manufacturing a false "up to date".
 The Central UI holds the snapshot behind a process-wide singleton
 `IPendingUpdatesCache` (`PendingUpdatesCache`, mirroring `KpiSnapshotCache`): one
 `SingleFlightMemo<PendingUpdatesSnapshot>` keyed by
 `ScadaBridge:DeploymentManager:PendingUpdatesCacheTtl` (default 60 s, validated
 positive by `DeploymentManagerOptionsValidator`), each flight running the
 evaluator in its own DI scope. However many Blazor circuits poll
 `GetAsync(forceRefresh)`, the fleet is flattened **at most once per TTL**, and not
 at all when no Deployer/Admin circuit is open. See
 `docs/plans/2026-09-14-pending-updates-design.md` for the full design, including
 the Sites-page badge/re-check UI and the rail-footer indicator
 (Component-CentralUI.md → *Site & Data Connection Management* and *Technology*).
 Not in scope for this slice (deferred-work register rows 124–125): a
 template-graph-watermark short-circuit so an unchanged fleet costs no re-flatten
 per TTL, and a `deploy` CLI / Health-dashboard KPI surface for the counts.
 ## Instance Lifecycle Commands
@@ -902,6 +902,8 @@ List all registered sites.
 scadabridge --url <url> site list
 ```
 `site list` has no table projector, so both `--format json` and `--format table` show the full `Site` entity for every row, unfiltered. As of 2026-09-14 that includes `artifactRevisionHash` and `artifactsDeployedAt` (`null` on either means artifacts have never been deployed to that site) — see `docs/requirements/Component-DeploymentManager.md` → *Per-site artifact revision*.
 #### `site create`
 Register a new site.