list deployment compaction & inspect deployment

docs/current_roadmap.md

@@ -1,46 +1,62 @@
 # Current Roadmap
 
-This is the short active roadmap after the core type-shape cleanup. It is based
-on both the current docs and the implementation state.
+This is the short active roadmap after the core type-shape cleanup and MCP
+workflow authoring cleanup pass. It is based on both the current docs and the
+implementation state.
 
-## Next Work
+## Completed Cleanup Pass
 
 1. **Docs index and prune**
-   - Add/maintain a clear docs entry point.
-   - Keep current architecture docs separate from historical plans and scratch
+   - Current architecture docs are separated from historical plans and scratch
      notes.
+   - The active roadmap now lives here instead of being scattered through older
+     planning files.
 
 2. **MCP workflow authoring UX**
-   - Make the LLM/client path progressive: inspect sources, create a draft,
-     patch, validate, compile, save, run.
-   - Prefer smaller discovery/inspection responses over one huge payload.
-   - Done: the operator manual now categorizes workflow tools into discovery,
-     draft workspace, stateless draft, artifact/deployment, and raw escape
+   - The operator manual categorizes workflow tools into discovery, draft
+     workspace, stateless draft, artifact/deployment, run/debug, and raw escape
      hatch groups.
-   - Next: tighten the actual tool responses around that map so list calls stay
-     compact and inspect/run calls carry the detailed payloads.
+   - List-style tools are more compact, while inspect/run tools carry the
+     detailed payloads.
 
 3. **Wrapper creation ergonomics**
-   - Help create workflow-ready wrappers from raw capabilities.
-   - Suggest state schema, input bindings, output bindings, default `ok` /
-     `error` handling, and missing decisions.
+   - Wrapper draft helpers can suggest state schema, input bindings, output
+     bindings, default `ok` / `error` handling, and missing decisions.
+   - The end-to-end runbook documents the wrapper path from capability
+     discovery through deployment/run.
 
 4. **Run and deployment story**
-   - Tighten list/inspect/run/debug for artifacts and deployments.
-   - Keep dependency validation and trace/error output compact and actionable.
+   - Deployment listing is summary-first, with dedicated inspection for detail.
+   - `run_deployment` returns compact status by default and exposes trace slices
+     through an explicit `trace_range`.
+   - Dependency validation and error output remain part of the run path.
 
 5. **Source inventory polish**
-   - Make `list_sources` / `inspect_source` clearly show raw capabilities,
-     workflow-ready node specs, admin-only tools, docs/resources, enabled state,
-     and changes after reload.
+   - `list_sources` / `inspect_source` now present source-owned capabilities
+     progressively.
+   - Source inventory distinguishes external sources, local workflow-facing
+     sources, docs/resources, and admin-only control surfaces.
 
-## Runtime Work To Revisit Later
+## Runtime and Platform Roadmap
 
-- **Native subgraphs**: add child run state, child trace preservation, interrupt
-  bubbling, and resume back into the child workflow.
+- **Native subgraphs / graph-as-node**: add child run state, child trace
+  preservation, interrupt bubbling, and resume back into the child workflow.
+  Wrapper artifacts currently execute as deployments and return run status;
+  true graph-as-node outcome propagation belongs here.
 - **Async parallel foreach**: add explicit scheduling, reducer/merge semantics,
   and failure policy. Do not model this as plain parallel calls over sync
   handlers.
+- **Persistent run history**: add a run store before adding stable `run_id`,
+  `inspect_run`, or `read_run_trace(run_id, range)` APIs. Current traces are
+  returned directly from immediate run responses.
+- **Protocol-native long-running runs**: investigate MCP tasks/progress
+  notifications for long-running workflow execution. Avoid inventing a custom
+  "start" convention unless protocol-native behavior is insufficient.
+- **Dynamic saved workflows as tools**: defer until the stable run/inspect
+  surface is strong. Many MCP clients do not refresh tool lists reliably, so
+  `wf.workflow.run_deployment` remains the dependable front door.
+- **Dashboard/source controls**: future UI should consume the same source
+  inventory and deployment metadata instead of reverse-engineering MCP tools.
 
 Frame stress points to solve before either feature:
 
@@ -57,6 +73,8 @@ Frame stress points to solve before either feature:
 
 ## Why This Order
 
-`wf_core` is now coherent enough for the next bottleneck to be platform and DX:
-how a human or LLM discovers capabilities, turns them into workflow-ready
-pieces, saves them, and runs them again.
+The MCP workflow authoring path is now usable enough for real testing. The next
+bottleneck is runtime/platform correctness: resumable child execution,
+parallel scheduling, persistent run history, and protocol-native progress
+reporting. Those pieces should come before adding more high-level authoring
+sugar.

docs/wf_mcp_operator_manual.md

@@ -118,6 +118,9 @@ Supporting:
 - `wf.workflow.list_artifacts`: compact list of saved workflow and wrapper
   artifacts.
 - `wf.workflow.inspect_artifact`: full saved artifact payload.
+- `wf.workflow.list_deployments`: compact list of saved deployment summaries.
+- `wf.workflow.inspect_deployment`: full deployment payload including source
+  bindings.
 
 ### Draft Workspaces
 
@@ -173,6 +176,8 @@ Primary:
 
 - `wf.workflow.save_deployment`: bind one saved artifact version to concrete
   sources.
+- `wf.workflow.inspect_deployment`: inspect source bindings for one saved
+  deployment.
 - `wf.workflow.validate_deployment`: check dependency availability and drift.
 - `wf.workflow.run_deployment`: execute a saved deployment with input. The
   default response is compact and returns `trace_count`; pass `trace_range`
@@ -372,6 +377,9 @@ data.
 | Save a workflow definition from a draft | `wf.workflow.create_artifact_from_draft` |
 | Save a compiled raw workflow definition | `wf.workflow.create_artifact_from_plan` |
 | List saved workflows/wrappers | `wf.workflow.list_artifacts` |
+| Inspect one saved workflow/wrapper | `wf.workflow.inspect_artifact` |
+| List saved deployments | `wf.workflow.list_deployments` |
+| Inspect one saved deployment | `wf.workflow.inspect_deployment` |
 | Bind a saved workflow to concrete sources | `wf.workflow.save_deployment` |
 | Check whether a deployment can run | `wf.workflow.validate_deployment` |
 | Execute a saved workflow | `wf.workflow.run_deployment` |

docs/workflow_artifacts.md

@@ -69,6 +69,21 @@ semantics.
 Dynamic projection of saved workflows as individual MCP tools can exist later,
 but it should be optional. The stable run tool is the reliable base layer.
 
+Current `run_deployment` calls are synchronous request/response executions. They
+return compact status, output, diagnostics, and `trace_count`; optional ranged
+trace detail is for debugging only.
+
+Future run history should introduce a stable `run_id` only when there is a real
+run store behind it. A `run_id` without persisted state, trace paging, and
+status lookup would be misleading. The likely shape is:
+
+- `run_deployment` starts or completes a run and returns `run_id`
+- `inspect_run(run_id)` returns status, output, diagnostics, and trace metadata
+- `read_run_trace(run_id, range)` returns bounded trace slices
+
+Until that exists, clients should treat the current response as the complete
+ephemeral run result for this request.
+
 For long-running workflow execution, prefer MCP-native execution mechanisms
 where available: