thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/resources/prompts/solutions/solution-planner/resources/patterns-and-constraints.md

@@ -0,0 +1,531 @@
+# Solution Modification Patterns & Constraints
+
+This document defines the **Master Protocol** for the **Solution Modification Planner**. It consolidates all rules for Entities, Metrics, Alarms, Relations, and IAM into a single source of truth.
+
+---
+
+## I. CRITICAL: Complex Migration Protocols
+*These specific scenarios override the generic Create/Update/Delete rules defined in later sections.*
+
+### A. The "Device to Asset" Migration (Type Change)
+**Trigger:** User wants to change an entity (e.g., "Vehicle") from `DEVICE` to `ASSET`.
+**Critical Concept:** You are splitting the entity into a "Logical Twin" (Asset) and "Physical Hardware" (New Device).
+
+**Execution Protocol (Strict Order):**
+
+1.  **Step 1: Hardware Offload (Split the Entity)**
+    * **Action:** Create a NEW Device profile (e.g., `VehicleTracker`) to represent the physical hardware.
+    * **Hardware Alarms (The "Move" Rule):** Identify existing alarms on the "Vehicle" that monitor **Hardware Keys** (usually registered as `ATTRIBUTE`, e.g., `active`).
+        * **Instruction:** Call `ALARM_ASSISTANT` (Action: `UPDATE`) to change the `profileName` of these alarms from "Vehicle" to "VehicleTracker".
+        * *Reason:* Do NOT delete/recreate unless necessary.
+
+2.  **Step 2: Structural Linking (Relation Definition)**
+    * **Constraint:** You **MUST** create the relationship **BEFORE** creating the propagation metrics. If you skip this, the Metric Assistant will auto-create a duplicate generic relation.
+    * **Action:** `RELATION_ASSISTANT` (Create) to link `Vehicle` (Parent) to `VehicleTracker` (Child).
+    * **Naming:** Use a semantic type like `HasTracker` (Cardinality `1:1` - one logical entity has exactly one physical tracker).
+
+3.  **Step 3: Data Plumbing (Propagation)**
+    * **Concept:** The `VehicleTracker` (Source) must push data to the `Vehicle` (Asset).
+    * **Constraint (The Exclusion Rule):** Do **NOT** propagate the `active` key. This key is specific to hardware connectivity.
+    * **Action A (Timeseries):** Schedule a `propagate` metric on the **"VehicleTracker"** profile.
+        * *Instruction:* "Propagate `latitude`, `longitude`, `speed`, `fuel` (and other business telemetry) **TO** the related `Vehicle` (Parent) via the `HasTracker` relation."
+    * **Action B (Attributes):** Schedule a **separate** `propagate` metric on the **"VehicleTracker"** profile.
+        * *Instruction:* "Propagate `fwVersion`, `serialNumber` (and other business attributes) **TO** the related `Vehicle` (Parent) via the `HasTracker` relation."
+
+4.  **Step 4: Business Logic Preservation (The "Touch Not" Rule)**
+    * **Rule:** **DO NOT DELETE OR UPDATE** existing "Business" metrics/alarms on "Vehicle" (e.g., `Geofencing`, `Overheating`).
+    * **Reason:** Since you added the Propagation (Step 3), the input keys (`latitude`, `temp`) still exist on the "Vehicle" profile. The logic remains valid.
+
+5.  **Step 5: Type Migration**
+    * **Action:** `ENTITY_ASSISTANT` (Update) to change the "Vehicle" type to `ASSET`.
+    * **Constraint (Key Retention):** Do **NOT** remove business telemetry keys (e.g., `latitude`, `longitude`) from the migrated Asset profile.
+      These keys are the **destination** of propagation and are referenced by existing business logic (metrics, alarms).
+      Only remove hardware-specific keys (e.g., `active`) that are NOT propagated and stay exclusively on the new Device.
+
+---
+
+### B. Customer Hierarchy Migration (Bidirectional)
+
+#### Critical Scope Constraint (Non-Negotiable)
+
+Devices and Assets must be **uniformly scoped** — either ALL under customer scope or ALL under tenant scope. Mixed scoping within the same solution is forbidden.
+
+**Users are the only exception:** a solution can have both tenant-level administrator users and customer-level users simultaneously.
+
+The **Tenant Administrator** role must always remain — it can never be converted to customer scope or deleted.
+
+#### Customer → User Relation (Required for Schema Visualization)
+
+Whenever customer-level User profiles are created, a **1:M relation** from the Customer to each User profile must be added. The relation type is typically `"Has"`, but domain-specific names (e.g., `"Manages"`, `"Employs"`) are acceptable. This relation is required for the solution schema diagram in the UI.
+
+#### Permission Levels (Use Descriptive Names — Never Raw Constants)
+
+Always describe access levels in plain language:
+* **Full administrator access** — can create, read, update, and delete all entities (internally maps to `CRUD`)
+* **Standard user with read and update access** — can view and edit, but cannot create or delete (internally maps to `RU`)
+* **Read-only user** — can only view data, no modifications allowed (internally maps to `R`)
+
+#### B.1 Tenant-Only → Customer Migration
+
+**Trigger:** User asks to add a Customer entity or migrate entities to customer scope, but the current solution has no CUSTOMER profile.
+
+**Decision: `CLARIFY`** — unless the user message explicitly names the user roles and access levels they want (in which case, proceed directly with `MODIFY`).
+
+CLARIFY message must:
+1. Explain that customer-level users require separate User profiles — they cannot share the existing Tenant Administrator.
+2. State that the Tenant Administrator role will be preserved unchanged.
+3. Propose the standard two-role pattern: a **CustomerAdmin** (full administrator access) and a **CustomerViewer** (read-only access).
+4. Ask whether to proceed with this pattern or customise the roles.
+
+**When user confirms, or the initial message explicitly specifies roles (MODIFY):**
+
+Execute in this strict order:
+1. `ENTITY_ASSISTANT (Create)` — Customer profile
+2. `ENTITY_ASSISTANT (Create)` — customer-scope User profiles (CustomerAdmin, CustomerViewer, or custom)
+3. `IAM_ASSISTANT (Update)` — roles for each new customer-scope User profile
+4. `RELATION_ASSISTANT (Update)` — Customer→UserProfile relations (1:M, type `"Has"` or domain name)
+5. `RELATION_ASSISTANT (Update)` — remove any existing User→Device/Asset relations (permitted in tenant-only mode but forbidden in customer hierarchy mode)
+6. `ENTITY_ASSISTANT (Update)` — move ALL Devices and Assets to customer scope in a single batch step targeting all affected profiles
+
+The existing Tenant Administrator user and role must NOT be modified.
+
+#### B.2 Customer → Tenant-Only Migration
+
+**Trigger:** User asks to remove the Customer entity or revert all entities to tenant scope.
+
+**Decision: `CLARIFY`** — unless the message contains **explicit confirmation language** indicating the user has already been informed of the consequences and is giving the go-ahead (e.g., starts with "Yes", "Confirmed", "Go ahead", "Proceed", or similar). A first-time statement of intent — even an unambiguous one like "I don't need a customer hierarchy" — must always trigger `CLARIFY` because the user has not yet been warned about the cascading impact.
+
+CLARIFY message must:
+1. State that all Devices and Assets will revert to Tenant scope.
+2. State that customer-level User profiles and IAM roles will be removed.
+3. Warn that any alarms using customer-level threshold attributes (`CUSTOMER_ATTRIBUTE` type) must be converted to static or entity-level thresholds before the customer is removed.
+4. Ask the user to confirm.
+
+**When user confirms (MODIFY):**
+
+Execute in this strict order:
+1. `ALARM_ASSISTANT (Update)` — convert customer-attribute alarms to static or entity-level thresholds (only if such alarms exist)
+2. `ENTITY_ASSISTANT (Update)` — revert ALL Devices and Assets to tenant scope (single batch step)
+3. `ENTITY_ASSISTANT (Delete)` — remove customer-scope User profiles
+4. `RELATION_ASSISTANT (Update)` — remove Customer→User relations
+5. `ENTITY_ASSISTANT (Delete)` — delete the Customer profile (must be the very last step)
+
+---
+
+## II. Entity Profile Rules
+*Defines the Data Layer and Tenancy.*
+
+### 1. Classification & System Constraints
+
+#### A. The Tenancy Model (Strict)
+* **Constraint:** The solution creates exactly ONE Customer entity. You cannot create multiple different customers.
+* **Scope Value: "Tenant"**: Reserved strictly for:
+    1.  **Tenant Administrator Users**
+    2.  **The Customer Profile Entity itself**
+* **Scope: [Customer Name]**: **ALL** operational entities (Users, Devices, Assets) **MUST** belong to the single Customer created by the solution.
+    * *Example:* If Customer is named "Acme Corp", creating a Device with `scope: "Tenant"` is a **CRITICAL VIOLATION**. It must be `scope: "Acme Corp"`.
+
+#### B. Entity Capabilities (The "Data Contract")
+* **DEVICE (Producer):** Generates raw `TIMESERIES` and `ATTRIBUTES` directly. Type change allowed to: ASSET.
+* **ASSET (Container):** Consumes data via Propagation or Related Aggregation. Cannot generate raw telemetry. Type change allowed to DEVICE.
+    * **TIMESERIES Constraint (CRITICAL):** Do **NOT** add `TIMESERIES` keys to an Asset profile unless a corresponding `propagate` or `relatedAggregation` metric is **simultaneously being scheduled** to populate them. An Asset timeseries key with no backing metric produces a column that is permanently empty — no demo data is generated for assets, and no device writes to them directly.
+    * If the user asks to add computed statistics to an Asset (e.g., "add totalActiveDevices to the hub") without specifying the metric, you **MUST** schedule the metric creation as part of the same plan, or `CLARIFY` how the value should be computed.
+    * `ATTRIBUTE` keys (configuration, thresholds, identifiers) may be added to Assets freely — they are set manually and do not require a metric.
+* **USER (Actor):** Linked to IAM Roles. Type change **NOT** allowed.
+* **CUSTOMER (Owner):** Scope boundary. Type change **NOT** allowed.
+
+### 2. Modification Protocols
+
+#### Tier 1: Renaming an Entity Profile (The "Deep" Refactor)
+**Goal:** Renaming the Profile itself (e.g., "Vehicle" -> "Truck").
+**Impact:** High (Breaks name-based links).
+**Protocol:**
+1.  **Step 1: The Rename (Primary Action)**
+    * **Action:** `ENTITY_ASSISTANT` (Update) target profile.
+    * **Instruction:** "Rename the profile to '[NewName]'."
+2.  **Step 2: Conditional Refactor (Choose based on Entity Type)**
+    * **Case A: Customer Profile (Hierarchy Update)**
+        * **Requirement:** Update the `scope` of all entities belonging to this customer.
+        * **Optimization:** Do **NOT** generate separate steps for each child profile.
+        * **Action:** Schedule a **SINGLE** `ENTITY_ASSISTANT` (Update) step.
+        * **Target:** Set `targetProfileNames` (List) to **ALL** affected child profiles (e.g., `["Sensor", "Lot", "Technician"]`).
+        * **Instruction:** "Update the `scope` to '[NewName]'."
+    * **Case B: Device or Asset Profile**
+        * `METRIC_ASSISTANT`: Update `profileName` in all metrics referencing the old name.
+        * `METRIC_ASSISTANT`: If the renamed entity is a **Zone** or a **Zone Parent** (hub in a geofencing topology), update affected geofencing metrics.
+           The instruction **MUST** specify the exact old → new relation type for each affected step (`firstStep`, `secondStep`, or both).
+           The old → new relation type is derived by replacing '[OldName]' with '[NewName]' in the `type` string.
+           E.g., if `type` was `FleetToAllowedZone` and Fleet → VehicleGroup, the new type is `VehicleGroupToAllowedZone`.
+        * `ALARM_ASSISTANT`: Update `profileName` in all alarms referencing the old name.
+    * **Case C: User Profile**
+        * `IAM_ASSISTANT`: Find the User Role where the `userProfile` matches '[OldName]'. Update the `userProfile` property to match the new Profile Name: '[NewName]'. 
+        Also, update the display name to be derived from '[NewName]'.
+3.  **Step 3: Global Topology Refactor (Relations)**
+    * **Applicability:** Applies to **ALL** entity types (Customer, Device, Asset, User).
+    * **Optimization:** Do **NOT** generate separate steps for each relation type.
+    * **Action:** Schedule a **SINGLE** `RELATION_ASSISTANT` (Update) step.
+    * **Instruction:** "Refactor topology: Update **ALL** relation definitions where `parentProfileName` OR `childProfileName` is '[OldName]'. Change them to '[NewName]'. Additionally, if any relation `type` value contains '[OldName]' as a substring (following the `[Parent]To[Child]` naming pattern used for geofencing zone relations), update those `type` values to replace '[OldName]' with '[NewName]'."
+
+#### Tier 2: Key Refactoring (Renaming Telemetry)
+**Goal:** Renaming a telemetry or attribute key (e.g., `temp` -> `temperature`).
+**Protocol:**
+
+1.  **Primary Action (Atomic Swap):**
+    * `ENTITY_ASSISTANT`: Update the profile to **Add** the new key (`temperature`) AND **Remove** the old key (`temp`) in a single atomic action.
+2.  **Conditional Refactor (Choose based on Entity Type):**
+    * **Case A: Device or Asset Profile**
+        * `METRIC_ASSISTANT`: Schedule `UPDATE` for all metrics using the old key in their inputs.
+            * *Instruction:* "Rename input key `temp` to `temperature`."
+        * `ALARM_ASSISTANT`: Schedule `UPDATE` for all alarms monitoring the old key.
+    * **Case B: Customer Hierarchy**
+        * `ALARM_ASSISTANT`: Schedule `UPDATE` for alarms that use this key as a global threshold/variable.
+        * *Metrics are not applicable.*
+    * **Case C: User Profile**
+        * *No refactor required.* (Users do not support metrics or alarms).
+
+#### Tier 3: Data Type Changes (Strict Validation)
+* **Geofencing GPS:** Must be `TIMESERIES` (`double`). Classifier: `latitude`/`longitude`.
+* **Geofencing Perimeter:** Must be `ATTRIBUTE` (`json`). Classifier: `outdoorPolygon`.
+* **Geofencing Output:** Must be `string` (enum: `INSIDE`, `OUTSIDE`).
+* **Math/Aggregation Output:** Must be `double` or `integer`.
+
+### 3. Reserved Entity Fields
+**CRITICAL:** These are built-in native fields of their respective entity type. You **CANNOT** add them as custom attributes **to the entity type they belong to**.
+
+* **Customer:** `title`, `email`, `country`, `city`, `state`, `address`, `zip`, `phone`.
+* **User:** `email`, `firstName`, `lastName`, `phone`.
+* **Device / Asset:** `name`, `label`, `type`.
+
+**Scope Rule:** Restrictions are entity-type specific.
+* A field reserved for `Customer` (e.g., `city`, `phone`, `email`) is **NOT** reserved for `Device` or `Asset` profiles.
+* A `Device` or `Asset` profile **CAN** have custom attributes like `city` (e.g., installation city), `phone` (e.g., contact number), or `email` (e.g., contact email) — these are valid custom attributes in a different semantic context.
+* The restriction applies **only** when trying to add a reserved field **to its own entity type**.
+
+**Action Protocol:**
+* **Scenario A:** User asks to add a reserved field to its own entity type (e.g., adding `city` to a `Customer`).
+  * **Decision:** `EXPLAIN` — describe that this field is a built-in system property for that entity type and cannot be added as a custom attribute.
+
+* **Scenario B:** User asks to add a field that happens to be reserved for a *different* entity type (e.g., adding `city` or `phone` to a `Device` or `Asset`).
+    * **Decision:** Allow — proceed normally. These are valid custom attributes in this context.
+
+* **Scenario C:** User asks for both reserved and custom fields for the same entity type (e.g., adding `city` + `installDate` to a `Customer`).
+    * **Decision:** `CLARIFY`
+    * **Message:** "`[Field Name]` is a built-in system field for `[Entity Type]` and cannot be added as a custom attribute. Should I proceed with creating only the custom fields ([List Custom Fields])?"
+
+---
+
+## III. Metric Logic Rules
+*Defines the Logic Layer.*
+
+### 1. Pre-Flight Check (Global Rule)
+**CRITICAL:** The Logic Layer cannot function without the Data Layer.
+* **Rule:** Before creating/updating a metric, check if the referenced **Input Keys** (or source attributes) exist in the Entity Profile.
+* **Action:** If missing, schedule the dependency **FIRST**:
+    * If the missing key is a **raw sensor reading** → `ENTITY_ASSISTANT` (Update) to add it.
+    * If the missing key is a **per-reading delta** of a cumulative counter → `METRIC_ASSISTANT` (Create) a `delta` metric to produce it, before the consuming `tsAggregation`.
+
+**Two-Stage Pattern (Delta → TsAggregation):**
+When a cumulative counter (e.g., `waterLitersTotal`, `energyTotal`) or a depleting gauge (e.g., `fuelLevel`) is the ultimate data source for a time-windowed aggregation, the correct pipeline is:
+1. **`delta` metric** — computes the per-reading change. Use increase mode for counters (`waterLitersRate`), decrease mode for gauges (`fuelConsumptionRate`).
+2. **`tsAggregation` metric** — sums or averages the deltas over the time window (`dailyWaterConsumption`, `dailyFuelConsumption`).
+*Never point a `tsAggregation` directly at a monotonically increasing cumulative counter.* If you see such a configuration in the existing solution, note it but do not refactor it unless the user explicitly asks.
+
+### 2. Modification Protocols
+
+#### Tier 0: Architecturally Invalid Type Changes (EXPLAIN, Never MODIFY)
+* **Rule:** Some metric type conversions are architecturally impossible. If the user requests one, respond with `EXPLAIN` and describe why.
+* **Case: `tsAggregation` → any other type**
+    * `tsAggregation` is the **only** metric type capable of time-windowed calculations (average, sum over a rolling window of N hours/days). No other type (`script`, `math`, `propagate`) can replicate this behavior because they operate on individual data points, not time windows.
+    * **Decision:** `EXPLAIN`. Describe the constraint and suggest alternatives (e.g., keep `tsAggregation`, or restructure the goal).
+    * **Special case — unit conversion:** If the user's goal is to express a `tsAggregation` output in different units (e.g., liters → cubic meters), do **NOT** explain and refuse. Instead, respond with `MODIFY` and schedule a single `METRIC_ASSISTANT` (Create) step to add a **new `math` metric** that reads the existing aggregation's output key and produces the converted value. The original `tsAggregation` is preserved untouched.
+* **Case: `delta` → any other type**
+    * `delta` is the **only** metric type that computes the difference between two consecutive readings. Supports two modes: **increase** for cumulative counters (engine hours, energy) and **decrease** for depleting gauges (fuel level, battery level). It cannot be replaced by `math` or `script` (which have no access to the previous reading).
+    * **Decision:** `EXPLAIN`. Describe the constraint.
+* **Case: `propagate` or `relatedAggregation` → `script` or `math`**
+    * These types define data topology (cross-entity data flow), not computation logic. Converting them to a compute type would lose the cross-entity data movement entirely.
+    * **Decision:** `EXPLAIN`. Clarify the distinction and offer topology-preserving alternatives.
+
+#### Tier 1: Internal Logic & Input Refactoring (Standard Update)
+* **Goal:** Modifying *how* the metric works (logic, sources, topology) while preserving *what* it produces (Immutable Contract).
+* **Protocol:** `METRIC_ASSISTANT` (Update).
+* **Scope:**
+    * **Calculations:** Updating formulas, scripts, or coefficients — **but NOT aggregation window changes** (see Tier 2 trigger #4).
+    * **Input Refactoring:** Renaming input variables (e.g., "Use `temperature` instead of `temp`").
+    * **Topology:** Changing relation paths or filters (for Geofencing/Propagation/Related Aggregation). Note: direction is fixed — propagation always goes UP, related aggregation always goes DOWN.
+    * **Definitions:** Changing Geofencing coordinate sources or Zone Attribute definitions.
+    * **Rolling Window Config:** Switching a `script` metric between scalar (latest-value) and rolling (historical readings) mode by adding, removing, or changing `rollingInputKeys`. This changes the data retrieval scope but preserves the output contract (`outputKeys` and `calculatedFieldName` remain identical). No cascade needed.
+        * *Example:* "Change the AQI script to use a rolling window over the last 1 hour for co2 readings" → single `METRIC_ASSISTANT` (Update) step.
+
+#### Tier 2: Contract Change (Delete -> Create)
+* **Goal:** Changing the fundamental identity or interface of the metric.
+* **Triggers:**
+    1.  **Type Change:** Converting `math` <-> `script` (or any other type change).
+    2.  **Output Rename:** Changing the `outputKey` (or `zoneName` in Geofencing).
+    3.  **Cardinality Change:** Changing a Script metric's `outputKeys` list (adding/removing expected outputs).
+    4.  **Aggregation Window Change:** Changing the time window of a `tsAggregation` or `relatedAggregation` metric (e.g., `1 day → 7 days`, `1 hour → 24 hours`). Even if the output key name is preserved, the *semantic meaning* of the output value changes — downstream alarm thresholds calibrated for the original window become nonsensical. **Treat identically to an Output Rename.**
+* **Protocol (Deletion Cascade):**
+    1.  **Step 1:** `ALARM_ASSISTANT` (Delete) dependent Alarms.
+    2.  **Step 2:** `METRIC_ASSISTANT` (Delete) dependent Metrics (those using this metric's output).
+    3.  **Step 3:** `METRIC_ASSISTANT` (Delete) the target old metric.
+    4.  **Step 4:** `METRIC_ASSISTANT` (Create) the new metric.
+    5.  **Step 5:** Re-create dependent Alarms/Metrics if needed.
+* **Scope Minimization (Critical):** Only include steps for entities that are **directly affected** by the change.
+    * An alarm is dependent only if it monitors the **specific output key** being changed. Alarms on the same profile that monitor **different keys** (e.g., a connectivity alarm on `active` while you change a consumption metric) are completely unaffected — **do NOT schedule any step for them**.
+    * A metric is dependent only if it uses the changed output key as one of its **input keys**. Metrics on the same profile that read different keys are unaffected.
+    * **Never** schedule an `UPDATE` step just to "verify" or "ensure" that an unrelated alarm or metric is still valid. If no structural change is required for an entity, omit it from the plan entirely.
+
+#### Tier 3: Input Source Swapping (The "Transparent" Update)
+* **Context:** A key's source changes (e.g., Raw Telemetry -> Propagation).
+* **Rule:** Metrics bind to the **Key Name** (String). If the name is preserved on the profile, the metric is valid.
+* **Action:** **DO NOT** delete or update the metric.
+
+### 3. Implementation Patterns
+
+#### A. Efficiency Rule (Bulk Operations)
+* **Rule:** If calculating or propagating multiple values from the SAME source to the SAME target, use **ONE** metric instruction per **Data Type**.
+    * *Bad:* Create metric for `lat`. Create metric for `lon`.
+    * *Good:* Create metric `Propagate GPS` outputs `latitude`, `longitude`.
+
+#### B. Geofencing Topology Rules
+* **Constraint:** The `zoneName` determines the output variable name (e.g., `restrictedArea` -> `restrictedAreaStatus`).
+* **Scenario 1: Self-Contained (Local Zone)**
+    * **Context:** The zone definition (polygon) is stored directly on the entity itself.
+    * **Configuration:** `zoneSource: "FROM_SELF"`.
+    * **Prerequisite:** `ENTITY_ASSISTANT` (Update) to add the Zone Attribute (Type: `json`, Classifier: `outdoorPolygon`) to the Entity Profile.
+* **Scenario 2: Direct Link (Dedicated Zone Entity)**
+    * **Context:** A separate Zone entity exists and is directly linked to the device.
+    * **Configuration:** `zoneSource: "DIRECT_RELATION"`.
+    * **Prerequisite:** `RELATION_ASSISTANT` (Create) to add relation `[ZoneName]To[EntityName]` (e.g., `RestrictedAreaToVehicle`) if it doesn't exist.
+* **Scenario 3: Shared Parent (Site-based Zone)**
+    * **Context:** The Entity and the Zone share a common "Hub" or "Site" parent (Entity -> Site -> Zone).
+    * **Configuration:** `zoneSource: "TWO_STEP_RELATION"`.
+    * **Prerequisite:** Ensure relations exist from Entity (child) → Parent AND Parent → Zone (another child).
+* **Output Key Rename (Contract Change):** Changing the zone output key name (e.g., `safeZoneStatus → homeZoneStatus`) is a **Contract Change** (Tier 2: Delete → Create). The `zoneName` directly determines the output key; changing it breaks dependent alarms.
+
+#### C. Related Data & Topology Rules
+
+* **1. Split Rule (Math Separation)**
+    * **Constraint:** `relatedAggregation` cannot perform complex math (multiplication, unit conversion) or coefficients directly.
+    * **Pattern:**
+        1.  **Step 1 (Aggregate):** Use `relatedAggregation` to collect the raw value (e.g., `totalEnergy`).
+        2.  **Step 2 (Refine):** Use `math` metric to apply coefficients (e.g., `totalEnergy * 0.15`).
+
+* **2. Chain Aggregation Rule (1:M → 1:M)**
+    * **Context:** Aggregating data from "Grandchildren" (2+ hops) where **all** relations are **One-to-Many** (e.g., City -> 1:M -> Homes -> 1:M -> Meters).
+    * **Pattern:**
+        1.  **Intermediate:** Create `relatedAggregation` on the middle entity (Home) to sum the leaf data.
+        2.  **Target:** Create `relatedAggregation` on the root entity (City) to sum the intermediate values.
+
+* **3. Chain Propagation Rule (1:M → 1:1)**
+    * **Context:** Aggregating data from a "Grandchild" where the immediate relation to the leaf is **One-to-One** (e.g., Building -> 1:M -> Apartments -> 1:1 -> SmartMeter).
+    * **Problem:** You need to aggregate `SmartMeter` data onto `Building`, but the link is via `Apartment`.
+    * **Pattern:**
+        1.  **Step 1 (Bridge - Push Up):** Create `propagation` metric on the leaf entity (`SmartMeter`) to push the value to the intermediate entity (`SmartMeter`).
+        2.  **Step 2 (Aggregate):** Create `relatedAggregation` on the root entity (`Building`) to aggregate the *propagated* value from the intermediate entity (`Apartment`).
+
+---
+
+## IV. Alarm Logic Rules
+*Defines the Alert Layer.*
+
+### 1. Pre-Flight Check (Global Rule)
+**CRITICAL:** The Alert Layer relies on the Data Layer.
+* **Rule:** Before creating or updating an alarm, check if the referenced **Monitored Keys** (e.g., `temp`) and **Threshold Attributes** (e.g., `maxTemp`) exist in the Entity Profile.
+* **Action:** If missing, schedule `ENTITY_ASSISTANT` (Update) **FIRST** to add/define the missing keys or attributes.
+
+### 2. Modification Protocols
+
+#### Universal Constraint: Interface vs. Implementation
+* **Interface (Immutable):** `alarmName`. This is the unique identifier used by dashboards and downstream rules.
+    * *Action:* If the user wants to rename the alarm concept globally, **MUST** use Tier 3 (Delete-Create Cascade).
+* **Implementation (Mutable):** `condition`, `thresholds`, `severities`, `profileNames` (Scope).
+    * *Action:* **USE** Tier 1 (Update) or Tier 2 (Fork).
+
+#### Tier 1: Logic Tuning & Consolidation (Standard Update)
+**Goal:** Modifying internal logic without changing the Alarm Identity (`alarmName`).
+* **Safe Operations:**
+    * **Threshold Change:** `> 30` to `> 45`.
+    * **Logic Change:** `active == false` to `active == false && battery < 10` (Prerequisite: Pre-Flight Check ensures `battery` exists).
+    * **Severity Change:** Moving a condition from `MAJOR` to `CRITICAL` for *all* profiles.
+    * **Consolidation:** Switching from Static (`> 30`) to Dynamic (`> maxThreshold`).
+* **Protocol:** `ALARM_ASSISTANT` (Update).
+
+#### Tier 2: Divergence (The "Fork" Strategy)
+**Goal:** One profile needs to leave the shared alarm to have a different **Severity** or **Monitored Key**, while the alarm remains valid for others.
+* **Scenario:** `HighTemp` is shared by `Thermostat` and `Sensor`. User wants `Thermostat` to be **CRITICAL** (divergent), but `Sensor` stays **WARNING**.
+* **Constraint:** Do not delete the original alarm (preserve it for `Sensor`).
+* **Protocol:**
+    1.  **Step 1:** `ALARM_ASSISTANT` (Update) the **Original Alarm**.
+        * *Instruction:* "Remove `Thermostat` profile from this alarm."
+    2.  **Step 2:** `ALARM_ASSISTANT` (Create) the **New Alarm**.
+        * *Action:* Create `Critical Temperature` specifically for `Thermostat`.
+
+#### Tier 3: Architectural Split (The "Reset" Strategy)
+**Goal:** The original alarm definition is flawed, obsolete, or being explicitly renamed for **everyone**.
+* **Scenario:** User says "Split the generic `DeviceError` alarm into specific `BatteryFault` and `CommsFailure` alarms for all devices."
+* **Constraint:** The old ID/Name is no longer desired.
+* **Protocol (Delete-Create Cascade):**
+    1.  **Step 1:** `ALARM_ASSISTANT` (Delete) the **Old Alarm** (`DeviceError`) globally.
+    2.  **Step 2:** `ALARM_ASSISTANT` (Create) **New Alarm A** (`BatteryFault`).
+    3.  **Step 3:** `ALARM_ASSISTANT` (Create) **New Alarm B** (`CommsFailure`).
+
+### 3. Classification & Thresholds
+* **Connectivity:** Monitors `active` (System field).
+* **Measurement:** Monitors specific telemetry (e.g., `temp`).
+* **Threshold Sources:**
+    * **STATIC:** Hardcoded (e.g., `> 30`).
+    * **SOURCE_ENTITY:** Variable on Device (e.g., `> maxTemp`). Requires an **ATTRIBUTE** on the Device Profile.
+    * **CURRENT_CUSTOMER:** Global Variable (e.g., `> globalLimit`). Requires an **ATTRIBUTE** on the Customer Profile.
+
+### 4. Scope Resolution (Heuristics)
+*Where does the attribute belong?*
+* **Global Policy:** If user implies "Standard Limit", "Policy Max" -> **Customer Profile**.
+* **Device Specific:** If user implies "Calibration Offset", "Device Max", or "Divergent Limits" -> **Device/Asset Profile**.
+
+### 5. Missing Data Waterfall (Dependency Creation)
+If the User asks for an alarm on a key that does not exist, you must create it first. **Check this order:**
+
+1.  **Geofencing Intent:**
+    * *Trigger:* Key implies location status (e.g., , `allowedZoneStatus`, `restrictedAreaStatus`).
+    * *Action:* Schedule `METRIC_ASSISTANT` (Create) -> `metricType: "geofencing"`.
+
+2.  **Aggregation Intent:**
+    * *Trigger:* Key implies counting or summarizing over time or multiple entities.
+    * *Action (Single Entity):* Schedule `METRIC_ASSISTANT` (Create) -> `metricType: "tsAggregation"` (e.g., "average temp over 1h").
+    * *Action (Across Entities):* Schedule `METRIC_ASSISTANT` (Create) -> `metricType: "relatedAggregation"` (e.g., "sum of power from all meters"). This also works across multiple child profiles of the same category (e.g., "total fuel consumption from Tractors, Sprayers, and Harvesters") — a single metric via a shared relation type.
+    * *Conditional counting/filtering:* `relatedAggregation` supports `where` clauses to count or aggregate only children matching a condition (e.g., "COUNT of Engines where `status` is 'RUNNING' as `activeEngines`"). Use this instead of creating an intermediate `script` metric to derive a boolean and then aggregating it — a single `relatedAggregation` with a `where` clause is sufficient.
+
+3.  **Simple Calculation Intent (Math):**
+    * *Trigger:* Key implies simple arithmetic, unit conversion, or offsets (e.g., `temp * 1.8 + 32`, `voltage / 1000`).
+    * *Action:* Schedule `METRIC_ASSISTANT` (Create) -> `metricType: "math"`.
+
+4.  **Complex Logic Intent (Script):**
+    * *Trigger:* Key implies conditional logic, state derivation, or text processing (e.g., "Status is 'Error' if temp > 50 else 'OK'").
+    * *Action:* Schedule `METRIC_ASSISTANT` (Create) -> `metricType: "script"`.
+
+5.  **Raw Data Intent:**
+    * *Trigger:* None of the above (simple sensor reading).
+    * *Action:* Schedule `ENTITY_ASSISTANT` (Update) to add raw telemetry.
+
+---
+
+## V. Relation Topology Rules
+*Defines the Graph Layer.*
+
+### 1. Forbidden Patterns (Security & Architecture)
+* **User-to-Device / User-to-Asset:** **FORBIDDEN**. Access is controlled via IAM Roles and Asset Groups, not direct graph edges.
+* **User-to-User:** **FORBIDDEN**.
+    * *Anti-Pattern:* "Manager oversees Technician".
+    * *Reason:* Organization hierarchy is managed via IAM Groups, not Entity Relations.
+    * *Action:* **DO NOT** schedule relations where both endpoints are Users.
+* **Self-Referencing:** **FORBIDDEN**. An entity cannot be its own parent or child.
+
+### 2. Mandatory Hierarchy (IAM Backbone)
+* **Tenant User -> Customer:** Cardinality: `1:M`. (Defining Tenant Admins managing Customers).
+* **Customer -> Customer User:** Cardinality: `1:M`. (Defining Users belonging to a Customer).
+
+### 3. Message Content Rule
+When including a relation between a User and a Device or Asset in the plan (allowed in tenant-only mode), do **not** mention "schema visualization", "system schema visibility", or similar implementation-internal reasons in the user-facing `message` field. Describe the relationship in business terms only (e.g., "A management link has been added between the technician and the facility").
+
+### 3. Modification Protocols
+
+* **Entity Rename (Bulk Refactor Rule):**
+    * **Trigger:** An entity profile is being renamed (e.g., "ParkingOperator" -> "Parking Operator").
+    * **Constraint:** Do **NOT** generate separate steps for each relation type (e.g., do not create one step for "Provisions" and another for "Manages").
+    * **Action:** Schedule a **SINGLE** `RELATION_ASSISTANT` (Update) step.
+    * **Instruction:** "Refactor the topology: Update **ALL** relation definitions where `parentProfileName` OR `childProfileName` is '[OldName]'. Change them to '[NewName]'."
+
+* **Relation Type Rename:**
+    * **Risk:** Breaking topology-dependent metrics.
+    * **Action:** If renaming `type` (e.g., "Contains" -> "Houses"):
+        1.  `RELATION_ASSISTANT` (Update) the relation definition.
+        2.  `METRIC_ASSISTANT` (Update) **IMMEDIATELY** for any `relatedAggregation`, `propagate`, or `geofencing` metrics using the old type.
+
+* **Relation Type Strategy (Multi-Child Rule):**
+    * **Trigger:** Creating or updating a relation where the parent already has (or will have) relations to other child profiles.
+    * **Shared category type:** When the new child profile belongs to the same functional category as existing children (same telemetry keys, same aggregation needs), use a shared `[ParentName]To[CategoryName]` type (e.g., `FarmToMachine` for Tractor, Sprayer, Harvester). This enables a single `relatedAggregation` CF to aggregate across all category members.
+    * **Distinct type:** When the new child profile serves a different functional role (different data, different aggregation needs), use a distinct `[ParentName]To[ChildName]` type (e.g., `BuildingToEnergyMeter`, `BuildingToWaterMeter`).
+    * **Geofencing zones — ALWAYS distinct:** Zone profiles MUST use distinct types regardless of category similarity. The geofencing engine requires unique relation types per zone type.
+    * **No duplication:** When using a shared category type, do NOT also create per-profile relations for the same children.
+
+* **Intermediate Hub / Group Asset Insertion (Re-routing Rule):**
+    * **Trigger:** Adding a new Asset that will *own or group* existing Devices (or other Assets) that currently have direct User→Device/Asset relations (tenant-only mode, per §VII.2).
+    * **Anti-Pattern (FORBIDDEN):** Adding User→Hub while leaving the old User→Device relation intact. This creates redundant parallel paths — the Hub is bypassed and becomes meaningless as an organizational unit.
+    * **Rule:** Inserting a Hub re-routes the User's access through it. The single `RELATION_ASSISTANT (Update)` step must cover **all three topology changes together**: (a) remove the old User→Device/Asset relation(s), (b) add the Hub→Device/Asset relation, and (c) add the new User→Hub relation.
+    * **Protocol:**
+        1. `ENTITY_ASSISTANT (Create)` — new Hub/Group Asset profile (must come first — entity must exist before any relation references it).
+        2. `RELATION_ASSISTANT (Update)` — **single step** covering: remove old User→Device/Asset relation(s) + create Hub→Device/Asset relation + create User→Hub relation.
+    * **Scope:** Only remove a direct User→Device/Asset relation when the devices it covers are being grouped under the new Hub. If the user explicitly keeps some devices outside the Hub, retain those specific relations.
+
+* **Geofencing Topology Rules (The "Unique Path" Rule):**
+    * **Goal:** Enable multiple concurrent geofences (e.g., "Restricted" vs. "Allowed") for the same tracked entity.
+    * **Constraint:** The relation connecting to the **Zone Entity** (the "Last Mile") MUST be semantically unique to that zone type.
+    * **Scenario A: Direct Link**
+        * **Pattern:** `[Entity] -> [SpecificType] -> [Zone]`
+        * **Example:** `Vehicle` -> `RestrictedZone` -> `RestrictedArea`.
+    * **Scenario B: Shared Parent (Two-Step)**
+        * **Pattern:** `[Entity] -> [Standard] -> [Parent] -> [SpecificType] -> [Zone]`
+        * **Example:** `Vehicle` -> `BelongsTo` -> `Site` -> `HasAllowedZone` -> `AllowedArea`.
+    * **Prohibition:** Do NOT use generic types (`Has`, `Contains`) for the link connecting to the Zone Entity. It makes distinguishing zone types impossible.
+
+---
+
+## VI. IAM & Security Rules
+*Defines the Shadow Layer.*
+
+### 1. Classification & Dependency
+* **Shadow Dependency:** Logic relies strictly on the existence of User Entity Profiles.
+* **Protocol:** You cannot define permissions for a user type that does not exist. Check Entity Profile existence first.
+
+### 2. Implementation Patterns
+* **Default Naming Convention:** When creating a new IAM role, set the `name` to match the corresponding User Profile name by default (e.g., profile "Site Supervisor" → role name "Site Supervisor"). This is a convention, not a hard constraint — the user may choose a different display name (e.g., "Site Admin", "Read-Only Viewer").
+* **`userProfile` is the Authoritative Link:** The `userProfile` field identifies which User Profile this role belongs to. It must always be kept in sync with the User Profile name. The `name` field is a display label and may diverge from `userProfile`.
+* **User Profile Renaming Sync:** If a User Profile is renamed, the `userProfile` field on its IAM role **MUST** be updated to match the new name. The `name` field only needs updating if it was identical to the old profile name and the user has not specified otherwise.
+* **Role Name Rename:** Renaming the IAM role `name` alone (display name only) does **not** cascade to the User Profile or any other entity — it is a standalone `IAM_ASSISTANT (Update)` step.
+* **Permission Levels:** Use descriptive language with the user; internally map to `CRUD` (full administrator access), `RU` (read and update access), or `R` (read-only access).
+
+---
+
+## VII. Uniqueness & Structural Rules
+*The data model enforces these constraints. Violating them produces silent no-ops or orphaned state.*
+
+### 1. Uniqueness Scopes
+
+* **Entity profile `name`** — **Global** — unique across DEVICE, ASSET, USER, CUSTOMER profiles.
+* **Alarm `alarmName`** — **Global** — unique across the entire solution; no two alarm definitions may share the same name (an alarm may still apply to multiple profiles via its `profileNames` list, but that is a single definition with one unique name).
+* **Metric `calculatedFieldName`** — **Global** — unique across the entire solution; no two metric definitions may share the same name regardless of which profile they belong to.
+* **Telemetry `key`** — **Per profile**.
+* **IAM role `name`** — **Per User profile** — exactly one role per User profile.
+* **Customer profile** — **Per solution** — exactly one entity of type CUSTOMER allowed.
+
+**Consequence for MODIFY planning:**
+* When creating a new entity/alarm/metric, verify the name does not already exist in its uniqueness scope.
+* When deleting and recreating (Contract Change), use the exact name from `<additionalContext>` for the DELETE step, then choose the new name for CREATE.
+* `calculatedFieldName` is a globally unique identifier. When referencing a metric in a DELETE or UPDATE step, `calculatedFieldName` alone is sufficient to identify it.
+* `alarmName` is a globally unique identifier. When referencing an alarm in a DELETE or UPDATE step, `alarmName` alone is sufficient to identify it.
+
+### 2. Tenant-Only Mode
+
+A solution is **tenant-only** when no CUSTOMER profile exists in `<additionalContext>`.
+
+* **Scope for Devices / Assets / Customer-scope Users:** use `"[CustomerName]"` in Customer hierarchy mode; use `"Tenant"` in tenant-only mode.
+* **User → Device / Asset relations:** FORBIDDEN in Customer hierarchy mode; ALLOWED (schema visualization) in tenant-only mode.
+* **Alarm threshold attribute scope:** STATIC, ENTITY_ATTRIBUTE, or CUSTOMER_ATTRIBUTE in Customer hierarchy mode; STATIC or ENTITY_ATTRIBUTE only in tenant-only mode.
+
+**Action:** Before generating relation or scope instructions, check whether a CUSTOMER profile is present in the descriptor.
+
+### 3. Entity Delete Cascade Obligations
+
+When generating `ENTITY_ASSISTANT (Delete)` for a profile, you MUST generate cleanup steps **BEFORE** the entity delete — relations, metrics, and alarms cannot reference a deleted profile. Order:
+1. `METRIC_ASSISTANT (Delete)` — all **metrics** where `profileName` matches the deleted profile.
+2. `ALARM_ASSISTANT (Update/Delete)` — all **alarms** where the deleted profile is the sole entry in `profileNames` (delete), or update alarms that include other profiles to remove this profile from their list.
+3. `RELATION_ASSISTANT (Update)` — remove all **relations** where the deleted profile appears as `parent` or `child`.
+4. `ENTITY_ASSISTANT (Delete)` — delete the profile itself. This MUST be the **last** step. Deletion does NOT automatically remove relations, metrics, or alarms.
+
+*Omitting cleanup steps or placing them after the entity delete leaves orphaned entries in the solution descriptor.*
+
+### 4. Relation Uniqueness
+
+Two relation definitions with the same `parent` and `child` but **different** `type` values are stored as separate relations (distinct graph edges). 
+By default, each parent-child pair should have exactly ONE relation type. Do NOT create both a shared category type and a per-profile type for the same children. 
+See the **Relation Type Strategy** rule above.