Skip to content

✨ feat(plan): Node AST, strict Planned values, GraphBuildError - #181

Merged
roninjin10 merged 1 commit into
mainfrom
plan-node-ast
Aug 13, 2026
Merged

✨ feat(plan): Node AST, strict Planned values, GraphBuildError#181
roninjin10 merged 1 commit into
mainfrom
plan-node-ast

Conversation

@roninjin10

Copy link
Copy Markdown
Contributor

Summary

The authoring half of @smthrs/plan: the pure Node AST that flow bodies will build, ahead of Graph.build (PR4) and the declared Activity/Flow surface (PR2/PR3).

  • Node.ts + internal/node.ts: seven closure-free, serializable variants — Succeed, All, Map, AndThen, FlowCall, ActivityCall, Branch. Deferred functions (map transforms, branch predicates, continuations) live in out-of-band WeakMap tables with fnv1a32-source/v1 digests in the AST, so an edited function re-keys exactly its cone.
  • Planned.ts: the Planned<T> branded placeholder for step results at plan time. Property access records reference paths (legal — becomes Ref{from, path} key material); any computation — Symbol.toPrimitive, valueOf, toString, toJSON, function application — throws GraphBuildError naming the node and the fix (Node.map to compute, Node.branch to decide, or pass into a payload).
  • GraphBuildError.ts: planned_value_computed, invalid_continuation, invalid_all_member, recursion_requires_boundary (reserved for PR4).
  • Design per docs/specs/Concepts/Unified Flow Authoring.md + Trampoline Loops.md (decided 2026-08-11). Deviations from the agent-repo prior art are deliberate: Branch/ActivityCall added, Dynamic dropped (agent-layer concept), lenient proxy made strict.

Verification

  • npm run check --workspace @smthrs/plan — clean
  • npm run lint --workspace @smthrs/plan — clean
  • New: Node.test.ts (13), Planned.test.ts (8), GraphBuildError.test.ts (2); full package suite 6 files / 79 tests, 100% branch/function/line/statement coverage enforced by the run
  • vitest.config.ts: focused single-file runs now scope coverage to the same-named source module; the package-wide src/** 100% gate is unchanged for full runs

…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)
@roninjin10

Copy link
Copy Markdown
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.

@roninjin10
roninjin10 merged commit 85b3de4 into main Aug 13, 2026
1 check failed
@roninjin10
roninjin10 deleted the plan-node-ast branch August 13, 2026 01:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant