---
name: crosslogic-bridge
description: >-
  CrossLogic HVAC knowledge wiki + IoT tag resolution. Use when: resolving IoT
  tag keys to roles/ranges, looking up HVAC component types, checking system
  archetypes, validating sensor naming (SS 741). NOT for: SCADA rendering,
  layout positioning, DSL syntax, pipe routing.
---

# CrossLogic Bridge — HVAC Wiki + Tag Resolution

API at `http://localhost:3210` (start: `node ~/dev/ceduix/crosslogic/api/serve.js`).
Wiki: `~/dev/ceduix/crosslogic/wiki/*.json` (7 files, verified).

## Decision Rules

| # | Rule | When | Trap |
|---|------|------|------|
| 1 | GT tens digit = function: 1x=supply, 3x=outdoor, 4x=return | Mapping sensor names | GT12 ≠ return (it's supply unit 2) |
| 2 | SV3 is ATOMIC (3-way valve), not SV + number 3 | Parsing component names | SV3 ≠ SV21 pattern |
| 3 | Scale: Exigo /10, ECL310 /100, Abelko /10 | Reading raw Modbus values | Per-register, NOT per-controller |
| 4 | HP prefix = heat_exchanger, HP system code = värmepump | Resolving HP tags | Context-dependent disambiguation |
| 5 | Check `gaps.json` before confident HVAC claims | Making domain assertions | Explicit uncertainty > hallucination |
| 6 | Supply flows FROM HX, return TO HX (secondary side) | Determining flow direction | Inverted from primary side intuition |

## API Endpoints

| Method | Path | Returns |
|--------|------|---------|
| GET | `/api/resolve/:tagKey` | `{prefix, num, suffix, role_sv, role_en, unit, range, rail, system}` |
| GET | `/api/component/:prefix` | Component type + function codes + unit |
| GET | `/api/system/:code` | Archetype + mandatory/optional components |
| GET | `/api/range/:role` | Normal/alarm bounds per HVAC role |
| GET | `/api/gaps` | Known conflicts + open questions |
| POST | `/api/crosslogic` | `{dsl}` → enriched IR + spatial state + warnings |
| POST | `/api/dsl-to-state` | `{dsl}` → editor-ready JSON + enrichment map |

## Cross-Project Tag Patterns

```
Koligo:  SAGAX_VB_VS01_GT11_PV  → resolveTag() → {prefix:'GT', num:11, role_sv:'framledning'}
NervIQ:  SITE_VS01_GT11_PV      → same resolver, strips site prefix
```

Tag format: `{SITE}_{SYSTEM}_{COMPONENT}_{SUFFIX}` — longest-suffix-first matching.

## Calibration

### Resolve an IoT tag to HVAC meaning
INPUT: "What does SAGAX_VB_VS01_GT41_PV measure?"
BAD: "GT41 is a temperature sensor" (vague, no role)
GOOD: `curl localhost:3210/api/resolve/SAGAX_VB_VS01_GT41_PV` → returledning (return temp), 18-50°C, return rail
WHY: Wiki resolution gives role_sv + range + rail — always use API, never guess roles.

### Check if a system is complete
INPUT: "Is this VS system complete: GT11, GT41?"
BAD: "Yes, it has supply and return sensors" (missing valve + pump)
GOOD: `curl localhost:3210/api/system/VS` → mandatory: gt11/sp, gt41, sv21/op, p1. Missing: sv21/op, p1.
WHY: Archetype defines completeness. Never assume — check mandatory list.