split .route into + add multiple distinct helpers

2026-05-19 01:16:50 +07:00
parent 8d9796dd04
commit 8210ae3b85
5 changed files with 347 additions and 60 deletions
@@ -0,0 +1,200 @@
+# Authoring Control Flow Design
+
+## Goal
+
+Make `wf_authoring` control flow precise enough that future sugar layers can
+delegate to it instead of reimplementing graph semantics.
+
+The current problem is `route()`: it accepts both `PathExpr` and `Expr`, then
+dispatches to two different behaviors. Both "route" something, but the caller
+must understand different case semantics depending on the argument type.
+
+That is too blurry for the core authoring API.
+
+## Design Rule
+
+Each public control-flow method should name one decision mechanism.
+
+| Method | Decision source | Meaning |
+| --- | --- | --- |
+| `branch` | a node's declared outcome | wire outcome labels to targets |
+| `match` | one graph value | compare that value against equality cases |
+| `when` | one boolean condition | route through `true` / `false` |
+| `choose` | ordered boolean conditions | first true condition wins |
+| future `handle` | several source/outcome pairs | send shared outcomes to one target |
+
+Future fluent builders or operator sugar must call these methods rather than
+constructing edges/conditions independently.
+
+## Keep `branch`
+
+`branch()` is already good:
+
+```python
+g.branch(tool, {
+    "ok": next_step,
+    "error": fail_step,
+})
+```
+
+It has one clear meaning:
+
+```text
+route an existing node outcome
+```
+
+It should remain named `branch`. Alternatives such as `on_outcome` are more
+literal but worse to use, and the current method does not suffer from the
+semantic overloading that `route()` does.
+
+## Replace `route`
+
+### `match`
+
+```python
+g.match(
+    state("status"),
+    {
+        "done": finish,
+        "retry": retry,
+    },
+    default=fail,
+)
+```
+
+Meaning:
+
+```text
+if state.status == "done": finish
+elif state.status == "retry": retry
+else: fail
+```
+
+This is the existing `PathExpr` branch of `route()`, renamed to say what it
+actually does.
+
+### `when`
+
+```python
+g.when(
+    state("count").ge(1),
+    then=positive,
+    otherwise=zero,
+)
+```
+
+Meaning:
+
+```text
+if state.count >= 1: positive
+else: zero
+```
+
+This is the existing `Expr` branch of `route()`, made explicit and easier to
+call correctly.
+
+### `choose`
+
+```python
+g.choose(
+    (state("x").gt(10), big),
+    (state("y").exists(), has_y),
+    default=fail,
+)
+```
+
+Meaning:
+
+```text
+if state.x > 10: big
+elif state.y exists: has_y
+else: fail
+```
+
+This is an ordered predicate chain. It should lower through the same condition
+construction/connect machinery as `when`, repeated for each clause.
+
+`choose` is intentionally one call. Multiple-call fluent syntax can be built
+later on top of it if it proves useful.
+
+## Lowering
+
+These methods may generate core condition nodes, but callers should not need to
+know the exact node construction details to choose the right API.
+
+Canonical lowering:
+
+- `branch`
+  - no new condition nodes
+  - wires declared outcome strings from one source
+- `match`
+  - ordered equality-check condition chain
+  - one generated condition per case
+- `when`
+  - one condition node
+  - `true` and `false` edges
+- `choose`
+  - ordered condition chain
+  - one generated condition per clause
+
+Trace behavior should document that `match` and `choose` expand to generated
+condition nodes.
+
+## Outcome Names
+
+Outcome names are strings at the core wire level, but Python authoring should
+eventually avoid handwritten strings when a `NodeSpec` already declares them.
+
+Future improvement:
+
+```python
+tool.outcomes.ok
+tool.outcomes.error
+```
+
+derived from `NodeSpec.outcomes`, not duplicated constants that can drift from
+the contract.
+
+This is orthogonal to the control-flow rename, but it belongs in the same
+authoring quality bar.
+
+## Migration
+
+`route()` should become deprecated compatibility sugar for one release window,
+then be removed.
+
+Recommended behavior during compatibility:
+
+- mark `route()` with `@deprecated` so IDEs surface the replacement path
+- `route(PathExpr, cases, ...)`
+  - warns and forwards to `match(...)`
+- `route(Expr, {True: a, False: b}, ...)`
+  - warns and forwards to `when(...)`
+
+The public docs should prefer only:
+
+- `branch`
+- `match`
+- `when`
+- `choose`
+
+## Not In This Pass
+
+- reverse-branch/shared handlers (`handle`)
+- fluent/cursor builder APIs
+- operator overloading
+- graph-as-node/subgraph support
+- JSON draft `match` / `when` / `choose` shapes
+
+Those later layers should depend on this API once it is stable.
+
+## Testing
+
+Tests should prove:
+
+1. `branch` still wires outcome labels only
+2. `match` reproduces current value-route behavior
+3. `when` reproduces current boolean-route behavior
+4. `choose` lowers ordered predicates correctly
+5. `route` emits deprecation warnings while preserving old behavior
+6. later sugar can delegate to these without needing private builder internals