[NOD-003] Streaming and field-preservation parity for OpenAI-compatible forwarding

[mrnicholasbcarter-code]

User story

As an API consumer, I need Node OpenAI-compatible forwarding to preserve streaming and response fields exactly, so Core governance does not break provider semantics.

Problem

Forwarding/SSE behavior is not tracked as a dedicated parity contract. Field loss, malformed SSE, tool-call corruption, usage loss, or inconsistent error mapping can make the governed edge unusable.

Current state

verdict-node contains forwarding and SSE handling, but no open issue covers end-to-end field-preservation parity.

Target state

Node preserves request/response fields, tool calls, usage, finish reasons, metadata, and SSE ordering while applying Core envelope checks before forwarding.

Design

• Define canonical request/response/SSE fixtures for chat, tools, usage, errors, and streaming.
• Treat SSE as an ordered event stream; preserve event type, data, IDs, terminal event, and disconnect semantics.
• Validate envelope before opening the upstream stream.
• Map transport/provider failures to stable typed errors without leaking credentials or upstream secrets.
• Add abort, timeout, backpressure, and malformed-event behavior.

Repositories/files

• verdict-node/src/middleware/forwarder.ts
• verdict-node/src/middleware/**
• verdict-node/tests/**
• shared contract fixtures

Dependencies

• verdict-node#NOD-002 (or its created GitHub issue)
• verdict-core#220, #221

Acceptance criteria

• Non-stream responses preserve all supported JSON fields byte/semantic-equivalently.
• Stream responses preserve event order, tool-call deltas, usage, finish reason, terminal event, and request correlation.
• Envelope denial occurs before any upstream request/stream is opened.
• Client abort and upstream timeout close resources and emit typed evidence/error results.
• Malformed upstream events fail safely without partial false success.
• Tests cover chat, tools, usage, errors, SSE, abort, timeout, backpressure, and field additions.
• Compatibility fixtures run in CI against supported Node versions.

Testing

Run unit, fixture parity, property/fuzz tests for event ordering, and an upstream fake-server integration suite. Attach build/test evidence.

Security/NFR

No credential/header leakage. Bounded buffering. No unbounded reads. Preserve latency within an agreed regression threshold documented in CI.

Definition of done

Implementation, fixtures, tests, docs, and CI gate merged.