docs changes

docs/core_state_mapping_and_merge.md

@@ -42,15 +42,20 @@ Examples:
 ```json
 {
   "input": [
-    {"target": "user.name", "path": "state.person.name"},
-    {"target": "user.email", "path": "state.digital.email"},
-    {"target": "job.title", "path": "state.job.title"},
-    {"target": "mode", "value": "fast"}
+    {
+      "target": {"root": "local", "parts": ["user", "name"]},
+      "path": {"root": "state", "parts": ["person", "name"]}
+    },
+    {
+      "target": {"root": "local", "parts": ["mode"]},
+      "value": "fast"
+    }
   ],
   "output": [
-    {"source": "job.wage", "target": "state.job.wage"},
-    {"source": "job.years", "target": "state.experience.years"},
-    {"source": "user.age", "target": "state.person.age"}
+    {
+      "source": {"root": "local", "parts": ["job", "wage"]},
+      "target": {"root": "state", "parts": ["job", "wage"]}
+    }
   ]
 }
 ```
@@ -59,8 +64,18 @@ Whole-object mapping remains valid:
 
 ```json
 {
-  "input": [{"target": "user", "path": "state.person"}],
-  "output": [{"source": "user", "target": "state.person"}]
+  "input": [
+    {
+      "target": {"root": "local", "parts": ["user"]},
+      "path": {"root": "state", "parts": ["person"]}
+    }
+  ],
+  "output": [
+    {
+      "source": {"root": "local", "parts": ["user"]},
+      "target": {"root": "state", "parts": ["person"]}
+    }
+  ]
 }
 ```
 
@@ -68,8 +83,18 @@ Whole-payload mapping uses the local root path `"."`:
 
 ```json
 {
-  "input": [{"target": ".", "path": "state.rates"}],
-  "output": [{"source": ".", "target": "state.rates"}]
+  "input": [
+    {
+      "target": {"root": "local", "parts": []},
+      "path": {"root": "state", "parts": ["rates"]}
+    }
+  ],
+  "output": [
+    {
+      "source": {"root": "local", "parts": []},
+      "target": {"root": "state", "parts": ["rates"]}
+    }
+  ]
 }
 ```
 
@@ -96,8 +121,14 @@ Valid:
 
 ```json
 [
-  {"target": "user.name", "path": "state.person.name"},
-  {"target": "user.email", "path": "state.person.email"}
+  {
+    "target": {"root": "local", "parts": ["user", "name"]},
+    "path": {"root": "state", "parts": ["person", "name"]}
+  },
+  {
+    "target": {"root": "local", "parts": ["user", "email"]},
+    "path": {"root": "state", "parts": ["person", "email"]}
+  }
 ]
 ```
 
@@ -105,8 +136,14 @@ Invalid:
 
 ```json
 [
-  {"target": "user", "path": "state.person"},
-  {"target": "user.name", "path": "state.person.name"}
+  {
+    "target": {"root": "local", "parts": ["user"]},
+    "path": {"root": "state", "parts": ["person"]}
+  },
+  {
+    "target": {"root": "local", "parts": ["user", "name"]},
+    "path": {"root": "state", "parts": ["person", "name"]}
+  }
 ]
 ```
 
@@ -122,8 +159,14 @@ Invalid:
 
 ```json
 [
-  {"source": "user", "target": "state.person"},
-  {"source": "user.name", "target": "state.person.name"}
+  {
+    "source": {"root": "local", "parts": ["user"]},
+    "target": {"root": "state", "parts": ["person"]}
+  },
+  {
+    "source": {"root": "local", "parts": ["user", "name"]},
+    "target": {"root": "state", "parts": ["person", "name"]}
+  }
 ]
 ```
 

docs/historical/path_mapping_scratch.md

@@ -1,5 +1,9 @@
 # Path And Mapping Scratch
 
+> Historical note: this scratchpad records how the mapping model evolved.
+> Current core behavior uses canonical `input`/`output` and interrupt
+> `request`/`resume` binding lists. See `core_state_mapping_and_merge.md`.
+
 This is a focused scratchpad for the `wf_core` path/mapping design thread.
 Clean this into real docs later.
 

docs/historical/scratchpad.md

@@ -1,5 +1,9 @@
 # Graph as struct? workflow as struct
 
+> Historical note: this file preserves older design notes. Current binding
+> shapes are documented in `core_state_mapping_and_merge.md`,
+> `structural_refs.md`, and `workflow_drafts.md`.
+
 This file is now mostly a working design note.
 
 The original top section was rough brainstorming around a few ideas that did end

docs/wf_core_architecture.md

@@ -71,15 +71,17 @@ limits and intended adapter seam.
 
 ## What This Cleanup Does Not Solve Yet
 
-- Node-local mapping paths are still top-level only in the current runtime.
-  The intended direction for nested node-local paths, patch commits, and future
-  nested merge metadata is documented in
+- Node-local input/output bindings now support nested local paths and atomic
+  state patch commits. The remaining mapping design notes for future reducer
+  metadata are documented in
   [`core_state_mapping_and_merge.md`](core_state_mapping_and_merge.md).
 - Foreach is still serial-only. Parallel foreach needs an explicit scheduling
-  model, not just `asyncio.gather`.
+  model, not just `asyncio.gather`. `ForeachNode.over` is typed as a
+  `GraphSourcePath`, but execution is still serial.
 - Interrupt lifecycle is still node-level and run-state-level. Long-lived
   external subscriptions or notification streams need a separate lifecycle
-  design.
+  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.