lda-wf/docs/superpowers/research/2026-06-01-wf-api-extraction-map.md

wf_api Extraction Map

Executive Summary

WorkflowSurfaceHandlers (src/wf_mcp/workflow_surface/handlers.py:104) is a 1,130-line application-service class that owns all workflow-facing operations: capability discovery, artifact CRUD, draft workspace management, deployment validation, and durable run lifecycle. It currently depends on WfMcpService (src/wf_mcp/broker/service/core.py:79) via a single self.service field, but only uses a narrow slice of that 960-line god object.

The extraction seam is clean: WorkflowSurfaceHandlers touches ~6 distinct capabilities of WfMcpService (artifact store, draft store, run store, capability sources, workflow execution, event bus). None of these require MCP transport, connection adapters, or proxy machinery. The class is already used protocol-neutrally by wf_cli via CliContext (src/wf_cli/context.py:14).

Recommended first slice: Option B — introduce a WorkflowApi facade backed by a small WorkflowApiBackend ports object, adapt WfMcpService into it, then move the facade to wf_api. This avoids the large-class move (Option A) and the premature domain split (Option C).

Public Operation Inventory

WorkflowSurfaceHandlers — Public Methods

Method	Line	Category	Input Parameters	Return Shape	Direct Dependencies	Callers/Tests
list_artifacts	110	artifacts	query, kind, cursor, limit	{nodes, next_cursor, total}	self.service.artifact_store, self.service.workflow_artifact_catalog_entry	tools.py:49, artifacts.py:41, test_artifacts.py:11
list_capabilities	147	capabilities	query, source_id, cursor, limit	{capabilities, next_cursor, total}	self.service.capability_sources	tools.py:91, caps.py:41, test_capabilities.py:20
inspect_capability	193	capabilities	qualified_name	capability contract dict	self.service.capability_sources	tools.py:132, caps.py:65, test_capabilities.py:102
call_capability	213	capabilities	qualified_name, payload, deployment_id	{qualified_name, source_id, kind, deployment_id, outcome, output, diagnostics}	self.service._get_qualified_spec, self.service.capability_sources, self.service.run_workflow_from_plan, self.service.artifact_store	tools.py:144, test_capabilities.py:50, test_wrappers.py:69
save_artifact	416	artifacts	artifact dict	{artifact_id, version, saved}	self.service.artifact_store, self.service._record_event	tools.py:162
create_artifact_from_plan	437	artifacts	artifact_id, version, title, plan, outcomes, kind, description, required_capabilities, source_bindings, created_from_catalog_version	{artifact_id, version, saved}	self.service.artifact_store, self.service._record_event	tools.py:186, test_wrappers.py:15
validate_draft	492	drafts	draft dict	{status, diagnostics, compiled_plan}	(none — pure wf_artifacts)	tools.py:170, test_drafts.py:23
compile_draft	498	drafts	draft dict	{compiled_plan, required_capabilities}	self.service (via _required_capabilities_for_plan)	tools.py:178
create_artifact_from_draft	511	drafts/artifacts	artifact_id, version, title, draft, outcomes, kind, description, required_capabilities, source_bindings, created_from_catalog_version	{artifact_id, version, saved, required_logical_sources, suggested_bindings}	self.service.artifact_store, self.service._record_event	tools.py:229, test_drafts.py:61
patch_draft	570	drafts	draft, patch	patched draft dict	(none — pure wf_artifacts)	tools.py:269
list_draft_workspaces	583	draft workspaces	(none)	{workspaces}	self.service.draft_workspace_store	tools.py:280, test_drafts.py
create_draft_workspace	593	draft workspaces	workspace_id, draft, title	workspace summary	self.service.draft_workspace_store	tools.py:293, test_drafts.py
get_draft_workspace	607	draft workspaces	workspace_id, include_draft	workspace summary	self.service.draft_workspace_store	tools.py:309, test_drafts.py
delete_draft_workspace	619	draft workspaces	workspace_id	{workspace_id, deleted, status}	self.service.draft_workspace_store	tools.py:325, test_drafts.py
validate_draft_workspace	627	draft workspaces	workspace_id	workspace summary	self.service.draft_workspace_store	tools.py:360, test_drafts.py
patch_draft_workspace	641	draft workspaces	workspace_id, revision, patch	workspace summary	self.service.draft_workspace_store	tools.py:341, test_drafts.py
set_draft_name	655	draft workspaces	workspace_id, revision, name	workspace summary	(delegates to patch_draft_workspace)	tools.py:372, test_drafts.py
set_draft_route	668	draft workspaces	workspace_id, revision, step_id, outcome, target	workspace summary	(delegates to patch_draft_workspace)	tools.py:386, test_drafts.py
set_step_input_map	692	draft workspaces	workspace_id, revision, step_id, input_map	workspace summary	(delegates to patch_draft_workspace)	tools.py:405, test_drafts.py
set_step_output_map	712	draft workspaces	workspace_id, revision, step_id, output_map	workspace summary	(delegates to patch_draft_workspace)	tools.py:425, test_drafts.py
create_minimal_draft_workspace	732	draft workspaces	workspace_id, name, capability_name, schemas, bindings	workspace summary	self.service.draft_workspace_store (via _draft_store), self.service._get_qualified_spec (via _outcomes_for_capability)	tools.py:446, test_drafts.py
create_draft_workspace_from_capability	802	draft workspaces	workspace_id, capability_name, optional schemas/bindings	workspace summary + wrapper_hints + next_actions	(delegates to inspect_capability + create_minimal_draft_workspace)	tools.py:474, test_drafts.py
create_artifact_from_workspace	847	artifacts	workspace_id, artifact_id, version, title, outcomes, kind, description, required_capabilities, source_bindings, created_from_catalog_version	save result or validation error	self.service.draft_workspace_store	tools.py:502, test_drafts.py
create_wrapper_from_workspace	884	artifacts	same as above (without kind)	save result	(delegates to create_artifact_from_workspace with kind="wrapper")	tools.py:536, test_drafts.py
inspect_artifact	917	artifacts	artifact_id, version	full artifact dict	self.service.artifact_store	tools.py:563, test_artifacts.py:58
list_deployments	925	deployments	(none)	{deployments}	self.service.artifact_store	tools.py:577, test_deployments.py
inspect_deployment	935	deployments	deployment_id	full deployment dict	self.service.artifact_store	tools.py:585, test_deployments.py
save_deployment	942	deployments	deployment dict	{deployment_id, artifact_id, artifact_version, saved}	self.service.artifact_store, self.service._record_event	tools.py:593, test_deployments.py
delete_deployment	965	deployments	deployment_id	{deployment_id, deleted}	self.service.artifact_store, self.service._record_event	tools.py:604, test_deployments.py
validate_deployment	979	deployments	deployment_id, live_check	{deployment_id, artifact_id, artifact_version, status, diagnostics, next_actions}	self.service.artifact_store, self.service.capability_sources, self.service.connections, self.service.adapters, self.service.load_auth	tools.py:617, test_deployments.py:39
run_deployment	1010	runs	deployment_id, workflow_input, trace_range	run payload dict	self.service.artifact_store, self.service.run_workflow_from_plan, self.service.run_store	tools.py:650, test_runs.py:40
resume_run	1074	runs	run_id, resume_payload, resume_outcome, trace_range	run payload dict	self.service.run_store, self.service.resume_workflow_from_plan, self.service.capability_sources	tools.py:681, test_runs.py
inspect_run	1154	runs	run_id	run payload dict	self.service.run_store	tools.py:712, test_runs.py:78
read_run_trace	1172	runs	run_id, trace_range	run payload dict with trace	self.service.run_store	tools.py:722, test_runs.py:79

Private Methods

Method	Line	Notes
_wrapper_artifact_for_capability_name	272	helper for wrapper resolution
_wrapper_capability_summaries	297	projects wrappers into capability discovery
_wrapper_capability_detail	340	NodeSpec-like contract for wrappers
_call_wrapper_artifact	371	executes wrapper through workflow runner
_draft_store	578	accessor for self.service.draft_workspace_store
_outcomes_for_capability	911	delegates to self.service._get_qualified_spec
_run_store	1196	accessor for self.service.run_store
_deployment_validation	1202	shared validation logic for deployment operations

Module-Level Private Helpers

Function	Line	Used By	Dependencies
_available_sources	1238	_deployment_validation, resume_run, _live_source_diagnostics	service.capability_sources
_live_source_diagnostics	1277	validate_deployment	service.connections, service.adapters, service.load_auth
_required_live_sources	1326	_live_source_diagnostics	(pure)
_required_capabilities_for_plan	1341	compile_draft	service (for _observed_node_specs)
_required_capability_payloads	1373	multiple	(pure)
_suggested_self_bindings	1382	create_artifact_from_draft	(pure)
_observed_node_specs	1389	create_artifact_from_plan, create_artifact_from_draft, _required_capabilities_for_plan	service.capability_sources
_schema_field_names	1400	list_capabilities	(pure)
_draft_input_maps	1408	create_minimal_draft_workspace	(pure)
_draft_output_map	1436	create_minimal_draft_workspace	(pure)
_draft_input_bindings_payload	1449	create_minimal_draft_workspace, set_step_input_map	(pure)
_draft_output_bindings_payload	1463	create_minimal_draft_workspace, set_step_output_map	(pure)
_graph_path_payload	1471	multiple	(pure)
_local_path_payload	1476	multiple	(pure)
_state_path_payload	1480	multiple	(pure)
_escape_json_pointer	1484	draft patch helpers	(pure)
_draft_name_from_capability	1489	create_draft_workspace_from_capability	(pure)
_source_id_for_capability	1494	call_capability	(pure)
_capability_name	1505	_available_sources	(pure)
_artifact_capability_id	1516	multiple	(pure)
_raw_plan_from_artifact	1526	run_deployment, resume_run, _call_wrapper_artifact	(pure)
_plan_field	1543	_raw_plan_from_artifact	(pure)
_plan_nodes	1553	_required_capabilities_for_plan	(pure)
_run_payload	1558	run_deployment, resume_run, inspect_run, read_run_trace	(pure)
_interrupt_payload	1608	_run_payload	(pure)
_deployment_summary	1621	list_deployments	(pure)

WfMcpService Dependency Inventory

Members Accessed from WorkflowSurfaceHandlers

Member	Type	Accessed Via	Usage Count	Category
artifact_store	WorkflowArtifactStore | None	self.service.artifact_store	~25	artifact storage
draft_workspace_store	DraftWorkspaceStore | None	self.service.draft_workspace_store	~8	draft storage
run_store	RunStore | None	self.service.run_store	~5	run storage
capability_sources	dict[str, CapabilitySource]	self.service.capability_sources	~8	source/capability inventory
_get_qualified_spec(qualified_name)	NodeSpec	self.service._get_qualified_spec(...)	3	private helper
_record_event(event)	None	self.service._record_event(...)	7	private helper (event bus)
run_workflow_from_plan(...)	RunState	self.service.run_workflow_from_plan(...)	3	workflow execution
resume_workflow_from_plan(...)	RunState	self.service.resume_workflow_from_plan(...)	1	workflow execution
workflow_artifact_catalog_entry(artifact)	WorkflowArtifactCatalogEntry	self.service.workflow_artifact_catalog_entry(...)	1	artifact projection
connections	ConnectionRegistry	self.service.connections	1	MCP-specific (live source check)
adapters	dict[str, BackendAdapter]	self.service.adapters	1	MCP-specific (live source check)
load_auth(connection_id)	AuthRecord | None	self.service.load_auth(...)	1	MCP-specific (live source check)

Source/catalog ownership is now split: WfMcpService coordinates broker runtime state, while SourceCatalogService owns capability source maps, planner catalog projection, snapshot hydration, and local docs lookup.

Workflow runtime ownership is now split: WorkflowRuntimeService owns plan compilation, dependency preparation, run, and resume. WfMcpService remains the broker coordinator and compatibility façade.

Event recording ownership is now split: BrokerEventRecorder owns EventBus publication, simple event construction, event history reads, and catalog-change fanout. WfMcpService remains the coordinator and compatibility façade.

Connection registration/config reload reconciliation is now owned by wf_mcp.broker.service.connection_service.ConnectionService. The service owns the ConnectionRegistry; WfMcpService.connections is only a compatibility property.

WfMcpService Members NOT Used by WorkflowSurfaceHandlers

These members of WfMcpService (src/wf_mcp/broker/service/core.py) are NOT accessed by WorkflowSurfaceHandlers:

• store (MCP catalog/auth storage)
• default_catalog_max_age_seconds
• include_builtin_specs
• tool_executor
• event_bus (only accessed indirectly via _record_event)
• register_connection
• sync_connections_from_config
• register_adapter
• _tool_executor_for
• save_auth
• register_specs
• get_catalog
• get_planner_catalog
• list_sources
• list_source_summaries
• inspect_source
• list_available_specs
• get_connection_snapshot
• connection_statuses
• list_resources
• list_prompts
• get_resource
• get_prompt
• read_resource
• invoke_method
• send_notification
• render_prompt
• _local_documentation_resource
• _local_documentation_prompt
• refresh_connection_catalog
• compile_plan
• _prepare_workflow_runtime
• register_capability_source
• _hydrate_connection_source_from_snapshot
• _spec_from_snapshot_entry
• _record_catalog_change_events

Protocol-Neutral vs MCP-Specific Dependencies

Dependency	Package Today	MCP-Specific?	Should Live In
WorkflowArtifactStore	wf_artifacts	No	wf_artifacts (already there)
DraftWorkspaceStore	wf_artifacts	No	wf_artifacts (already there)
RunStore	wf_artifacts	No	wf_artifacts (already there)
CapabilitySource	wf_platform	No	wf_platform (already there)
EventBus / McpEvent	wf_mcp.events	Renamed but protocol-neutral	wf_api.events or rename to wf_platform.events
make_event	wf_mcp.events	Protocol-neutral	Move to wf_api or wf_platform
matches_query	wf_mcp.shared.listing	Protocol-neutral	wf_api.shared or wf_platform
paged_list_payload	wf_mcp.shared.listing	Protocol-neutral	wf_api.shared or wf_platform
page_items	wf_platform	No	wf_platform (already there)
RawWorkflowPlan	wf_mcp.models	No	wf_api.models or wf_core
ConnectionRegistry	wf_mcp.connections	Yes (MCP connection model)	stays in wf_mcp
ConnectionConfig	wf_mcp.models	Yes (MCP connection model)	stays in wf_mcp
BackendAdapter	wf_mcp.sdk	Yes (MCP adapter protocol)	stays in wf_mcp
require_adapter	wf_mcp.broker.service.adapters	Yes (MCP adapter lookup)	stays in wf_mcp
AuthRecord	wf_mcp.models	Yes (MCP auth model)	stays in wf_mcp
Store / FileStore	wf_mcp.storage	Yes (MCP catalog/auth storage)	stays in wf_mcp
WorkflowArtifact, WorkflowDeployment, etc.	wf_artifacts	No	wf_artifacts (already there)
CapabilityRef, CapabilitySource	wf_platform	No	wf_platform (already there)
NodeSpec, build_async_registry	wf_authoring	No	wf_authoring (already there)
RuntimeContext	wf_core	No	wf_core (already there)
InputBinding, OutputBinding	wf_core.models.steps	No	wf_core (already there)
GraphSourcePath, LocalPath, StatePath	wf_core.paths	No	wf_core (already there)
TraceRange	wf_mcp.workflow_surface.models	No	wf_api.models
NextActions	wf_mcp.workflow_surface.next_actions	No	wf_api.next_actions
SavedSubgraphTree	wf_mcp.workflow_surface.saved_subgraphs	No	wf_api.saved_subgraphs
resolve_runtime_dependencies	wf_mcp.workflow_surface.runtime_dependencies	No	wf_api.runtime_dependencies
wrapper_hints_for_capability	wf_mcp.workflow_surface.wrapper_hints	No	wf_api.wrapper_hints
parse_workflow_surface_capability_id	wf_mcp.workflow_surface.refs	No	wf_api.refs
run_lifecycle helpers	wf_mcp.workflow_surface.run_lifecycle	No	wf_api.run_lifecycle
constants	wf_mcp.workflow_surface.constants	No	wf_api.constants
create_pinned_environment	wf_mcp.workflow_surface.run_lifecycle	No	wf_api.run_lifecycle

Summary Classification

Protocol-neutral (should move to wf_api):

• All wf_artifacts types and functions
• All wf_platform types
• All wf_authoring types
• All wf_core types
• EventBus / McpEvent / make_event (rename from "Mcp" to generic)
• matches_query, paged_list_payload (listing utilities)
• RawWorkflowPlan
• TraceRange, NextActions, SavedSubgraphTree, resolve_runtime_dependencies, wrapper_hints, refs, run_lifecycle, constants

MCP-specific (stays in wf_mcp):

• ConnectionRegistry, ConnectionConfig
• BackendAdapter, require_adapter
• AuthRecord
• Store, FileStore (MCP catalog/auth persistence)
• BrokerConfig, build_service_from_config
• All proxy/MCP transport/session code
• FastMCP tool registration (register_workflow_tools)

Extraction Options

Option A: Move Class First

Move WorkflowSurfaceHandlers to wf_api.service.WorkflowApi, keep same constructor accepting WfMcpService.

Pros:

• Minimal code changes — just move the file, update imports
• Tests keep passing with import-only changes
• No new abstractions

Cons:

• wf_api would still depend on WfMcpService (a wf_mcp type)
• Circular dependency risk: wf_api → wf_mcp → wf_api (if wf_mcp tools import from wf_api)
• Doesn't actually decouple from MCP — just relocates the code
• Makes future FastAPI adapter harder because the service dependency is still monolithic

Option B: Introduce API Facade with Ports (Recommended)

Create WorkflowApi that depends on a smaller WorkflowApiBackend/ports object instead of all WfMcpService, then adapt WfMcpService into that backend.

Pros:

• Clean dependency direction: wf_api → ports/interfaces, wf_mcp → adapts WfMcpService into ports
• wf_cli can also adapt its own backend (or reuse the wf_mcp adapter)
• FastAPI later becomes just another adapter over the same ports
• Testable in isolation — mock the ports
• Incremental: can introduce ports one domain at a time

Cons:

• More upfront work — need to define the port interface
• Risk of over-abstracting if ports are too fine-grained
• Need to decide what WorkflowApiBackend actually exposes

Option C: Split Handlers by Domain First

Split capabilities/drafts/artifacts/deployments/runs into separate classes before moving packages.

Pros:

• Each domain class is smaller and easier to reason about
• Could enable partial extraction (move artifacts first, then drafts, etc.)
• Better separation of concerns regardless of extraction

Cons:

• Large refactor with many test changes
• Still coupled to WfMcpService until ports are introduced
• May create artificial boundaries — some operations span domains (e.g., create_artifact_from_workspace touches both drafts and artifacts)
• Doesn't solve the packaging problem by itself

Recommended First Slice

Option B: Introduce API facade with ports, starting with a minimal port surface.

Why

1. The dependency direction is the core problem. WorkflowSurfaceHandlers currently reaches into WfMcpService for ~6 distinct capabilities. Extracting without ports just moves the coupling.

2. The port surface is small. Looking at the actual accesses, the port interface needs:

   • artifact_store: WorkflowArtifactStore | None
   • draft_workspace_store: DraftWorkspaceStore | None
   • run_store: RunStore | None
   • capability_sources: dict[str, CapabilitySource]
   • get_qualified_spec(qualified_name: str) -> NodeSpec
   • record_event(event: McpEvent) -> None
   • run_workflow_from_plan(plan, input, ...) -> RunState
   • resume_workflow_from_plan(plan, run, ...) -> RunState
   • workflow_artifact_catalog_entry(artifact) -> WorkflowArtifactCatalogEntry

3. The live-source-check (_live_source_diagnostics) is the only MCP-specific operation. It can stay in wf_mcp as an extension or be gated behind a protocol-neutral liveness_check callback.

First Slice Steps

1. Define WorkflowApiBackend protocol in wf_api/backend.py with the ~9 members above.
2. Create WorkflowApi in wf_api/service.py that takes WorkflowApiBackend instead of WfMcpService.
3. Move WorkflowSurfaceHandlers logic into WorkflowApi (rename or keep as alias).
4. Create WfMcpServiceBackendAdapter in wf_mcp that adapts WfMcpService → WorkflowApiBackend.
5. Update wf_mcp.workflow_surface.tools to create WorkflowApi(WfMcpServiceBackendAdapter(service)).
6. Update wf_cli.context to create WorkflowApi(WfMcpServiceBackendAdapter(service)).
7. Move protocol-neutral helpers (matches_query, paged_list_payload, make_event, etc.) to wf_api or wf_platform.
8. Keep register_workflow_tools in wf_mcp (it's the MCP tool registration layer).

Proposed Package Shape

First Slice (extraction)

src/wf_api/
    __init__.py              # public API: WorkflowApi, WorkflowApiBackend
    backend.py               # WorkflowApiBackend protocol
    service.py               # WorkflowApi (renamed WorkflowSurfaceHandlers)
    models.py                # TraceRange, NextActions, RunPayload, etc.
    refs.py                  # parse_workflow_surface_capability_id
    constants.py             # DEFAULT_CALL_STEP_ID, outcomes, etc.
    next_actions.py          # NextActions model
    saved_subgraphs.py       # SavedSubgraphTree, resolve/validate
    run_lifecycle.py         # create_pinned_environment, persist_stopped_run, etc.
    runtime_dependencies.py  # resolve_runtime_dependencies
    wrapper_hints.py         # wrapper_hints_for_capability

Later Slices

src/wf_api/
    shared/
        listing.py           # matches_query, paged_list_payload (or move to wf_platform)
    events.py                # EventBus, make_event (rename from McpEvent)

What Stays in wf_mcp

src/wf_mcp/
    workflow_surface/
        tools.py             # register_workflow_tools (MCP tool registration)
        __init__.py          # re-exports for backward compat
    broker/
        service/
            core.py          # WfMcpService (unchanged)
            adapters.py      # WfMcpServiceBackendAdapter (NEW)
    connections.py            # ConnectionRegistry
    models.py                # ConnectionConfig, AuthRecord, BrokerConfig, CatalogSnapshot
    storage/                 # Store, FileStore
    sdk/                     # BackendAdapter
    events/                  # EventBus, McpEvent (wf_mcp-specific event bus)
    shared/                  # names, errors, pagination (MCP-specific utilities)
    proxy/                   # MCP proxy mounts
    server/                  # MCP server construction
    runtime/                 # ToolExecutor
    admin_surface/           # admin tools

What Stays in wf_cli

src/wf_cli/
    context.py               # CliContext now uses WorkflowApi instead of WorkflowSurfaceHandlers
    commands/                 # unchanged — they call context.handlers.X()

Test Coverage

Tests That Protect the Extraction

Test File	Lines	Coverage Area
tests/wf_mcp/workflow_surface/test_artifacts.py	71	list_artifacts, inspect_artifact, paging, filtering
tests/wf_mcp/workflow_surface/test_capabilities.py	206	list_capabilities, inspect_capability, call_capability, wrapper capabilities
tests/wf_mcp/workflow_surface/test_drafts.py	723	validate_draft, compile_draft, create_artifact_from_draft, draft workspaces (CRUD, patch, name, route, input/output maps), create_minimal_draft_workspace, create_draft_workspace_from_capability, create_artifact_from_workspace, create_wrapper_from_workspace
tests/wf_mcp/workflow_surface/test_deployments.py	282	validate_deployment, live_check, save_deployment, delete_deployment
tests/wf_mcp/workflow_surface/test_runs.py	423	run_deployment, resume_run, inspect_run, read_run_trace, interrupts, reducers, saved subgraphs
tests/wf_mcp/workflow_surface/test_wrappers.py	172	create_artifact_from_plan (wrapper), call_capability (wrapper), logical refs
tests/wf_mcp/workflow_surface/test_next_actions.py	148	NextActions model behavior
tests/wf_mcp/workflow_surface/conftest.py	380	Shared fixtures: handlers(), artifact(), echo_artifact(), echo_draft(), etc.
tests/wf_cli/test_context.py	33	load_cli_context builds service and handlers
tests/wf_cli/test_app.py	88	CLI help output (smoke tests)
tests/wf_cli/test_run_deploy.py	218	CLI deploy validate, run start, run inspect, run trace
tests/wf_cli/test_discovery_lifecycle.py	370	CLI cap list, artifact list, draft create-from-capability, deploy save, render formats
tests/wf_cli/test_explain.py	174	explain command (diagnostic code lookup)
tests/wf_mcp/test_workflow_surface_refs.py	—	parse_workflow_surface_capability_id
tests/wf_mcp/test_workflow_wrapper_hints.py	—	wrapper_hints_for_capability
tests/wf_mcp/test_saved_subgraphs.py	—	SavedSubgraphTree resolution and validation

Missing Tests Needed Before Extraction

• Integration test for WorkflowApi with a mock backend: Verify that WorkflowApi works correctly when given a WorkflowApiBackend that is NOT WfMcpService. This catches accidental coupling.
• Test that wf_cli works with the new WorkflowApi path: The existing test_run_deploy.py uses patch("wf_cli.commands.runs.load_cli_context", ...) — need to verify the patching surface doesn't change unexpectedly.
• Negative test for live-source-check separation: Verify that validate_deployment(live_check=True) still works after the MCP-specific liveness probe is decoupled.

Things To Keep In wf_mcp For Now

• MCP transport/proxy/runtime/session code (src/wf_mcp/proxy/, src/wf_mcp/server/, src/wf_mcp/runtime/)
• FastMCP registration tools (src/wf_mcp/workflow_surface/tools.py — register_workflow_tools)
• Connection adapters (src/wf_mcp/sdk/, src/wf_mcp/broker/service/adapters.py)
• Connection registry (src/wf_mcp/connections.py)
• Broker server construction (src/wf_mcp/broker/server.py, src/wf_mcp/broker/config.py)
• MCP-specific auth (src/wf_mcp/models.py:AuthRecord)
• MCP catalog storage (src/wf_mcp/storage/)
• Admin surface (src/wf_mcp/admin_surface/)
• MCP event bus (src/wf_mcp/events/) — may need a protocol-neutral fork
• Discovery/refresh (src/wf_mcp/broker/discovery.py)

Risks And Open Questions

Circular Import Risks

• Current: wf_mcp.workflow_surface.handlers imports from wf_mcp.broker.service (type-checking only via TYPE_CHECKING). No circular import today.
• After extraction: wf_api.service must NOT import from wf_mcp. The WfMcpServiceBackendAdapter lives in wf_mcp and imports from wf_api. Direction: wf_mcp → wf_api, never reverse.
• Risk: The live_source_diagnostics helper currently imports require_adapter from wf_mcp.broker.service.adapters. This must stay in wf_mcp or be passed as a callback.

Private Method Dependencies

• self.service._get_qualified_spec(qualified_name) — used 3 times. This is a private method on WfMcpService. Must become a port method.
• self.service._record_event(event) — used 7 times. This is a private method. Must become a port method (or the event bus itself becomes a port).

Store Ownership

• wf_artifacts owns workflow store protocols and file-backed implementations.
• wf_api.stores.WorkflowStores groups the artifact, draft workspace, and run stores as protocol-neutral API dependencies.
• MCP config construction creates file-backed workflow stores from BrokerConfig.store_root and injects them into WfMcpService.
• WfMcpService.__post_init__ no longer creates workflow stores from its MCP Store; direct service tests must inject stores when they exercise workflow persistence.
• Future HTTP/API entrypoints should construct or receive the same WorkflowStores bundle instead of importing wf_mcp.

Naming Confusion

• McpEvent / EventBus — the name says "Mcp" but the event system is protocol-neutral. Rename to DomainEvent / EventBus or move to wf_platform.
• WorkflowSurfaceHandlers — the name suggests MCP surface. Rename to WorkflowApi.
• wf_mcp.workflow_surface — the package name implies MCP. The extracted package becomes wf_api.

Tests That Monkeypatch wf_cli.commands.*.load_cli_context

• tests/wf_cli/test_run_deploy.py patches wf_cli.commands.deployments.load_cli_context, wf_cli.commands.runs.load_cli_context
• tests/wf_cli/test_discovery_lifecycle.py patches wf_cli.commands.caps.load_cli_context, tests/wf_cli/test_discovery_lifecycle.py patches multiple command modules
• These patches inject _load_cli_context_with_specs which calls load_cli_context then register_specs. After extraction, load_cli_context will construct WorkflowApi instead of WorkflowSurfaceHandlers. The patches should still work as long as CliContext.handlers remains the same attribute name.

FastAPI Implications

• The WorkflowApiBackend port pattern makes FastAPI trivial: create a FastApiBackendAdapter that provides the same stores/sources/execution without MCP.
• The MCP-specific live-source-check can be an opt-in dependency injected into the API.
• RawWorkflowPlan should move to wf_api.models or wf_core so FastAPI can use it without importing wf_mcp.

Other Weirdness

• WorkflowSurfaceHandlers._wrapper_artifact_for_capability_name uses parse_workflow_surface_capability_id from wf_mcp.workflow_surface.refs. This parser understands the workflow.<id>.v<version> naming convention. It's protocol-neutral and should move to wf_api.refs.
• _available_sources (line 1238) is a module-level function that takes WfMcpService directly. It should take the port interface instead, or become a method on WorkflowApi.
• _live_source_diagnostics (line 1277) is the only function that needs MCP adapters/connections. It should be injected as an optional callback or stay as a wf_mcp extension.

Suggested Next Plan

1. Define the port interface (WorkflowApiBackend) in a new src/wf_api/backend.py. Start with the 9 members identified above.
2. Create WorkflowApi in src/wf_api/service.py by copying WorkflowSurfaceHandlers and changing self.service: WfMcpService to self.backend: WorkflowApiBackend.
3. Create adapter in src/wf_mcp/broker/service/adapters.py (or a new file) that wraps WfMcpService into WorkflowApiBackend.
4. Update consumers (wf_mcp.workflow_surface.tools, wf_cli.context) to use WorkflowApi(WfMcpServiceBackendAdapter(service)).
5. Move protocol-neutral modules (next_actions, saved_subgraphs, run_lifecycle, runtime_dependencies, wrapper_hints, refs, constants, models) to wf_api.
6. Move listing utilities (matches_query, paged_list_payload) to wf_platform or wf_api.shared.
7. Rename event types from McpEvent to DomainEvent (or create a protocol-neutral fork).
8. Run full test suite — all existing tests must pass with import-only changes.
9. Update CliContext to use WorkflowApi instead of WorkflowSurfaceHandlers.
10. Add integration test for WorkflowApi with a mock backend (not WfMcpService).
11. Define store ownership before extracting service construction: remove implicit workflow-store creation from WfMcpService.__post_init__, add config/API hooks for injected stores, and update tests to pass stores explicitly.

Dependency Graph After Extraction

wf_api (new)
  ├── depends on: wf_artifacts, wf_platform, wf_authoring, wf_core
  └── defines: WorkflowApiBackend (protocol), WorkflowApi (implementation)

wf_mcp
  ├── depends on: wf_api, wf_artifacts, wf_platform, wf_authoring, wf_core
  ├── adapts: WfMcpService → WorkflowApiBackend
  ├── registers: FastMCP tools via register_workflow_tools (uses WorkflowApi)
  └── owns: connections, adapters, proxy, server, admin, MCP events, MCP storage

wf_cli
  ├── depends on: wf_api, wf_mcp (for service construction)
  ├── uses: WorkflowApi via CliContext
  └── owns: CLI commands, formatting, I/O