✨ feat(flow): the body interpreter — bodied flows execute - #185
Merged
Conversation
…Error The authoring half of the plan: seven closure-free node variants (Succeed, All, Map, AndThen, FlowCall, ActivityCall, Branch) with digested deferred functions in out-of-band tables, the Planned<T> branded placeholder whose proxy throws GraphBuildError on any computation (toPrimitive, valueOf, toString, toJSON, application), and the GraphBuildError vocabulary. Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit 64624ac)
Activity.make gains a string-first overload: a named, schema-typed atom (payload/success/error/tier/idempotencyKey) whose implementation attaches separately via .toLayer(execute) through the existing registration and activity machinery, and whose .call(payload) records an ActivityCall node for plans. The inline options form is unchanged. Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit b883814)
…otations Flow.make accepts an optional plan-time body (required once the migration completes), Flow.prototype.call records a FlowCall node, the trampoline outcome vocabulary lands as pure data (Flow.done / flow.to / Flow.park over the existing Waiting reasons), and Capabilities / EffectsDeclaration / Placement join the annotation keys. Docs: docs/specs/Concepts/Unified Flow Authoring.md Docs: docs/specs/Concepts/Trampoline Loops.md (cherry picked from commit ad7df62)
roninjin10
force-pushed
the
flow-graph-build
branch
from
August 12, 2026 05:48
f8bf150 to
ba7b300
Compare
roninjin10
force-pushed
the
engine-body-interpreter
branch
from
August 12, 2026 05:48
42ee5ce to
72f9b1e
Compare
Contributor
Author
|
Review round 1 complete (sol + fable, independent). Findings for this PR were fixed and folded into its commit; the full ledger (15 fixes, 6 resolved-as-designed) lives in the stack's review notes. All 14 branches rebased and re-verified: whole-repo check green, all package suites at 100% coverage, rebuilt tip byte-identical to the verified fix tree. |
Evaluates a body against its real payload with strict Planned placeholders for step results, expands branch arms as static topology, splices inline flow calls with capability intersection, rejects recursive calls with recursion_requires_boundary, reads effects/capabilities/placement from the authoring annotations, and emits NodeDrafts that Plan.compile keys directly. Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit f8bf150)
Interpreter.layer(flow) registers a generic handler over the FlowRuntime port: Graph.build against the real payload, dependency-order driving of the compiled drafts, activity calls through the existing persistence machinery with declared implementations resolved from an Implementations table, branch predicates on real values running only the taken arm, Ref-path projection threading, and journaled replay on execution-id reuse. Bodied flows reject toLayer; behavior comes from exactly one place. Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit 42ee5ce) (cherry picked from commit 72f9b1e)
roninjin10
force-pushed
the
flow-graph-build
branch
from
August 12, 2026 06:51
ba7b300 to
ce958cc
Compare
roninjin10
force-pushed
the
engine-body-interpreter
branch
from
August 12, 2026 06:51
72f9b1e to
7a586e5
Compare
Contributor
Author
|
Swap pass complete — review loop closed. Both seats have now reviewed every PR. Swap findings (6: nested-catch subject scoping, foreign-flow wait tokens, two |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bodied flows execute.
Interpreter.layer(flow)registers a generic handler over theFlowRuntimeport:Graph.buildagainst the real payload → dependency-order driving of the compiled drafts → activities through the existing persistence machinery (implementations resolved from anActivity.Implementationstable), branch predicates evaluated on real values with only the taken arm executing,Ref-path projections threading upstream results, and journaled replay on execution-id reuse (re-execution returns settled results without re-running effects).toLayer(BodyDefinesBehaviorerror) — behavior comes from exactly one place.@smthrs/flowagainst the port, so every runtime implementation gets identical semantics;// OPEN QUESTION (2026-08-11): PlanScheduler as the drivermarks where the durable scheduler plugs in later.packages/flowsconformance suite caught it — the pinned-config law stands;Planned.ts's one unreachable-by-construction directive is now in the pinned allowlist with its justification.Depends-on: #184
Verification
npm run checkacross all 20 workspaces — clean; lint clean (flow, engine, plan, flows); browser + circular checks passInterpreter.test.ts(17) +BodyInterpreter.test.ts(4, engine integration); full suites at the rebuilt tip: flow 16 files / 158 tests, engine 20 files / 149 tests, plan 100% (451/451 statements),packages/flowsconformance all green (independently re-verified after the stack rebase)Decisions taken (were open questions — review these)
Interpreter.ts:208). Rationale: PlanScheduler has zero production call sites, its NodeExecutor seam has no FlowRuntime implementation, and wiring it requires the durable-store stack in every runtime including in-memory tests. The inline walk gives identical settle-once semantics through the same activity persistence. PlanScheduler integration remains the upgrade path once plans persist per-execution — the marker stays at the seam where it plugs in.@smthrs/flowagainst theFlowRuntimeport, not inside@smthrs/engine. Every runtime implementation (in-memory, durable) gets identical body semantics for free; the engine stays a port implementation.