wxcli 1.2.0__py3-none-any.whl

wxcli/migration/execute/__init__.py

@@ -0,0 +1,303 @@
+"""Execution planning layer — models, constants, and tier assignments.
+
+Defines the data structures for the execution DAG: operations (nodes),
+dependency types (edge labels), broken cycles, and batches. Also contains
+the static tier assignments and API call estimates sourced from
+05-dependency-graph.md.
+
+(from 05-dependency-graph.md — MigrationOp, DependencyType, batch model)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class DependencyType(str, Enum):
+    """Edge types in the dependency DAG.
+    (from 05-dependency-graph.md lines 104-108)
+    """
+    REQUIRES = "requires"       # hard: A must exist before B can be created
+    CONFIGURES = "configures"   # hard: A must be created before settings applied
+    SOFT = "soft"               # breakable: nice-to-have ordering
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+class MigrationOp(BaseModel):
+    """One node in the dependency DAG.
+    (from 05-dependency-graph.md lines 22-32)
+    """
+    canonical_id: str           # links back to objects table
+    op_type: str                # "create", "configure", "assign", etc.
+    resource_type: str          # "location", "user", "device", etc.
+    tier: int                   # from TIER_ASSIGNMENTS
+    batch: str | None = None    # site/batch assignment
+    api_calls: int = 1          # estimated API call count for rate limit budgeting
+    description: str = ""       # human-readable: "Create user jsmith@acme.com"
+    depends_on: list[str] = Field(default_factory=list)  # node_ids this op must wait for
+    payload: dict | None = None  # Bulk ops: handler data that doesn't come from a canonical object
+
+
+class BrokenCycle(BaseModel):
+    """Record of a cycle that was broken during DAG construction.
+    (from 05-dependency-graph.md lines 186-193)
+    """
+    from_node: str
+    to_node: str
+    dep_type: str | None = None
+    reason: str = ""
+
+
+class Batch(BaseModel):
+    """A group of operations to execute together.
+    (from 05-dependency-graph.md lines 244-258)
+    """
+    site: str                   # "org-wide" or a location canonical_id
+    tier: int
+    operations: list[str] = Field(default_factory=list)  # node_ids
+    estimated_api_calls: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Static tier assignments
+# (from 05-dependency-graph.md — tier system lines 79-100, batch ordering
+#  lines 206-216, expand_to_operations example lines 41-74)
+# ---------------------------------------------------------------------------
+
+TIER_ASSIGNMENTS: dict[tuple[str, str], int] = {
+    # Tier 0: Infrastructure — locations created first, then calling enabled
+    ("location", "create"): 0,
+    ("location", "enable_calling"): 0,
+    # Tier 1: Routing backbone — trunks, schedules, route groups, line key templates
+    ("trunk", "create"): 1,
+    ("route_group", "create"): 1,
+    ("route_list", "create"): 1,
+    ("route_list", "configure_numbers"): 1,
+    ("operating_mode", "create"): 1,
+    ("schedule", "create"): 1,
+    ("line_key_template", "create"): 1,
+    # Tier 2: People creation + org-wide routing objects
+    ("user", "create"): 2,
+    ("workspace", "create"): 2,
+    ("dial_plan", "create"): 2,
+    ("translation_pattern", "create"): 2,
+    # calling_permission has no "create" op — permissions are per-user, not standalone
+    # Tier 3: Numbers, devices (Fix 12: license+number folded into create)
+    ("workspace", "assign_number"): 3,
+    ("device", "create"): 3,
+    ("device", "create_activation_code"): 3,
+    # Tier 4: Call features (depend on users/workspaces existing)
+    ("hunt_group", "create"): 4,
+    ("call_queue", "create"): 4,
+    ("auto_attendant", "create"): 4,
+    ("call_park", "create"): 4,
+    ("pickup_group", "create"): 4,
+    ("paging_group", "create"): 4,
+    ("voicemail_group", "create"): 4,
+    # Tier 5: Settings configuration (depends on licensed users)
+    ("user", "configure_settings"): 5,
+    ("user", "configure_voicemail"): 5,
+    ("workspace", "configure_settings"): 5,
+    ("device", "configure_settings"): 5,
+    ("calling_permission", "assign"): 5,
+    ("call_forwarding", "configure"): 5,
+    ("single_number_reach", "configure"): 5,
+    # Feature forwarding/holiday/night service configuration
+    # (from 2026-04-10-feature-forwarding-night-service.md)
+    ("hunt_group", "configure_forwarding"): 5,
+    ("call_queue", "configure_forwarding"): 5,
+    ("call_queue", "configure_holiday_service"): 5,
+    ("call_queue", "configure_night_service"): 5,
+    ("call_queue", "configure_stranded_calls"): 5,
+    ("auto_attendant", "configure_forwarding"): 5,
+    ("ecbn_config", "configure"): 5,
+    # Tier 6: Shared/virtual lines + monitoring (depend on users + devices)
+    ("shared_line", "configure"): 6,
+    ("virtual_line", "create"): 6,
+    ("virtual_line", "configure"): 6,
+    ("monitoring_list", "configure"): 6,
+    ("receptionist_config", "configure"): 6,
+    # Tier 7: Device finalization + cycle fixups
+    # NOTE: tier 7 is shared between device finalization and cycle-break fixups.
+    # Fixups use batch="fixups"; device ops use location-derived batches — no conflict.
+    ("device_layout", "configure"): 7,
+    ("softkey_config", "configure"): 7,
+    # Device settings templates — location-level config at tier 1, per-device overrides at tier 5
+    ("device_settings_template", "apply_location_settings"): 1,
+    ("device_settings_template", "apply_device_override"): 5,
+    # Hoteling / Hot Desking (depends on users + devices)
+    ("device_profile", "enable_hoteling_guest"): 5,
+    ("device_profile", "enable_hoteling_host"): 5,
+    ("hoteling_location", "enable_hotdesking"): 0,  # Same tier as location:enable_calling
+    # Bulk job operations (Phase: bulk-operations)
+    ("bulk_device_settings", "submit"): 5,
+    ("bulk_line_key_template", "submit"): 7,
+    ("bulk_dynamic_settings", "submit"): 7,
+    ("bulk_rebuild_phones", "submit"): 8,  # Tier 8: runs after all device finalization
+    # DECT network provisioning (depends on location, users/workspaces)
+    ("dect_network", "create"): 2,              # Create DECT network at location
+    ("dect_network", "create_base_stations"): 2,  # Register base stations with MACs
+    ("dect_network", "assign_handsets"): 3,     # Assign handsets (after users/workspaces created)
+    # Advisory-to-execution bridge (Phase A: no-op placeholders)
+    ("music_on_hold", "configure"): 5,   # Settings tier — location must exist + calling enabled
+    ("announcement", "upload"): 1,       # Routing backbone — features reference announcements
+    # Executive/assistant pairing (from 2026-04-10-executive-assistant-migration.md §4e)
+    # Type assignments must precede pairing; pairing must precede alert/filtering/screening.
+    # Steps 4-7 (alert, filtering, screening, assistant settings) can run in parallel after step 3.
+    ("executive_assistant", "assign_executive_type"): 5,
+    ("executive_assistant", "assign_assistant_type"): 5,
+    ("executive_assistant", "assign_assistants"): 5,
+    ("executive_assistant", "configure_alert"): 5,
+    ("executive_assistant", "configure_filtering"): 5,
+    ("executive_assistant", "configure_screening"): 5,
+    ("executive_assistant", "configure_assistant_settings"): 5,
+}
+
+# ---------------------------------------------------------------------------
+# API call estimates per operation
+# (from 05-dependency-graph.md lines 268-281)
+# ---------------------------------------------------------------------------
+
+API_CALL_ESTIMATES: dict[str, int] = {
+    # Tier 0: Infrastructure
+    "location:create": 1,           # POST /locations (from provisioning.md)
+    "location:enable_calling": 1,   # POST /telephony/config/locations (Fix 13)
+    # Tier 1: Routing backbone + org-wide infrastructure
+    "trunk:create": 1,              # POST /telephony/config/premisePstn/trunks (from call-routing.md)
+    "route_group:create": 1,        # POST /telephony/config/premisePstn/routeGroups (from call-routing.md)
+    "route_list:create": 1,              # POST /telephony/config/premisePstn/routeLists
+    "route_list:configure_numbers": 1,   # PUT /telephony/config/premisePstn/routeLists/{id}/numbers
+    "operating_mode:create": 1,     # POST /telephony/config/operatingModes (from location-call-settings-media.md)
+    "schedule:create": 1,           # POST /telephony/config/locations/{id}/schedules (from location-call-settings-media.md)
+    "line_key_template:create": 1,  # POST /telephony/config/devices/lineKeyTemplates
+    # Tier 2: People + org-wide routing
+    "user:create": 1,               # POST /people (from provisioning.md) — Fix 12: includes license + extension
+    "user:configure_settings": 5,   # ~5 PUT calls: callForwarding, callerId, callWaiting, doNotDisturb,
+                                    # + 1 more (monitoring/recording/intercept) (from person-call-settings-*.md)
+    "user:configure_voicemail": 1,  # PUT /people/{id}/features/voicemail (from person-call-settings-media.md)
+    "workspace:create": 1,          # POST /workspaces with calling config (from devices-workspaces.md)
+    "workspace:assign_number": 1,   # PUT number assignment if DID needed beyond extension in create
+                                    # (from devices-workspaces.md Raw HTTP section)
+    "workspace:configure_settings": 3,  # ~3 PUT calls: callForwarding, callWaiting, callerId
+                                        # (from devices-workspaces.md Workspace Call Settings section)
+    "device:create": 1,             # POST /devices by MAC or POST /devices/activationCode
+                                    # (from devices-core.md lines 1312-1323, 1304-1308)
+    "device:create_activation_code": 1,  # POST /devices/activationCode (from devices-core.md)
+    "device:configure_settings": 1, # PUT /telephony/config/devices/{id}/settings (from devices-core.md)
+    "dial_plan:create": 1,          # POST /telephony/config/premisePstn/dialPlans (from call-routing.md)
+    "translation_pattern:create": 1,  # POST /telephony/config/callRouting/translationPatterns (from call-routing.md)
+    "calling_permission:create": 0,   # logical grouping only — no standalone API (from person-call-settings-permissions.md)
+    "calling_permission:assign": 1,   # PUT /people/{id}/features/outgoingPermission per user
+                                      # (from person-call-settings-permissions.md line 401)
+    "call_forwarding:configure": 1,   # PUT /people/{id}/features/callForwarding
+    "single_number_reach:configure": 2,  # PUT SNR enable + POST per number
+    # Feature forwarding/holiday/night service configuration
+    "hunt_group:configure_forwarding": 1,         # PUT .../huntGroups/{id}/callForwarding
+    "call_queue:configure_forwarding": 1,         # PUT .../queues/{id}/callForwarding
+    "call_queue:configure_holiday_service": 1,    # PUT .../queues/{id}/holidayService
+    "call_queue:configure_night_service": 1,      # PUT .../queues/{id}/nightService
+    "call_queue:configure_stranded_calls": 1,     # PUT .../queues/{id}/strandedCalls
+    "auto_attendant:configure_forwarding": 1,     # PUT .../autoAttendants/{id}/callForwarding
+    "ecbn_config:configure": 1,  # PUT /telephony/config/{kind}/{id}/emergencyCallbackNumber
+    # Tier 4: Call features
+    "hunt_group:create": 1,         # POST /telephony/config/locations/{id}/huntGroups
+                                    # agents optional at create (from call-features-major.md line 894)
+    "call_queue:create": 1,         # POST /telephony/config/locations/{id}/queues
+                                    # (from call-features-major.md lines 616-627)
+    "auto_attendant:create": 1,     # POST /telephony/config/locations/{id}/autoAttendants — menu is part of
+                                    # the create body, not a separate PUT (from call-features-major.md line 184)
+    "call_park:create": 1,          # POST /telephony/config/locations/{id}/callParks (from call-features-additional.md)
+    "pickup_group:create": 1,       # POST /telephony/config/locations/{id}/callPickups (from call-features-additional.md)
+    "paging_group:create": 1,       # POST /telephony/config/locations/{id}/paging (from call-features-additional.md)
+    "voicemail_group:create": 1,    # POST /telephony/config/locations/{id}/voicemailGroups
+    # Tier 6: Shared/virtual lines + monitoring
+    "shared_line:configure": 2,     # Approximate — one PUT per owner to /people/{id}/applications/members
+                                    # (from person-call-settings-behavior.md §4)
+    "virtual_line:create": 1,       # POST /telephony/config/virtualLines (from virtual-lines.md lines 93-104)
+    "virtual_line:configure": 1,    # PUT /telephony/config/virtualLines/{id} (from virtual-lines.md lines 132-147)
+    "monitoring_list:configure": 1,
+    "receptionist_config:configure": 2,  # PUT reception + POST directory # PUT /people/{id}/features/monitoring
+    # Tier 7: Device finalization
+    "device_layout:configure": 3,   # PUT members + PUT layout + POST applyChanges
+    "softkey_config:configure": 2,  # PUT dynamicSettings + POST applyChanges
+    # Device settings templates
+    "device_settings_template:apply_location_settings": 1,  # PUT /telephony/config/locations/{id}/devices/settings
+    "device_settings_template:apply_device_override": 1,    # PUT /telephony/config/devices/{id}/settings
+    # Hoteling / Hot Desking
+    "device_profile:enable_hoteling_guest": 1,  # PUT /people/{id}/features/hoteling
+    "device_profile:enable_hoteling_host": 1,   # PUT /telephony/config/people/{id}/devices/settings/hoteling
+    "hoteling_location:enable_hotdesking": 1,   # PUT /telephony/config/locations/{id}/features/hotDesking
+    # Bulk job operations (submit=1 + ~5-10 polling calls; conservatively estimated at 10)
+    "bulk_device_settings:submit": 10,
+    "bulk_line_key_template:submit": 10,
+    "bulk_dynamic_settings:submit": 10,
+    "bulk_rebuild_phones:submit": 10,
+    # DECT network provisioning
+    "dect_network:create": 1,              # POST /telephony/config/locations/{id}/dectNetworks
+    "dect_network:create_base_stations": 1,  # POST /telephony/config/locations/{id}/dectNetworks/{id}/baseStations
+    "dect_network:assign_handsets": 1,     # POST /telephony/config/locations/{id}/dectNetworks/{id}/handsets
+    # Advisory-to-execution bridge (Phase A: no-op placeholders, 0 API calls)
+    "music_on_hold:configure": 0,
+    "announcement:upload": 0,
+    # Executive/assistant pairing
+    "executive_assistant:assign_executive_type": 1,   # PUT /people/{id}/features/executiveAssistant
+    "executive_assistant:assign_assistant_type": 2,   # PUT per assistant (typically 1-3)
+    "executive_assistant:assign_assistants": 1,        # PUT /telephony/config/people/{id}/executive/assignedAssistants
+    "executive_assistant:configure_alert": 1,          # PUT /telephony/config/people/{id}/executive/alert
+    "executive_assistant:configure_filtering": 1,      # PUT /telephony/config/people/{id}/executive/callFiltering
+    "executive_assistant:configure_screening": 1,      # PUT /telephony/config/people/{id}/executive/screening
+    "executive_assistant:configure_assistant_settings": 2,  # PUT per assistant /executive/assistant
+}
+
+# ---------------------------------------------------------------------------
+# Org-wide resource types — these go into the "org-wide" batch, not per-site
+# (from 05-dependency-graph.md batch ordering lines 206-216)
+# ---------------------------------------------------------------------------
+
+ORG_WIDE_TYPES: set[str] = {
+    "location",
+    "trunk",
+    "route_group",
+    "route_list",
+    "operating_mode",
+    "dial_plan",
+    "translation_pattern",
+    "calling_permission",
+    "line_key_template",    # Org-scoped; not tied to a specific location
+}
+
+# ---------------------------------------------------------------------------
+# Bulk job support
+# (from docs/superpowers/specs/2026-04-10-bulk-operations.md §3a, §4c)
+# ---------------------------------------------------------------------------
+
+BULK_DEVICE_THRESHOLD_DEFAULT: int = 100
+
+# Resource types whose ops must run sequentially within a tier, not via
+# asyncio.gather(). Driven by Webex's one-job-per-org constraint for these
+# job families (spec §4c, §5a).
+SERIALIZED_RESOURCE_TYPES: set[str] = {
+    "bulk_device_settings",
+    "bulk_line_key_template",
+    "bulk_dynamic_settings",
+    "bulk_rebuild_phones",
+}
+
+# Maps internal bulk resource_type to the Webex jobType path segment used
+# for polling and error-fetch URLs:
+# GET /v1/telephony/config/jobs/devices/{jobType}/{jobId}[/errors]
+BULK_JOB_TYPES: dict[str, str] = {
+    "bulk_device_settings": "callDeviceSettings",
+    "bulk_line_key_template": "applyLineKeyTemplate",
+    "bulk_dynamic_settings": "dynamicDeviceSettings",
+    "bulk_rebuild_phones": "rebuildPhones",
+}

wxcli/migration/execute/batch.py

@@ -0,0 +1,277 @@
+"""Batch partitioning — split the DAG into executable batches.
+
+Two-level partitioning:
+1. Org-wide vs site-specific (based on batch assignment on each node)
+2. Within each group, split by tier
+
+Batch ordering:
+1. org-wide tiers 0-1 (locations, trunks, schedules, route groups)
+2. org-wide tier 2 (dial plans, calling permissions)
+3. Per-site tiers 2-6 (users, devices, features, settings)
+4. Fixups tier 7 (broken cycle fixups)
+
+(from 05-dependency-graph.md lines 202-261)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+from collections import defaultdict
+
+import networkx as nx
+
+from wxcli.migration.execute import Batch, DependencyType
+
+logger = logging.getLogger(__name__)
+
+
+def partition_into_batches(
+    G: nx.DiGraph,
+    rate_limit_per_minute: int = 100,
+) -> list[Batch]:
+    """Partition the DAG into executable batches.
+
+    Batches are ordered: org-wide first, then per-site, then fixups.
+    Within each group, split by tier. Returns a list of Batch objects
+    with estimated API call counts and timing.
+
+    (from 05-dependency-graph.md lines 221-258)
+    """
+    # Separate nodes by batch assignment
+    org_wide_nodes: list[str] = []
+    fixup_nodes: list[str] = []
+    site_nodes: dict[str, list[str]] = defaultdict(list)
+
+    for node in nx.topological_sort(G):
+        batch = G.nodes[node].get("batch")
+
+        if batch == "fixups":
+            fixup_nodes.append(node)
+        elif batch is None or batch == "org-wide":
+            org_wide_nodes.append(node)
+        else:
+            site_nodes[batch].append(node)
+
+    batches: list[Batch] = []
+
+    # 1. Org-wide batches first, split by tier
+    batches.extend(_split_by_tier(org_wide_nodes, G, "org-wide"))
+
+    # 2. Per-site batches, sorted by site name for determinism
+    for site in sorted(site_nodes.keys()):
+        batches.extend(_split_by_tier(site_nodes[site], G, site))
+
+    # 3. Fixup batch last
+    if fixup_nodes:
+        batches.extend(_split_by_tier(fixup_nodes, G, "fixups"))
+
+    # Log summary
+    total_ops = sum(len(b.operations) for b in batches)
+    total_api = sum(b.estimated_api_calls for b in batches)
+    logger.info(
+        "Partitioned %d operations into %d batches "
+        "(estimated %d API calls, ~%d min at %d req/min)",
+        total_ops,
+        len(batches),
+        total_api,
+        math.ceil(total_api / rate_limit_per_minute) if total_api else 0,
+        rate_limit_per_minute,
+    )
+
+    return batches
+
+
+def _split_by_tier(
+    nodes: list[str],
+    G: nx.DiGraph,
+    site: str,
+) -> list[Batch]:
+    """Split a set of nodes into one batch per tier.
+
+    (from 05-dependency-graph.md lines 244-258)
+    """
+    by_tier: dict[int, list[str]] = defaultdict(list)
+    for n in nodes:
+        tier = G.nodes[n].get("tier", 0)
+        by_tier[tier].append(n)
+
+    batches = []
+    for tier in sorted(by_tier.keys()):
+        tier_nodes = by_tier[tier]
+        api_calls = sum(G.nodes[n].get("api_calls", 1) for n in tier_nodes)
+        batches.append(Batch(
+            site=site,
+            tier=tier,
+            operations=tier_nodes,
+            estimated_api_calls=api_calls,
+        ))
+
+    return batches
+
+
+def format_batch_plan(
+    batches: list[Batch],
+    rate_limit_per_minute: int = 100,
+) -> str:
+    """Format a human-readable execution plan from batches.
+
+    (from 05-dependency-graph.md lines 285-295 — plan output format)
+    """
+    if not batches:
+        return "No batches to execute."
+
+    lines: list[str] = ["Execution Plan", "=" * 60]
+
+    total_api = 0
+    for batch in batches:
+        total_api += batch.estimated_api_calls
+        est_minutes = math.ceil(batch.estimated_api_calls / rate_limit_per_minute) if batch.estimated_api_calls else 0
+
+        # Count operations by type
+        op_counts: dict[str, int] = defaultdict(int)
+        for node_id in batch.operations:
+            # node_id format: "canonical_id:op_type"
+            parts = node_id.rsplit(":", 1)
+            if len(parts) == 2:
+                op_counts[parts[1]] += 1
+            else:
+                op_counts["unknown"] += 1
+
+        op_summary = ", ".join(
+            f"{count} {op_type}" for op_type, count in sorted(op_counts.items())
+        )
+
+        lines.append(f"\nBatch: {batch.site} / tier {batch.tier}")
+        lines.append(f"  Operations: {op_summary}")
+        lines.append(f"  Estimated API calls: {batch.estimated_api_calls}")
+        if est_minutes > 0:
+            lines.append(f"  Estimated time at {rate_limit_per_minute} req/min: ~{est_minutes} minutes")
+
+    total_minutes = math.ceil(total_api / rate_limit_per_minute) if total_api else 0
+    lines.append(f"\n{'=' * 60}")
+    lines.append(f"Total: {sum(len(b.operations) for b in batches)} operations, "
+                 f"{total_api} API calls, ~{total_minutes} minutes")
+
+    return "\n".join(lines)
+
+
+def save_plan_to_store(
+    G: nx.DiGraph,
+    store: "MigrationStore",
+) -> None:
+    """Persist the execution plan (operations + edges) to SQLite.
+
+    Writes to plan_operations and plan_edges tables. Clears any
+    existing plan data first (idempotent re-planning).
+
+    (from 05-dependency-graph.md lines 300-327 — plan_operations + plan_edges tables)
+    """
+    conn = store.conn
+
+    # Clear existing plan (edges first — FK constraint)
+    conn.execute("DELETE FROM plan_edges")
+    conn.execute("DELETE FROM plan_operations")
+
+    # Write operations
+    for node_id in G.nodes():
+        node = G.nodes[node_id]
+        payload = node.get("payload")
+        data_json = json.dumps(payload) if payload else None
+        cid = node.get("canonical_id", "")
+        # Bulk ops have synthetic canonical_ids not in the objects table.
+        # Insert a placeholder row so the FK constraint is satisfied.
+        if payload and cid:
+            conn.execute(
+                """INSERT OR IGNORE INTO objects
+                   (canonical_id, object_type, status, data, created_at, updated_at)
+                   VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))""",
+                (cid, node.get("resource_type", "bulk_job"), "analyzed",
+                 data_json),
+            )
+        conn.execute(
+            """INSERT INTO plan_operations
+               (node_id, canonical_id, op_type, resource_type, tier, batch,
+                api_calls, description, status, data_json)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                node_id,
+                node.get("canonical_id", ""),
+                node.get("op_type", ""),
+                node.get("resource_type", ""),
+                node.get("tier", 0),
+                node.get("batch"),
+                node.get("api_calls", 1),
+                node.get("description", ""),
+                "pending",
+                data_json,
+            ),
+        )
+
+    # Write edges
+    for u, v, data in G.edges(data=True):
+        dep_type = data.get("type", DependencyType.CONFIGURES)
+        dep_type_str = dep_type.value if hasattr(dep_type, "value") else str(dep_type)
+        conn.execute(
+            """INSERT OR IGNORE INTO plan_edges (from_node, to_node, dep_type, broken)
+               VALUES (?, ?, ?, ?)""",
+            (u, v, dep_type_str, 0),
+        )
+
+    conn.commit()
+
+    total_ops = G.number_of_nodes()
+    total_edges = G.number_of_edges()
+    logger.info("Saved plan to SQLite: %d operations, %d edges", total_ops, total_edges)
+
+
+def load_plan_from_store(store: "MigrationStore") -> nx.DiGraph:
+    """Reconstruct the NetworkX DiGraph from SQLite plan tables.
+
+    The tables are the source of truth; the in-memory graph is a working view.
+
+    (from 05-dependency-graph.md line 328)
+    """
+    G = nx.DiGraph()
+    conn = store.conn
+
+    # Load nodes
+    rows = conn.execute(
+        """SELECT node_id, canonical_id, op_type, resource_type, tier, batch,
+                  api_calls, description, status
+           FROM plan_operations"""
+    ).fetchall()
+    for row in rows:
+        G.add_node(
+            row["node_id"],
+            canonical_id=row["canonical_id"],
+            op_type=row["op_type"],
+            resource_type=row["resource_type"],
+            tier=row["tier"],
+            batch=row["batch"],
+            api_calls=row["api_calls"],
+            description=row["description"],
+            status=row["status"],
+        )
+
+    # Load edges
+    edge_rows = conn.execute(
+        "SELECT from_node, to_node, dep_type, broken FROM plan_edges"
+    ).fetchall()
+    for row in edge_rows:
+        _valid_values = {e.value for e in DependencyType}
+        dep_type = DependencyType(row["dep_type"]) if row["dep_type"] in _valid_values else row["dep_type"]
+        G.add_edge(
+            row["from_node"],
+            row["to_node"],
+            type=dep_type,
+            broken=bool(row["broken"]),
+        )
+
+    logger.info(
+        "Loaded plan from SQLite: %d operations, %d edges",
+        G.number_of_nodes(),
+        G.number_of_edges(),
+    )
+    return G