📄️ Part 1: Overview & Mental Model
The runtime model, core objects, callback directions, and tunnel lifecycle you must understand before changing any WaterWall tunnel.
📄️ Part 2: Lines & Lifetime
The connection lifecycle, re-entrancy hazards, line locking, and the clean-finish patterns that keep WaterWall tunnels free of use-after-free bugs.
📄️ Part 3: Buffers & Padding
The sbuf_t buffer model, worker buffer pools, left-padding budgets, and how to prepend protocol headers without breaking chain composition.
📄️ Part 4: Packet Tunnels
Packet-line semantics, pure packet tunnels, packet/stream bridges, packet-line initialization, and paired-tunnel direction rules for layer-3 work.
📄️ Part 5: Anatomy & Workflow
The on-disk layout of a WaterWall tunnel, what each file owns, node.c metadata, the create/line-state patterns, HTTP constraints, and the implementation workflow.
📄️ Part 6: Build, Test & Review
CMake presets, focused builds, the integration test harness, build-environment gotchas, the full review checklist, and the report format expected from coding agents.
📄️ Part 7: Shutdown & Signals
The three process shutdown APIs, the shutdown phase state machine, exit-code arbitration, worker stop/join rules, and how to classify a termination call site.