docs: record workflow api surface and rpc split
This commit is contained in:
+21
-14
@@ -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
|
||||
API used by both CLI commands and MCP workflow tools.
|
||||
- `wf_api.WorkflowApiSurface` is now the protocol-neutral workflow operation
|
||||
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
|
||||
`WorkflowApi` without `WfMcpService`; later slices add remote CLI targeting,
|
||||
JSON-RPC-over-HTTP first transport, remote CLI targeting, WebSocket/MCP
|
||||
transport siblings, source providers, auth, streaming/progress,
|
||||
transactional storage, and live upstream MCP sources.
|
||||
initial slices proved a lightweight local/static server and JSON-RPC
|
||||
transport; later slices add 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.
|
||||
- Completed: the first JSON-RPC-over-HTTP transport can expose the local/static
|
||||
`WorkflowServer` through fixed dotted methods. Remote CLI targeting remains
|
||||
the next transport-facing slice.
|
||||
`WorkflowApi` without `WfMcpService`.
|
||||
- Completed: the first JSON-RPC-over-HTTP transport can expose the
|
||||
local/static `WorkflowServer` through fixed dotted methods.
|
||||
- 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
|
||||
HTTP API backend.
|
||||
- Preserve the current local CLI path until the API backend is proven.
|
||||
- Completed for the basic lifecycle: selected `wf` commands can target local
|
||||
process-backed stores/runtime or JSON-RPC HTTP through the same
|
||||
`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
|
||||
|
||||
+45
-11
@@ -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_cli` | CLI frontend over `wf_api`; it may run locally against process-local stores or later target an HTTP backend. |
|
||||
| `wf_transport_rpc_http` | JSON-RPC-over-HTTP transport adapter and remote client over `WorkflowApiSurface`, not a reimplementation of workflow business logic. |
|
||||
| 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
|
||||
-> WorkflowApi(required_store_context)
|
||||
transport route/controller
|
||||
-> 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`.
|
||||
2. Introduce a stricter required-store context/factory for durable API surfaces.
|
||||
3. Design the durable HTTP/API frontend around `WorkflowApi`.
|
||||
4. Align CLI so it can target either local process stores or the future HTTP API.
|
||||
1. Continue hardening persisted run/resume behavior behind `WorkflowRunApi`.
|
||||
2. Keep CLI and transport entrypoints typed against `WorkflowApiSurface`.
|
||||
3. Add missing server/source/auth operations behind the same surface or explicit
|
||||
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.
|
||||
|
||||
@@ -26,8 +26,9 @@ relevant concern package directly.
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
- `wf_api` is the process-local workflow application API. `wf_mcp` may import
|
||||
and adapt it; `wf_api` must not import `wf_mcp`.
|
||||
- `wf_api` defines the workflow application surface and process-local
|
||||
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
|
||||
domain services (`WorkflowCapabilityApi`, `WorkflowDraftApi`,
|
||||
`WorkflowArtifactApi`, `WorkflowDeploymentApi`, `WorkflowRunApi`) from a
|
||||
`WorkflowOperationContext`.
|
||||
The old backend-adapter/protocol layer has been removed. `WorkflowApiSurface`
|
||||
is now the structural workflow operation contract. The local `WorkflowApi`
|
||||
implementation composes domain services (`WorkflowCapabilityApi`,
|
||||
`WorkflowDraftApi`, `WorkflowArtifactApi`, `WorkflowDeploymentApi`,
|
||||
`WorkflowRunApi`) from a `WorkflowOperationContext`.
|
||||
|
||||
New code should treat `wf_api.WorkflowApi` as the application-facing API. Do not
|
||||
add new callers that import `WorkflowSurfaceHandlers` directly unless they are
|
||||
compatibility tests.
|
||||
New code should type consumers against `wf_api.WorkflowApiSurface` when they can
|
||||
work with either local or remote implementations. Use concrete `WorkflowApi`
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user