wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/mappers/dect_mapper.py

@@ -0,0 +1,367 @@
+"""DECT mapper: Canonical DECT networks -> enriched Webex DECT Network objects.
+
+Reads CanonicalDECTNetwork objects produced by normalize_dect_group() (post-normalization
+step), resolves locations via device_pool_to_location cross-refs, resolves handset owners
+via device_owned_by_user cross-refs, merges any operator-provided base station inventory,
+auto-selects network model (DBS-110 vs DBS-210), and generates decisions for ambiguous cases.
+
+(from docs/superpowers/specs/2026-04-10-dect-migration.md §5c, §7a, §7b)
+
+Cross-ref reads:
+    device_pool_to_location  (DevicePool -> Location)      — resolve location per network
+    device_owned_by_user     (Device -> EndUser)           — resolve handset owner
+
+Decisions generated:
+    DECT_NETWORK_DESIGN      — missing location, no base station inventory, or
+                               multiple zones map to same location
+    DECT_HANDSET_ASSIGNMENT  — handset has no owner (unowned/shared handset)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalDECTNetwork,
+    DecisionType,
+    DeviceCompatibilityTier,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    accept_option,
+    decision_to_store_dict,
+    extract_provenance,
+    manual_option,
+    skip_option,
+)
+
+logger = logging.getLogger(__name__)
+
+# Handset count threshold: zones with > 30 handsets require DBS-210.
+# Zones with <= 30 handsets default to DBS-110.
+# (from spec §3c: DBS-110 max 30 line ports; DBS-210 max 1000 line ports)
+_DBS110_MAX_HANDSETS = 30
+
+
+class DECTMapper(Mapper):
+    """Map normalized DECT networks to enriched Webex DECT Network objects.
+
+    Runs after location_mapper (so device_pool_to_location cross-refs are set),
+    device_mapper (so DECT-tier devices exist in the store), and user_mapper
+    (so device_owned_by_user cross-refs can be resolved to canonical user IDs).
+
+    (from docs/superpowers/specs/2026-04-10-dect-migration.md §5c)
+    """
+
+    name = "dect_mapper"
+    depends_on = ["location_mapper", "device_mapper", "user_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        """Read CanonicalDECTNetwork objects and enrich them with resolved data."""
+        result = MapperResult()
+
+        networks = store.get_objects("dect_network")
+        if not networks:
+            return result
+
+        # Build a map of location_canonical_id -> list of network canonical_ids
+        # to detect when multiple zones share the same location.
+        # (spec §7a: "multiple device pools with DECT handsets map to the same Webex location")
+        location_to_networks: dict[str, list[str]] = {}
+
+        for network_data in networks:
+            network_cid = network_data["canonical_id"]
+            pool_name = (network_data.get("pre_migration_state") or {}).get("cucm_device_pool", "")
+
+            # --- Location resolution ---
+            # device_pool_to_location cross-ref is written by LocationMapper.
+            # The network's pre_migration_state.cucm_device_pool is the device pool name.
+            pool_id = f"device_pool:{pool_name}" if pool_name else None
+            location_canonical_id: str | None = None
+
+            if pool_id:
+                loc_refs = store.find_cross_refs(pool_id, "device_pool_to_location")
+                location_canonical_id = loc_refs[0] if loc_refs else None
+
+            if location_canonical_id:
+                location_to_networks.setdefault(location_canonical_id, []).append(network_cid)
+
+            # Store location on the network for the second pass below
+            # (we update the network objects after the full scan)
+            network_data["_resolved_location"] = location_canonical_id
+
+        # Second pass: update each network with resolved data and generate decisions.
+        for network_data in networks:
+            network_cid = network_data["canonical_id"]
+            pool_name = (network_data.get("pre_migration_state") or {}).get("cucm_device_pool", "")
+            location_canonical_id = network_data.pop("_resolved_location", None)
+
+            handset_assignments: list[dict[str, Any]] = network_data.get("handset_assignments", [])
+            handset_count = len(handset_assignments)
+
+            # --- Auto-select network model ---
+            # DBS-110 supports up to 30 handsets / 1 base station.
+            # DBS-210 supports up to 1000 handsets / 254 base stations.
+            # (spec §5c rule 5)
+            model = "DBS-110" if handset_count <= _DBS110_MAX_HANDSETS else "DBS-210"
+
+            # --- Resolve handset owners and detect unowned/orphaned handsets ---
+            enriched_assignments: list[dict[str, Any]] = []
+            for assignment in handset_assignments:
+                device_cid = assignment.get("device_canonical_id")
+                owner_canonical_id: str | None = None
+
+                if device_cid:
+                    # device_owned_by_user cross-ref source is the device canonical_id
+                    owner_refs = store.find_cross_refs(device_cid, "device_owned_by_user")
+                    owner_canonical_id = owner_refs[0] if owner_refs else None
+
+                enriched = dict(assignment)
+                enriched["user_canonical_id"] = owner_canonical_id
+                enriched_assignments.append(enriched)
+
+                # Look up device model and extension for decision context
+                device_model: str | None = None
+                device_extension: str | None = None
+                if device_cid:
+                    device_obj = store.get_object(device_cid)
+                    if device_obj:
+                        device_model = device_obj.get("model")
+                        # Extension from first line appearance
+                        line_apps = device_obj.get("line_appearances") or []
+                        if line_apps:
+                            device_extension = line_apps[0].get("directory_number") or line_apps[0].get("dn")
+
+                # Determine if a DECT_HANDSET_ASSIGNMENT decision is needed:
+                # 1. Handset has no owner (unowned/shared)
+                # 2. Owner is transitioning to Webex App (no physical phone in Webex)
+                needs_assignment = False
+                owner_status = "owned"
+
+                if owner_canonical_id is None:
+                    needs_assignment = True
+                    owner_status = "unowned"
+                elif owner_canonical_id:
+                    # Check if the owner's other devices are all WEBEX_APP tier,
+                    # meaning the user is transitioning to Webex App only and
+                    # won't have a DECT handset in Webex.
+                    # device_owned_by_user: from=device, to=user — reverse lookup
+                    owner_device_refs = store.get_cross_refs(
+                        to_id=owner_canonical_id, relationship="device_owned_by_user",
+                    )
+                    owner_devices = [ref["from_id"] for ref in owner_device_refs]
+                    # Filter to non-DECT devices owned by this user
+                    non_dect_devices = []
+                    for dev_id in owner_devices:
+                        dev = store.get_object(dev_id)
+                        if dev and dev.get("compatibility_tier") != DeviceCompatibilityTier.DECT:
+                            non_dect_devices.append(dev)
+                    # If all non-DECT devices are WEBEX_APP, the user is transitioning
+                    if non_dect_devices and all(
+                        d.get("compatibility_tier") == DeviceCompatibilityTier.WEBEX_APP
+                        for d in non_dect_devices
+                    ):
+                        needs_assignment = True
+                        owner_status = "webex_app_transition"
+
+                if needs_assignment:
+                    cucm_device_name = assignment.get("cucm_device_name", device_cid or "unknown")
+                    summary_reason = (
+                        "has no owner"
+                        if owner_status == "unowned"
+                        else "owner is transitioning to Webex App (no physical phone)"
+                    )
+                    decision = self._create_decision(
+                        store=store,
+                        decision_type=DecisionType.DECT_HANDSET_ASSIGNMENT,
+                        severity="INFO",
+                        summary=(
+                            f"DECT handset '{cucm_device_name}' {summary_reason} — "
+                            f"needs person or workspace assignment"
+                        ),
+                        context={
+                            "device_canonical_id": device_cid,
+                            "cucm_device_name": cucm_device_name,
+                            "model": device_model,
+                            "extension": device_extension,
+                            "device_pool": pool_name,
+                            "owner_status": owner_status,
+                            "network_canonical_id": network_cid,
+                        },
+                        options=[
+                            accept_option(
+                                "Create a Webex workspace for this handset and assign as PLACE"
+                            ),
+                            manual_option(
+                                "Assign to a specific person (operator provides person ID/email)"
+                            ),
+                            skip_option("Do not migrate this handset"),
+                        ],
+                        affected_objects=[network_cid],
+                    )
+                    store.save_decision(decision_to_store_dict(decision))
+                    result.decisions.append(decision)
+
+            # --- Merge operator-provided base station inventory ---
+            # Base station data lives in pre_migration_state.base_stations if provided
+            # via --dect-inventory flag on discover. If absent, base_stations stays empty.
+            base_stations: list[dict[str, Any]] = (
+                (network_data.get("pre_migration_state") or {}).get("base_stations", [])
+                or network_data.get("base_stations", [])
+            )
+            has_inventory = bool(base_stations)
+
+            # --- Generate DECT_NETWORK_DESIGN decisions for ambiguous cases ---
+
+            # Case 1: No location resolved
+            if location_canonical_id is None:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.DECT_NETWORK_DESIGN,
+                    severity="HIGH",
+                    summary=(
+                        f"DECT network for pool '{pool_name}' could not resolve a "
+                        f"target Webex location — manual assignment required"
+                    ),
+                    context={
+                        "network_canonical_id": network_cid,
+                        "cucm_device_pool": pool_name,
+                        "total_handsets": handset_count,
+                        "base_stations_provided": has_inventory,
+                        "location_name": None,
+                        "zone_count": 1,
+                        "handsets_per_zone": {pool_name: handset_count},
+                    },
+                    options=[
+                        manual_option(
+                            "Assign this DECT network to a Webex location and re-run the mapper"
+                        ),
+                        skip_option("Exclude this DECT network from migration"),
+                    ],
+                    affected_objects=[network_cid],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+            # Case 2: No base station inventory provided
+            if not has_inventory:
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.DECT_NETWORK_DESIGN,
+                    severity="MEDIUM",
+                    summary=(
+                        f"DECT network for pool '{pool_name}' has no base station inventory — "
+                        f"provide MAC addresses to enable automated provisioning"
+                    ),
+                    context={
+                        "network_canonical_id": network_cid,
+                        "cucm_device_pool": pool_name,
+                        "total_handsets": handset_count,
+                        "base_stations_provided": False,
+                        "location_name": location_canonical_id,
+                        "zone_count": 1,
+                        "handsets_per_zone": {pool_name: handset_count},
+                    },
+                    options=[
+                        accept_option(
+                            f"Create one {'DBS-210' if handset_count > _DBS110_MAX_HANDSETS else 'DBS-110'} "
+                            f"DECT network for this zone — base stations must be added manually in Control Hub"
+                        ),
+                        manual_option(
+                            "Provide base station inventory CSV (--dect-inventory) and re-run"
+                        ),
+                        skip_option("Operator will design DECT networks manually in Control Hub"),
+                    ],
+                    affected_objects=[network_cid],
+                )
+                store.save_decision(decision_to_store_dict(decision))
+                result.decisions.append(decision)
+
+            # Case 3: Multiple zones map to the same location (detected via location_to_networks)
+            if location_canonical_id and len(location_to_networks.get(location_canonical_id, [])) > 1:
+                # Only emit this decision for the first network in the location group to avoid
+                # N duplicate decisions. The first network is the canonical_id at index 0.
+                zone_group = location_to_networks[location_canonical_id]
+                if zone_group[0] == network_cid:
+                    # Collect per-zone handset counts for all networks in this location
+                    handsets_per_zone: dict[str, int] = {}
+                    total_in_loc = 0
+                    for sibling_cid in zone_group:
+                        sibling_data = next(
+                            (n for n in networks if n["canonical_id"] == sibling_cid), {}
+                        )
+                        sibling_pool = (sibling_data.get("pre_migration_state") or {}).get(
+                            "cucm_device_pool", sibling_cid
+                        )
+                        sibling_count = len(sibling_data.get("handset_assignments", []))
+                        handsets_per_zone[sibling_pool] = sibling_count
+                        total_in_loc += sibling_count
+
+                    decision = self._create_decision(
+                        store=store,
+                        decision_type=DecisionType.DECT_NETWORK_DESIGN,
+                        severity="MEDIUM",
+                        summary=(
+                            f"Multiple DECT coverage zones ({len(zone_group)}) map to the same "
+                            f"Webex location '{location_canonical_id}' — "
+                            f"decide: one combined network or separate networks per zone"
+                        ),
+                        context={
+                            "network_canonical_id": network_cid,
+                            "location_name": location_canonical_id,
+                            "zone_count": len(zone_group),
+                            "total_handsets": total_in_loc,
+                            "handsets_per_zone": handsets_per_zone,
+                            "base_stations_provided": has_inventory,
+                        },
+                        options=[
+                            accept_option(
+                                "Create one DBS-210 multi-cell network for the location — "
+                                "all base stations and handsets go into this network"
+                            ),
+                            manual_option(
+                                "Create separate DECT networks per coverage zone — "
+                                "provide zone-to-base-station mapping"
+                            ),
+                            skip_option(
+                                "Operator will design DECT networks manually in Control Hub "
+                                "after migration"
+                            ),
+                        ],
+                        affected_objects=zone_group,
+                    )
+                    store.save_decision(decision_to_store_dict(decision))
+                    result.decisions.append(decision)
+
+            # --- Build and upsert the enriched CanonicalDECTNetwork ---
+            provenance = extract_provenance(network_data)
+            # Webex DECT display_name max 11 chars (shown on handset screen)
+            raw_display = network_data.get("display_name") or network_data.get("network_name") or f"DECT-{pool_name}"
+            display_name = raw_display[:11] if raw_display else None
+            enriched_network = CanonicalDECTNetwork(
+                canonical_id=network_cid,
+                provenance=provenance,
+                status=MigrationStatus.ANALYZED,
+                location_canonical_id=location_canonical_id,
+                network_name=network_data.get("network_name") or f"DECT-{pool_name}",
+                display_name=display_name,
+                model=model,
+                access_code=network_data.get("access_code") or "",
+                base_stations=base_stations,
+                handset_assignments=enriched_assignments,
+                pre_migration_state={
+                    **(network_data.get("pre_migration_state") or {}),
+                    "handset_count": handset_count,
+                    "has_base_station_inventory": has_inventory,
+                    "auto_selected_model": model,
+                },
+            )
+
+            store.upsert_object(enriched_network)
+            result.objects_created += 1
+
+        return result

wxcli/migration/transform/mappers/device_layout_mapper.py

@@ -0,0 +1,289 @@
+"""DeviceLayoutMapper: per-device resolved line key + KEM layout.
+
+Merges CanonicalLineKeyTemplate structure with per-phone line appearances,
+speed dials, and BLF entries. Resolves DNs to canonical user IDs and
+detects shared lines via CanonicalSharedLine objects.
+
+Reads raw phone objects (object_type="phone") which contain the full AXL
+getPhone response in pre_migration_state. Key fields:
+  - lines: list of line dicts with {index, label, dirn: {pattern, routePartitionName}}
+  - speeddials: {speeddial: [{dirn, label, index}, ...]}
+  - busyLampFields: {busyLampField: [{blfDest, label, index}, ...]}
+  - ownerUserName: zeep ref dict {"_value_1": "userid", "uuid": "..."}
+
+(from tier2-phase2-phone-config-design.md §4.2)
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import (
+    CanonicalDeviceLayout,
+    MapperResult,
+    MigrationStatus,
+)
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.mappers.base import (
+    Mapper,
+    extract_provenance,
+)
+from wxcli.migration.transform.mappers.monitoring_mapper import (
+    _extract_blf_entries,
+    _extract_speed_dials,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _ref_value(field: Any) -> str | None:
+    """Extract display value from a zeep ref dict or plain string."""
+    if field is None:
+        return None
+    if isinstance(field, str):
+        return field or None
+    if isinstance(field, dict):
+        val = field.get("_value_1")
+        return val if val else None
+    return None
+
+
+class DeviceLayoutMapper(Mapper):
+    """Per-device layout: merges button template with actual phone data."""
+
+    name = "device_layout_mapper"
+    depends_on = ["button_template_mapper", "monitoring_mapper", "line_mapper", "device_mapper"]
+
+    def map(self, store: MigrationStore) -> MapperResult:
+        result = MapperResult()
+
+        shared_dns = self._build_shared_dn_set(store)
+
+        for phone_data in store.get_objects("phone"):
+            phone_id = phone_data["canonical_id"]
+            state = phone_data.get("pre_migration_state") or {}
+
+            # Skip common-area phones (no ownerUserName)
+            owner_raw = _ref_value(state.get("ownerUserName"))
+            if not owner_raw and state.get("class") == "Phone":
+                continue
+
+            phone_name = state.get("name", phone_id.split(":", 1)[-1])
+            device_id = f"device:{phone_name}"
+
+            # Resolve owner via device cross-ref (device_owned_by_user links device:, not phone:)
+            owner_id = None
+            owner_refs = store.find_cross_refs(device_id, "device_owned_by_user")
+            if owner_refs:
+                owner_id = owner_refs[0]
+
+            # Resolve button template via phone cross-ref
+            tmpl_refs = store.find_cross_refs(phone_id, "phone_uses_button_template")
+            tmpl_id = None
+            tmpl_line_keys: list[dict] = []
+            tmpl_kem_keys: list[dict] = []
+            if tmpl_refs:
+                lkt_id = tmpl_refs[0].replace("button_template:", "line_key_template:")
+                lkt = store.get_object(lkt_id)
+                if lkt:
+                    tmpl_id = lkt_id
+                    lkt_data = lkt if isinstance(lkt, dict) else lkt.model_dump()
+                    tmpl_line_keys = lkt_data.get("line_keys", [])
+                    tmpl_kem_keys = lkt_data.get("kem_keys", [])
+
+            # Raw phone data: lines are a flat list from the extractor
+            raw_lines = state.get("lines", [])
+            if isinstance(raw_lines, dict):
+                raw_lines = raw_lines.get("line", [])
+                if isinstance(raw_lines, dict):
+                    raw_lines = [raw_lines]
+
+            # Index line appearances by position
+            la_by_index: dict[int, dict] = {}
+            for la in raw_lines:
+                if not isinstance(la, dict):
+                    continue
+                dirn = la.get("dirn")
+                if not dirn or not isinstance(dirn, dict):
+                    continue
+                idx = la.get("index")
+                if idx is not None:
+                    la_by_index[int(idx)] = la
+
+            # Speed dials and BLF indexed by button position
+            speed_dials_raw = _extract_speed_dials(state)
+            blf_entries_raw = _extract_blf_entries(state)
+
+            sd_by_index: dict[int, dict] = {}
+            for sd in speed_dials_raw:
+                idx = sd.get("index") or sd.get("speedDialIndex")
+                if idx is not None:
+                    sd_by_index[int(idx)] = sd
+
+            blf_by_index: dict[int, dict] = {}
+            for blf in blf_entries_raw:
+                idx = blf.get("index")
+                if idx is not None:
+                    blf_by_index[int(idx)] = blf
+
+            # Build line_members from line appearances
+            line_members: list[dict[str, Any]] = []
+            for la_idx in sorted(la_by_index.keys()):
+                la = la_by_index[la_idx]
+                dirn = la.get("dirn", {})
+                dn = dirn.get("pattern", "")
+                partition = _ref_value(dirn.get("routePartitionName"))
+                label = la.get("label")
+
+                member_id = self._resolve_dn_to_user(store, dn)
+
+                dn_key = f"{dn}:{partition}" if partition else dn
+                line_type = (
+                    "SHARED_LINE"
+                    if dn_key in shared_dns or dn in shared_dns
+                    else "PRIMARY"
+                )
+
+                line_members.append({
+                    "port": la_idx,
+                    "member_canonical_id": member_id,
+                    "line_type": line_type,
+                    "line_label": label,
+                })
+
+            # Merge template keys with phone data
+            resolved_line_keys = self._resolve_keys(
+                tmpl_line_keys, la_by_index, sd_by_index, blf_by_index, store,
+            )
+            resolved_kem_keys = self._resolve_keys(
+                tmpl_kem_keys, la_by_index, sd_by_index, blf_by_index, store,
+            )
+
+            # Collect speed dials
+            speed_dials = []
+            for idx in sorted(sd_by_index.keys()):
+                sd = sd_by_index[idx]
+                speed_dials.append({
+                    "index": idx,
+                    "label": sd.get("label", ""),
+                    "number": sd.get("dirn") or sd.get("speedDialNumber", ""),
+                })
+
+            # Skip CONVERTIBLE devices — they use activation-code registration
+            # and configure themselves post-registration. Layout application for
+            # these phones is deferred to a post-registration bulk job.
+            _skip_device_obj = store.get_object(device_id)
+            if _skip_device_obj and _skip_device_obj.get("compatibility_tier") == "convertible":
+                continue
+
+            # Copy device_id_surface from the associated CanonicalDevice
+            device_obj = store.get_object(device_id)
+            device_id_surface = device_obj.get("device_id_surface", "telephony") if device_obj else "telephony"
+
+            layout = CanonicalDeviceLayout(
+                canonical_id=f"device_layout:{phone_name}",
+                provenance=extract_provenance(phone_data),
+                status=MigrationStatus.ANALYZED,
+                device_canonical_id=device_id,
+                template_canonical_id=tmpl_id,
+                owner_canonical_id=owner_id,
+                line_members=line_members,
+                resolved_line_keys=resolved_line_keys,
+                resolved_kem_keys=resolved_kem_keys,
+                speed_dials=speed_dials,
+                device_id_surface=device_id_surface,
+            )
+            store.upsert_object(layout)
+
+            store.add_cross_ref(phone_id, layout.canonical_id, "phone_has_layout")
+            if device_obj is not None:
+                store.add_cross_ref(device_id, layout.canonical_id, "device_has_layout")
+            if layout.template_canonical_id:
+                store.add_cross_ref(
+                    layout.canonical_id,
+                    layout.template_canonical_id,
+                    "layout_uses_template",
+                )
+            result.objects_created += 1
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_keys(
+        self,
+        template_keys: list[dict],
+        la_by_index: dict[int, dict],
+        sd_by_index: dict[int, dict],
+        blf_by_index: dict[int, dict],
+        store: MigrationStore,
+    ) -> list[dict[str, Any]]:
+        """Resolve template key slots with phone-specific values."""
+        resolved = []
+        for key in template_keys:
+            idx = key.get("index", 0)
+            key_type = key.get("key_type", "OPEN")
+            entry: dict[str, Any] = {"index": idx, "key_type": key_type}
+
+            if key_type in ("PRIMARY_LINE", "SHARED_LINE", "LINE"):
+                la = la_by_index.get(idx)
+                if la:
+                    dirn = la.get("dirn", {})
+                    dn = dirn.get("pattern", "") if isinstance(dirn, dict) else ""
+                    entry["label"] = la.get("label")
+                    entry["target_canonical_id"] = self._resolve_dn_to_user(store, dn)
+
+            elif key_type == "SPEED_DIAL":
+                sd = sd_by_index.get(idx)
+                if sd:
+                    entry["label"] = sd.get("label", "")
+                    entry["value"] = sd.get("dirn") or sd.get("speedDialNumber", "")
+
+            elif key_type == "MONITOR":
+                blf = blf_by_index.get(idx)
+                if blf:
+                    target_dn = blf.get("blfDest") or ""
+                    entry["label"] = blf.get("label", target_dn)
+                    entry["target_canonical_id"] = self._resolve_dn_to_user(
+                        store, target_dn,
+                    )
+
+            elif key_type == "CALL_PARK_EXTENSION":
+                entry["label"] = "Call Park"
+
+            resolved.append(entry)
+        return resolved
+
+    def _resolve_dn_to_user(
+        self, store: MigrationStore, dn: str,
+    ) -> str | None:
+        """Resolve a DN to a user canonical_id via line cross-refs."""
+        if not dn:
+            return None
+        for line_data in store.get_objects("line"):
+            line_state = line_data.get("pre_migration_state") or {}
+            line_ext = (
+                line_data.get("extension")
+                or line_state.get("extension")
+                or line_state.get("pattern")
+            )
+            if line_ext == dn:
+                line_id = line_data["canonical_id"]
+                user_refs = store.find_cross_refs(line_id, "line_assigned_to_user")
+                if user_refs:
+                    return user_refs[0]
+        return None
+
+    def _build_shared_dn_set(self, store: MigrationStore) -> set[str]:
+        """Build a set of DN keys that are shared lines."""
+        shared: set[str] = set()
+        for sl in store.get_objects("shared_line"):
+            dn_id = sl.get("dn_canonical_id", "")
+            if dn_id:
+                parts = dn_id.split(":", 1)
+                if len(parts) > 1:
+                    shared.add(parts[1])
+                shared.add(dn_id)
+        return shared