Sans-I/O TDS core (3/N): invert token/decoder to a sync step() core

[Saurabh Singh (saurabh500)]

⚠️ Perf-neutral layer — does NOT move the ~2× fetch gap. This PR is pure enabling/plumbing. The async/block_on tax this effort targets lives in the parser core, which lands in L4 (parser-level column-atomic step()). "L3 green" means the reader seam is inverted and safe — not that any benchmark improved. The P8 fetch A/B is intentionally not re-measured until L4 lands, to avoid reproducing ~2× mid-stack and polluting the record.

Layer 3 of the green-at-every-step sans-I/O stack

Base: dev/saurabh/sans-io-layer2-transport (#191). Public API is frozen — mssql-odbc and mssql-py-core build unchanged.

What this lands

This slice inverts the reader seam to a synchronous, I/O-free core while the async shell remains the only public driver. It is the foundation the parser-level step() core builds on next.

• Sync core: PacketBuffer::ensure(n) -> Result<(), NeedBytes> — an atomic, non-consuming guard reporting the exact byte shortfall. Paired with the existing atomic take_* accessors, a fixed-width read never advances on a short buffer and is always safe to re-drive after a refill.
• Inverted readers: both TdsPacketReader impls (test PacketReader + production NetworkTransport) are now thin async driver loops: loop { match buf.ensure(n) { Ok => take, NeedBytes => refill().await } }. Trait signatures are unchanged, so TdsClient and the frozen API are untouched. Both #[cfg(fuzzing)] / #[cfg(not(fuzzing))] trait defs are maintained.
• Anti-spin invariant (the L2 hang class): every refill must expose ≥1 new byte or the loop fails loudly (debug_assert) / returns a ProtocolError — never spins on a zero-payload packet.
• PLP dedup: deleted the read_plp_bytes collect-all duplicate (~90 lines of copied chunk framing) and routed eager materialization through the shared PlpChunkStreamReader via a thin collect_plp helper. All size/chunk guards now live in one place.
• Tests: empty-input and exact-packet-boundary termination (proving no hang), plus ensure shortfall/atomicity invariants, plus direct PacketBuffer accessor + over-consume bounds-guard coverage.

Scope note (honest labeling)

The reader-seam inversion + sync NeedBytes core + PLP dedup are landed here as a self-contained, low-risk layer. The parser-level column-atomic step() core (re-driving decode_row_columns / NBCROW / PLP chunk parsing over the sync buffer) is L4 — kept separate so every step stays green, and it is the layer that actually removes the async tax. DecodePolicy / BatchExit enums were intentionally not introduced: no existing bool / unreachable! in the touched code maps cleanly to them, so adding them would be noise per the repo's no-AI-slop charter.

Validation (green)

• cargo build ✅
• cargo bclippy (warnings = errors) ✅
• cargo bfmt ✅
• cargo btest (nextest): lib green except the 7 pre-existing test_certificates / win_tls cert-fixture failures (integration tests needing a live SQL Server are environmental); failing set verified byte-for-byte identical to the base branch. ✅
• cargo build --manifest-path mssql-py-core/Cargo.toml (outside workspace) ✅

LOC delta reported on the final rebased commit.

[Copilot]

Pull request overview

Introduces the synchronous Sans-I/O buffer guard and adapts async readers around it while consolidating PLP decoding.

Changes:

• Adds atomic PacketBuffer::ensure.
• Converts packet readers into refill-driven loops.
• Consolidates eager PLP collection through the streaming reader.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
mssql-tds/src/io/packet_reader.rs	Adds refill loops and termination tests.
mssql-tds/src/io/packet_buffer.rs	Adds NeedBytes, ensure, and accessor tests.
mssql-tds/src/datatypes/decoder.rs	Deduplicates PLP materialization.
mssql-tds/src/connection/transport/network_transport.rs	Adopts synchronous guards in production reads.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Saurabh Singh (saurabh500)]

Closing: the sans-I/O restructuring is not going to be productionized.

The row-decode performance work that motivated much of this has been re-scoped around #247, where benchmarked spikes show the dominant win comes from a far smaller change — converting TdsPacketReader to RPITIT to remove per-read boxing (#252, measured at −61.6% decode time) — rather than from inverting the core to a sync step() driver. Given that, this stack is a large amount of surface area for a win that is already available more cheaply.

This is cleanup rather than a rejection of the analysis. The branch is deliberately not deleted, so the work remains recoverable if the direction is revisited.