lda-wf/docs/superpowers/research/2026-06-08-extraction-audit/compatibility-shim-retirement-map.md

Compatibility Shim Retirement Map

Date: 2026-06-08 Scope: wf_mcp → wf_sources_mcp re-export shims, wf_mcp → wf_api extraction shims Goal: Decide what can stay indefinitely, what can be deprecated, and what has no callers.

---

Shim Module Inventory

1. Pure Re-export Shims (wf_sources_mcp → wf_mcp)

These modules exist solely to re-export canonical symbols from wf_sources_mcp. No additional logic.

Shim Module	Canonical Module	Re-exported Symbols	Prod Callers	Test Callers
wf_mcp.auth	wf_sources_mcp.auth	AuthRecord, auth_missing_diagnostic, auth_ref_for_connection, connection_auth_diagnostic, mcp_auth_env, mcp_auth_from_neutral, mcp_auth_headers, neutral_auth_from_mcp	wf_mcp.models, wf_mcp.broker.discovery, wf_mcp.broker.service.source_registry_admin	test_auth.py, test_compat_imports.py, service/test_events.py, service/test_upstream_transport.py, workflow_surface/conftest.py, test_stateful_runtime.py, test_support.py, service/conftest.py, test_workflow_wrappers.py, test_broker_server.py, service/test_auth_admin.py
wf_mcp.capabilities	wf_sources_mcp.catalog.entries	CatalogNodeEntry, CatalogPromptEntry, CatalogResourceEntry, DiscoveredPrompt, DiscoveredResource, DiscoveredTool	wf_mcp.broker.discovery (DiscoveredTool), wf_mcp.broker.service.core (via wf_sources_mcp directly)	test_compat_imports.py, service/conftest.py, test_stateful_runtime.py, test_support.py, test_sdk_adapter.py, test_workflow_wrappers.py, service/test_event_recorder.py, workflow_surface/conftest.py, workflow_surface/test_deployments.py, test_deployment_api.py
wf_mcp.catalog.__init__	wf_sources_mcp.catalog (via .models)	CatalogSnapshot, dump_catalog_snapshot	wf_mcp.broker.discovery (DiscoveredTool via wf_sources_mcp directly)	test_compat_imports.py
wf_mcp.catalog.models	wf_sources_mcp.catalog.models	CatalogSnapshot, dump_catalog_snapshot	wf_mcp.models	test_compat_imports.py, test_workflow_config_bridge.py
wf_mcp.sdk.__init__	wf_sources_mcp.sdk	BackendAdapter, McpSdkAdapter, PromptRuntime, ResourceRuntime, StatefulMcpRuntime, ToolCallResult, ToolRuntime	wf_mcp.broker.config, wf_mcp.broker.server, wf_mcp.server.core (all via wf_sources_mcp directly)	test_compat_imports.py, test_sdk_adapter.py, test_deployment_api.py, service/conftest.py, service/test_events.py, test_stateful_runtime.py, test_workflow_wrappers.py, workflow_surface/conftest.py, workflow_surface/test_deployments.py
wf_mcp.sdk.base	wf_sources_mcp.sdk	BackendAdapter, PromptRuntime, ResourceRuntime, StatefulMcpRuntime, ToolCallResult, ToolRuntime	(none - only test_compat_imports)	test_compat_imports.py
wf_mcp.sdk.adapter	wf_sources_mcp.sdk.adapter	McpSdkAdapter	wf_mcp.broker.server, wf_mcp.server.core (via wf_sources_mcp directly)	test_compat_imports.py, test_sdk_adapter.py
wf_mcp.sdk.converters	wf_sources_mcp.sdk.converters	prompt_to_discovered, resource_to_discovered, tool_result_to_call_result, tool_to_discovered, workflow_output_schema_from_mcp_tool_schema	(none - only test_compat_imports)	test_compat_imports.py, test_sdk_converters.py
wf_mcp.storage.__init__	wf_sources_mcp.storage	AuthStore, CatalogStore, FileAuthStore, FileCatalogStore, FileStore, Store	wf_mcp.broker.config, wf_mcp.broker.service.core, wf_mcp.broker.service.auth_admin, wf_mcp.broker.service.upstream_transport (all via wf_sources_mcp directly)	test_compat_imports.py, test_admin_auth_rpc.py, test_mcp_backed_server_rpc.py, test_auth.py, test_store.py, test_mcp_workflow_server.py, service/conftest.py, service/test_upstream_transport.py, service/test_connection_service.py, service/test_catalog.py, service/test_events.py, service/test_auth_admin.py, workflow_surface/conftest.py, workflow_surface/test_runs.py, workflow_surface/test_wrappers.py
wf_mcp.storage.store	wf_sources_mcp.storage.store	AuthStore, CatalogStore, FileAuthStore, FileCatalogStore, FileStore, Store	wf_mcp.broker.service.auth_admin (AuthStore via wf_sources_mcp directly)	test_compat_imports.py
wf_mcp.runtime.factory	wf_sources_mcp.runtime.factory	PersistentSessionFactory	wf_mcp.broker.config (via wf_sources_mcp directly)	test_compat_imports.py, test_stateful_runtime.py
wf_mcp.runtime.pool	wf_sources_mcp.runtime.pool	McpRuntimePool, SessionFactory, connection_runtime_fingerprint	wf_mcp.broker.config (via wf_sources_mcp directly)	test_compat_imports.py, test_stateful_runtime.py
wf_mcp.runtime.session	wf_sources_mcp.runtime.session	PersistentMcpSession, RawToolCaller	(none - only test_compat_imports)	test_compat_imports.py, test_stateful_runtime.py
wf_mcp.runtime.protocols	wf_sources_mcp.sdk	ToolExecutor	(none - only test_compat_imports)	test_compat_imports.py
wf_mcp.broker.catalog	wf_sources_mcp.catalog	CombinedCatalog, snapshot_from_specs	wf_mcp.broker.__init__ (re-exports)	test_compat_imports.py
wf_mcp.broker.service.adapters	wf_sources_mcp.adapters	AdapterLookupRef, LegacyAdapterRef, SourceAdapterRef, require_adapter	wf_mcp.broker.service.upstream_transport (via wf_sources_mcp directly)	test_compat_imports.py
wf_mcp.workflow.wrappers	wf_sources_mcp.tool_wrappers (+ schema_models)	wrap_discovered_tool, _model_from_schema	wf_mcp.workflow.__init__ (re-exports)	test_compat_imports.py, test_workflow_wrappers.py, test_stateful_runtime.py
wf_mcp.workflow.__init__	wf_mcp.workflow.wrappers	wrap_discovered_tool	(none outside wf_mcp)	test_compat_imports.py, test_stateful_runtime.py, test_workflow_wrappers.py

2. Shim + Local Logic (wf_sources_mcp → wf_mcp)

These modules re-export from canonical but also contain additional local code that must be preserved or migrated.

Shim Module	Canonical Module	Local Code	Prod Callers	Test Callers
wf_mcp.connections	wf_sources_mcp.ids	ConnectionRegistry class, qualify_node_name function	wf_mcp.broker.service.core, wf_mcp.broker.service.connection_service, wf_mcp.broker.service.source_registry_admin	test_compat_imports.py, test_store.py, service/test_upstream_transport.py, service/test_connection_service.py, service/test_source_registry_admin.py
wf_mcp.source_registry	wf_sources_mcp.source_registry	registry_entry_to_connection_config, workflow_mcp_source_to_connection_config	wf_mcp.broker.config, wf_mcp.broker.service.connection_service	test_compat_imports.py, test_mcp_workflow_server.py, test_broker_server.py, service/test_connection_service.py, service/test_source_registry_admin.py, test_source_registry.py, server/test_docs.py
wf_mcp.runtime.__init__	wf_sources_mcp.runtime (+ local ToolExecutor)	Re-exports ToolExecutor from wf_sources_mcp.sdk alongside runtime types	wf_mcp.broker.service.core, wf_mcp.broker.service.upstream_transport (via wf_sources_mcp directly)	test_compat_imports.py, service/test_connection_service.py, service/test_events.py, service/test_source_registry_admin.py, test_workflow_wrappers.py
wf_mcp.models	wf_mcp.auth + wf_mcp.broker.models + wf_api.models + wf_sources_mcp.catalog.models	Aggregator shim: re-exports AuthRecord, BrokerConfig, BrokerStoreRoots, ConnectionConfig, SourceConfigOwnership, RawWorkflowPlan, CatalogSnapshot, dump_catalog_snapshot	(none outside wf_mcp)	Heavy: 50+ test files import from this module

3. wf_api Extraction Shims (wf_api → wf_mcp.workflow_surface)

Code extracted from wf_mcp.workflow_surface to wf_api. These shims preserve backward compatibility.

Shim Module	Canonical Module	Re-exported Symbols	Prod Callers	Test Callers
wf_mcp.workflow_surface.run_lifecycle	wf_api.run_lifecycle	create_pinned_environment, has_blocking_diagnostics, load_stored_run, mark_resume_blocked, persist_stopped_run, restore_interrupted_run, validate_pinned_resume_environment	(none outside wf_mcp)	test_run_lifecycle_extraction.py
wf_mcp.workflow_surface.saved_subgraphs	wf_api.saved_subgraphs	SavedSubgraphTree, direct_wrapper_interrupt_diagnostic, prepare_saved_subgraphs, resolve_saved_subgraph_tree, saved_subgraph_tree_from_snapshots, validate_saved_subgraph_tree	(none outside wf_mcp)	test_saved_subgraphs_extraction.py
wf_mcp.workflow_surface.runtime_dependencies	wf_api.runtime_dependencies	RuntimeDependencies, resolve_runtime_dependencies	(none outside wf_mcp)	test_runtime_dependencies_extraction.py
wf_mcp.workflow_surface.next_actions	wf_api.next_actions	NextActionPatchExample, NextActions, NextActionTool	(none outside wf_mcp)	test_next_actions.py (line 164)

---

Analysis: Which Shims Are Still Needed for Public Compatibility

Shims with production callers INSIDE wf_mcp (still needed internally)

These shims are imported by other wf_mcp modules. They are "needed" but the callers could switch to canonical.

Shim	Internal Callers (within wf_mcp)
wf_mcp.auth	wf_mcp.models, wf_mcp.broker.discovery, wf_mcp.broker.service.source_registry_admin
wf_mcp.connections	wf_mcp.broker.service.core, wf_mcp.broker.service.connection_service, wf_mcp.broker.service.source_registry_admin
wf_mcp.source_registry	wf_mcp.broker.config, wf_mcp.broker.service.connection_service
wf_mcp.models	wf_mcp.broker.discovery, wf_mcp.broker.service.core, wf_mcp.broker.service.source_catalog, wf_mcp.broker.service.upstream_transport, wf_mcp.broker.service.connection_service, wf_mcp.broker.service.source_registry_admin
wf_mcp.runtime.__init__	(only test callers)
wf_mcp.workflow.wrappers	wf_mcp.workflow.__init__

Shims with NO production callers (outside wf_mcp and test_compat_imports)

These shims exist solely for the test_compat_imports.py regression suite. They can be deprecated.

Shim	Notes
wf_mcp.sdk.base	Only caller is test_compat_imports.py
wf_mcp.sdk.converters	Only caller is test_compat_imports.py + test_sdk_converters.py
wf_mcp.runtime.protocols	Only caller is test_compat_imports.py
wf_mcp.runtime.session	Only caller is test_compat_imports.py
wf_mcp.storage.store	Only caller is test_compat_imports.py
wf_mcp.broker.service.adapters	Only caller is test_compat_imports.py

---

Which Shims Are Only Used by Tests

Shim	Test-Only Callers
wf_mcp.sdk.base	test_compat_imports.py
wf_mcp.sdk.converters	test_compat_imports.py, test_sdk_converters.py
wf_mcp.runtime.protocols	test_compat_imports.py
wf_mcp.runtime.session	test_compat_imports.py, test_stateful_runtime.py
wf_mcp.storage.store	test_compat_imports.py
wf_mcp.broker.service.adapters	test_compat_imports.py
wf_mcp.workflow_surface.run_lifecycle	test_run_lifecycle_extraction.py
wf_mcp.workflow_surface.saved_subgraphs	test_saved_subgraphs_extraction.py
wf_mcp.workflow_surface.runtime_dependencies	test_runtime_dependencies_extraction.py
wf_mcp.workflow_surface.next_actions	test_next_actions.py (line 164)

---

Which Imports in Production Should Be Switched to Canonical Paths

These are wf_mcp modules (not shims) that import from wf_sources_mcp directly but could instead import through the shim or vice versa. The inconsistency means some internal callers use the shim while the "real" code uses canonical. This is fine architecturally but creates confusion.

Production imports currently going through shims (should switch to canonical)

File	Current Import	Should Import From
wf_mcp.models	from wf_mcp.auth import AuthRecord	from wf_sources_mcp.auth import AuthRecord
wf_mcp.broker.discovery	from ..auth import AuthRecord	from wf_sources_mcp.auth import AuthRecord
wf_mcp.broker.service.source_registry_admin	from ...auth import AuthRecord, connection_auth_diagnostic	from wf_sources_mcp.auth import AuthRecord, connection_auth_diagnostic
wf_mcp.broker.service.source_catalog	from ...connections import ConnectionConfig, qualify_node_name	Keep as-is (ConnectionConfig is broker-specific)
wf_mcp.broker.service.core	from ...connections import ConnectionRegistry	Keep as-is (ConnectionRegistry is broker-specific)
wf_mcp.broker.service.connection_service	from wf_mcp.source_registry import connection_config_to_registry_entry, registry_entry_to_connection_config	Keep as-is (these are broker-specific conversion helpers)
wf_mcp.broker.service.connection_service	from wf_sources_mcp.source_registry import SourceRegistryFile, SourceRegistryStore	Already canonical
wf_mcp.broker.service.events	from wf_sources_mcp.catalog.models import CatalogSnapshot	Already canonical
wf_mcp.broker.config	from wf_sources_mcp.runtime import ...	Already canonical
wf_mcp.broker.config	from wf_sources_mcp.sdk import McpSdkAdapter	Already canonical
wf_mcp.broker.server	from wf_sources_mcp.sdk import McpSdkAdapter	Already canonical
wf_mcp.broker.server	from wf_sources_mcp.source_registry import FileSourceRegistryStore, SourceRegistryStore	Already canonical
wf_mcp.server.core	from wf_sources_mcp.sdk import McpSdkAdapter	Already canonical
wf_mcp.server.core	from wf_sources_mcp.source_registry import FileSourceRegistryStore	Already canonical

Production imports that are already canonical (no change needed)

• wf_mcp.broker.config → wf_sources_mcp.runtime, wf_sources_mcp.sdk, wf_sources_mcp.source_registry, wf_sources_mcp.storage
• wf_mcp.broker.server → wf_sources_mcp.sdk, wf_sources_mcp.source_registry
• wf_mcp.broker.service.core → wf_sources_mcp.auth, wf_sources_mcp.catalog, wf_sources_mcp.sdk, wf_sources_mcp.source_registry, wf_sources_mcp.storage
• wf_mcp.broker.service.source_catalog → wf_sources_mcp.auth, wf_sources_mcp.catalog, wf_sources_mcp.connections, wf_sources_mcp.schema_models, wf_sources_mcp.sdk, wf_sources_mcp.storage
• wf_mcp.broker.service.upstream_transport → wf_sources_mcp.adapters, wf_sources_mcp.auth, wf_sources_mcp.catalog, wf_sources_mcp.connections, wf_sources_mcp.discovery, wf_sources_mcp.sdk, wf_sources_mcp.storage
• wf_mcp.broker.service.auth_admin → wf_sources_mcp.storage
• wf_mcp.broker.service.source_registry_admin → wf_sources_mcp.connections, wf_sources_mcp.source_registry
• wf_mcp.broker.discovery → wf_sources_mcp.catalog, wf_sources_mcp.connections, wf_sources_mcp.discovery, wf_sources_mcp.sdk, wf_sources_mcp.tool_events
• wf_mcp.shared.names → wf_sources_mcp.ids (one constant)
• wf_mcp.workflow.wrappers → wf_sources_mcp.schema_models, wf_sources_mcp.tool_wrappers

---

Recommended Next Cleanup Slice

Slice 1: Switch internal callers to canonical imports (low risk)

Goal: Remove internal wf_mcp code that imports through shims when canonical is available.

1. wf_mcp.models: Change from wf_mcp.auth import AuthRecord → from wf_sources_mcp.auth import AuthRecord
2. wf_mcp.broker.discovery: Change from ..auth import AuthRecord → from wf_sources_mcp.auth import AuthRecord
3. wf_mcp.broker.service.source_registry_admin: Change from ...auth import AuthRecord, connection_auth_diagnostic → from wf_sources_mcp.auth import AuthRecord, connection_auth_diagnostic

These three changes remove the internal dependency chain where wf_mcp.broker.service.* imports through wf_mcp.auth (shim) instead of directly from wf_sources_mcp.auth (canonical).

Slice 2: Deprecate test-only shims

Goal: Mark shims that have NO production callers (only test_compat_imports) as deprecated.

Candidates:

• wf_mcp.sdk.base
• wf_mcp.sdk.converters
• wf_mcp.runtime.protocols
• wf_mcp.runtime.session
• wf_mcp.storage.store
• wf_mcp.broker.service.adapters

These can be marked with a # DEPRECATED: import from wf_sources_mcp directly comment and removed once test_compat_imports.py is updated.

Slice 3: Deprecate wf_api extraction shims

Goal: Mark wf_mcp.workflow_surface.{run_lifecycle, saved_subgraphs, runtime_dependencies, next_actions} as deprecated.

These are already extraction-complete shims. The test files (test_*_extraction.py) verify they point to canonical. They can be removed once no external callers remain.

Slice 4: Consolidate wf_mcp.models (high impact, medium risk)

Goal: wf_mcp.models is the highest-traffic shim (50+ test files). It aggregates AuthRecord, BrokerConfig, ConnectionConfig, CatalogSnapshot, RawWorkflowPlan, etc.

• BrokerConfig, ConnectionConfig, BrokerStoreRoots, SourceConfigOwnership are broker-specific DTOs — they should stay in wf_mcp.broker.models (already canonical).
• AuthRecord comes from wf_sources_mcp.auth via wf_mcp.auth shim.
• CatalogSnapshot, dump_catalog_snapshot come from wf_sources_mcp.catalog.models via wf_mcp.catalog.models shim.
• RawWorkflowPlan comes from wf_api.models.

Recommended: Keep wf_mcp.models as a convenience aggregator for tests, but update the imports within it to use canonical paths. New production code should import from wf_mcp.broker.models or wf_sources_mcp.* directly.

---

Summary Table

Category	Count	Action
Pure re-export shims (wf_sources_mcp)	17 modules	Deprecate test-only ones (6); keep rest for now
Shim + local logic (wf_sources_mcp)	4 modules	Keep (local code is broker-specific)
wf_api extraction shims	4 modules	Deprecate (extraction complete)
Non-shim modules (own implementation)	~30+ modules	No action needed

Total shim modules: 21 Shims with zero production callers: 6 (+ 4 wf_api extraction shims) Shims with internal-only callers: 11 Shims with external (non-wf_mcp) callers: 0 (all external callers are test files)