Skip to content

Reporter overhaul (5/6): Heft protocol track (negotiated child descriptors) - #5869

Open
Sean Larkin (TheLarkInn) wants to merge 3 commits into
reporter/4-opt-in-reportersfrom
reporter/5-heft-protocol
Open

Reporter overhaul (5/6): Heft protocol track (negotiated child descriptors)#5869
Sean Larkin (TheLarkInn) wants to merge 3 commits into
reporter/4-opt-in-reportersfrom
reporter/5-heft-protocol

Conversation

@TheLarkInn

@TheLarkInn Sean Larkin (TheLarkInn) commented Jul 15, 2026

Copy link
Copy Markdown
Member

📚 Reporter Overhaul PR stack (merge bottom-up)

# PR Phase Base
1 #5865 Contracts & baselines (package) main
2 #5866 Bootstrap & compatibility #5865
3 #5867 Shadow structured emission #5866
4 #5868 Opt-in reporters #5867
5 #5869 Heft protocol track #5868
6 #5870 Perf budgets & default flip #5869

Each PR's diff is scoped to its phase; review independently, merge from #5865 upward.

👉 This is PR 5 of 6.

Phase 5 — Heft protocol track (RFC §8.1)

Adds structured cross-process reporting for Heft child builds, with backward compatibility for older Heft.

What's included

  • Negotiated child descriptors — Rush allocates an inherited descriptor (via a private env var); the child emits NDJSON hello + events over it, correlated with the parent session/operation ids.
  • Raw-stream fallback — when negotiation is unavailable, child stdout/stderr is preserved and diagnostics are recovered through the problem matchers from Phase 4.

Validation

  • rush build --to @rushstack/reporterrush test --only @rushstack/reporter ✅ (adds HeftIntegration suite covering both the descriptor path and the raw-stream path)
  • All exports @beta.

Scope note

Standalone package; not yet wired into the live CLI. Independently releasable/revertible per RFC §8.1.

Integrate Heft as a cross-process reporter producer for @rushstack/reporter (#5858).

- Add allocateChildDescriptor and readChildDescriptorFd so Rush passes a
  dynamically allocated inherited descriptor to the child through a private
  environment variable while stdout and stderr stay normal streams
- Add HeftChildEmitter, which emits structured NDJSON over the descriptor or
  falls back to raw stdout and stderr when negotiation is unavailable
- Add HeftDescriptorHost, which negotiates the child hello and correlates each
  child event with the parent session and operation ids, surfacing an
  update-global-Rush diagnostic on rejection
- Keep the raw-stream and problem-matcher path for older Heft versions
- Cover both the new descriptor and old raw-stream paths with tests

Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3
Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3
HeftDescriptorHost gains incremental record processing (processChildRecord)
and createStreamProcessor(), which decodes NDJSON chunks as they arrive and
forwards accepted events in receipt order. This continuously drains the child
pipe (a chatty child no longer blocks on a full OS pipe buffer) and surfaces
child progress live, per the design-review realignment. The batch
processChildNdjson path is retained for completed streams and tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Needs triage

Development

Successfully merging this pull request may close these issues.

1 participant