wxcli 1.2.0__py3-none-any.whl

wxcli/migration/execute/handlers.py

@@ -0,0 +1,2232 @@
+"""Operation handlers — pure functions mapping canonical data to API requests.
+
+Each handler takes:
+    data: dict — canonical object data from the migration store
+    resolved_deps: dict — {canonical_id: webex_id} for completed dependencies
+    ctx: dict — session context (orgId, CALLING_LICENSE_ID, etc.)
+
+Each handler returns:
+    list[tuple[str, str, dict | None]] — [(method, url, body), ...]
+
+Most handlers return a single tuple. Multi-call operations (e.g., user
+configure_settings) return multiple tuples to be executed sequentially.
+
+Handlers are pure functions — no IO, no side effects, fully testable.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode
+
+from wxcli.migration.phone_models import (
+    PHONEOS_LINE_KEY_COUNTS,
+    PHONEOS_MODEL_NUMBERS,
+)
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://webexapis.com/v1"
+
+
+@dataclass(frozen=True)
+class SkippedResult:
+    """Sentinel returned by handlers when a required dependency is missing.
+
+    Engine intercepts this and calls ``update_op_status(..., 'skipped',
+    error_message=reason)`` instead of marking the op completed. Use when a
+    hard prerequisite (e.g., upstream Webex ID not resolved) is missing. For
+    legitimate no-ops ("feature disabled", "nothing to configure") keep
+    returning ``[]`` — the engine marks those completed.
+    """
+    reason: str
+
+
+def skipped(reason: str) -> "SkippedResult":
+    """Return a SkippedResult sentinel with the given reason."""
+    return SkippedResult(reason=reason)
+
+
+# Handlers may return either a list of API calls or a SkippedResult sentinel.
+# Wave 2 will migrate individual guard-clause sites from ``return []`` to
+# ``return skipped(...)`` where the ``[]`` truly means "dependency missing".
+HandlerResult = list[tuple[str, str, dict | None]] | SkippedResult
+
+
+def _url(path: str, ctx: dict, query: dict | None = None) -> str:
+    """Build full URL with optional orgId injection."""
+    params = {}
+    if ctx.get("orgId"):
+        params["orgId"] = ctx["orgId"]
+    if query:
+        params.update(query)
+    url = f"{BASE}{path}"
+    if params:
+        url += f"?{urlencode(params)}"
+    return url
+
+
+def _resolve(deps: dict, canonical_id: str) -> str | None:
+    """Look up a Webex ID from resolved_deps by canonical_id."""
+    return deps.get(canonical_id)
+
+
+def _resolve_location(data: dict, deps: dict) -> str | None:
+    """Resolve location Webex ID from canonical location_id."""
+    loc_cid = data.get("location_id")
+    if not loc_cid:
+        return None
+    return deps.get(loc_cid)
+
+
+# PhoneOS model membership comes from ``wxcli.migration.phone_models`` —
+# single source of truth shared with device_mapper / softkey_mapper /
+# button_template_mapper / layout_overflow.
+
+
+def _normalize_device_model(model: str) -> str:
+    """Normalize a canonical device model string for the Webex devices API.
+
+    PhoneOS phones (9800-series + 8875) must NOT carry the "DMS " prefix —
+    the device-create and activation-code APIs reject it with
+    "Device model is not supported." All other phones require the "DMS "
+    prefix. The " IP Phone " token is always collapsed because CUCM models
+    may arrive as "Cisco IP Phone 8851" while Webex expects "Cisco 8851".
+    """
+    # Defensive early-return: callers generally guard with ``if model:`` but
+    # an empty string used to fall through to the classic-MPP branch and
+    # return "DMS ", which is invalid.
+    if not model:
+        return model
+    # Always collapse " IP Phone " first so downstream checks see the
+    # concise form ("Cisco 9841" vs "Cisco IP Phone 9841").
+    model = model.replace(" IP Phone ", " ")
+    is_phoneos = any(s in model for s in PHONEOS_MODEL_NUMBERS)
+    if is_phoneos:
+        # Strip any pre-existing "DMS " prefix — PhoneOS rejects it.
+        if model.startswith("DMS "):
+            model = model[len("DMS "):]
+    else:
+        if not model.startswith("DMS "):
+            model = f"DMS {model}"
+    return model
+
+
+def _resolve_location_from_deps(deps: dict) -> str | None:
+    """Fallback: find a location webex_id in resolved_deps by prefix.
+    Used when the canonical model doesn't have a location_id field."""
+    for cid, wid in deps.items():
+        if cid.startswith("location:") and wid:
+            return wid
+    return None
+
+
+def _resolve_agents(
+    data: dict, deps: dict, field: str = "agents"
+) -> tuple[list[dict], list[str]]:
+    """Resolve agent canonical IDs to Webex person IDs (object format for HG/CQ).
+
+    Returns a tuple ``(resolved, skipped)``:
+
+    * ``resolved`` — list of ``{"id": webex_id}`` dicts for agents whose canonical
+      IDs successfully resolved in ``deps``.
+    * ``skipped`` — list of canonical IDs that FAILED to resolve. Callers should
+      log a warning for each skipped agent and, where possible, record them in
+      the op metadata.
+
+    Per spec resolved decision #3, hunt groups/call queues proceed with partial
+    membership when some agents don't resolve — the alternative (no HG at all)
+    routes calls to nobody. The operator can add missing members post-migration.
+
+    Wave 3 will wire full op metadata recording; today we log-only.
+    """
+    agents: list[dict] = []
+    skipped_agents: list[str] = []
+    for cid in data.get(field, []):
+        wid = deps.get(cid)
+        if wid:
+            agents.append({"id": wid})
+        else:
+            skipped_agents.append(cid)
+    return agents, skipped_agents
+
+
+def _resolve_agent_ids(data: dict, deps: dict, field: str = "agents") -> list[str]:
+    """Resolve agent canonical IDs to plain Webex ID strings (for pickup/paging)."""
+    ids = []
+    for cid in data.get(field, []):
+        wid = deps.get(cid)
+        if wid:
+            ids.append(wid)
+    return ids
+
+
+def _find_webex_id(data: dict, deps: dict) -> str | None:
+    """Resolve the Webex ID for the canonical object referenced by `data`.
+
+    Looks up `data['canonical_id']` in `deps`. Returns None if the feature
+    has not been created yet (handler should return [] in that case).
+    """
+    cid = data.get("canonical_id")
+    if not cid:
+        return None
+    return deps.get(cid)
+
+
+# ---------------------------------------------------------------------------
+# Tier 0: Infrastructure
+# ---------------------------------------------------------------------------
+
+def handle_location_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    addr = data.get("address", {})
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "timeZone": data.get("time_zone"),
+        "preferredLanguage": data.get("preferred_language"),
+        "announcementLanguage": data.get("announcement_language"),
+        "address": {
+            "address1": addr.get("address1"),
+            "city": addr.get("city"),
+            "state": addr.get("state"),
+            "postalCode": addr.get("postal_code"),
+            "country": addr.get("country"),
+        },
+    }
+    # Optional fields
+    if addr.get("address2"):
+        body["address"]["address2"] = addr["address2"]
+    return [("POST", _url("/locations", ctx), body)]
+
+
+def handle_location_enable_calling(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve this op's own location by canonical_id rather than scanning
+    # deps for the first "location:" prefix. Runtime injects ALL completed
+    # location ops into resolved_deps (see runtime.py:get_next_batch), so
+    # the scan would pick whichever location happens to be first in dict
+    # iteration order — not necessarily this op's own location.
+    loc_cid = data.get("canonical_id")
+    loc_wid = deps.get(loc_cid) if loc_cid else None
+    body: dict[str, Any] = {
+        "id": loc_wid,
+        "name": data.get("name"),
+        "timeZone": data.get("time_zone"),
+        "preferredLanguage": data.get("preferred_language"),
+        "announcementLanguage": data.get("announcement_language"),
+    }
+    # Address is required when re-enabling calling on an existing location
+    addr = data.get("address")
+    if addr:
+        body["address"] = {
+            "address1": addr.get("address1"),
+            "city": addr.get("city"),
+            "state": addr.get("state"),
+            "postalCode": addr.get("postal_code"),
+            "country": addr.get("country"),
+        }
+    return [("POST", _url("/telephony/config/locations", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 1: Routing backbone
+# ---------------------------------------------------------------------------
+
+def handle_trunk_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "locationId": loc_wid,
+        "trunkType": data.get("trunk_type", "REGISTERING"),
+        "password": data.get("password"),
+    }
+    if data.get("address"):
+        body["address"] = data["address"]
+    if data.get("domain"):
+        body["domain"] = data["domain"]
+    if data.get("port"):
+        body["port"] = data["port"]
+    if data.get("max_concurrent_calls"):
+        body["maxConcurrentCalls"] = data["max_concurrent_calls"]
+    if data.get("dual_identity_support_enabled") is not None:
+        body["dualIdentitySupportEnabled"] = data["dual_identity_support_enabled"]
+    return [("POST", _url("/telephony/config/premisePstn/trunks", ctx), body)]
+
+
+def handle_route_group_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    gateways = []
+    for gw in data.get("local_gateways", []):
+        trunk_cid = gw.get("trunk_canonical_id")
+        trunk_wid = deps.get(trunk_cid) if trunk_cid else None
+        if trunk_wid:
+            gateways.append({
+                "id": trunk_wid,
+                "priority": gw.get("priority", 1),
+            })
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "localGateways": gateways,
+    }
+    return [("POST", _url("/telephony/config/premisePstn/routeGroups", ctx), body)]
+
+
+def handle_route_list_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    rg_cid = data.get("route_group_id", "")
+    rg_wid = deps.get(rg_cid)
+    if not rg_wid:
+        return skipped(
+            f"route group {rg_cid!r} not resolved for route list "
+            f"{data.get('name')!r}"
+        )
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "locationId": loc_wid,
+        "routeGroupId": rg_wid,
+    }
+    return [("POST", _url("/telephony/config/premisePstn/routeLists", ctx), body)]
+
+
+def handle_route_list_configure_numbers(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    rl_cid = data.get("canonical_id", "")
+    rl_wid = deps.get(rl_cid)
+    if not rl_wid:
+        return skipped(
+            f"route list {rl_cid!r} not resolved — cannot configure numbers"
+        )
+    numbers = data.get("numbers", [])
+    if not numbers:
+        return []  # true no-op: no numbers to configure
+    body: dict[str, Any] = {
+        "numbers": [{"number": n, "action": "ADD"} for n in numbers],
+    }
+    return [("PUT", _url(f"/telephony/config/premisePstn/routeLists/{rl_wid}/numbers", ctx), body)]
+
+
+def handle_operating_mode_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "level": data.get("level", "ORGANIZATION"),
+    }
+    schedule_type = data.get("schedule_type")
+    if schedule_type:
+        body["type"] = schedule_type
+
+    # Convert canonical same_hours_daily {startTime, endTime} to Webex API format
+    # Webex API: {mondayToFriday: {enabled, allDayEnabled, startTime?, endTime?}, saturdayToSunday: ...}
+    same = data.get("same_hours_daily")
+    if same:
+        start = same.get("startTime", "00:00")
+        end = same.get("endTime", "24:00")
+        all_day = (start == "00:00" and end in ("24:00", "00:00"))
+        day_entry: dict[str, Any] = {"enabled": True, "allDayEnabled": all_day}
+        if not all_day:
+            day_entry["startTime"] = start
+            day_entry["endTime"] = end
+        body["sameHoursDaily"] = {
+            "mondayToFriday": day_entry,
+            "saturdayToSunday": day_entry,
+        }
+
+    # Convert canonical different_hours_daily {day_N: {startTime, endTime}} or
+    # {monday: ..., tuesday: ...} to Webex API format
+    diff = data.get("different_hours_daily")
+    if diff:
+        _DAY_NAMES = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
+        # Canonical may use day_0..day_6 keys (numeric) or already-named keys
+        webex_diff: dict[str, Any] = {}
+        for key, val in diff.items():
+            if key.startswith("day_"):
+                idx = int(key.split("_", 1)[1])
+                day_name = _DAY_NAMES[idx] if idx < len(_DAY_NAMES) else key
+            else:
+                day_name = key  # already named
+            start = val.get("startTime", "00:00")
+            end = val.get("endTime", "17:00")
+            all_day = (start == "00:00" and end in ("24:00", "00:00"))
+            entry: dict[str, Any] = {"enabled": True, "allDayEnabled": all_day}
+            if not all_day:
+                entry["startTime"] = start
+                entry["endTime"] = end
+            webex_diff[day_name] = entry
+        body["differentHoursDaily"] = webex_diff
+
+    if data.get("holidays"):
+        body["holidays"] = data["holidays"]
+    return [("POST", _url("/telephony/config/operatingModes", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 1: Line key templates (org-wide, no dependencies)
+# ---------------------------------------------------------------------------
+
+def handle_line_key_template_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Skip templates with no Webex device model mapping (e.g., Standard Analog, ATA 191)
+    device_model = data.get("device_model")
+    if not device_model:
+        return []
+
+    # PhoneOS 9800-series and 8875 use "Cisco {model}" not "DMS Cisco {model}"
+    # The ButtonTemplateMapper stores "DMS Cisco {model}" for all phones, but
+    # PhoneOS phones require the non-DMS model name for the lineKeyTemplates API.
+    # Also track the max physical line key count for PhoneOS phones so we can
+    # split overflow indices from line_keys into kem_keys (mapper puts all button
+    # indices into line_keys regardless of phone key count).
+    #
+    # Counts come from ``wxcli.migration.phone_models.PHONEOS_LINE_KEY_COUNTS``
+    # — shared with button_template_mapper and layout_overflow.
+    phoneos_max: int | None = None
+    for phoneos_model, max_lk in PHONEOS_LINE_KEY_COUNTS.items():
+        if device_model == f"DMS Cisco {phoneos_model}":
+            device_model = f"Cisco {phoneos_model}"
+            phoneos_max = max_lk
+            break
+
+    def _map_key(k: dict, idx_field: str, mod_field: str | None = None) -> dict:
+        key_prefix = "kemKey" if mod_field else "lineKey"
+        key_type = k["key_type"]
+        # SPEED_DIAL without a value is rejected by the API (Error 27650).
+        # A template-level speed dial slot with no assigned number is effectively OPEN.
+        if key_type == "SPEED_DIAL" and not k.get("value"):
+            key_type = "OPEN"
+        entry: dict[str, Any] = {idx_field: k["index"], f"{key_prefix}Type": key_type}
+        if mod_field:
+            entry[mod_field] = k.get("module_index", 1)
+        if k.get("label"):
+            entry[f"{key_prefix}Label"] = k["label"]
+        if k.get("value"):
+            entry[f"{key_prefix}Value"] = k["value"]
+        return entry
+
+    all_line_keys = [k for k in data.get("line_keys", []) if k.get("key_type") != "UNMAPPED"]
+
+    # For PhoneOS phones, the mapper may place KEM button indices (> max_lk) in
+    # line_keys instead of kem_keys. Split them here: indices <= phoneos_max → lineKeys,
+    # indices > phoneos_max → kemKeys (re-index from 1 within the KEM range).
+    overflow_as_kem: list[dict] = []
+    if phoneos_max is not None:
+        phone_line_keys = [k for k in all_line_keys if k["index"] <= phoneos_max]
+        overflow_raw = sorted(
+            [k for k in all_line_keys if k["index"] > phoneos_max],
+            key=lambda x: x["index"],
+        )
+        # Re-index KEM overflow starting at 1
+        for new_idx, k in enumerate(overflow_raw, 1):
+            overflow_as_kem.append({**k, "index": new_idx})
+        all_line_keys = phone_line_keys
+    else:
+        phone_line_keys = all_line_keys
+
+    line_keys = [_map_key(k, "lineKeyIndex") for k in all_line_keys]
+    body: dict[str, Any] = {
+        "templateName": data.get("name"),
+        "deviceModel": device_model,
+        "lineKeys": line_keys,
+    }
+    if data.get("kem_module_type"):
+        body["kemModuleType"] = data["kem_module_type"]
+    kem_keys = [
+        _map_key(k, "kemKeyIndex", "kemModuleIndex")
+        for k in data.get("kem_keys", [])
+        if k.get("key_type") != "UNMAPPED"
+    ]
+    # Append overflow line_keys that were re-routed to KEM
+    kem_keys.extend([_map_key(k, "kemKeyIndex", "kemModuleIndex") for k in overflow_as_kem])
+    if kem_keys:
+        body["kemKeys"] = kem_keys
+    return [("POST", _url("/telephony/config/devices/lineKeyTemplates", ctx), body)]
+
+
+def handle_schedule_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Location schedule (businessHours or holidays) — used by AAs."""
+    loc_wid = _resolve_location(data, deps)
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "type": data.get("schedule_type", "businessHours"),
+    }
+    if data.get("events"):
+        body["events"] = data["events"]
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/schedules", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 2: People & Routing
+# ---------------------------------------------------------------------------
+
+def handle_user_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps)
+    body: dict[str, Any] = {
+        "emails": data.get("emails", []),
+        "firstName": data.get("first_name"),
+        "lastName": data.get("last_name"),
+        "displayName": data.get("display_name"),
+        "locationId": loc_wid,
+        "extension": data.get("extension"),
+    }
+    license_id = ctx.get("CALLING_LICENSE_ID")
+    if license_id:
+        body["licenses"] = [license_id]
+    if data.get("phone_numbers"):
+        body["phoneNumbers"] = data["phone_numbers"]
+    if data.get("department"):
+        body["department"] = data["department"]
+    if data.get("title"):
+        body["title"] = data["title"]
+    return [("POST", _url("/people", ctx, {"callingData": "true"}), body)]
+
+
+def handle_workspace_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps)
+    calling_config: dict[str, Any] = {
+        "type": data.get("calling_type", "webexCalling"),
+        "webexCalling": {
+            "locationId": loc_wid,
+        },
+    }
+    if data.get("extension"):
+        calling_config["webexCalling"]["extension"] = data["extension"]
+    if data.get("phone_number"):
+        calling_config["webexCalling"]["phoneNumber"] = data["phone_number"]
+    ws_license = ctx.get("WORKSPACE_LICENSE_ID")
+    if ws_license:
+        calling_config["webexCalling"]["licenses"] = [ws_license]
+    body: dict[str, Any] = {
+        "displayName": data.get("display_name"),
+        "supportedDevices": data.get("supported_devices", "phones"),
+        "type": data.get("workspace_type", "other"),
+        "calling": calling_config,
+    }
+    if data.get("hotdesking_status"):
+        body["hotdeskingStatus"] = data["hotdesking_status"]
+    return [("POST", _url("/workspaces", ctx), body)]
+
+
+def handle_workspace_assign_number(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve target workspace by this op's own canonical_id rather than
+    # scanning deps for the first "workspace:" prefix. Multiple workspaces
+    # in deps (edge case, but possible via cross-object rules) would cause
+    # the scan to misaddress the PUT and assign the number to the wrong ws.
+    ws_cid = data.get("canonical_id")
+    ws_wid = deps.get(ws_cid) if ws_cid else None
+    if not ws_wid:
+        return skipped(
+            f"workspace not resolved for assign_number "
+            f"(display_name={data.get('display_name')!r})"
+        )
+    if not data.get("phone_number"):
+        return []  # true no-op: no DID configured to assign
+    body: dict[str, Any] = {"phoneNumbers": [{"type": "work", "value": data["phone_number"]}]}
+    return [("PUT", _url(f"/workspaces/{ws_wid}", ctx), body)]
+
+
+def handle_device_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    body: dict[str, Any] = {}
+    if data.get("mac"):
+        body["mac"] = data["mac"]
+    model = data.get("model")
+    if model:
+        # PhoneOS phones (9800-series + 8875) reject the "DMS " prefix;
+        # all other phones require it. See _normalize_device_model.
+        body["model"] = _normalize_device_model(model)
+    # Resolve owner: person or workspace
+    owner_cid = data.get("owner_canonical_id")
+    if owner_cid:
+        owner_wid = deps.get(owner_cid)
+        if owner_wid:
+            if owner_cid.startswith("user:"):
+                body["personId"] = owner_wid
+            elif owner_cid.startswith("workspace:"):
+                body["workspaceId"] = owner_wid
+    return [("POST", _url("/devices", ctx), body)]
+
+
+def handle_device_create_activation_code(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Generate an activation code for a firmware-convertible device.
+
+    Used for CUCM-sourced phones classified as DeviceCompatibilityTier.CONVERTIBLE
+    (8845/8851/8865/7821/7841/7861). These phones are factory-reset, reflashed
+    with MPP firmware, and then registered to Webex via the returned activation
+    code. Unlike handle_device_create, this flow:
+
+    - does NOT send the MAC address (the code, not the MAC, establishes identity)
+    - REQUIRES `model` for phones (absent → code only works on RoomOS devices)
+    - normalizes the model string to the Webex "DMS <name>" format
+    """
+    body: dict[str, Any] = {}
+
+    model = data.get("model")
+    if model:
+        # CanonicalDevice.model may arrive as either "Cisco 8851" or
+        # "Cisco IP Phone 8851" (both are recognized as convertible in
+        # cross_reference._CONVERTIBLE_PATTERNS). The Webex activation
+        # code API expects the concise form and rejects the "DMS " prefix
+        # on PhoneOS models — see _normalize_device_model.
+        body["model"] = _normalize_device_model(model)
+
+    owner_cid = data.get("owner_canonical_id")
+    if owner_cid:
+        owner_wid = deps.get(owner_cid)
+        if owner_wid:
+            if owner_cid.startswith("user:"):
+                body["personId"] = owner_wid
+            elif owner_cid.startswith("workspace:"):
+                body["workspaceId"] = owner_wid
+
+    return [("POST", _url("/devices/activationCode", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 3: Routing patterns
+# ---------------------------------------------------------------------------
+
+def handle_dial_plan_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    route_cid = data.get("route_id")
+    route_wid = deps.get(route_cid) if route_cid else None
+    # Create takes plain strings; modify (PUT) takes {"dialPattern": p, "action": "ADD"}
+    patterns = data.get("dial_patterns", [])
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "routeId": route_wid,
+        "routeType": data.get("route_type", "TRUNK"),
+        "dialPatterns": patterns,
+    }
+    return [("POST", _url("/telephony/config/premisePstn/dialPlans", ctx), body)]
+
+
+def handle_translation_pattern_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "matchingPattern": data.get("matching_pattern"),
+        "replacementPattern": data.get("replacement_pattern"),
+    }
+    return [("POST", _url("/telephony/config/callRouting/translationPatterns", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 4: Call features
+# ---------------------------------------------------------------------------
+
+def handle_hunt_group_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps)
+    agents, skipped_agents = _resolve_agents(data, deps, "agents")
+    # Per spec resolved decision #3: create the hunt group with partial
+    # membership when some agents don't resolve. Log a WARNING for each
+    # skipped agent so the operator can reconcile post-migration.
+    # Wave 3 will add full op-metadata recording; today this is log-only.
+    if skipped_agents:
+        hg_name = data.get("name", "<unnamed>")
+        for cid in skipped_agents:
+            logger.warning(
+                "hunt_group '%s': agent %s not resolved — excluded from create "
+                "(add manually post-migration)",
+                hg_name, cid,
+            )
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "extension": data.get("extension"),
+    }
+    if data.get("phone_number"):
+        body["phoneNumber"] = data["phone_number"]
+    if data.get("policy"):
+        body["callPolicies"] = {"policy": data["policy"]}
+        if data.get("no_answer_rings"):
+            body["callPolicies"]["noAnswer"] = {
+                "numberOfRings": data["no_answer_rings"]
+            }
+    if agents:
+        body["agents"] = agents
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/huntGroups", ctx), body)]
+
+
+def handle_call_queue_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps)
+    agents, skipped_agents = _resolve_agents(data, deps, "agents")
+    # Per spec resolved decision #3: call queues proceed with partial
+    # membership when some agents fail to resolve. Log a WARNING for each
+    # so the operator can reconcile post-migration.
+    # Wave 3 will add full op-metadata recording; today this is log-only.
+    if skipped_agents:
+        cq_name = data.get("name", "<unnamed>")
+        for cid in skipped_agents:
+            logger.warning(
+                "call_queue '%s': agent %s not resolved — excluded from create "
+                "(add manually post-migration)",
+                cq_name, cid,
+            )
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "extension": data.get("extension"),
+        "callPolicies": {
+            "routingType": data.get("routing_type", "PRIORITY_BASED"),
+            "policy": data.get("policy", "CIRCULAR"),
+        },
+    }
+    if data.get("phone_number"):
+        body["phoneNumber"] = data["phone_number"]
+    if agents:
+        body["agents"] = agents
+    if data.get("queue_size"):
+        body["queueSize"] = data["queue_size"]
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/queues", ctx), body)]
+
+
+def _sanitize_aa_menu(menu: dict) -> dict:
+    """Remove value field from TRANSFER_TO_OPERATOR keys (value is only valid
+    for TRANSFER_TO_EXTENSION / TRANSFER_TO_NUMBER actions).
+    Also remove value from TRANSFER_TO_OPERATOR to avoid 4806 phone validation.
+    """
+    if not menu:
+        return menu
+    cleaned = dict(menu)
+    key_configs = cleaned.get("keyConfigurations", [])
+    sanitized = []
+    for kc in key_configs:
+        kc = dict(kc)
+        if kc.get("action") == "TRANSFER_TO_OPERATOR":
+            kc.pop("value", None)
+        sanitized.append(kc)
+    cleaned["keyConfigurations"] = sanitized
+    return cleaned
+
+
+def handle_auto_attendant_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+    }
+    if data.get("extension"):
+        body["extension"] = data["extension"]
+    if data.get("phone_number"):
+        body["phoneNumber"] = data["phone_number"]
+    # API requires at least one of extension or phoneNumber
+    if "extension" not in body and "phoneNumber" not in body:
+        return []  # No-op: no reachable number, skip AA creation
+    if data.get("business_schedule"):
+        body["businessSchedule"] = data["business_schedule"]
+    if data.get("business_hours_menu"):
+        body["businessHoursMenu"] = _sanitize_aa_menu(data["business_hours_menu"])
+    if data.get("after_hours_menu"):
+        body["afterHoursMenu"] = _sanitize_aa_menu(data["after_hours_menu"])
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/autoAttendants", ctx), body)]
+
+
+def handle_call_park_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "extension": data.get("extension"),
+        "recall": {"option": "ALERT_PARKING_USER_ONLY"},
+    }
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/callParks", ctx), body)]
+
+
+def handle_pickup_group_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    # Call Pickup API takes agents as plain string array, not [{"id": ...}]
+    agent_ids = _resolve_agent_ids(data, deps, "agents")
+    body: dict[str, Any] = {"name": data.get("name")}
+    if agent_ids:
+        body["agents"] = agent_ids
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/callPickups", ctx), body)]
+
+
+def handle_paging_group_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # CanonicalPagingGroup has no location_id field — resolve from deps
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "extension": data.get("extension"),
+    }
+    # Paging Group API takes targets/originators as plain string arrays, not [{"id": ...}]
+    target_ids = _resolve_agent_ids(data, deps, "targets")
+    if target_ids:
+        body["targets"] = target_ids
+    originator_ids = _resolve_agent_ids(data, deps, "originators")
+    if originator_ids:
+        body["originators"] = originator_ids
+        body["originatorCallerIdEnabled"] = True
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/paging", ctx), body)]
+
+
+def handle_voicemail_group_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Create a Webex Voicemail Group at a location.
+
+    (from docs/superpowers/specs/2026-04-10-voicemail-groups.md)
+    POST /v1/telephony/config/locations/{locationId}/voicemailGroups
+    """
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"location not resolved for voicemail_group "
+            f"{data.get('name')!r}"
+        )
+
+    if not data.get("extension"):
+        return []  # true no-op: no extension configured, cannot create VM group
+
+    body: dict[str, Any] = {
+        "name": data.get("name"),
+        "extension": data.get("extension"),
+        "passcode": data.get("passcode"),
+        "languageCode": data.get("language_code", "en_us"),
+        "messageStorage": data.get(
+            "message_storage", {"storageType": "INTERNAL"}
+        ),
+        "notifications": data.get("notifications", {"enabled": False}),
+        "faxMessage": data.get("fax_message", {"enabled": False}),
+        "transferToNumber": data.get(
+            "transfer_to_number", {"enabled": False}
+        ),
+        "emailCopyOfMessage": data.get(
+            "email_copy_of_message", {"enabled": False}
+        ),
+    }
+    if data.get("phone_number"):
+        body["phoneNumber"] = data["phone_number"]
+    caller_id_name = data.get("caller_id_name")
+    if caller_id_name:
+        body["directLineCallerIdName"] = {
+            "selection": "CUSTOM_NAME",
+            "customName": caller_id_name,
+        }
+        body["dialByName"] = caller_id_name
+
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/voicemailGroups", ctx
+    )
+    return [("POST", url, body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 5: Settings configuration
+# ---------------------------------------------------------------------------
+
+# Features that require read-before-write: the API rejects partial bodies
+# because it proxies to a backend that needs all fields present.
+# For these features, the handler emits GET (read current) then PUT (merge + overwrite).
+_READ_BEFORE_WRITE_FEATURES = {"callRecording"}
+
+
+def handle_user_configure_settings(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve the target user by this op's own canonical_id rather than
+    # scanning deps for the first "user:" prefix. In dep graphs where more
+    # than one user is resolved (e.g., monitoring, shared lines), the scan
+    # could pick the wrong user and silently rewrite settings on them —
+    # especially risky now that callRecording does GET + merge + PUT.
+    user_cid = data.get("canonical_id")
+    person_wid = deps.get(user_cid) if user_cid else None
+    if not person_wid:
+        return skipped(
+            f"user not resolved for configure_settings "
+            f"(canonical_id={user_cid!r})"
+        )
+    settings = data.get("call_settings", {})
+    calls = []
+    for feature_name, feature_body in settings.items():
+        url = _url(f"/people/{person_wid}/features/{feature_name}", ctx)
+        if feature_name in _READ_BEFORE_WRITE_FEATURES:
+            # Read current state first, then merge our overrides on top
+            calls.append(("GET", url, None))
+            calls.append(("PUT", url, {**feature_body, "_merge_from_previous": True}))
+        else:
+            calls.append(("PUT", url, feature_body))
+    return calls
+
+
+def handle_user_configure_voicemail(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Same rationale as handle_user_configure_settings — resolve target
+    # user by this op's canonical_id, not by scanning deps. Writing to the
+    # wrong user's voicemail settings would be silently destructive.
+    user_cid = data.get("canonical_id")
+    person_wid = deps.get(user_cid) if user_cid else None
+    if not person_wid:
+        return skipped(
+            f"user not resolved for configure_voicemail "
+            f"(canonical_id={user_cid!r})"
+        )
+    vm_data = data.get("voicemail") or data.get("voicemail_settings") or {}
+    return [("PUT", _url(f"/telephony/config/people/{person_wid}/voicemail", ctx), vm_data)]
+
+
+def handle_ecbn_config_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure ECBN for a user, workspace, or virtual line.
+
+    (from 2026-04-10-e911-ecbn-execution.md §4.4)
+    """
+    entity_type = data.get("entity_type", "")
+    entity_cid = data.get("entity_canonical_id", "")
+    entity_wid = deps.get(entity_cid)
+    if not entity_wid:
+        return skipped(f"ECBN target {entity_cid!r} ({entity_type}) not resolved")
+
+    path_map = {
+        "user": "people",
+        "workspace": "workspaces",
+        "virtual_line": "virtualLines",
+    }
+    path_segment = path_map.get(entity_type)
+    if not path_segment:
+        return skipped(f"ECBN entity_type {entity_type!r} not supported")
+
+    selection = data.get("ecbn_selection", "")
+    body: dict[str, Any] = {"selected": selection}
+    if selection == "LOCATION_MEMBER_NUMBER":
+        member_cid = data.get("location_member_canonical_id", "")
+        member_wid = deps.get(member_cid)
+        if not member_wid:
+            return skipped(f"ECBN location_member {member_cid!r} not resolved")
+        body["locationMemberId"] = member_wid
+
+    url = _url(
+        f"/telephony/config/{path_segment}/{entity_wid}/emergencyCallbackNumber",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_device_configure_settings(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve target device by this op's own canonical_id rather than
+    # scanning deps for the first "device:" prefix (same class of bug as
+    # handle_user_configure_settings: wrong device → silent mis-config).
+    device_cid = data.get("canonical_id")
+    device_wid = deps.get(device_cid) if device_cid else None
+    if not device_wid:
+        return skipped("device:configure_settings — device not resolved from deps")
+    settings = data.get("device_settings", {})
+    if not settings:
+        return []
+    return [("PUT", _url(f"/telephony/config/devices/{device_wid}/settings", ctx), settings)]
+
+
+def handle_workspace_configure_settings(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve target workspace by this op's own canonical_id (see
+    # handle_user_configure_settings for full rationale).
+    ws_cid = data.get("canonical_id")
+    ws_wid = deps.get(ws_cid) if ws_cid else None
+    if not ws_wid:
+        return skipped("workspace:configure_settings — workspace not resolved from deps")
+    # Workspace settings use /telephony/config/workspaces/{id}/ path family
+    # (NOT /workspaces/{id}/features/ — that's a different API surface)
+    settings = data.get("call_settings", {})
+    calls = []
+    for feature_name, feature_body in settings.items():
+        url = _url(f"/telephony/config/workspaces/{ws_wid}/{feature_name}", ctx)
+        calls.append(("PUT", url, feature_body))
+    return calls
+
+
+def handle_calling_permission_assign(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    permissions = data.get("calling_permissions", [])
+    api_permissions = [
+        {"callType": p["call_type"], "action": p.get("action", "ALLOW")}
+        for p in permissions
+    ]
+    body: dict[str, Any] = {
+        "useCustomEnabled": data.get("use_custom_enabled", True),
+        "callingPermissions": api_permissions,
+    }
+    calls = []
+    for user_cid in data.get("assigned_users", []):
+        person_wid = deps.get(user_cid)
+        if person_wid:
+            url = _url(f"/people/{person_wid}/features/outgoingPermission", ctx)
+            calls.append(("PUT", url, body))
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# Tier 5: Call forwarding
+# ---------------------------------------------------------------------------
+
+def handle_call_forwarding_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    user_cid = data.get("user_canonical_id", "")
+    person_wid = deps.get(user_cid)
+    if not person_wid:
+        return skipped(f"call_forwarding: user {user_cid!r} not resolved")
+    # Only generate if at least one forwarding type is enabled
+    if not any([data.get("always_enabled"), data.get("busy_enabled"), data.get("no_answer_enabled")]):
+        return []
+    def _cf_block(**kwargs: Any) -> dict[str, Any]:
+        """Build a callForwarding sub-block, omitting None-valued optional fields."""
+        return {k: v for k, v in kwargs.items() if v is not None}
+
+    body: dict[str, Any] = {
+        "callForwarding": {
+            "always": _cf_block(
+                enabled=bool(data.get("always_enabled")),
+                destination=data.get("always_destination"),
+                ringReminderEnabled=False,
+                destinationVoicemailEnabled=bool(data.get("always_to_voicemail")),
+            ),
+            "busy": _cf_block(
+                enabled=bool(data.get("busy_enabled")),
+                destination=data.get("busy_destination"),
+                destinationVoicemailEnabled=bool(data.get("busy_to_voicemail")),
+            ),
+            "noAnswer": _cf_block(
+                enabled=bool(data.get("no_answer_enabled")),
+                destination=data.get("no_answer_destination"),
+                destinationVoicemailEnabled=bool(data.get("no_answer_to_voicemail")),
+                numberOfRings=data.get("no_answer_ring_count"),
+            ),
+        },
+        "businessContinuity": {"enabled": False},
+    }
+    return [("PUT", _url(f"/people/{person_wid}/features/callForwarding", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 5: Single Number Reach
+# ---------------------------------------------------------------------------
+
+def handle_snr_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure Single Number Reach for a person.
+
+    Produces 1 PUT (enable SNR) + 1 POST per number.
+    (from tier2-enterprise-expansion.md §4)
+    """
+    user_cid = data.get("user_canonical_id", "")
+    person_wid = deps.get(user_cid)
+    if not person_wid:
+        return skipped(f"single_number_reach: user {user_cid!r} not resolved")
+    numbers = data.get("numbers") or []
+    if not numbers:
+        return []
+
+    calls: list[tuple[str, str, dict | None]] = []
+
+    # Call 1: Enable SNR at the top level
+    enable_body = {
+        "enabled": bool(data.get("enabled", True)),
+        "alertAllNumbersForClickToDialCallsEnabled": bool(data.get("alert_click_to_dial", False)),
+    }
+    calls.append((
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/singleNumberReach", ctx),
+        enable_body,
+    ))
+
+    # Call 2+: Add each number
+    for num in numbers:
+        phone_number = num.get("phone_number") or ""
+        if not phone_number:
+            continue
+        num_body = {
+            "phoneNumber": phone_number,
+            "enabled": bool(num.get("enabled", True)),
+            "answerConfirmationEnabled": bool(num.get("answer_confirmation", False)),
+        }
+        name = num.get("name")
+        if name:
+            num_body["name"] = name
+        calls.append((
+            "POST",
+            _url(f"/telephony/config/people/{person_wid}/singleNumberReach/numbers", ctx),
+            num_body,
+        ))
+
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# Tier 6: Monitoring list
+# ---------------------------------------------------------------------------
+
+def handle_monitoring_list_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    user_cid = data.get("user_canonical_id", "")
+    person_wid = deps.get(user_cid)
+    if not person_wid:
+        return skipped(f"monitoring_list: user {user_cid!r} not resolved")
+    members: list[dict[str, Any]] = []
+    unresolved: list[str] = []
+    total_count = 0
+    for m in data.get("monitored_members", []):
+        target_cid = m.get("target_canonical_id")
+        if not target_cid:
+            continue
+        total_count += 1
+        wid = deps.get(target_cid)
+        if wid:
+            members.append({"id": wid})
+        else:
+            unresolved.append(target_cid)
+    if total_count and not members:
+        list_name = data.get("name") or user_cid
+        return skipped(
+            f"monitoring list {list_name!r}: all {total_count} members unresolved",
+        )
+    if unresolved:
+        logger.warning(
+            "Monitoring list for %s: %d of %d members unresolved: %s",
+            person_wid,
+            len(unresolved),
+            total_count,
+            unresolved,
+        )
+    if not members:
+        return []
+    body: dict[str, Any] = {
+        "enableCallParkNotification": bool(data.get("call_park_notification_enabled")),
+        "monitoredMembers": members,
+    }
+    return [("PUT", _url(f"/people/{person_wid}/features/monitoring", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 6: Receptionist configuration
+# ---------------------------------------------------------------------------
+
+
+def handle_receptionist_config_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Enable receptionist client + create location contact directory."""
+    user_cid = data.get("user_canonical_id", "")
+    person_wid = deps.get(user_cid)
+    if not person_wid:
+        return skipped(f"receptionist_config: user {user_cid!r} not resolved")
+    members = []
+    for cid in data.get("monitored_members", []):
+        wid = deps.get(cid)
+        if wid:
+            members.append(wid)
+    reception_body: dict[str, Any] = {
+        "receptionEnabled": True,
+        "monitoredMembers": members,
+    }
+    calls: HandlerResult = [
+        ("PUT", _url(f"/people/{person_wid}/features/reception", ctx), reception_body),
+    ]
+    loc_cid = data.get("location_canonical_id", "")
+    loc_wid = deps.get(loc_cid) if loc_cid else None
+    if loc_wid and members:
+        contacts = [{"personId": wid} for wid in members]
+        dir_body: dict[str, Any] = {
+            "name": "Reception Directory",
+            "contacts": contacts,
+        }
+        calls.append((
+            "POST",
+            _url(f"/telephony/config/locations/{loc_wid}/receptionistContacts/directories", ctx),
+            dir_body,
+        ))
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# Tier 7: Device finalization (after monitoring, shared lines)
+# ---------------------------------------------------------------------------
+
+def handle_device_layout_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    device_cid = data.get("device_canonical_id")
+    device_wid = deps.get(device_cid) if device_cid else None
+    if not device_wid:
+        return skipped(f"device_layout: device {device_cid!r} not resolved")
+
+    results: HandlerResult = []
+
+    # Call 1 (conditional): PUT members
+    resolved_members = []
+    for m in data.get("line_members", []):
+        member_cid = m.get("member_canonical_id")
+        wid = deps.get(member_cid) if member_cid else None
+        if wid:
+            resolved_members.append({"id": wid, "port": m.get("port", 1)})
+    if resolved_members:
+        results.append((
+            "PUT",
+            _url(f"/telephony/config/devices/{device_wid}/members", ctx),
+            {"members": resolved_members},
+        ))
+
+    # Call 2: PUT layout
+    def _map_lk(k: dict) -> dict:
+        entry: dict[str, Any] = {"lineKeyIndex": k["index"], "lineKeyType": k["key_type"]}
+        if k.get("label"):
+            entry["lineKeyLabel"] = k["label"]
+        if k.get("value"):
+            entry["lineKeyValue"] = k["value"]
+        return entry
+
+    def _map_kk(k: dict) -> dict:
+        entry: dict[str, Any] = {
+            "kemModuleIndex": k.get("module_index", 1),
+            "kemKeyIndex": k["index"],
+            "kemKeyType": k["key_type"],
+        }
+        if k.get("label"):
+            entry["kemKeyLabel"] = k["label"]
+        return entry
+
+    raw_line_keys = data.get("resolved_line_keys", [])
+    raw_kem_keys = data.get("resolved_kem_keys", [])
+    # Filter line keys for Webex layout API:
+    # - Skip PRIMARY_LINE (auto-assigned by Webex at index 1)
+    # - Skip keys that require a value but have none (MONITOR, BLF, CALL_PARK_EXTENSION)
+    # - Skip OPEN keys (no-op placeholders)
+    # - Keep only SPEED_DIAL with a value
+    _SKIP_TYPES = {"PRIMARY_LINE", "OPEN"}
+    _VALUE_REQUIRED_TYPES = {"SPEED_DIAL", "MONITOR", "CALL_PARK_EXTENSION", "BLF"}
+    line_keys = []
+    idx = 2  # Start at 2 — index 1 is the primary line (auto-assigned)
+    for k in raw_line_keys:
+        kt = k.get("key_type", "OPEN")
+        if kt in _SKIP_TYPES:
+            continue
+        if kt in _VALUE_REQUIRED_TYPES and not k.get("value"):
+            continue
+        line_keys.append({**k, "index": idx, "key_type": kt})
+        idx += 1
+    # Skip KEM keys if device model doesn't support KEM (7841, 78xx without KEM)
+    kem_keys = raw_kem_keys if data.get("kem_supported") else []
+    layout_mode = "CUSTOM" if line_keys else "DEFAULT"
+    layout_body: dict[str, Any] = {"layoutMode": layout_mode}
+    if line_keys:
+        layout_body["lineKeys"] = [_map_lk(k) for k in line_keys]
+    if kem_keys:
+        layout_body["kemKeys"] = [_map_kk(k) for k in kem_keys]
+    results.append((
+        "PUT",
+        _url(f"/telephony/config/devices/{device_wid}/layout", ctx),
+        layout_body,
+    ))
+
+    # Call 3: POST applyChanges
+    results.append((
+        "POST",
+        _url(f"/telephony/config/devices/{device_wid}/actions/applyChanges/invoke", ctx),
+        None,
+    ))
+    return results
+
+
+def handle_softkey_config_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    if not data.get("is_psk_target"):
+        return []
+    device_cid = data.get("device_canonical_id")
+    device_wid = deps.get(device_cid) if device_cid else None
+    if not device_wid:
+        return skipped(f"softkey_config: device {device_cid!r} not resolved")
+
+    settings = []
+    for m in data.get("psk_mappings", []):
+        slot = m.get("psk_slot", "").lower()   # "PSK1" -> "psk1"
+        keyword = m.get("keyword", "")
+        if slot and keyword:
+            settings.append({"key": f"softKeyLayout.psk.{slot}", "value": keyword})
+    for state, keywords in (data.get("state_key_lists") or {}).items():
+        value = ";".join(keywords) if keywords else ""
+        if value:
+            settings.append({
+                "key": f"softKeyLayout.softKeyMenu.{state}KeyList",
+                "value": value,
+            })
+    if not settings:
+        return []
+
+    return [
+        (
+            "PUT",
+            _url(f"/telephony/config/devices/{device_wid}/dynamicSettings", ctx),
+            {"settings": settings},
+        ),
+        (
+            "POST",
+            _url(f"/telephony/config/devices/{device_wid}/actions/applyChanges/invoke", ctx),
+            None,
+        ),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Tier 6: Shared/virtual lines
+# ---------------------------------------------------------------------------
+
+def handle_shared_line_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    owner_cids = data.get("owner_canonical_ids", [])
+
+    # Resolve all owner Webex IDs
+    resolved_owners = []
+    for cid in owner_cids:
+        wid = deps.get(cid)
+        if wid:
+            resolved_owners.append((cid, wid))
+
+    if len(resolved_owners) < 2:
+        # Need at least 2 owners for a shared line (issue #17).
+        return skipped(
+            f"shared line requires 2+ resolved owners; "
+            f"only {len(resolved_owners)} of {len(owner_cids)} resolved",
+        )
+
+    calls = []
+
+    for owner_cid, owner_wid in resolved_owners:
+        # Build members list: all OTHER resolved owners
+        members = []
+        port = 1
+        for other_idx, (other_cid, other_wid) in enumerate(resolved_owners):
+            if other_cid == owner_cid:
+                continue
+            is_primary = (other_idx == 0)  # First owner in list is primary
+            members.append({
+                "memberId": other_wid,
+                "port": port,
+                "primaryOwner": is_primary,
+                "lineType": "SHARED_CALL_APPEARANCE",
+                "lineWeight": port,
+            })
+            port += 1
+
+        if members:
+            calls.append((
+                "PUT",
+                _url(f"/telephony/config/people/{owner_wid}/applications/members", ctx),
+                {"members": members},
+            ))
+
+    return calls
+
+
+def handle_virtual_line_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    loc_wid = _resolve_location(data, deps)
+    body: dict[str, Any] = {
+        "firstName": data.get("display_name", "Virtual"),
+        "lastName": "Line",
+        "locationId": loc_wid,
+    }
+    if data.get("extension"):
+        body["extension"] = data["extension"]
+    if data.get("phone_number"):
+        body["phoneNumber"] = data["phone_number"]
+    return [("POST", _url("/telephony/config/virtualLines", ctx), body)]
+
+
+def handle_virtual_line_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    # Resolve target virtual line by this op's own canonical_id (see
+    # handle_user_configure_settings for full rationale).
+    vl_cid = data.get("canonical_id")
+    vl_wid = deps.get(vl_cid) if vl_cid else None
+    if not vl_wid:
+        return skipped(
+            f"virtual_line:configure — virtual line "
+            f"{data.get('display_name') or data.get('canonical_id')!r} not resolved from deps",
+        )
+    # Virtual line settings — pass through whatever canonical data has
+    settings = data.get("settings", {})
+    if not settings:
+        return []
+    return [("PUT", _url(f"/telephony/config/virtualLines/{vl_wid}", ctx), settings)]
+
+
+# ---------------------------------------------------------------------------
+# Tier 1/5: Device settings templates
+# ---------------------------------------------------------------------------
+
+def handle_device_settings_template_apply_location_settings(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Apply device settings at location level."""
+    loc_cid = data.get("location_canonical_id")
+    if not loc_cid:
+        return skipped(
+            "device_settings_template:apply_location_settings — "
+            "location_canonical_id missing from template data",
+        )
+    loc_wid = deps.get(loc_cid)
+    if not loc_wid:
+        return skipped(
+            f"device_settings_template:apply_location_settings — "
+            f"location {loc_cid!r} not resolved",
+        )
+    settings = data.get("settings") or {}
+    if not settings:
+        return []
+    body = {"customizations": {"mpp": settings}, "customEnabled": True}
+    return [("PUT", _url(f"/telephony/config/locations/{loc_wid}/devices/settings", ctx), body)]
+
+
+def handle_device_settings_template_apply_device_override(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Apply per-device settings override."""
+    override = data.get("override") or {}
+    device_cid = override.get("device_canonical_id")
+    if not device_cid:
+        return skipped(
+            "device_settings_template:apply_device_override — "
+            "device_canonical_id missing from override data",
+        )
+    device_wid = deps.get(device_cid)
+    if not device_wid:
+        return skipped(
+            f"device_settings_template:apply_device_override — "
+            f"device {device_cid!r} not resolved",
+        )
+    settings = override.get("settings") or {}
+    if not settings:
+        return []
+    body = {"customizations": {"mpp": settings}, "customEnabled": True}
+    return [("PUT", _url(f"/telephony/config/devices/{device_wid}/settings", ctx), body)]
+
+
+# ---------------------------------------------------------------------------
+# Hoteling / Hot Desking handlers (tier 5 / tier 0)
+# ---------------------------------------------------------------------------
+
+def handle_hoteling_guest_enable(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Enable hoteling guest for a user with an EM device profile."""
+    if not data.get("hoteling_guest_enabled"):
+        return []
+    user_cid = data.get("user_canonical_id")
+    person_wid = deps.get(user_cid) if user_cid else None
+    if not person_wid:
+        return skipped(f"hoteling_guest_enable: user {user_cid!r} not resolved")
+    return [("PUT", _url(f"/people/{person_wid}/features/hoteling", ctx), {"enabled": True})]
+
+
+def handle_hoteling_host_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure hoteling host on devices that were EM-enabled."""
+    host_cids = data.get("host_device_canonical_ids") or []
+    if not host_cids:
+        return []
+    user_cid = data.get("user_canonical_id")
+    person_wid = deps.get(user_cid) if user_cid else None
+    if not person_wid:
+        return skipped(f"hoteling_host_configure: user {user_cid!r} not resolved")
+    if not any(deps.get(cid) for cid in host_cids):
+        return skipped(
+            f"hoteling_host_configure: none of {len(host_cids)} host devices "
+            f"resolved ({host_cids!r})",
+        )
+    auto_minutes = data.get("auto_logout_minutes", 0)
+    hoteling_body: dict[str, Any] = {"enabled": True}
+    if auto_minutes > 0:
+        hoteling_body["limitGuestUse"] = True
+        hoteling_body["guestHoursLimit"] = max(1, auto_minutes // 60)
+    else:
+        hoteling_body["limitGuestUse"] = False
+    return [(
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/devices/settings/hoteling", ctx),
+        {"hoteling": hoteling_body},
+    )]
+
+
+def handle_location_hotdesking_enable(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Enable voice portal hot desk sign-in at a location."""
+    state = data.get("pre_migration_state") or {}
+    loc_cid = state.get("location_canonical_id")
+    loc_wid = deps.get(loc_cid) if loc_cid else None
+    if not loc_wid:
+        return skipped(
+            f"location_hotdesking_enable: location {loc_cid!r} not resolved",
+        )
+    return [(
+        "PUT",
+        _url(f"/telephony/config/locations/{loc_wid}/features/hotDesking", ctx),
+        {"voicePortalHotDeskSignInEnabled": True},
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Tier 5: Feature forwarding / holiday / night service
+# (from 2026-04-10-feature-forwarding-night-service.md)
+# ---------------------------------------------------------------------------
+
+def handle_hunt_group_configure_forwarding(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    hg_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps)
+    if not hg_wid:
+        return skipped(
+            f"hunt group {data.get('name')!r} not created — "
+            "cannot configure forwarding"
+        )
+    if not loc_wid:
+        return skipped(
+            f"hunt group {data.get('name')!r}: location not resolved — "
+            "cannot configure forwarding"
+        )
+    cf: dict[str, Any] = {}
+    if data.get("forward_always_enabled") and data.get("forward_always_destination"):
+        cf["always"] = {
+            "enabled": True,
+            "destination": data["forward_always_destination"],
+            "ringReminderEnabled": False,
+            "destinationVoicemailEnabled": False,
+        }
+    if data.get("forward_no_answer_enabled") and data.get("forward_no_answer_destination"):
+        cf["selective"] = {
+            "enabled": True,
+            "destination": data["forward_no_answer_destination"],
+            "ringReminderEnabled": False,
+            "destinationVoicemailEnabled": False,
+        }
+    if data.get("forward_busy_enabled") and data.get("forward_busy_destination") and "always" not in cf:
+        # Map CUCM forward-on-busy onto Webex always-forward when always is unused
+        cf["always"] = {
+            "enabled": True,
+            "destination": data["forward_busy_destination"],
+            "ringReminderEnabled": False,
+            "destinationVoicemailEnabled": False,
+        }
+    if not cf:
+        return []
+    body = {"callForwarding": cf}
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/huntGroups/{hg_wid}/callForwarding",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_call_queue_configure_forwarding(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    cq_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps)
+    if not cq_wid:
+        return skipped(
+            f"call queue {data.get('name')!r} not created — "
+            "cannot configure forwarding"
+        )
+    if not loc_wid:
+        return skipped(
+            f"call queue {data.get('name')!r}: location not resolved — "
+            "cannot configure forwarding"
+        )
+    cf: dict[str, Any] = {}
+    always_dest = (
+        data.get("forward_always_destination")
+        or data.get("queue_full_destination")
+    )
+    if always_dest:
+        cf["always"] = {
+            "enabled": True,
+            "destination": always_dest,
+            "ringReminderEnabled": False,
+            "destinationVoicemailEnabled": False,
+        }
+    if not cf:
+        return []
+    body = {"callForwarding": cf}
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/queues/{cq_wid}/callForwarding",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_call_queue_configure_holiday_service(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    cq_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps)
+    if not cq_wid:
+        return skipped(
+            f"call queue {data.get('name')!r} not created — "
+            "cannot configure holiday service"
+        )
+    if not loc_wid:
+        return skipped(
+            f"call queue {data.get('name')!r}: location not resolved — "
+            "cannot configure holiday service"
+        )
+    if not data.get("holiday_service_enabled"):
+        return []
+    body: dict[str, Any] = {
+        "holidayServiceEnabled": True,
+        "action": data.get("holiday_action", "BUSY"),
+        "holidayScheduleLevel": data.get("holiday_schedule_level", "LOCATION"),
+        "holidayScheduleName": data.get("holiday_schedule_name"),
+        "playAnnouncementBeforeEnabled": True,
+        "audioMessageSelection": "DEFAULT",
+    }
+    if data.get("holiday_action") == "TRANSFER" and data.get("holiday_transfer_number"):
+        body["transferPhoneNumber"] = data["holiday_transfer_number"]
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/queues/{cq_wid}/holidayService",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_call_queue_configure_night_service(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    cq_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps)
+    if not cq_wid:
+        return skipped(
+            f"call queue {data.get('name')!r} not created — "
+            "cannot configure night service"
+        )
+    if not loc_wid:
+        return skipped(
+            f"call queue {data.get('name')!r}: location not resolved — "
+            "cannot configure night service"
+        )
+    if not data.get("night_service_enabled"):
+        return []
+    body: dict[str, Any] = {
+        "nightServiceEnabled": True,
+        "action": data.get("night_action", "TRANSFER"),
+        "businessHoursLevel": data.get("night_business_hours_level", "LOCATION"),
+        "businessHoursName": data.get("night_business_hours_name"),
+        "playAnnouncementBeforeEnabled": True,
+        "announcementMode": "NORMAL",
+        "audioMessageSelection": "DEFAULT",
+        "forceNightServiceEnabled": False,
+        "manualAudioMessageSelection": "DEFAULT",
+    }
+    if data.get("night_transfer_number"):
+        body["transferPhoneNumber"] = data["night_transfer_number"]
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/queues/{cq_wid}/nightService",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_call_queue_configure_stranded_calls(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    cq_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps)
+    if not cq_wid:
+        return skipped(
+            f"call queue {data.get('name')!r} not created — "
+            "cannot configure stranded calls"
+        )
+    if not loc_wid:
+        return skipped(
+            f"call queue {data.get('name')!r}: location not resolved — "
+            "cannot configure stranded calls"
+        )
+    if not data.get("no_agent_destination"):
+        return []
+    body: dict[str, Any] = {
+        "action": "TRANSFER",
+        "transferPhoneNumber": data["no_agent_destination"],
+    }
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/queues/{cq_wid}/strandedCalls",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+def handle_auto_attendant_configure_forwarding(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    aa_wid = _find_webex_id(data, deps)
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    if not aa_wid:
+        return skipped(
+            f"auto attendant {data.get('name')!r} not created — "
+            "cannot configure forwarding"
+        )
+    if not loc_wid:
+        return skipped(
+            f"auto attendant {data.get('name')!r}: location not resolved — "
+            "cannot configure forwarding"
+        )
+    if not (data.get("forward_always_enabled") and data.get("forward_always_destination")):
+        return []
+    body = {
+        "callForwarding": {
+            "always": {
+                "enabled": True,
+                "destination": data["forward_always_destination"],
+                "ringReminderEnabled": False,
+                "destinationVoicemailEnabled": False,
+            },
+        },
+    }
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/autoAttendants/{aa_wid}/callForwarding",
+        ctx,
+    )
+    return [("PUT", url, body)]
+
+
+# ---------------------------------------------------------------------------
+# Bulk job handlers (Phase: bulk-operations)
+# Submit jobs that replace per-device operations when device count exceeds
+# the configured threshold. Polling is handled by the engine, not the handler.
+# (from docs/superpowers/specs/2026-04-10-bulk-operations.md §2, §3d)
+# ---------------------------------------------------------------------------
+
+def handle_bulk_device_settings_submit(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Submit a bulk Change Device Settings job for a location.
+
+    POST /v1/telephony/config/jobs/devices/callDeviceSettings
+    (spec §2b)
+    """
+    loc_cid = data.get("location_canonical_id", "")
+    loc_wid = deps.get(loc_cid) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"bulk_device_settings:submit — location {loc_cid!r} not resolved"
+        )
+    body: dict[str, Any] = {
+        "locationId": loc_wid,
+        "locationCustomizationsEnabled": True,
+        "customizations": data.get("customizations", {}),
+    }
+    return [("POST", _url("/telephony/config/jobs/devices/callDeviceSettings", ctx), body)]
+
+
+def handle_bulk_line_key_template_submit(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Submit a bulk Apply Line Key Template job.
+
+    POST /v1/telephony/config/jobs/devices/applyLineKeyTemplate
+    (spec §2a)
+    """
+    template_cid = data.get("template_canonical_id", "")
+    template_wid = deps.get(template_cid)
+    if not template_wid:
+        return skipped(
+            f"bulk_line_key_template:submit — line key template "
+            f"{template_cid!r} not created"
+        )
+    loc_wids = [
+        deps[cid]
+        for cid in data.get("location_canonical_ids", [])
+        if cid in deps and deps[cid]
+    ]
+    body: dict[str, Any] = {
+        "action": "APPLY_TEMPLATE",
+        "templateId": template_wid,
+    }
+    if loc_wids:
+        body["locationIds"] = loc_wids
+    return [("POST", _url("/telephony/config/jobs/devices/applyLineKeyTemplate", ctx), body)]
+
+
+def handle_bulk_dynamic_settings_submit(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Submit a bulk Update Dynamic Device Settings job.
+
+    POST /v1/telephony/config/jobs/devices/dynamicDeviceSettings
+    (spec §2d)
+    """
+    loc_cid = data.get("location_canonical_id", "")
+    loc_wid = deps.get(loc_cid, "") if loc_cid else ""
+    if not loc_wid:
+        return skipped(
+            f"bulk_dynamic_settings:submit — location {loc_cid!r} not resolved"
+        )
+    body: dict[str, Any] = {
+        "locationId": loc_wid,
+        "tags": data.get("tags", []),
+    }
+    return [("POST", _url("/telephony/config/jobs/devices/dynamicDeviceSettings", ctx), body)]
+
+
+def handle_bulk_rebuild_phones_submit(
+    data: dict, deps: dict, ctx: dict,
+) -> HandlerResult:
+    """Submit a bulk Rebuild Phones job for a location.
+
+    POST /v1/telephony/config/jobs/devices/rebuildPhones
+    (spec §2c). Not supported for Webex for Government.
+    """
+    loc_cid = data.get("location_canonical_id", "")
+    loc_wid = deps.get(loc_cid) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"bulk_rebuild_phones:submit — location {loc_cid!r} not resolved"
+        )
+    body: dict[str, Any] = {"locationId": loc_wid}
+    return [("POST", _url("/telephony/config/jobs/devices/rebuildPhones", ctx), body)]
+
+
+def handle_music_on_hold_configure(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Phase A no-op. The op appears in the deployment plan so operators
+    see music_on_hold tracked, but no API call is made. Real per-location
+    MOH configuration + custom audio upload is deferred to Phase B.
+
+    Phase B prerequisites:
+    1. MOHMapper sets location_canonical_id (one object per location)
+    2. MOHMapper writes moh_in_location cross-ref → dependency rule activates
+    3. API_CALL_ESTIMATES["music_on_hold:configure"] updated from 0 to 1
+    4. This handler upgraded to: PUT /telephony/config/locations/{locId}/musicOnHold
+       with greeting=SYSTEM (default) or greeting=CUSTOM + audioFile.id (custom)
+    5. engine.py multipart support for custom audio upload (aiohttp.FormData)
+    """
+    return []
+
+
+def handle_announcement_upload(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Phase A no-op. The AnnouncementMapper creates AUDIO_ASSET_MANUAL
+    decisions for every announcement, so operators already know to manually
+    download/upload. The op exists in the plan for visibility. Real multipart
+    upload is deferred to Phase B alongside engine multipart support.
+
+    Phase B prerequisites:
+    1. AnnouncementMapper sets location_canonical_id (from associated feature's location)
+    2. AnnouncementMapper writes announcement_in_location cross-ref → dependency rule activates
+    3. API_CALL_ESTIMATES["announcement:upload"] updated from 0 to 1
+    4. engine.py multipart support (aiohttp.FormData) for binary WAV upload
+    5. This handler upgraded to: POST /telephony/config/locations/{locId}/announcements
+       with multipart/form-data (name field + binary file field)
+    6. cucm-collect script integration to pre-download audio files from CUCM
+    """
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Tier 5: Executive/assistant pairing
+# (from 2026-04-10-executive-assistant-migration.md §4e)
+# ---------------------------------------------------------------------------
+
+def handle_executive_type_assign(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Set EXECUTIVE type on the executive person.
+
+    PUT /people/{personId}/features/executiveAssistant
+    Scope: spark-admin:people_write
+    (spec §3a)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    person_wid = deps.get(exec_cid) if exec_cid else None
+    if not person_wid:
+        return skipped(
+            f"executive user {exec_cid!r} not resolved — "
+            "cannot set EXECUTIVE type"
+        )
+    return [(
+        "PUT",
+        _url(f"/people/{person_wid}/features/executiveAssistant", ctx),
+        {"type": "EXECUTIVE"},
+    )]
+
+
+def handle_assistant_type_assign(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Set EXECUTIVE_ASSISTANT type on each assistant person.
+
+    PUT /people/{personId}/features/executiveAssistant  (once per assistant)
+    Scope: spark-admin:people_write
+    (spec §3a)
+    """
+    asst_cids = list(data.get("assistant_canonical_ids", []))
+    calls: list[tuple[str, str, dict | None]] = []
+    unresolved: list[str] = []
+    for asst_cid in asst_cids:
+        person_wid = deps.get(asst_cid)
+        if person_wid:
+            calls.append((
+                "PUT",
+                _url(f"/people/{person_wid}/features/executiveAssistant", ctx),
+                {"type": "EXECUTIVE_ASSISTANT"},
+            ))
+        else:
+            unresolved.append(asst_cid)
+    # If assistant_cids were specified but NONE resolved, this is a missing-dep
+    # scenario (all assistant user-creates failed/skipped). Surface it as SKIPPED
+    # so the op doesn't silently look completed. An empty assistant_cids list is
+    # a true no-op (nothing to configure) — keep returning [].
+    if asst_cids and not calls:
+        return skipped(
+            f"assistant_type_assign: none of the {len(unresolved)} assistant(s) "
+            f"resolved ({unresolved!r})"
+        )
+    return calls
+
+
+def handle_executive_assign_assistants(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Pair assistants to the executive.
+
+    PUT /telephony/config/people/{personId}/executive/assignedAssistants
+    Scope: spark-admin:telephony_config_write
+    (spec §3b)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    person_wid = deps.get(exec_cid) if exec_cid else None
+    if not person_wid:
+        return skipped(
+            f"executive user {exec_cid!r} not resolved — "
+            "cannot assign assistants"
+        )
+    asst_cids = list(data.get("assistant_canonical_ids", []))
+    assistants = []
+    unresolved: list[str] = []
+    for asst_cid in asst_cids:
+        asst_wid = deps.get(asst_cid)
+        if asst_wid:
+            assistants.append({"id": asst_wid, "optInEnabled": True})
+        else:
+            unresolved.append(asst_cid)
+    if not assistants:
+        # assistant_cids were specified (or empty). Either way, zero resolved
+        # assistants means we have nothing to pair. If the plan expected at
+        # least one, surface SKIPPED with the unresolved list so this doesn't
+        # look silently completed.
+        if asst_cids:
+            return skipped(
+                f"executive_assign_assistants: none of the {len(unresolved)} "
+                f"assistant(s) resolved ({unresolved!r})"
+            )
+        return []
+    body: dict[str, Any] = {
+        "allowOptInEnabled": True,
+        "assistants": assistants,
+    }
+    return [(
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/executive/assignedAssistants", ctx),
+        body,
+    )]
+
+
+def handle_executive_configure_alert(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure executive alert settings (alerting mode, rollover).
+
+    PUT /telephony/config/people/{personId}/executive/alert
+    Scope: spark-admin:telephony_config_write
+    (spec §3c)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    person_wid = deps.get(exec_cid) if exec_cid else None
+    if not person_wid:
+        return skipped(
+            f"executive user {exec_cid!r} not resolved — "
+            "cannot configure alert settings"
+        )
+    alerting_mode = data.get("alerting_mode", "SIMULTANEOUS")
+    body: dict[str, Any] = {
+        "alertingMode": alerting_mode,
+        "nextAssistantNumberOfRings": 3,
+        "rolloverEnabled": True,
+        "rolloverAction": "VOICE_MESSAGING",
+        "rolloverWaitTimeInSecs": 20,
+        "clidNameMode": "EXECUTIVE_ORIGINATOR",
+        "clidPhoneNumberMode": "EXECUTIVE",
+    }
+    return [(
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/executive/alert", ctx),
+        body,
+    )]
+
+
+def handle_executive_configure_filtering(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure executive call filtering.
+
+    PUT /telephony/config/people/{personId}/executive/callFiltering
+    Scope: spark-admin:telephony_config_write
+    (spec §3d)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    person_wid = deps.get(exec_cid) if exec_cid else None
+    if not person_wid:
+        return skipped(
+            f"executive user {exec_cid!r} not resolved — "
+            "cannot configure call filtering"
+        )
+    if not data.get("filter_enabled"):
+        return []
+    # Map CUCM filter types to Webex filter types
+    _filter_type_map: dict[str, str] = {
+        "ALL_CALLS": "ALL_CALLS",
+        "INTERNAL_ONLY": "ALL_INTERNAL_CALLS",
+        "EXTERNAL_ONLY": "ALL_EXTERNAL_CALLS",
+    }
+    raw_filter_type = data.get("filter_type", "ALL_CALLS")
+    filter_type = _filter_type_map.get(raw_filter_type, "ALL_CALLS")
+    body: dict[str, Any] = {
+        "enabled": True,
+        "filterType": filter_type,
+    }
+    return [(
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/executive/callFiltering", ctx),
+        body,
+    )]
+
+
+def handle_executive_configure_screening(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure executive call screening.
+
+    PUT /telephony/config/people/{personId}/executive/screening
+    Scope: spark-admin:telephony_config_write
+    (spec §3e)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    person_wid = deps.get(exec_cid) if exec_cid else None
+    if not person_wid:
+        return skipped(
+            f"executive user {exec_cid!r} not resolved — "
+            "cannot configure call screening"
+        )
+    if not data.get("screening_enabled"):
+        return []
+    body: dict[str, Any] = {
+        "enabled": True,
+        "alertType": "RING_SPLASH",
+    }
+    return [(
+        "PUT",
+        _url(f"/telephony/config/people/{person_wid}/executive/screening", ctx),
+        body,
+    )]
+
+
+def handle_assistant_configure_settings(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Configure assistant forward/opt-in settings for each assistant.
+
+    PUT /telephony/config/people/{personId}/executive/assistant  (once per assistant)
+    Scope: spark-admin:telephony_config_write
+    (spec §3f)
+    """
+    exec_cid = data.get("executive_canonical_id")
+    exec_wid = deps.get(exec_cid) if exec_cid else None
+
+    asst_cids = list(data.get("assistant_canonical_ids", []))
+    calls: list[tuple[str, str, dict | None]] = []
+    unresolved: list[str] = []
+    for asst_cid in asst_cids:
+        asst_wid = deps.get(asst_cid)
+        if not asst_wid:
+            unresolved.append(asst_cid)
+            continue
+        body: dict[str, Any] = {
+            "forwardFilteredCallsEnabled": False,
+        }
+        if exec_wid:
+            body["executives"] = [{"personId": exec_wid, "optInEnabled": True}]
+        calls.append((
+            "PUT",
+            _url(f"/telephony/config/people/{asst_wid}/executive/assistant", ctx),
+            body,
+        ))
+    # If assistant_cids were specified but NONE resolved, surface SKIPPED so
+    # the op doesn't silently look completed. An empty assistant_cids list is
+    # a true no-op (nothing to configure).
+    if asst_cids and not calls:
+        return skipped(
+            f"assistant_configure_settings: none of the {len(unresolved)} "
+            f"assistant(s) resolved ({unresolved!r})"
+        )
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# DECT Network provisioning (Tier 2/3)
+# ---------------------------------------------------------------------------
+
+def handle_dect_network_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Create a DECT network at a location.
+
+    POST /telephony/config/locations/{locationId}/dectNetworks
+    Body: { name, displayName, model, defaultAccessCodeEnabled, defaultAccessCode }
+    Returns dectNetworkId in response.
+    (from spec §5e — handle_dect_network_create)
+    """
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"DECT network {data.get('network_name') or data.get('display_name')!r}: "
+            "location not resolved — cannot create"
+        )
+
+    name = data.get("network_name") or data.get("display_name")
+    if not name:
+        return []
+
+    access_code = data.get("access_code")
+    body: dict[str, Any] = {
+        "name": name,
+        "displayName": data.get("display_name") or name,
+        "model": data.get("model"),
+        "defaultAccessCodeEnabled": access_code is not None,
+        "defaultAccessCode": access_code,
+    }
+    return [("POST", _url(f"/telephony/config/locations/{loc_wid}/dectNetworks", ctx), body)]
+
+
+def handle_dect_base_station_create(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Register base stations with a DECT network by MAC address.
+
+    POST /telephony/config/locations/{locationId}/dectNetworks/{dectNetworkId}/baseStations
+    Body: { baseStationMacs: [...] }
+    (from spec §5e — handle_dect_base_station_create)
+    """
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"DECT base stations for {data.get('canonical_id')!r}: "
+            "location not resolved"
+        )
+
+    cid = data.get("canonical_id", "")
+    dect_network_wid = deps.get(cid)
+    if not dect_network_wid:
+        return skipped(
+            f"DECT network {cid!r} not created — "
+            "cannot register base stations"
+        )
+
+    # MACs come from base_stations list — each entry has a 'mac' field
+    base_stations = data.get("base_stations") or []
+    macs = [bs["mac"] for bs in base_stations if bs.get("mac")]
+    if not macs:
+        return []
+
+    body: dict[str, Any] = {"baseStationMacs": macs}
+    return [(
+        "POST",
+        _url(
+            f"/telephony/config/locations/{loc_wid}/dectNetworks/{dect_network_wid}/baseStations",
+            ctx,
+        ),
+        body,
+    )]
+
+
+def handle_dect_handset_assign(data: dict, deps: dict, ctx: dict) -> HandlerResult:
+    """Assign handsets to users/workspaces in a DECT network (bulk, batches of 50).
+
+    POST /telephony/config/locations/{locationId}/dectNetworks/{dectNetworkId}/handsets/bulk
+    Body: { items: [ { line1MemberId, customDisplayName, line2MemberId? } ] }
+    (from spec §5e — handle_dect_handset_assign)
+    """
+    loc_wid = _resolve_location(data, deps) or _resolve_location_from_deps(deps)
+    if not loc_wid:
+        return skipped(
+            f"DECT handsets for {data.get('canonical_id')!r}: "
+            "location not resolved"
+        )
+
+    cid = data.get("canonical_id", "")
+    dect_network_wid = deps.get(cid)
+    if not dect_network_wid:
+        return skipped(
+            f"DECT network {cid!r} not created — "
+            "cannot assign handsets"
+        )
+
+    handset_assignments = data.get("handset_assignments") or []
+    items: list[dict[str, Any]] = []
+    for assignment in handset_assignments:
+        owner_cid = assignment.get("user_canonical_id")
+        line1_wid = deps.get(owner_cid) if owner_cid else None
+        if not line1_wid:
+            # Try resolving from line1_canonical_id directly
+            line1_cid = assignment.get("line1_canonical_id")
+            line1_wid = deps.get(line1_cid) if line1_cid else None
+        if not line1_wid:
+            continue
+
+        item: dict[str, Any] = {
+            "line1MemberId": line1_wid,
+            "customDisplayName": assignment.get("display_name", ""),
+        }
+        # Optional line 2 (virtual line or second user)
+        line2_cid = assignment.get("line2_canonical_id")
+        if line2_cid:
+            line2_wid = deps.get(line2_cid)
+            if line2_wid:
+                item["line2MemberId"] = line2_wid
+        items.append(item)
+
+    if not items:
+        return []
+
+    # Batch into groups of 50 (Webex bulk handset API limit)
+    url = _url(
+        f"/telephony/config/locations/{loc_wid}/dectNetworks/{dect_network_wid}/handsets/bulk",
+        ctx,
+    )
+    calls: HandlerResult = []
+    batch_size = 50
+    for i in range(0, len(items), batch_size):
+        batch = items[i : i + batch_size]
+        calls.append(("POST", url, {"items": batch}))
+    return calls
+
+
+# HANDLER_REGISTRY — complete with all operation types
+HANDLER_REGISTRY: dict[tuple[str, str], Any] = {
+    ("location", "create"): handle_location_create,
+    ("location", "enable_calling"): handle_location_enable_calling,
+    ("line_key_template", "create"): handle_line_key_template_create,
+    ("trunk", "create"): handle_trunk_create,
+    ("route_group", "create"): handle_route_group_create,
+    ("route_list", "create"): handle_route_list_create,
+    ("route_list", "configure_numbers"): handle_route_list_configure_numbers,
+    ("operating_mode", "create"): handle_operating_mode_create,
+    ("schedule", "create"): handle_schedule_create,
+    ("user", "create"): handle_user_create,
+    ("workspace", "create"): handle_workspace_create,
+    ("workspace", "assign_number"): handle_workspace_assign_number,
+    ("device", "create"): handle_device_create,
+    ("device", "create_activation_code"): handle_device_create_activation_code,
+    ("dial_plan", "create"): handle_dial_plan_create,
+    ("translation_pattern", "create"): handle_translation_pattern_create,
+    ("hunt_group", "create"): handle_hunt_group_create,
+    ("call_queue", "create"): handle_call_queue_create,
+    ("auto_attendant", "create"): handle_auto_attendant_create,
+    # Feature forwarding / holiday / night service (tier 5)
+    ("hunt_group", "configure_forwarding"): handle_hunt_group_configure_forwarding,
+    ("call_queue", "configure_forwarding"): handle_call_queue_configure_forwarding,
+    ("call_queue", "configure_holiday_service"): handle_call_queue_configure_holiday_service,
+    ("call_queue", "configure_night_service"): handle_call_queue_configure_night_service,
+    ("call_queue", "configure_stranded_calls"): handle_call_queue_configure_stranded_calls,
+    ("auto_attendant", "configure_forwarding"): handle_auto_attendant_configure_forwarding,
+    ("call_park", "create"): handle_call_park_create,
+    ("pickup_group", "create"): handle_pickup_group_create,
+    ("paging_group", "create"): handle_paging_group_create,
+    ("voicemail_group", "create"): handle_voicemail_group_create,
+    ("user", "configure_settings"): handle_user_configure_settings,
+    ("user", "configure_voicemail"): handle_user_configure_voicemail,
+    ("ecbn_config", "configure"): handle_ecbn_config_configure,
+    ("device", "configure_settings"): handle_device_configure_settings,
+    ("workspace", "configure_settings"): handle_workspace_configure_settings,
+    ("calling_permission", "assign"): handle_calling_permission_assign,
+    ("call_forwarding", "configure"): handle_call_forwarding_configure,
+    ("single_number_reach", "configure"): handle_snr_configure,
+    # Tier 6
+    ("monitoring_list", "configure"): handle_monitoring_list_configure,
+    ("receptionist_config", "configure"): handle_receptionist_config_configure,
+    ("shared_line", "configure"): handle_shared_line_configure,
+    ("virtual_line", "create"): handle_virtual_line_create,
+    ("virtual_line", "configure"): handle_virtual_line_configure,
+    # Tier 7
+    ("device_layout", "configure"): handle_device_layout_configure,
+    ("softkey_config", "configure"): handle_softkey_config_configure,
+    # Device settings templates
+    ("device_settings_template", "apply_location_settings"): handle_device_settings_template_apply_location_settings,
+    ("device_settings_template", "apply_device_override"): handle_device_settings_template_apply_device_override,
+    # Hoteling / Hot Desking
+    ("device_profile", "enable_hoteling_guest"): handle_hoteling_guest_enable,
+    ("device_profile", "enable_hoteling_host"): handle_hoteling_host_configure,
+    ("hoteling_location", "enable_hotdesking"): handle_location_hotdesking_enable,
+    # Bulk job handlers
+    ("bulk_device_settings", "submit"): handle_bulk_device_settings_submit,
+    ("bulk_line_key_template", "submit"): handle_bulk_line_key_template_submit,
+    ("bulk_dynamic_settings", "submit"): handle_bulk_dynamic_settings_submit,
+    ("bulk_rebuild_phones", "submit"): handle_bulk_rebuild_phones_submit,
+    # DECT network provisioning
+    ("dect_network", "create"): handle_dect_network_create,
+    ("dect_network", "create_base_stations"): handle_dect_base_station_create,
+    ("dect_network", "assign_handsets"): handle_dect_handset_assign,
+    # Advisory-to-execution bridge (Phase A: no-op placeholders)
+    ("music_on_hold", "configure"): handle_music_on_hold_configure,
+    ("announcement", "upload"): handle_announcement_upload,
+    # Executive/assistant pairing (tier 5)
+    ("executive_assistant", "assign_executive_type"): handle_executive_type_assign,
+    ("executive_assistant", "assign_assistant_type"): handle_assistant_type_assign,
+    ("executive_assistant", "assign_assistants"): handle_executive_assign_assistants,
+    ("executive_assistant", "configure_alert"): handle_executive_configure_alert,
+    ("executive_assistant", "configure_filtering"): handle_executive_configure_filtering,
+    ("executive_assistant", "configure_screening"): handle_executive_configure_screening,
+    ("executive_assistant", "configure_assistant_settings"): handle_assistant_configure_settings,
+}