docs: arch-review remediation — component docs sweep, execution log, residuals register

Final consistency sweep per plan §6: verified component docs against shipped
WP1-WP3 + adversarial-review-fix state, corrected drift found in SiteRuntime
(recursion-exempt run cap, stale ScriptExecutionActor/AlarmExecutionActor
references), TemplateEngine (BundleImporter watermark path), DeploymentManager
(phase-2 PendingDeployment staging), CentralUI (shared KPI cache, dedup'd alarm
poll, render coalescing), StoreAndForward (rate-limited drop logging), and
ConfigurationDatabase (documented DbContext-pooling non-adoption). Updated the
docs/components/ developer-reference set (SiteRuntime, SiteEventLogging,
InboundAPI) to drop the deleted per-run actor classes. Amended one known-issue
for the superseding MaxBatchSize:64 read-page pin. Added CLAUDE.md bullets for
stream graceful-completion reconnect, the required site audit DB path, honest
CLI HTTP timeouts, bulk DeploySiteAsync, and LocalDb 0.2.1. New execution log
records the phase→commit map, gate results, adversarial-review tally, the
three test-flake root causes, and the nine-item residuals register.
This commit is contained in:
Joseph Doherty
2026-08-15 01:30:59 -04:00
parent a9ca51e008
commit 7804fe7958
12 changed files with 244 additions and 49 deletions
+25 -5
View File
@@ -152,11 +152,19 @@ which still collapses the repeated composed-chain loads inside a single instance
flatten.
Cache validity is decided by **`ITemplateGraphWatermark`**, a process-wide set of
monotonic counters bumped by the configuration-database unit of work — the only
place every template-graph writer funnels through (`TemplateService`, the
`ManagementActor` native-alarm-source handlers, and the Transport bundle importer
all commit via the same `SaveChangesAsync`, and the change tracker is inspected
pre-commit to attribute each change to its owning template or instance):
monotonic counters. `TemplateService` and the `ManagementActor` native-alarm-source
handlers bump it via `TemplateEngineRepository.SaveChangesAsync`'s change-tracker
inspection, which attributes each pending change to its owning template or
instance pre-commit. The Transport bundle importer (`BundleImporter`) commits
through the raw `DbContext` instead — bypassing that repository — so it calls
`ITemplateGraphWatermark.BumpAll()` itself, once per import: after commit on
success, after rollback on failure (a bundle import can touch templates,
instances, and connections in one transaction, so a scoped bump isn't
worthwhile). A data connection edit (`SiteRepository.SaveChangesAsync`) also bumps — via `BumpAll()`,
since a connection has no owning template — because `Protocol`/`PrimaryConfiguration`/
`BackupConfiguration`/`FailoverRetryCount` are revision-hash inputs (review fix, commit
`e0e4b246`, F2c). All three writers converge on the same watermark, so a cached flatten
still invalidates correctly regardless of which one changed the graph:
- a memoised **template** is keyed on `(id, template version)`;
- a memoised **chain** is valid only while BOTH the graph's `StructureVersion`
@@ -225,6 +233,18 @@ A derived template stores `IsInherited` **placeholder rows** mirroring every mem
Both delegate to one **order-independent reconcile** that compares a template's stored inherited rows against the inheritance resolver's effective set (the same precedence + HiLo merge the editor preview and deploy use) and only ever touches `IsInherited` placeholder rows — never an authored override (`IsInherited == false`). Because the resolver ignores placeholder rows when picking winners, reconciling one template never changes what another resolves, so the operation needs no particular ordering. The effective value mirrored into each placeholder matches the staleness comparison key per member type, so after a reconcile the "base changed" banner clears. Reconcile is best-effort housekeeping for the *stored authoring rows*: a deploy always re-resolves the chain fresh regardless, so a not-yet-resynced template still deploys correctly.
### Slim List Projections (WP2.5)
The `ListTemplates` management command (backing the CLI `template list` and the Central UI
template tree) previously materialised every template's full child graph — attributes, alarms,
script bodies, compositions, native alarm sources — to page it in memory and discard all but one
page. `ITemplateEngineRepository.GetTemplateSummariesAsync(skip, take)` instead pages **in the
database** against `TemplateSummary`, a row-shaped projection (id, name, description, parent/folder
ids, derived flag) with child collections reduced to **counts** — the only thing a list surface
renders. `TemplateSummary.MaxPageSize` (1000) mirrors the existing in-memory page clamp so DB-side
paging cannot be used to pull an unbounded result set. Additive-only message-contract evolution,
same rule as other Commons message types.
## Diff Calculation
The Template Engine can compare: