docs: record workflow api surface and rpc split

docs/current_roadmap.md

@@ -38,8 +38,10 @@ implementation state.
      sources, docs/resources, and admin-only control surfaces.
 
 6. **Workflow API seam**
-   - `wf_api.WorkflowApi` is now the process-local application-facing workflow
+   - `wf_api.WorkflowApiSurface` is now the protocol-neutral workflow operation
-     API used by both CLI commands and MCP workflow tools.
+     contract consumed by CLI and transport adapters.
+   - `wf_api.WorkflowApi` is the process-local implementation used by MCP
+     workflow tools and local CLI/server composition.
    - `wf_api` imports no `wf_mcp` modules. `WorkflowApi` composes domain
      services directly from `WorkflowOperationContext`; MCP owns only context
      construction and tool schemas.
@@ -83,25 +85,30 @@ implementation state.
    - Keep config/store construction and auth explicit.
    - Current design direction is recorded in
      [2026-06-03 long-lived workflow API boundary](./superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md):
-     first slice should prove a lightweight local/static server that constructs
+     initial slices proved a lightweight local/static server and JSON-RPC
-     `WorkflowApi` without `WfMcpService`; later slices add remote CLI targeting,
+     transport; later slices add transport siblings, source providers, auth,
-     JSON-RPC-over-HTTP first transport, remote CLI targeting, WebSocket/MCP
+     streaming/progress, transactional storage, and live upstream MCP sources.
-     transport siblings, source providers, auth, streaming/progress,
-     transactional storage, and live upstream MCP sources.
    - First slice implemented: `wf_server` can construct a local/static durable
-      `WorkflowApi` without `WfMcpService`. Transport adapters remain future work.
+     `WorkflowApi` without `WfMcpService`.
-    - Completed: the first JSON-RPC-over-HTTP transport can expose the local/static
+   - Completed: the first JSON-RPC-over-HTTP transport can expose the
-      `WorkflowServer` through fixed dotted methods. Remote CLI targeting remains
+     local/static `WorkflowServer` through fixed dotted methods.
-      the next transport-facing slice.
    - Completed: workflow config now distinguishes client targets from server
       hosting config, the basic `wf` lifecycle can target JSON-RPC HTTP:
       capability discovery, draft workspace authoring, artifact/deployment
       operations, run, inspect, and bounded trace.
+   - Completed: `wf_transport_rpc_http` is split by workflow domain. The
+      public `RpcWorkflowApiClient` still satisfies `WorkflowApiSurface`, while
+      client methods and server JSON-RPC registrations live in focused
+      capability, draft, artifact, deployment, and run modules.
 
 5. **CLI/API alignment**
-   - Let the CLI target either local process-backed stores/runtime or the future
+   - Completed for the basic lifecycle: selected `wf` commands can target local
-     HTTP API backend.
+     process-backed stores/runtime or JSON-RPC HTTP through the same
-   - Preserve the current local CLI path until the API backend is proven.
+     `WorkflowApiSurface`.
+   - Audit remaining local-only commands and keep `load_local_cli_context`
+     limited to commands that genuinely require same-process access.
+   - Preserve the current local CLI path until server source registry/auth/admin
+     operations are proven remotely.
 
 6. **Workflow primitive polish**
    - Return to native subgraph polish, fork/gather, foreach follow-ups, and graph

docs/wf_api_architecture.md

@@ -15,10 +15,11 @@ frontends can share.
 | `wf_core` | Workflow execution semantics: graph models, runtime state, scheduler, path/state mapping, interrupts, subgraphs, foreach, and run-state codec. |
 | `wf_artifacts` | Saved definitions and persistence contracts: workflow artifacts, deployments, draft workspaces, run records, checkpoints, artifact/deployment validation models. |
 | `wf_platform` | Shared capability/source concepts and platform-facing contracts such as capability refs, source inventory models, documentation source models, and JSON schema helpers. |
-| `wf_api` | Application workflows over core/artifacts/platform: capability discovery, wrapper hints, draft editing, artifact/deployment operations, run/resume operations, next actions, and progressive response shaping. |
+| `wf_api` | Application workflow contract and process-local implementation over core/artifacts/platform: capability discovery, wrapper hints, draft editing, artifact/deployment operations, run/resume operations, next actions, and progressive response shaping. |
 | `wf_mcp` | MCP-specific transport, tool schemas, upstream MCP adapters, broker services, proxy/admin tools, config reload, and `WorkflowApi` context construction for MCP. |
-| future `wf_http` | HTTP transport over `wf_api`, not a reimplementation of workflow business logic. |
+| `wf_transport_rpc_http` | JSON-RPC-over-HTTP transport adapter and remote client over `WorkflowApiSurface`, not a reimplementation of workflow business logic. |
-| `wf_cli` | CLI frontend over `wf_api`; it may run locally against process-local stores or later target an HTTP backend. |
+| future `wf_http` / WebSocket / MCP server transports | Additional transports over `WorkflowApiSurface`, not new workflow application APIs. |
+| `wf_cli` | CLI frontend over `WorkflowApiSurface`; it may run locally against process-local stores or target a remote JSON-RPC backend. |
 
 ## What Belongs In wf_api
 
@@ -35,6 +36,9 @@ frontends can share.
 Examples that belong in `wf_api`:
 
 - `WorkflowApi`
+- `WorkflowApiSurface`
+- domain surface protocols such as `WorkflowDraftSurface` and
+  `WorkflowRunSurface`
 - `WorkflowCapabilityApi`
 - `WorkflowDraftApi`
 - `WorkflowArtifactApi`
@@ -100,7 +104,32 @@ Important rules:
 Do not add a catch-all `service` field to the context. If a domain API needs a
 new dependency, add a narrow protocol or explicit field.
 
-## Domain Services
+## WorkflowApiSurface And Domain Services
+
+`WorkflowApiSurface` is the public application contract shared by local and
+remote frontends. It is a structural protocol, not a base class. Implementations
+can satisfy it by method shape:
+
+- `WorkflowApi` implements the surface in-process by composing domain services
+  over `WorkflowOperationContext`.
+- `RpcWorkflowApiClient` implements the same flat surface by serializing calls
+  to fixed JSON-RPC method names.
+- Future auth, cache, recording, WebSocket, or MCP-server adapters should also
+  target the same surface instead of importing concrete implementation classes.
+
+The surface is split into domain protocols:
+
+```text
+WorkflowApiSurface
+  WorkflowCapabilitySurface
+  WorkflowDraftSurface
+  WorkflowArtifactSurface
+  WorkflowDeploymentSurface
+  WorkflowRunSurface
+```
+
+The domain services below are the process-local implementation pieces, not the
+contract itself.
 
 `WorkflowApi` composes focused domain APIs:
 
@@ -179,13 +208,16 @@ MCP-specific concerns stay outside `wf_api`:
 
 ## Future HTTP/API Boundary
 
-A future HTTP API should reuse `WorkflowApi`, not copy MCP handlers.
+Future HTTP/WebSocket/MCP server transports should consume
+`WorkflowApiSurface`, usually backed by a process-local `WorkflowApi` instance.
+They must not copy MCP handlers or workflow business logic.
 
 Expected shape:
 
 ```text
-wf_http route/controller
+transport route/controller
-  -> WorkflowApi(required_store_context)
+  -> WorkflowApiSurface implementation
+  -> WorkflowApi(required_store_context) when running process-locally
   -> wf_api domain services
 ```
 
@@ -208,10 +240,12 @@ The HTTP layer should not own:
 
 The next implementation work should follow this order:
 
-1. Harden persisted run/resume contract tests in `wf_api`.
+1. Continue hardening persisted run/resume behavior behind `WorkflowRunApi`.
-2. Introduce a stricter required-store context/factory for durable API surfaces.
+2. Keep CLI and transport entrypoints typed against `WorkflowApiSurface`.
-3. Design the durable HTTP/API frontend around `WorkflowApi`.
+3. Add missing server/source/auth operations behind the same surface or explicit
-4. Align CLI so it can target either local process stores or the future HTTP API.
+   sibling admin surfaces.
+4. Add future WebSocket/MCP-server transports as adapters, not as new workflow
+   application layers.
 
 Workflow primitives such as fork/gather and additional authoring sugar should
 resume after the durability/platform boundary is stable.

docs/wf_mcp_architecture.md

@@ -26,8 +26,9 @@ relevant concern package directly.
 
 ## Dependency Rules
 
-- `wf_api` is the process-local workflow application API. `wf_mcp` may import
+- `wf_api` defines the workflow application surface and process-local
-  and adapt it; `wf_api` must not import `wf_mcp`.
+  implementation. `wf_mcp` may import and adapt it; `wf_api` must not import
+  `wf_mcp`.
 - `wf_mcp.sdk` should not import `wf_core` or `wf_authoring`.
 - `wf_mcp.proxy` should not import `wf_mcp.workflow`.
 - `wf_mcp.workflow` is the only layer that converts MCP capabilities into node specs.
@@ -42,6 +43,7 @@ Workflow lifecycle operations now have a protocol-neutral front door:
 
 ```text
 wf_mcp.workflow_surface.tools
+  -> wf_api.WorkflowApiSurface implementation
   -> wf_api.WorkflowApi
   -> wf_api domain services
   -> WorkflowOperationContext
@@ -51,14 +53,16 @@ wf_mcp.workflow_surface.tools
 `WorkflowSurfaceHandlers` is a compatibility shim only. New entrypoints should
 construct `WorkflowApi(context_from_service(service))` directly.
 
-The old backend-adapter/protocol layer has been removed. `WorkflowApi` composes
+The old backend-adapter/protocol layer has been removed. `WorkflowApiSurface`
-domain services (`WorkflowCapabilityApi`, `WorkflowDraftApi`,
+is now the structural workflow operation contract. The local `WorkflowApi`
-`WorkflowArtifactApi`, `WorkflowDeploymentApi`, `WorkflowRunApi`) from a
+implementation composes domain services (`WorkflowCapabilityApi`,
-`WorkflowOperationContext`.
+`WorkflowDraftApi`, `WorkflowArtifactApi`, `WorkflowDeploymentApi`,
+`WorkflowRunApi`) from a `WorkflowOperationContext`.
 
-New code should treat `wf_api.WorkflowApi` as the application-facing API. Do not
+New code should type consumers against `wf_api.WorkflowApiSurface` when they can
-add new callers that import `WorkflowSurfaceHandlers` directly unless they are
+work with either local or remote implementations. Use concrete `WorkflowApi`
-compatibility tests.
+only when same-process stores/runtime are required. Do not add new callers that
+import `WorkflowSurfaceHandlers` directly unless they are compatibility tests.
 
 The broader application-service boundary is documented in
 [`wf_api_architecture.md`](wf_api_architecture.md).