PRD run: onboarding, unified Event, maintenance drift, mapper engine + logbook profiles

CONTEXT.md

@@ -0,0 +1,105 @@
+# Context Glossary
+
+Canonical terms for the open_datEAUbase domain. Glossary only — no implementation
+details. When code or conversation uses one of these words, it means *this*.
+
+## Stream
+
+The supertype of a sensor **Channel** and a lab **AnalysisSeries** (table-per-type
+inheritance; every Channel and AnalysisSeries owns exactly one Stream row via
+`Stream_ID`). The unit of selection in the Data Explorer. A "time series" the user
+plots or downloads is a Stream.
+
+## Provenance
+
+The **processing-step lineage DAG** of a Stream: how it was derived from upstream
+streams through processing steps (outlier removal, drift correction, smoothing, …),
+plus accumulated traits. This is the *transformation history*. Surfaced by the
+`/lineage/streams/{id}/provenance` endpoint and the Explore Provenance panel. Not to
+be confused with [pedigree].
+
+## Pedigree
+
+The **organizational and spatial context** of a Stream — distinct from [provenance].
+The pedigree splits into a time-invariant identity and a **time-bound deployment
+timeline**:
+
+- Identity (fixed): parameter, unit, value kind, label.
+- Deployment timeline (one segment per slice of the stream's life):
+  - Sampling location (the SamplingPoint)
+  - Process unit (the ProcessUnit the sampling point sits on)
+  - Site (owning the sampling point / campaign)
+  - Campaign
+  - Responsible person (the campaign's `ResponsiblePerson`)
+  - Equipment (sensor only)
+
+A **sensor channel's** location and campaign are *historical*: its equipment is
+rewired (`EquipmentWiringHistory`) and moved between sampling points
+(`EquipmentLocationHistory`) over time, so one channel's data can span several
+locations and campaigns. The pedigree therefore carries a list of segments, each
+with its own `valid_from`/`valid_to`, not a single snapshot. A **lab
+AnalysisSeries** has a single fixed sampling point + campaign — one open segment.
+
+Pedigree is the *who/where/why*; provenance is the *how-derived*. The data-export
+metadata YAML carries pedigree, and each exported CSV row carries the sampling
+location + campaign active at that row's timestamp.
+
+## Event
+
+A discrete, time-stamped occurrence in the operational life of the system —
+a calibration, maintenance action, failure, power outage, site visit, etc.
+The supertype generalizing the former **EquipmentEvent**. Each Event attaches
+to exactly one **target** at its *smallest logical unit* via an exclusive arc —
+any node of the two operational hierarchies plus Campaign: a Channel, Equipment,
+SignalInterface, DataAcquisitionSystem, SamplingPoint, ProcessUnit, Site, or
+Campaign (exactly one non-NULL, enforced by CHECK). Has a start (and optional end /
+instantaneous flag), a performed-by and a recorded-by Person, an
+[EventKind], and free-text notes. The destination for plant **logbook**
+entries. Not to be confused with an [annotation], which anchors to a
+measurement [Stream] over a time range rather than to an operational unit.
+_Avoid_: EquipmentEvent (now a special case), SiteEvent (never existed).
+
+## EventKind
+
+The controlled vocabulary classifying an [Event] (calibration, maintenance,
+failure, power outage, …). The supertype generalizing the former
+**EquipmentEventKind**.
+
+## Annotation
+
+A human-authored note anchored to a measurement [Stream] (one Channel or
+AnalysisSeries) over a time range. Distinct from an [Event]: an annotation
+is *about the data*; an event is *about the operational unit*. An annotation
+may optionally reference the Event that explains it.
+
+## Measurement Range
+
+The min/max a **sensor** can physically produce when configured and operated
+correctly. A property of the sensor itself, independent of location or time
+(IWA Ch3 D3.6). _Avoid_: confusing with the [Variable Range] (process) or a
+[Control Limit] (error tolerance) — they bound different things.
+
+## Variable Range
+
+The expected range of the **measured value** under normal operation — the
+"normal operating range" (IWA Ch3 D3.7). Describes the *process*, not the
+sensor, and is context-dependent (location, time of day, season). A per-[Stream]
+property. A value outside it is a candidate process anomaly / contextual outlier.
+
+## Control Limit
+
+A tolerance on a **derived quality metric** — maintenance drift `%diff`,
+offset/slope drift, bias — used to decide whether a sensor needs action. It
+bounds the *error*, not the measured value, so it is **not** a [Variable Range].
+Per `(Stream × metric-type)`, and **historicized** (re-baselined over time, à la
+SPC) like a calibration curve. The acceptance limits on the logbook's
+per-equipment maintenance sheets are Control Limits.
+
+[pedigree]: #pedigree
+[provenance]: #provenance
+[annotation]: #annotation
+[Stream]: #stream
+[Event]: #event
+[EventKind]: #eventkind
+[Variable Range]: #variable-range
+[Control Limit]: #control-limit

api/v1/endpoints/channels.py

@@ -227,23 +227,32 @@ def open_channel_port_history(
     body: ChannelPortHistoryIn,
     conn=Depends(get_db),
 ):
-    """Open a ChannelPortHistory row linking a channel to a port for a time period."""
+    """Open a ChannelPortHistory row linking a channel to a port for a time period.
+
+    Routes through ``set_channel_active_port``, the single writer of the CPH
+    active-row invariant: it closes the previous active row before opening the
+    new one, so a second post no longer collides with the
+    UQ_ChannelPortHistory_ActiveRow filtered unique index (previously a 500).
+    """
     cursor = conn.cursor()
-    cursor.execute(
-        "INSERT INTO [dbo].[ChannelPortHistory]"
-        "    ([Channel_ID], [SignalInterfacePort_ID], [ValidFrom], [GatingNote])"
-        " OUTPUT INSERTED.[ChannelPortHistory_ID], INSERTED.[Channel_ID],"
-        "   INSERTED.[SignalInterfacePort_ID],"
-        "   CONVERT(VARCHAR(50), INSERTED.[ValidFrom], 127),"
-        "   INSERTED.[GatingNote]"
-        " VALUES (?, ?, ?, ?)",
+    channel_repository.set_channel_active_port(
+        cursor,
         channel_id,
         body.signal_interface_port_id,
         body.valid_from,
         body.gating_note,
     )
-    row = cursor.fetchone()
     conn.commit()
+    # Return the resulting active row (the just-opened one, or the existing one
+    # when the port was already current — set_channel_active_port is a no-op then).
+    cursor.execute(
+        "SELECT [ChannelPortHistory_ID], [Channel_ID], [SignalInterfacePort_ID],"
+        "   CONVERT(VARCHAR(50), [ValidFrom], 127), [GatingNote]"
+        " FROM [dbo].[ChannelPortHistory]"
+        " WHERE [Channel_ID] = ? AND [ValidTo] IS NULL",
+        channel_id,
+    )
+    row = cursor.fetchone()
     return ChannelPortHistoryOut(
         channel_port_history_id=row[0],
         channel_id=row[1],

api/v1/endpoints/das_move.py

@@ -21,6 +21,8 @@
     DASConflictResponse,
     DASDeployRequest,
     DASDeployResponse,
+    DASMoveConflictsResponse,
+    StrandedEquipment,
 )
 
 router = APIRouter()
@@ -140,3 +142,29 @@ def conflict_check_endpoint(
         conflicting_campaign_id=conflict.get("campaign_id"),
         conflicting_campaign_name=conflict.get("campaign_name"),
     )
+
+
+@router.get(
+    "/{das_id}/move-conflicts",
+    response_model=DASMoveConflictsResponse,
+)
+def move_conflicts_endpoint(
+    das_id: int,
+    site_id: int,
+    conn=Depends(get_db),
+):
+    """Equipment that a pending move of this DAS to ``site_id`` would strand.
+
+    Lists equipment currently wired to this DAS whose active location is at a
+    SamplingPoint in a *different* Site than ``site_id``. Empty list = the move
+    is coherent. The wizard surfaces this so the user can relocate those
+    equipment too rather than leaving a silent location/DAS mismatch (which
+    ``vw_DeploymentCoherence`` would then report)."""
+    rows = temporal_history_repository.get_das_move_equipment_conflicts(
+        conn, das_id=das_id, new_site_id=site_id
+    )
+    return DASMoveConflictsResponse(
+        das_id=das_id,
+        site_id=site_id,
+        stranded_equipment=[StrandedEquipment(**r) for r in rows],
+    )

api/v1/endpoints/data_health.py

@@ -0,0 +1,94 @@
+"""Data-health endpoints — surface the broken-link views (consistency audit F5, F11).
+
+  GET /data-health/unlinked-channels            — raw channels needing wiring (F5)
+  GET /data-health/inactive-parent-references   — live wiring on soft-deleted parents (F11)
+
+Both read the reconciling views added in schema 2.3.0; they are reports, not
+mutations, so the app can show a "N channels need wiring" banner or confirm
+before deactivating a parent that still has live children.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from api.database import get_db
+from ..schemas.data_health import (
+    InactiveParentReference,
+    InactiveParentReferencesResponse,
+    UnlinkedChannel,
+    UnlinkedChannelsResponse,
+)
+
+router = APIRouter()
+
+
+@router.get("/unlinked-channels", response_model=UnlinkedChannelsResponse)
+def unlinked_channels(conn=Depends(get_db)):
+    """Raw channels that carry observations but have no active wiring (F5)."""
+    cursor = conn.cursor()
+    cursor.execute(
+        """
+        SELECT ChannelID, TagName, SignalInterfaceID, SignalInterfaceName,
+               ObservationCount, FirstObservation, LastObservation
+        FROM [dbo].[vw_UnlinkedChannels]
+        ORDER BY ObservationCount DESC
+        """
+    )
+    channels = [
+        UnlinkedChannel(
+            channel_id=r[0],
+            tag_name=r[1],
+            signal_interface_id=r[2],
+            signal_interface_name=r[3],
+            observation_count=r[4],
+            first_observation=r[5],
+            last_observation=r[6],
+        )
+        for r in cursor.fetchall()
+    ]
+    return UnlinkedChannelsResponse(count=len(channels), channels=channels)
+
+
+@router.get(
+    "/inactive-parent-references",
+    response_model=InactiveParentReferencesResponse,
+)
+def inactive_parent_references(
+    signal_interface_id: int | None = Query(default=None),
+    signal_interface_port_id: int | None = Query(default=None),
+    conn=Depends(get_db),
+):
+    """Active wiring rows still pointing at a soft-deleted interface/port (F11).
+
+    Optionally filter to a single parent — the deactivation flow passes the
+    interface/port about to be set inactive to ask "does this still have live
+    children?" before committing.
+    """
+    sql = """
+        SELECT ReferenceType, WiringHistoryID, EquipmentID, ParentID, ParentLabel
+        FROM [dbo].[vw_InactiveParentReferences]
+    """
+    clauses, params = [], []
+    if signal_interface_id is not None:
+        clauses.append("(ReferenceType = N'active-wiring->interface' AND ParentID = ?)")
+        params.append(signal_interface_id)
+    if signal_interface_port_id is not None:
+        clauses.append("(ReferenceType = N'active-wiring->port' AND ParentID = ?)")
+        params.append(signal_interface_port_id)
+    if clauses:
+        sql += " WHERE " + " OR ".join(clauses)
+
+    cursor = conn.cursor()
+    cursor.execute(sql, *params)
+    refs = [
+        InactiveParentReference(
+            reference_type=r[0],
+            wiring_history_id=r[1],
+            equipment_id=r[2],
+            parent_id=r[3],
+            parent_label=r[4],
+        )
+        for r in cursor.fetchall()
+    ]
+    return InactiveParentReferencesResponse(count=len(refs), references=refs)

api/v1/endpoints/equipment_move.py

@@ -25,6 +25,7 @@
     temporal_history_repository,
 )
 from ..schemas.equipment_move import (
+    ActiveCampaignDeploymentResponse,
     EquipmentRegisterInterfaceRequest,
     EquipmentRegisterInterfaceResponse,
     EquipmentRelocateRequest,
@@ -331,3 +332,37 @@ def get_location_at_time_endpoint(
         valid_from=row["valid_from"],
         valid_to=row["valid_to"],
     )
+
+
+@router.get(
+    "/{equipment_id}/active-campaign",
+    response_model=ActiveCampaignDeploymentResponse,
+)
+def get_active_campaign_endpoint(
+    equipment_id: int,
+    conn=Depends(get_db),
+):
+    """Return the still-running campaign whose deployment placed this equipment.
+
+    Reconfiguring (relocate/rewire) equipment placed by a campaign that has not
+    ended will close that campaign's deployment, since physical configuration is
+    shared across campaigns. The move UIs call this to warn before acting. All
+    fields are None when no open campaign row exists."""
+    row = temporal_history_repository.get_active_campaign_deployment(conn, equipment_id)
+    if row is None:
+        return ActiveCampaignDeploymentResponse(
+            equipment_id=equipment_id,
+            campaign_id=None,
+            campaign_name=None,
+            equipment_location_history_id=None,
+            sampling_point_id=None,
+            sampling_point_name=None,
+        )
+    return ActiveCampaignDeploymentResponse(
+        equipment_id=equipment_id,
+        campaign_id=row["campaign_id"],
+        campaign_name=row.get("campaign_name"),
+        equipment_location_history_id=row.get("equipment_location_history_id"),
+        sampling_point_id=row.get("sampling_point_id"),
+        sampling_point_name=row.get("sampling_point_name"),
+    )