✨ feat(flow): Sleep and WaitFor system activities - #189
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-system-activities
branch
from
August 12, 2026 05:48
417035e to
dc5ad88
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)
A bodied flow's root value settles as Complete (done), Suspended (park, existing Waiting vocabulary), or the new encoded Handoff (to): the engine plans the target and runs it as the next round. Rounds chain under one lineage via parent_run_id with deterministic (lineage, ordinal) execution ids, the settle-and-create seam is one storage transaction, maxRounds is declared on the origin flow and enforced at the handoff with a typed terminal failure, and the root caller's polling follows handoff chains transparently to the final value. Docs: docs/specs/Concepts/Trampoline Loops.md (cherry picked from commit acafd2e) (cherry picked from commit e1f2cc8)
flow.child(payload) records a non-expanded boundary node whose material carries the child's tag, payload, and declared envelope. The interpreter runs it as a genuine child execution with a deterministic id derived from the parent execution and node address, parent edges and suspension propagate through the existing machinery, and placement conflicts on inline .call() now error with placement_requires_boundary directing to .child(). Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit f09bc16) (cherry picked from commit b4ec945)
The branch move applied to the error channel: Node.catch protects a subgraph with a failure arm that is plan-visible via an explicit failure edge reason, filters errors by digested schema (missing filter = the full typed error channel), never intercepts defects or compensation failures, and settles the protected node's planned reference with the caught error so failure-arm payloads consume it without re-running failed work. Docs: docs/specs/Concepts/Unified Flow Authoring.md (cherry picked from commit 47ffb00) (cherry picked from commit 37d8dc2)
roninjin10
force-pushed
the
flow-system-activities
branch
from
August 12, 2026 06:51
dc5ad88 to
809d444
Compare
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
SleepandWaitForas core-shipped declared Activities over the existingDurableClock/DurableDeferred— timers and events become visible, keyed plan nodes instead of invisible engine mechanics. Park classification rides the existing Waiting vocabulary (timer/event); waiting annotations propagate from child attempts into the parent execution.Decisions taken (review these)
Sleeprequires exactly one ofmillis|until; expired deadlines settle immediately.WaitForrequires exactly one ofname|token; foreign/malformed tokens are rejected.engine/engine-storefor two small integration seams (stable per-node timer identity, durable waiting classification) — noted as a deviation, kept minimal.Note for reviewers: one pre-existing, unrelated
platform-nodehost-contract failure (localjjdetection) reproduces with this PR's changes stashed; not addressed here.Depends-on: #188
Verification
npm run checkpassed; check/lint/circular clean in flow, engine, engine-store, flowsSleep.test.ts(11),WaitFor.test.ts(11),AnnotatedWaiting.test.ts(4)