Reviewing Nacelle Rust and Runtime Changes

Use this domain workflow with the general review rules. Review the affected contracts; do not require every check below for unrelated changes.

Preparation

Read the repository instructions and Rust instructions. For the affected area, consult the architecture guide, owning crate, callers, tests, manifests, and public reference documentation. Apply the security and performance guidance when relevant.

Review Procedure

1. Check Ownership and Compatibility

• Keep reusable byte/message codecs and reader/writer buffers in nacelle-codec. Keep transport-neutral handlers, lifecycle, limits, telemetry, and TLS primitives in nacelle-core.
• Keep TCP/Unix policy in nacelle-tcp, HTTP policy in nacelle-http, provider implementations in their TLS crates, and convenience re-exports in nacelle.
• Keep the reference protocol in the unpublished examples/nacelle-reference-protocol package, outside the published library API.
• Trace public type, trait, error, configuration, default, feature, and wire changes through consumers and adapters. Confirm intended changes have compatibility documentation and focused coverage.

2. Check Decoding, Encoding, and Buffer Ownership

• Successful decoding must consume input; requesting more input must leave the cumulative buffer unchanged. Check partial input, multiple frames, malformed input, EOF, and oversized input where the change affects those paths.
• Verify size limits reject input before unbounded growth, and that reader and writer adapters preserve bounded buffering and backpressure.
• Preserve shared backing allocations and zero-copy behavior where promised. Trace slices and retained messages rather than assuming an extra clone or borrowed value is either necessary or safe.
• Check encoding and partial writes for dropped, duplicated, reordered, or incorrectly flushed data.
• Treat Nacelle's pending-frame queue and buffering inside AsyncWrite independently. An empty frame queue does not prove the underlying writer is flushed; account for both when tracing admission and streaming progress.
• Distinguish encoded, buffered, socket-written, and flushed bytes, and track which response owns each count. A failed coalesced flush must not attribute earlier responses' bytes to the current request, or lose current-response bytes already written before that flush. Compare every affected success and error call site of delivery-accounting helpers.
• Check silent completions, protocol error responses, and completion callbacks separately. A request that generates no response must not acquire response bytes merely because its rejection or cleanup flushes an earlier response.

3. Check Async Lifecycle and Resource Bounds

• Trace handler errors, cancellation, deadlines, connection teardown, and graceful shutdown through the affected tasks.
• Verify task, queue, connection, and buffer bounds; ensure slow peers or handlers cannot bypass the intended backpressure.
• Check blocking operations, lock scope across .await, task ownership, Send/Sync requirements, and cleanup when a future is dropped.
• At affected .await, select!, and join! boundaries, identify which future can be dropped, what partial I/O progress it owns, and whether subsequent cleanup can retry that work. Verify cancellation cannot replay a written prefix or restart an indefinitely blocked flush.
• Track connection, request, handler, and application leases through ownership transfers and every exit. Check their documented release boundaries when body pumping, handler completion, admission, and response delivery progress independently; do not assume one joined future's lifetime matches another's.
• For coupled admission, body-pump, handler, and delivery futures, record progress dependencies at concrete call sites in the evidence ledger: each bounded queue's producer and consumer, what each pending operation awaits, and which operation can cancel it. Check saturated queues and terminal failure paths. Failure reporting must reach the driver without awaiting capacity owned by work that the failure needs to cancel.
• Require deterministic coverage for changed timing behavior where practical; follow existing paused-time tests rather than adding sleep-based assumptions.

4. Check Features, TLS, and Diagnostics

• Read manifests and the feature matrix. Rustls serves TCP and HTTP; OpenSSL is TCP-specific. Negotiated TLS metadata belongs in nacelle-core.
• Preserve mutual exclusion of Rustls and OpenSSL; do not use workspace --all-features as a valid provider combination or let openssl implicitly select rustls.
• Verify changed feature-gated paths under the smallest relevant feature set and the supported provider combinations.
• Compare runtime scheduling with relevant features enabled and disabled, including pre-flush placement and concurrent body/handler progress. Successful compilation alone does not establish equivalent behavior.
• Keep peer-controlled data out of metric labels. Preserve low cardinality, stable rejection reasons, and opt-in diagnostic overhead.
• At each affected rejection checkpoint, compare legacy/static policies and listener/direct entry points across applicable shared, serial, and local paths. Trace the returned error, response-or-close behavior, lease release, operation phase, and actual observer-event/counter emission. Check metric switches, including the error domain, independently of observer delivery. Stable labels do not establish that an event is emitted or counted once.
• For hot-path changes, identify allocations, retained buffers, locks, timers, and instrumentation. Require comparable measurements before accepting a throughput, latency, or memory improvement claim.

5. Evaluate Evidence and Report

Start with focused tests for the owning crate. Codec changes start with cargo test -p nacelle-codec --all-features; performance claims also need the existing benchmark comparison under comparable conditions.

For delivery or admission changes, build a relevant behavioral coverage matrix from the invariants, not only from the tests already present:

• Immediate and coalesced delivery, with and without earlier pending responses.
• Ready rejection and pending admission; success and failure at affected hooks.
• Rejection with and without a protocol error response, including silent completions and callback-bearing responses where affected.
• Partial writes, write errors or deadlines, and failures of the underlying flush after response bytes have already been written.
• Body EOF/read deadlines, handler failure, cancellation, and teardown while another operation is pending.
• Relevant feature configurations, bounded-channel backpressure, response order, per-request byte attribution, and lease release.

Use this matrix as the behavioral part of the general review evidence ledger. For each applicable case, cite concrete call sites and exercised coverage, source-backed reasoning or a counterexample, or an explicit evidence gap. Justify irrelevant cases; do not require an unrelated Cartesian product. Favor deterministic partial-progress fixtures and paused time when tests are authorized. Passing existing tests must not be treated as proof that untested failure paths preserve these contracts.

Use the Rust instructions for formatting, lint, and test gates. Feature wiring, TLS, cross-crate changes, and readiness work require the broader ./scripts/validate-all.sh evidence. A review does not itself authorize running or installing every check.

Verify corresponding API, feature, configuration, security, and performance documentation updates. Report findings using the general review severity and evidence rules, with skipped checks and remaining uncertainty stated explicitly.