Apply Codex review findings across all 17 components
Template Engine: add composed member addressing (path-qualified canonical names), override granularity per entity type, semantic validation (call targets, arg types), graph acyclicity enforcement, revision hashes for flattened configs. Deployment Manager: add deployment ID + idempotency, per-instance operation lock covering all mutating commands, state transition matrix, site-side apply atomicity (all-or-nothing), artifact version compatibility policy. Site Runtime: add script trust model (forbidden APIs, execution timeout, constrained compilation), concurrency/serialization rules (Instance Actor serializes mutations), site-wide stream backpressure (per-subscriber buffering, fire-and-forget publish). Communication: add application-level correlation IDs for protocol safety beyond Akka.NET transport guarantees. External System Gateway: add 408/429 as transient errors, CachedCall idempotency note, dedicated dispatcher for blocking I/O isolation. Health Monitoring: add monotonic sequence numbers to prevent stale report overwrites. Security: require LDAPS/StartTLS for LDAP connections. Central UI: add failover behavior (SignalR reconnect, JWT survives, shared Data Protection keys, load balancer readiness). Cluster Infrastructure: add down-if-alone=on for safe singleton ownership. Site Event Logging: clarify active-node-only logging (no replication), add 1GB storage cap with oldest-first purge. Host: add readiness gating (health check endpoint, no traffic until operational). Commons: add message contract versioning policy (additive-only evolution). Configuration Database: add optimistic concurrency on deployment status records.
This commit is contained in:
@@ -64,6 +64,23 @@ Central cluster only. Sites receive flattened output and have no awareness of te
|
||||
- Stored in the configuration database.
|
||||
- Used for filtering/organizing instances in the UI.
|
||||
|
||||
## Composed Member Addressing
|
||||
|
||||
When a template composes a feature module, members from that module are addressed using a **path-qualified canonical name**: `[ModuleInstanceName].[MemberName]`. For nested compositions, the path extends: `[OuterModule].[InnerModule].[MemberName]`.
|
||||
|
||||
- All internal references (triggers, scripts, diffs, stream topics, UI display) use canonical names.
|
||||
- The composing template's own members (not from a module) have no prefix — they are top-level names.
|
||||
- Naming collision detection operates on canonical names, so two modules can define the same member name as long as their module instance names differ.
|
||||
|
||||
## Override Granularity
|
||||
|
||||
Override and lock rules apply per entity type at the following granularity:
|
||||
|
||||
- **Attributes**: Value and Description are overridable. Data Type and Data Source Reference are fixed by the defining level. Lock applies to the entire attribute (when locked, no fields can be overridden).
|
||||
- **Alarms**: Priority Level, Trigger Definition (thresholds/ranges/rates), Description, and On-Trigger Script reference are overridable. Name and Trigger Type (Value Match vs. Range vs. Rate of Change) are fixed. Lock applies to the entire alarm.
|
||||
- **Scripts**: C# source code, Trigger configuration, minimum time between runs, and parameter/return definitions are overridable. Name is fixed. Lock applies to the entire script.
|
||||
- **Composed module members**: A composing template or child template can override non-locked members inside a composed module using the canonical path-qualified name.
|
||||
|
||||
## Naming Collision Detection
|
||||
|
||||
When a template composes two or more feature modules, the system must check for naming collisions across:
|
||||
@@ -104,6 +121,30 @@ Before a deployment is sent to a site, the Template Engine performs comprehensiv
|
||||
- **Data connection binding completeness**: Every attribute with a data source reference has a data connection binding assigned on the instance, and the bound data connection name exists as a defined connection at the instance's site.
|
||||
- **Exception**: Validation does **not** verify that data source relative paths resolve to real tags on physical devices — that is a runtime concern.
|
||||
|
||||
### Semantic Validation
|
||||
|
||||
Beyond compilation, the Template Engine performs static semantic checks:
|
||||
|
||||
- **Script call targets**: `Instance.CallScript()` and `Scripts.CallShared()` targets must reference scripts that exist in the flattened configuration or shared script library.
|
||||
- **Argument compatibility**: Parameter count and data types at call sites must match the target script's parameter definitions.
|
||||
- **Return type compatibility**: If a script call's return value is used, the return type definition must match the caller's expectations.
|
||||
- **Trigger operand types**: Alarm triggers and script conditional triggers must reference attributes with compatible data types (e.g., Range Violation requires numeric attributes).
|
||||
|
||||
### Graph Acyclicity
|
||||
|
||||
The Template Engine enforces that inheritance and composition graphs are **acyclic**:
|
||||
|
||||
- A template cannot inherit from itself or from any descendant in its inheritance chain.
|
||||
- A template cannot compose itself or any ancestor/descendant that would create a circular composition.
|
||||
- These checks are performed on save.
|
||||
|
||||
### Flattened Configuration Revision
|
||||
|
||||
Each flattened configuration output includes a **revision hash** (computed from the resolved content). This hash is used for:
|
||||
|
||||
- Staleness detection: comparing the deployed revision to the current template-derived revision without a full diff.
|
||||
- Diff correlation: ensuring diffs are computed against a consistent baseline.
|
||||
|
||||
### On-Demand Validation
|
||||
|
||||
The same validation logic is available to Design users in the Central UI without triggering a deployment. This allows template authors to check their work for errors during authoring.
|
||||
|
||||
Reference in New Issue
Block a user