subgraph model & validation

docs/current_roadmap.md

@@ -45,11 +45,12 @@ implementation state.
   [ADR 0002](./adr/0002-concurrent-foreach-policy-and-barrier-commits.md).
 - Native subgraph design spec:
   [2026-05-24 native subgraphs](./superpowers/specs/2026-05-24-native-subgraphs-design.md).
-- **Native subgraphs / graph-as-node**: next major runtime feature. Add a
-  first-class subgraph step with child run/frame identity, child trace
-  preservation, interrupt bubbling, and resume back into the child workflow.
-  Wrapper helpers currently run child workflows as ordinary nodes; true
-  graph-as-node behavior belongs here.
+- **Native subgraphs / graph-as-node**: next major runtime feature. A
+  first-class `SubgraphNode` placeholder exists and validates parent-side
+  bindings/outcomes, but runtime execution still needs child run/frame identity,
+  child trace preservation, interrupt bubbling, and resume back into the child
+  workflow. Wrapper helpers currently run child workflows as ordinary nodes;
+  true graph-as-node behavior belongs here.
 - **Concurrent foreach**: implemented in core with explicit scheduling,
   reducer/merge semantics, item error policy, async handler batching, and
   quiescent interrupt behavior. Remaining work is polish and future reuse of

docs/superpowers/specs/2026-05-24-native-subgraphs-design.md

@@ -56,11 +56,19 @@ class SubgraphNode(BaseModel):
     id: str
     type: Literal["subgraph"]
     workflow: WorkflowRef
+    input_schema: SchemaRef
+    output_schema: SchemaRef
     input: list[InputBinding] = Field(default_factory=list)
     output: list[OutputBinding] = Field(default_factory=list)
     outcomes: list[str] = Field(default_factory=lambda: ["ok"])
 ```
 
+Current implementation status: `wf_core` has a first placeholder
+`SubgraphNode`, but `workflow` is still a plain string reference. The placeholder
+also carries `input_schema` and `output_schema` so validation can check parent
+bindings before native execution exists. Runtime execution intentionally raises
+until a later slice adds child scope/frame execution.
+
 `WorkflowRef` should be structural, not a dotted string parser:
 
 ```python

docs/wf_core_architecture.md

@@ -132,9 +132,11 @@ limits and intended adapter seam.
   external subscriptions or notification streams need a separate lifecycle
   design. Interrupt `request` and `resume` are canonical binding lists; nested
   child-workflow resume is still future work.
-- Native subgraphs are not part of `wf_core` yet. The core `Step` model only
-  includes node, condition, foreach, join, and interrupt steps; `Workflow` does
-  not contain nested workflow/subgraph steps.
+- Native subgraphs have a core model placeholder, `SubgraphNode`, but runtime
+  execution is not implemented yet. The placeholder carries a child workflow
+  reference, declared input/output schemas, binding lists, and declared
+  outcomes so parent graph structure can validate before execution support
+  lands.
 - Nested subgraph interruption is not first-class yet. The current
   `wf_authoring` subgraph helpers wrap a child workflow as an ordinary sync or
   async node and validate the child output; they do not preserve a child run
@@ -145,10 +147,11 @@ limits and intended adapter seam.
   upgrade: nested run state, child-frame trace preservation, interrupt bubbling
   with path metadata, and resume back into the child workflow.
 - Frames are no longer only a serial execution stack: the runtime has a ready
-  queue and `BLOCKED` frame state. Concurrent foreach and native subgraphs still
-  need more work: lineage isolation, barrier merge semantics, pending child
-  results, and explicit child workflow/deployment identity. Concurrent foreach
-  is the primary current use case for async concurrent node handler execution.
+  queue, `BLOCKED` frame state, lineage isolation, barrier merge semantics, and
+  pending child results for concurrent foreach. Native subgraphs still need
+  explicit child workflow/deployment identity and child-scope execution.
+  Concurrent foreach is the primary current use case for async concurrent node
+  handler execution.
 - Runtime errors are still ordinary exceptions plus failed run status. A richer
   error payload can be added later, but should be designed as part of trace/run
   state rather than scattered exceptions.

docs/workflow_artifacts.md

@@ -635,10 +635,12 @@ must not be parsed as a generic `CapabilityRef`.
 The first implementation should prefer artifact validation and dependency
 diagnostics before attempting persistent nested resume.
 
-Native subgraphs are not in `wf_core` yet. The current core `Step` model has
-node, condition, foreach, join, and interrupt steps, but no subgraph step. The
-current `wf_authoring.subgraph_node` and `async_subgraph_node` helpers execute
-a child workflow as a plain node and validate the child output. The async helper
+Native subgraphs now have a core `SubgraphNode` placeholder. It validates the
+parent-side contract: child workflow reference, declared child input/output
+schemas, binding lists, and declared outcomes. Runtime execution is still not
+implemented; reaching a subgraph step raises a clear runtime error. The current
+`wf_authoring.subgraph_node` and `async_subgraph_node` helpers still execute a
+child workflow as a plain node and validate the child output. The async helper
 is explicit because hiding `asyncio.run()` inside the sync wrapper would break
 inside already-running event loops. Future saved-workflow-as-node execution
 needs a real child run state if child interrupts should pause the parent and