docs: native alarm ingestion across component docs + CLAUDE.md

docs/requirements/Component-TemplateEngine.md

@@ -53,6 +53,13 @@ Central cluster only. Sites receive flattened output and have no awareness of te
 - Trigger Definition: Value Match, Range Violation, or Rate of Change.
 - Optional On-Trigger Script reference.
 
+### Native Alarm Source (`TemplateNativeAlarmSource`)
+- A read-only binding that mirrors **native alarms** raised by an upstream system — OPC UA Alarms & Conditions or the MxAccess Gateway — rather than alarms evaluated by the Site Runtime from attribute values.
+- Fields: Name, Description *(optional)*, ConnectionName (the data connection that carries the native alarms), SourceReference (a raw connection address — an OPC UA `SourceNode` nodeId, or an MxAccess object/area), ConditionFilter *(optional — when null, mirror **all** conditions under the source)*, and the standard locking flags (`IsLocked`, `IsInherited`, `LockedInDerived`).
+- `SourceReference` is a **raw connection address**, not a relative attribute path — the Template Engine does not interpret or rewrite it (contrast with an attribute's `DataSourceReference`).
+- Defined on a template as a first-class member via `Template.NativeAlarmSources`.
+- Resolved native alarm sources drive the Site Runtime's **NativeAlarmActor** (see Interactions); the Template Engine only models and flattens them.
+
 ### Script (Template-Level)
 - Name, Lock Flag, C# source code.
 - Trigger configuration: Interval, Value Change, Conditional, Expression, or invoked by alarm/other script. Conditional and Expression triggers also carry a fire mode — **OnTrue** (fire as the condition becomes true) or **WhileTrue** (re-fire on a timer while it stays true).
@@ -64,6 +71,7 @@ Central cluster only. Sites receive flattened output and have no awareness of te
 - Associated with a specific template and a specific site.
 - Assigned to an area within the site.
 - Can override non-locked attribute values (no adding/removing attributes).
+- Can override non-locked native alarm source bindings via `Instance.NativeAlarmSourceOverrides` (see Override Granularity) — no adding/removing sources.
 - Bound to data connections at instance creation — **per-attribute binding** where each attribute with a data source reference individually selects its data connection.
 - Can be in **enabled** or **disabled** state.
 - Can be **deleted** — deletion is blocked if the site is unreachable.
@@ -99,6 +107,7 @@ Override and lock rules apply per entity type at the following granularity:
 
 - **Attributes**: Value and Description are overridable. Data Type is fixed by the defining level. `DataSourceReference` on a template attribute defines the **default** physical address for that attribute. Instances may override per attribute via `InstanceConnectionBinding.DataSourceReferenceOverride`; the override replaces the template default at flattening time. When the override is null (the default), the template value is used. 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.
+- **Native alarm sources**: An instance overrides a non-locked source via `InstanceNativeAlarmSourceOverride`, keyed by `SourceCanonicalName`. `ConnectionNameOverride`, `SourceReferenceOverride`, and `ConditionFilterOverride` are individually overridable — each is applied only when non-null; a null field **keeps the inherited value**. Name is fixed. Lock applies to the entire source.
 - **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.
 
@@ -122,6 +131,14 @@ When an instance is deployed, the Template Engine resolves the full configuratio
 5. Resolve data connection bindings — replace connection name references with concrete connection details from the site.
 6. Output a flat structure: list of attributes with resolved values and data source addresses, list of alarms with resolved trigger definitions, list of scripts with resolved code and triggers.
 
+### Native Alarm Source Resolution
+
+The `FlatteningService` resolves native alarm sources alongside alarms, emitting a `ResolvedNativeAlarmSource` (CanonicalName, ConnectionName, SourceReference, ConditionFilter *(optional)*, and `Source` ∈ `Template` | `Inherited` | `Composed` | `Override`) for each. The resolved set is attached to `FlattenedConfiguration.NativeAlarmSources`.
+
+- **Inheritance**: resolution walks the chain base → derived; a derived-level source wins over the base unless the base level locked it.
+- **Composition**: a composed module's sources are path-qualified to the canonical name `[ModuleInstanceName].[Name]`, subject to the same naming-collision checks as other members. Because `SourceReference` is a raw connection address (not an attribute path), composition performs **no attribute-reference rewriting** on it.
+- **Instance overrides**: `InstanceNativeAlarmSourceOverride` applies its non-null fields (`ConnectionNameOverride`, `SourceReferenceOverride`, `ConditionFilterOverride`) over the inherited/composed result and sets `Source = Override`.
+
 ## Diff Calculation
 
 The Template Engine can compare:
@@ -150,6 +167,7 @@ Beyond compilation, the Template Engine performs static semantic checks:
 - **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).
+- **Native alarm sources** (`ValidationCategory.NativeAlarmSourceInvalid`): `SemanticValidator.Validate` flags a `ResolvedNativeAlarmSource` when its `SourceReference` is empty, its `ConnectionName` is empty, or — when the caller supplies the alarm-capable connection set — its connection is unknown or not alarm-capable (protocol ∉ {`OpcUa`, `MxGateway`}). The alarm-capable connection set is an **optional, additive third parameter** to `Validate`; the empty-field checks always run, and the connection-binding check runs only when the set is provided.
 
 ### Graph Acyclicity
 
@@ -185,5 +203,6 @@ For shared scripts, pre-compilation validation is performed before deployment. S
 ## Interactions
 
 - **Deployment Manager**: Requests flattened configurations, diffs, and validation results from the Template Engine.
-- **Central UI**: Provides the data model for template authoring, instance management, and on-demand validation.
+- **Central UI**: Provides the data model for template authoring, instance management, and on-demand validation. Native alarm source CRUD (template-level definitions and instance-level overrides) is exposed via the Management Service / CLI / Central UI alongside attributes and alarms.
+- **Site Runtime (#3)**: Consumes each `ResolvedNativeAlarmSource` in the flattened configuration to drive its **NativeAlarmActor**, which mirrors the native OPC UA A&C / MxAccess Gateway alarms identified by the resolved connection, source reference, and condition filter.
 - **Transport (#24)**: Reads templates, attributes, alarms, scripts, and composition relationships for bundle export; writes the same via repositories during bundle import.