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:
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user