ScadaBridge/docs/plans/2026-09-14-pending-updates-design.md

# Pending Updates: site artifact staleness, rail indicator, scrollable nav — Design

**Date:** 2026-09-14 · **Status:** approved for implementation (plan: `2026-09-14-pending-updates.md`)

## 1. Ask

Three Central UI changes, requested together:

1. The **Sites page** does not show whether a site's deployed **system-wide artifacts** (shared scripts,
   external systems, DB connections, that site's data connections) are out of date. It should carry a
   Stale / Current badge like the Topology (template-instance) page does for instances.
2. A **single "pending updates" indicator** in the rail footer, bottom-left just above the user name,
   summarising both kinds of pending update: stale instances and sites with stale artifacts.
3. The expanding rail menu should sit in a **scroll pane** so a long nav never pushes the footer off-screen.

## 2. Current state (verified 2026-09-14)

- Instance staleness = `DeploymentService.GetDeploymentComparisonAsync` re-flattens the instance
  (`validateScripts:false`) and compares `RevisionHash` with the `DeployedConfigSnapshot` (after the I-1
  List-value normalisation). Topology computes it per loaded page with bounded concurrency, off the
  15 s live timer, with a *Re-check staleness* button. There is **no aggregate** anywhere.
- Artifact deployment (`ArtifactDeploymentService`) builds one `DeployArtifactsCommand` per site and
  persists a `SystemArtifactDeploymentRecord` with a per-site status JSON, but **records no revision of
  what was sent**, so "are this site's artifacts current?" is currently unanswerable.
- The rail is the `ZB.MOM.WW.Theme` kit's `ThemeShell` (`nav.side-rail`, flex column; `.rail-foot`
  has `margin-top:auto`; `#theme-rail` is sticky `100vh` on ≥ lg). The nav items are direct children
  of `.side-rail`; nothing scrolls internally, so a long nav grows past the viewport.
- `SingleFlightMemo<T>` + `KpiSnapshotCache` already give the process-level, per-TTL, single-flight
  cache shape a polled aggregate needs.

## 3. Design

### 3.1 Site artifact revision (Commons + ConfigurationDatabase + DeploymentManager)

- `Site` gains two nullable columns: `ArtifactRevisionHash` (`string?`, max 100) and
  `ArtifactsDeployedAt` (`DateTimeOffset?`). Migration `AddSiteArtifactRevision`. Additive; a site that
  has never had artifacts deployed stays `null` = **Never deployed**.
- New `ArtifactRevisionHashService` (DeploymentManager) computes a deterministic SHA-256 over a
  canonical projection of a per-site `DeployArtifactsCommand`: every artifact class sorted by `Name`
  (ordinal), `DeploymentId`/timestamp excluded, alphabetically-declared hashable records, camelCase
  JSON, nulls omitted — the same determinism contract as `RevisionHashService`, pinned by a test.
  Data-connection configuration is plaintext in memory (EF value converter), so a no-op re-save that
  re-encrypts at rest does not change the hash.
- `ArtifactDeploymentService` stamps `ArtifactRevisionHash` + `ArtifactsDeployedAt` on the `Site` row
  **only for a site whose deploy succeeded** (both `DeployCoreAsync` and `RetryForSiteAsync`). A failed
  site keeps its previous stamp, so it keeps showing out of date. The stamp is written in the same
  `SaveChanges` as the deployment record where possible.
- `ArtifactDeploymentService.ComputeCurrentArtifactHashesAsync(sites)` returns `siteId → hash` for the
  *current* definitions, hoisting the global artifact queries once (same shape as `DeployCoreAsync`).
- **Transport does NOT carry the two columns.** They are environment-specific runtime state, exactly
  like imported instances landing `NotDeployed`; the round-trip guard exclusion list names them with
  that reason. An import that changes a site's data connections therefore makes the site read
  *out of date* until artifacts are redeployed — the correct outcome.

### 3.2 Pending-updates aggregate (DeploymentManager, cached in CentralUI)

- `DeploymentService.GetInstanceStalenessAsync(instanceIds)` → `IReadOnlyDictionary<int, bool?>`:
  one shared `FlattenSession` for the batch (template chains walked once, as `DeploySiteAsync` does),
  compares against a **projection read** of `(InstanceId, RevisionHash)` from `DeployedConfigSnapshot`
  (new `IDeploymentManagerRepository.GetDeployedRevisionHashesAsync()` — never the fat
  `ConfigurationJson` for the whole fleet). For a hash **mismatch only**, the full snapshot is read and
  the I-1 normalised deployed hash recomputed, so the aggregate agrees exactly with the Topology badge
  on old-form List snapshots. `null` = could not evaluate (flatten failed) — counted as *unknown*, never
  as stale.
- `PendingUpdatesEvaluator` (scoped, DeploymentManager) → `PendingUpdatesSnapshot`:
  `ComputedAt`, per site `SitePendingUpdates(SiteId, SiteIdentifier, SiteName, ArtifactState
  {NeverDeployed|Current|OutOfDate}, ArtifactsDeployedAt, DeployedInstanceCount, StaleInstanceCount,
  UnknownInstanceCount)`, plus totals `StaleInstanceCount` and `StaleArtifactSiteCount`. Instances are
  those with a deployed snapshot (the same gate Topology uses: `State != NotDeployed`).
- `IPendingUpdatesCache` / `PendingUpdatesCache` (CentralUI, **singleton**, mirrors `KpiSnapshotCache`):
  one `SingleFlightMemo<PendingUpdatesSnapshot>` with TTL `DeploymentManagerOptions.PendingUpdatesCacheTtl`
  (default 60 s, validated > 0), running the evaluator in its own DI scope. `GetAsync(forceRefresh)`.
  Consequence: however many circuits poll, the fleet is flattened at most once per TTL, and not at
  all when nobody is looking.
- Not in scope (register rows): a `deploy` CLI/`Health` KPI surface for the counts.
- **Unchanged-fleet short-circuit (Gitea #62, register row 124, owner decision (b) 2026-11-09).** Before
  the fleet pass the evaluator reads a change token = `IConfigGraphWatermarkReader` (ONE query:
  `MAX(RowVersion)` + `COUNT_BIG(*)` per table over the 18 input tables — Templates + their five member
  tables, Instances + their four override/binding tables, DataConnections, DeployedConfigSnapshots, Sites,
  SharedScripts, ExternalSystemDefinitions, ExternalSystemMethods, DatabaseConnectionDefinitions; migration
  `AddConfigGraphRowVersions`, list in `ConfigGraphRowVersions`) **plus** a SHA-256 stamp over the secret
  store's `ListAsync(includeDeleted: true)` metadata (name, revision, created/updated, tombstone, KEK id,
  content type, description). Equal to the token read before the last *clean* full evaluation → the
  previous snapshot is re-served (with a fresh `ComputedAt`). rowversion is database-wide and engine-bumped,
  so a peer central node's edit, a bundle import or an `ExecuteUpdate` all move it; the count catches a
  delete (which raises no rowversion). It is deliberately not the per-process template-graph watermark
  (MG-3). Safety net: every `PendingUpdatesFullEvaluationEvery`th evaluation (default 10 ≈ 10 min at the
  60 s TTL; `1` disables the short-circuit) is full regardless — it covers a same-KEK re-wrap (wrap
  envelope changes, revision does not) and any input table someone forgets to add (a SQL Server guard
  test fails if a repository read used by the evaluator touches an uncovered table). Always full: watermark
  unavailable (non-SQL-Server provider) or unreadable, secret listing fails, the previous evaluation could
  not compute a site's artifact hash (secret-store outage — re-serving it would pin a transient *Out of
  date*), a *Re-check* (`forceRefresh`), and the evaluation after a deploy completion. It never
  manufactures an answer — it only re-serves a real earlier one.

### 3.3 Sites page (Admin)

- Each site card shows an **Artifacts** badge next to the identifier: `Current` (light), `Out of date`
  (warning, `bi-exclamation-triangle`, tooltip = deployed-at UTC), `Never deployed` (secondary). Below
  it a muted line `N of M instances out of date` (link to `/deployment/topology`) when M > 0, since the
  snapshot already carries it. Badges match Topology's Bootstrap `.badge` convention (the kit's
  `StatusPill` is unused in this app).
- Header gains *Re-check* (forces `GetAsync(forceRefresh:true)`, disabled while running) and an
  *as of HH:mm:ss UTC* caption. A successful Deploy Artifacts (single or all) forces a refresh so the
  badge flips to Current immediately.
- The snapshot is loaded after the site list, never blocking it: cards render with a *checking…*
  placeholder until it arrives; a snapshot failure shows *unavailable* on the badge and logs.

### 3.4 Rail indicator (`PendingUpdatesIndicator`, MainLayout `RailFooter`, above `.rail-user`)

- Rendered only for a user holding **Deployer or Administrator** (the two roles that can act on it);
  hidden otherwise. Polls `IPendingUpdatesCache.GetAsync()` every 30 s through `PollGate` (cache TTL
  60 s ⇒ polling is cheap), disposes its timer with the circuit, renders via `InvokeAsync`.
- States: *Checking for updates…* (first load) · *Up to date* (muted, check icon) · **Pending updates**
  with a warning count pill and a breakdown line: `3 instances` (links to Topology when Deployer) ·
  `1 site` (links to `/admin/sites` when Administrator, plain text otherwise) · *Updates unavailable*
  (error, tooltip has the message). Tooltip on the block: *as of HH:mm UTC*.
- Site-scoped users see only their permitted sites' counts (`SiteScopeService`), consistent with
  Topology.

### 3.5 Scrollable nav

- `NavMenu.razor` wraps its items in `<div class="rail-scroll">`; `site.css` adds, ≥ lg only:
  `#theme-rail > .side-rail { height: 100%; }` (fill the sticky 100 vh rail so `.rail-foot`'s
  `margin-top:auto` actually pins) and `.rail-scroll { flex: 1 1 auto; min-height: 0; overflow-y: auto;
  overscroll-behavior: contain; }`. Below lg the rail is inline and scrolls with the page, unchanged.
  Kit untouched; a register row proposes upstreaming it into `ZB.MOM.WW.Theme` for the other consumers.

## 4. Tests

- Unit: hash determinism (order-insensitive, field-sensitive, alphabetical-declaration guard); stamping
  on success only; `GetInstanceStalenessAsync` (shared session used once, mismatch-only normalisation,
  null on flatten failure); evaluator totals; cache single-flight/TTL/force; bUnit for the indicator
  (all states, role gating, scope filter), Sites page (badges, re-check, refresh-after-deploy), NavMenu
  wrapper; Transport round-trip guard exclusions; migration snapshot.
- Rig: `docker/deploy.sh` (migration auto-applies), `docker/verify-pending-updates.sh` (CLI: site list
  shows `artifactRevisionHash` null → deploy artifacts → set; edit a shared script → central UI shows
  out of date; redeploy → current), plus a Playwright smoke for the indicator + Sites badge.

## 5. Operational notes

- Production/QA: the migration ships as a delta script (`dotnet ef migrations script
  AddAlarmMesReportable AddSiteArtifactRevision`). After upgrade every site reads **Never deployed**
  until artifacts are deployed once — deliberate; one *Deploy Artifacts to All Sites* clears it.
- Cost: one fleet flatten per `PendingUpdatesCacheTtl` while any Deployer/Admin circuit is open.