ScadaBridge/docs/plans/2026-06-18-m9-templates-authoring-design.md

# Design: M9 — Templates & Authoring (T22–T26, T28, T30–T32 + CLI cached-call Retry/Discard)

**Date:** 2026-06-18
**Status:** Approved (brainstorming session) — ready for writing-plans
**Milestone:** M9 of the system-completion roadmap (`docs/plans/2026-06-15-stillpending-completion-design.md` line 105)
**Branch:** `worktree-m9-templates-authoring` off `origin/main` @ `72aec3b4`
**Source backlog:** `stillpending.md` Tier 3 — "Templates / Data Connections / Triggers UI" + "Cached-call tracking"

## Goal

Deliver the in-scope authoring and templates backlog: make the template tree searchable and reorderable, let operators move and live-monitor data connections, surface multi-level inheritance + base-change staleness in the template editor, add an opt-in strict trigger-analysis mode, build schema-driven value entry (nested forms + Monaco hover/completion + a reusable `$ref` schema library), and put cached-call Retry/Discard on the CLI. One unified-outbox page item is explicitly deferred.

## Scope

### In scope (10 deliverables)
- **T22** — Template tree search/filter.
- **T23** — Folder sibling reorder + root-level context menu (menu-based; **no drag-drop**).
- **T24** — Move a data connection between sites.
- **T25** — Connection live-status indicators on the design page.
- **T26** — Base-template versioning *authoring*: multi-level inherited-member resolution in the editor + a read-only staleness banner.
- **T28** — Strict expression-trigger analysis *kind* (opt-in escalation).
- **T30** — Schema-driven nested value-entry forms.
- **T31** — Monaco JSON-Schema hover/completion on value-entry.
- **T32** — JSON Schema `$ref` resolver + a template-level schema library.
- **CLI** — `cached-call retry|discard` for site-local cached calls.

### Deferred (logged follow-ups, not in M9)
- **Unified notifications + site-calls outbox page** — the two data models diverge hard (enum vs string status lifecycles, offset vs keyset pagination, `string` vs strong-typed GUID ids, asymmetric provenance). A true union view-model is high-risk for marginal operator gain. Deferred; the CLI Retry/Discard ships instead.
- **Folder drag-drop** (HTML5 DnD via JS interop) — `[PERM]`-tagged; menu-based reorder delivers the capability without the Blazor-Server interop fragility.
- **T27** (promote-derived-to-base, cross-tenant libraries) and **T29** (WhileTrue alarm trigger) remain excluded per the roadmap.

## Locked decisions

- **D1 — T26 is authoring-only.** Instance flattening already re-walks the full inheritance chain fresh on every deploy (`TemplateResolver.BuildInheritanceChain` is arbitrary-depth; `CycleDetector` covers inheritance/composition/cross-graph). The only real gap is in the *editor*: it loads the immediate base only, derived templates carry stale `IsInherited` placeholder rows, and there is no staleness signal. M9 closes that with a **read-only** resolve + staleness banner. **No stored-row mutation, no `RefreshDerivedTemplate` command.**
- **D2 — T32 is fully in scope.** Build a template-level schema library (new entity + idempotent migration + repo) and a custom `$ref` resolver. **No new NuGet package** — `Directory.Packages.props` has no JSON-schema library and CLAUDE.md forbids adding one; everything uses `System.Text.Json` and extends the existing `InboundApiSchema` parser.
- **D3 — Unified outbox page deferred;** ship the CLI Retry/Discard from this cluster.
- **D4 — T23 is menu-based:** sibling Move-up/Move-down (uses the existing `TemplateFolder.SortOrder`) + a root-level context menu (New Folder / New Template at root) + completing the folder context menu. No drag-drop.
- **D5 — Move-connection is guarded.** A `MoveDataConnectionCommand` succeeds only when: (a) the target site exists; (b) no name collision with an existing connection at the target site; (c) **no `InstanceConnectionBinding` references the connection** (instances are site-scoped — a bound connection cannot leave its site without orphaning the binding). On block, return a clear error naming the blocking instances. Also re-point/validate name-based references (`TemplateNativeAlarmSource.ConnectionName`, `InstanceNativeAlarmSourceOverride.ConnectionNameOverride`) for collisions. Every move emits an audit-log row.
- **D6 — T25 reuses existing health transport.** Health already flows DCL → `ISiteHealthCollector.UpdateConnectionHealth` → `SiteHealthReport.DataConnectionStatuses` (name→`ConnectionHealth`) → `ICentralHealthAggregator` → the Health page renders badges. M9 surfaces the same data on the *design* `DataConnections` page (per-node badge + ~10s poll). No new transport, no SignalR.
- **D7 — T28 is an opt-in escalation layer.** Expression triggers already get a real Roslyn semantic compile + forbidden-API + undefined-attribute analysis that **blocks deploy** (delivered in M2/M3). T28 adds a per-trigger `AnalysisKind` (default **Advisory** = today's behavior; **Strict** escalates the currently-advisory findings — blank expression, ambiguous coercion — to deploy-blocking errors). The increment is the toggle + the escalation branch; implementation right-sizes after confirming exact current behavior.

## Current-state map (reconnaissance evidence)

### Cluster A — Template tree UI
- `CentralUI/Components/Shared/TreeView.razor` — generic tree; external-filter model (R8), `ContextMenu` render-fragment (R15); **no built-in DnD**.
- `CentralUI/Components/Shared/TemplateFolderTree.razor:68` — already exposes a `Filter` parameter with recursive substring match + ancestor auto-expand (`ApplyFilter`/`CopyMatching`).
- `CentralUI/Components/Pages/Design/Templates.razor` — uses `TemplateFolderTree` but **wires no search box**; folder context menu present (New Folder/Template, Rename, Move…, Delete); `MoveFolderDialog.razor` exists.
- `Commons/Entities/Templates/TemplateFolder.cs:12` — has `SortOrder`. `TemplateEngine/Services/TemplateFolderService.cs` — Create/Rename/Move (cycle + collision checks)/Delete; **no sort-order update method**.
- `Commons/Messages/Management/TemplateFolderCommands.cs` — Create/Move/Rename/Delete commands; **no reorder command**.

### Cluster B — Data connections
- `Commons/Entities/Sites/DataConnection.cs:8` — `SiteId` FK. `Commons/Messages/Management/DataConnectionCommands.cs` — Create/Update/Delete; `Update` does **not** change `SiteId`; **no move command**.
- `CentralUI/Components/Pages/Design/DataConnectionForm.razor` — site locked after creation. `DataConnections.razor` — site→connection tree, search box present, Edit/Delete actions; **no move, no health badge**.
- FK/blockers for move: `Instances/InstanceConnectionBinding.cs:12` (`DataConnectionId` FK), `Templates/TemplateNativeAlarmSource.cs:21` (`ConnectionName`, name-based), `Instances/InstanceNativeAlarmSourceOverride.cs:22` (`ConnectionNameOverride`, name-based).
- Health: `HealthMonitoring/ISiteHealthCollector.cs:58`, `Commons/Messages/Health/SiteHealthReport.cs:10` (`DataConnectionStatuses`), `ICentralHealthAggregator` (`GetSiteState`), `CentralUI/.../Monitoring/Health.razor` (existing badge render + `GetConnectionHealthBadge`).

### Cluster C — Inheritance authoring
- `Commons/Entities/Templates/Template.cs` — `ParentTemplateId` (inheritance), `IsDerived` + `OwnerCompositionId` (composition-materialized slots). Members carry `IsInherited` + `LockedInDerived` flags (`TemplateAttribute`/`TemplateAlarm`/`TemplateScript`/`TemplateNativeAlarmSource`).
- `TemplateEngine/TemplateResolver.cs:119` — `BuildInheritanceChain` walks arbitrary depth (root-first), cycle-guarded. `TemplateEngine/Flattening/FlatteningService.cs` — derived wins, `IsInherited` placeholders skip in favor of the live base value. `CycleDetector.cs` — inheritance/composition/cross-graph checks on save.
- `TemplateEngine/Flattening/RevisionHashService.cs` — deterministic SHA-256 of flattened config (already used for staleness in Transport/M8 via `IStaleInstanceProbe`).
- `CentralUI/Components/Pages/Design/TemplateEdit.razor:58` — loads only the **immediate** base (`_baseTemplate`, `_baseAttributesByName`, …); no multi-level resolution, no staleness banner.
- `ManagementService/ManagementActor.cs:178` — template command block; **no resolve/update-derived command**.

### Cluster D — Triggers + schema entry
- `TemplateEngine/Validation/ValidationService.cs:263` (`CheckExpressionTrigger`) — real Roslyn compile + forbidden-API + undefined-attribute checks; blank expression = warning; errors block deploy. Separate error/warning lists make selective escalation a clean seam.
- JSON Schema is canonical storage (migration `20260512211204_MigrateParametersToJsonSchema`); `Commons/Types/InboundApi/InboundApiSchema.cs` (`Parse`/`ParseSchema` recursive, depth-capped; `Validate`). `CentralUI/Components/Shared/SchemaBuilder.razor` authors schemas; `ParameterValueForm.razor:52` renders scalars but falls back to a **JSON textarea** for object/list. Monaco already integrated (`MonacoEditor.razor`). **No `$ref` resolution anywhere; no schema-library entity.** `Directory.Packages.props` — no JSON-schema package (System.Text.Json only).

### Cluster E — CLI cached-call Retry/Discard
- Backend relay fully exists: `ManagementActor.cs:220,380` (`RetryParkedMessageCommand`/`DiscardParkedMessageCommand`, Deployer-gated) → `SiteCallAuditActor.cs:877,909` (`HandleRetrySiteCall`/`HandleDiscardSiteCall` → `RetryParkedOperation`/`DiscardParkedOperation` relay) → site. Central UI Site Calls page already uses it.
- CLI pattern: `CLI/Commands/CommandHelpers.cs:34` (`ExecuteCommandAsync` → `ManagementHttpClient.SendCommandAsync`), command-name via `ManagementCommandRegistry.GetCommandName`. Model on `NotificationCommands.cs`. **No cached-call command group today** — must verify the registry maps the two commands.

## Design by feature

### T22 — Template tree search (small)
Add a search `<input>` to `Templates.razor`, bound to a local field, passed to `TemplateFolderTree.Filter`. The recursive filter + auto-expand already exist. UI-only — no service/entity/command change. Clear-filter restores the full tree and prior expansion state.

### T23 — Folder reorder + context menus (standard)
- `TemplateFolderService.ReorderFolderAsync(folderId, direction, user)` (or `MoveUp`/`MoveDown`) — swap `SortOrder` with the adjacent sibling under the same parent; no-op at the ends. New `ReorderTemplateFolderCommand` + ManagementActor handler (Designer-gated, matching the other folder commands).
- Sibling loads ordered by `SortOrder` (then Name) everywhere the folder tree is built.
- `Templates.razor` — Move-up/Move-down items in the folder context menu; a **root-level** context menu (right-click empty/root → New Folder, New Template at root). Complete any missing folder-menu items.

### T24 — Move connection between sites (high-risk)
- `MoveDataConnectionCommand(DataConnectionId, TargetSiteId)` + ManagementActor `HandleMoveDataConnection` (Designer-gated).
- Guards (D5), all server-side: target site exists; no name collision at target; **reject if any `InstanceConnectionBinding` references the connection** with an error naming blockers; validate name-based native-alarm-source references won't collide/orphan at the target.
- Persist via the existing `ISiteRepository.UpdateDataConnectionAsync` (sets `SiteId`); emit an audit row.
- UI: a "Move to Site…" action + `MoveDataConnectionDialog` (target-site picker, error surface) on `DataConnections.razor`.

### T25 — Connection live-status (standard)
- A central-side query (extend the health query service or inject `ICentralHealthAggregator`) returning a `connectionId → ConnectionHealth` map for a site: read the latest `SiteHealthReport.DataConnectionStatuses`, resolve names→ids via the repo.
- `DataConnections.razor` — render a health badge per connection node (reuse `GetConnectionHealthBadge`/`AlarmStateBadges`-style classes), refresh on a ~10s poll timer (mirror the Health page). Register the injected service in the existing `DataConnections` bUnit fixtures.

### T26 — Inheritance authoring resolve + staleness banner (high-risk)
- A resolve service/method that, given a derived or child template, walks the full inheritance chain (`BuildInheritanceChain`) and returns the **effective inherited member set** — including base members added *after* the derived template was created, across ≥2 inheritance levels — annotated per member with origin (own override / inherited-from-X / locked).
- A new read-only query command (e.g. `GetResolvedTemplateMembersCommand`) + ManagementActor handler returning that set (plus a staleness summary).
- `TemplateEdit.razor` renders the **full** resolved inherited set (not just the immediate base) and a read-only banner when the stored derived rows differ from the freshly-resolved chain ("Base changed — N inherited members differ"). **No mutation** — flattening at deploy is already correct; the banner is informational and the editor's own override actions are unchanged.

### T28 — Strict expression-trigger kind (small)
- Add `AnalysisKind` (Advisory default / Strict) to the trigger config (carried in the existing `TriggerConfiguration` JSON or a small dedicated field — chosen to stay additive to the flattened model and avoid a migration if feasible).
- `CheckExpressionTrigger` — when Strict, promote the currently-advisory findings to errors (deploy-blocking); Advisory preserves today's behavior exactly.
- Trigger editor selector (alarm/script trigger UI) + CLI flag (`--trigger-kind`/`--strict`). Right-size after confirming exact current advisory set.

### T30 — Schema-driven nested forms (standard)
- Extend `ParameterValueForm.razor` to recursively render object fields and list items as typed inputs (replacing the JSON textarea for object/list), driven by the parsed `InboundApiSchema` (including `$ref`-resolved schemas from T32). Per-field validation via `InboundApiSchema.Validate`; collect to canonical JSON. Re-register in existing fixtures.

### T31 — Monaco hover/completion (standard)
- Feed the resolved JSON Schema to the existing Monaco editor's JSON language config so the value-entry JSON surface gets schema-driven hover + completion. Reuses `MonacoEditor.razor`; no new package (Monaco's built-in JSON schema support).

### T32 — `$ref` resolver + template-level schema library (high-risk; build first)
- New `SharedSchema` entity (Id, Name unique, optional scope, `SchemaJson`) + EF config + **idempotent** migration + repository.
- Custom `$ref` resolver in `InboundApiSchema.Parse` (resolve `{"$ref":"lib:Name"}`-style pointers to library entries; depth/cycle-guarded, System.Text.Json only).
- ManagementActor CRUD commands (Designer-gated) + a Central UI schema-library page (reuse `SchemaBuilder`).
- Deploy-time validation that every `$ref` target exists (block on dangling ref), wired into the existing validation pipeline.

### CLI — cached-call Retry/Discard (small)
- New `CachedCallCommands.cs` (`cached-call retry|discard --site-id … --tracked-operation-id …`) calling the existing Deployer-gated `RetryParkedMessageCommand`/`DiscardParkedMessageCommand` via `CommandHelpers.ExecuteCommandAsync`. **Verify `ManagementCommandRegistry` maps both command names** (the CLI's `GetCommandName` depends on it). Update `CLI/README.md` + `Component-CLI.md`.

## Dependencies & wave plan

Execute **subagent-driven** in the `worktree-m9-templates-authoring` worktree. Implementers do **not** create worktrees; commit **pathspec** form (`-m` before `--`, never `git add -A`); keep ≤2–3 concurrent committers with a post-wave HEAD-presence check; targeted builds/tests per task; full-solution build + docker rebuild only at integration.

- **Wave 1 (low-risk, parallel — disjoint files):** T22 (`Templates.razor`) ‖ CLI Retry/Discard (CLI) ‖ T28 (Template Engine validation + trigger editor).
- **Wave 2:** T23 (`Templates.razor`, after T22 — same file) ‖ T25 (`DataConnections.razor`, additive).
- **Wave 3:** T24 (`DataConnections.razor`, after T25 — same file) ‖ T32 foundation (entity + migration + `$ref` resolver — Commons/ConfigDB/ManagementActor).
- **Wave 4:** T30 ‖ T31 (consume the resolver) ‖ T26 (`TemplateEdit.razor` + resolve service).
- **Wave 5 — integration.**

Classifications: T24, T26, T32, integration = **high-risk**; T23, T25, T30, T31 = **standard**; T22, T28, CLI = **small**.

## Integration (first-class verification phase)

Per `integration-catches-cross-cutting-gaps`:
- Full-solution `dotnet build ZB.MOM.WW.ScadaBridge.slnx`; **EF model-drift check** for the new `SharedSchema` entity (the M2-pre `PendingModelChangesWarning` lesson — idempotent migration, no pending changes).
- **Trace every new ManagementActor command end-to-end** through the registry + handler routing: `ReorderTemplateFolderCommand`, `MoveDataConnectionCommand`, the `GetResolvedTemplateMembersCommand`, the schema-library CRUD commands, and the CLI's two cached-call commands (confirm `ManagementCommandRegistry` mappings so the CLI resolves names).
- **Re-run the full bUnit suites of every shared component touched** (TreeView, `TemplateFolderTree`, `TemplateEdit`, `DataConnections`, `ParameterValueForm`, `SchemaBuilder`) — register substitutes for any newly-injected service in their existing fixtures.
- `bash docker/deploy.sh` rebuild + `/health/ready` smoke on central-a/central-b/LB; Playwright coverage for the new UI surfaces (search, reorder menu, move dialog, connection health badge, schema library, schema-driven form).

## Testing strategy

- **T22:** filter unit/bUnit (match, auto-expand, clear).
- **T23:** reorder swap (ends no-op, ordering persists); root-menu render.
- **T24:** guard tests — binding-blocks (error names instances), name-collision-blocks, success path; audit row asserted.
- **T25:** health map query (name→id resolution, missing report), badge render.
- **T26:** multi-level chain (A→B→C), base member added after derive shows in editor, locked member display, staleness banner true/false; adversarial chain/composition-derived cases.
- **T28:** Advisory preserves current pass/fail; Strict escalates each advisory finding to a deploy-block.
- **T30:** nested object/list render + per-field validation (incl. `$ref`-resolved schema).
- **T31:** schema fed to Monaco (smoke/bUnit where feasible).
- **T32:** `$ref` resolution (valid, dangling→deploy-block, depth/cycle guard); migration idempotency; CRUD round-trip.
- **CLI:** command-name registry mapping; retry/discard happy-path + not-parked/unreachable mapping.

## Risks

- **T32 migration ↔ EF model drift** — idempotent migration + a model-drift assertion in integration.
- **T26 resolution semantics** on multi-level + locked + composition-derived templates — adversarial chain tests; keep it strictly read-only to avoid any deploy-path regression.
- **T28 may be near-complete** — confirm the exact current advisory set before sizing; the deliverable is the toggle + escalation, not re-building analysis.
- **Shared-component injection regressions** (T25/T26/T30 inject into reused components) — the integration wave re-runs each touched component's full fixture suite.
- **CLI registry gap** — if `RetryParkedMessageCommand`/`DiscardParkedMessageCommand` aren't registered for name resolution, the CLI call fails; verified in Wave 1 and re-asserted at integration.

## Next step

Hand off to the writing-plans skill to produce the bite-sized, per-task implementation plan and `.tasks.json`, then execute subagent-driven wave-by-wave. Finish via finishing-a-development-branch (FF-merge to main + push, no force; docker rebuild to match main).