feat(engine): plan-time schedule-tree scheduler + runtime dataflow executor

[jensneuse]

feat(engine): plan-time schedule-tree scheduler + runtime dataflow executor

Two independent, default-off engine execution improvements that collapse
federated query latency to the dependency-graph critical path under skewed
subgraph latency, plus hot-path allocation reductions.
Measured on the gateways-benchmark workload (one slow subgraph):
−37% median latency for either feature vs the shipping wave executor.

What's in here (4 commits)

1. perf(resolve): pre-size buffers and slab-allocate parallel fetch results
   Single-slab result allocation in resolveParallel, HTTP request buffer
   pre-sizing, singleflight key buffer reuse, resolvable field-path buffer
   pre-sizing. Verified at parity on a flags-off A/B (+1.2%, within noise).

2. feat(postprocess): dominance-based schedule-tree scheduler (WithBuildScheduleTree)
   Ports the improve-query-order scheduler with two load-bearing fixes found
   by adversarial review against real planner output:

   • validateParallelLeaves trusts FetchID dependency edges ONLY. The
     path-containment heuristics false-positive on the canonical federation
     plan (a fetch attaching under an ancestor-provided subtree is independent
     of a sibling merging into a prefix path — the planner emits explicit
     edges when a dependency is real, e.g. deps [1,2] on the fetch that
     actually reads sibling data) and panicked every affected request.
   • buildScheduleTreeProcessor never panics: any scheduler/validator error
     falls back to the legacy orderSequenceByDependencies +
     createParallelNodes pipeline, planning exactly as with the option off.
     Includes the property/scenario suites, a 13-fetch real-plan schedule pin
     (TestBuildScheduleTreeRealGatewaysBenchmarkPlan), and the ADR.

3. feat(resolve): 3-phase prepare/load/merge protocol for nested schedule trees
   The executor support for nested plans, with three deviations, each pinned
   by a regression test that fails if the deviation is reverted:

   • flat Parallels inside a nested tree route through the locked nested path
     (useMergeMu || gate) — fixes a verified data race;
   • skip-on-errored-dependency gated on useMergeMu — flat-plan error-path
     bytes stay identical to the legacy executor;
   • pooled batch tools registered for Put BEFORE the prepare-error return —
     fixes a pooled-arena leak on failed batch prepares.

4. feat(resolve): dataflow executor (ResolverOptions.EnableDataflowExecution)
   Per-FetchID dependency gating for flat query plans: each fetch's network
   load starts when its OWN dependencies have merged. Nine falsifiable
   invariants documented in the file header; the load-bearing ones:

   • every arena access runs on the coordinator goroutine (workers execute
     only the arena-free source load) — no mutex, race-free by construction;
   • the three audited error sinks are swap-captured per leaf and replayed in
     leaf order — error/extension output is byte-identical to the wave
     executor;
   • dispatch pops the global leaf-index minimum, so pre-fetch hook call order
     (authorizer/rate-limiter) matches wave spawn order whenever the DAG
     permits;
   • nested (schedule-tree) plans are structurally rejected and fall back —
     the two features compose safely.

Default-off guarantee

With both options off, behavior is byte-identical and at performance parity:

• byte-identity gate: one sha256 across all four flag modes, 50 requests each;
• flags-off A/B vs the unmodified base: within noise;
• the full -race suites for resolve/postprocess/graphql_datasource pass with
  zero exclusions, including -count=50 stress on the byte-identity and race
  stress tests.

Known properties (documented in code)

• Nested executor appends errors/extensions in completion order across
  parallel branches (error-path only; tree-order sink staging is the named
  follow-up, and the dataflow executor already implements that staging).
• Dataflow merge-CONFLICT error attribution on type-conflicting sibling data
  (invalid federation data) follows completion order.

Review provenance

The implementation survived three adversarial codex review cycles to
GATE-CLEAN during development plus a final whole-branch review (GATE-CLEAN);
every P1 found along the way is fixed and pinned by an empirically falsified
regression test.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 72a8cf90-2a12-4900-8bec-0da5607fb108

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/schedule-tree-dataflow-executor

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}