Roadmap: unify NodeBridge + OptimizedNodeBridge under shared core #126
Description
Goal
Converge NodeBridge and OptimizedNodeBridge into a single shared implementation with consistent protocol guardrails, error classification, and lifecycle behavior. NodeBridge should remain the correctness-first default while performance features are opt-in.
Design / ADR
docs/adr/0001-unified-bridge-core.md
Why
- Avoid duplicated JSONL parsing/timeout logic and inconsistent edge-case handling.
- Make OptimizedNodeBridge a strict superset (pooling/caching optional) rather than a divergent path.
Acceptance criteria
- Extract a shared transport core (JSONL framing, protocol validation, error mapping, buffer limits, timeout handling).
- Preserve NodeBridge semantics as the baseline (minProcesses=1, caching off).
- Make performance features opt-in and documented.
- Add parity tests that run both modes against the same fixtures.
- Close the linked issues (see below).
Linked issues to close
- NodeBridge should preserve PATH on Windows (case-insensitive env allowlist) #97
- OptimizedNodeBridge should cap stdout buffer growth on malformed output #98
- OptimizedNodeBridge waitForAvailableWorker uses fixed 5s queue timeout #99
- OptimizedNodeBridge cache key generation throws on non-JSON-serializable args #100
- OptimizedNodeBridge should quarantine workers after request timeouts #101
- OptimizedNodeBridge should block late worker spawns after dispose #102
- OptimizedNodeBridge cleanup can terminate workers that became busy #103
- OptimizedNodeBridge waitForAvailableWorker leaks timers after timeout #104
- OptimizedNodeBridge should handle JSON.stringify failures without poisoning worker state #105
- NodeBridge should reset process after stdin write failures #107
- OptimizedNodeBridge should enforce protocolVersion via meta handshake #108
- OptimizedNodeBridge should surface explicit BridgeTimeoutError #109
- NodeBridge should validate JSON.stringify failures before marking requests pending #110
- NodeBridge should enforce bridge protocol version on meta refresh #111
- NodeBridge should cap stdout line length like stderr #112
- NodeBridge should handle child error/exit by rejecting pending with BridgeProtocolError and resetting #113
- OptimizedNodeBridge should guard against negative/NaN timeoutMs #114
- OptimizedNodeBridge should drain stderr into bounded buffer for timeout diagnostics #115
- NodeBridge/OptimizedNodeBridge should omit undefined env values before spawn #119
- python_bridge should validate incoming request shape before dispatch #121
- python_bridge should flush stderr warnings on protocol errors #122
- python_bridge should enforce request size limit to prevent memory spikes #123
- python_bridge should guard against stdout flush failures #124
- NodeBridge should sanitize stderr content to avoid unbounded growth on noisy crashes #125