• refactor: reorganize runtime and tests by serialization/RPC levels

  - add `just install-path` plus grouped test recipes
    (`test-serialization`, `test-rpc-level0..3`)
  - split tests into `tests/serialization` and
    `tests/rpc/level{0,1,2,3}`
  - wire cumulative RPC level build targets and update default `test`
    aggregation
  - move serialization modules to `src/serialization/*`
  - reorganize RPC modules under `src/rpc/level{0,1,2,3}`
  - extract promise/pipelining code into level1 (`peer_promises`,
    `peer_return_send_helpers`, `promised_answer_copy`,
    `promise_pipeline`)
  - rewire `cap_table`/`peer`/`mod` imports and re-exports to keep API
    behavior intact
  - update README/AGENTS/docs/handoff path references to the new layout

  Validation:
  - `zig build test --summary all`
  - `just check`

Author: nullstyle

AGENTS.md

@@ -2,16 +2,24 @@
 
 ## Project Structure & Module Organization
 - `src/` holds the Zig library and plugin entry point.
+- `src/serialization/` contains wire-format, schema, and reader/validation modules.
 - `src/capnpc-zig/` contains codegen utilities and generators.
-- `tests/` contains Zig test suites; fixture schemas live in `tests/test_schemas/`.
+- `src/rpc/level0`, `src/rpc/level1`, `src/rpc/level2`, and `src/rpc/level3` group RPC runtime modules by Cap'n Proto level.
+- `src/rpc/level1/` contains promise and pipelining primitives shared by higher-level peer flows.
+- `tests/serialization/` contains serialization-focused suites; `tests/rpc/level0..level3/` contain RPC suites by level.
+- `tests/` also contains support assets; fixture schemas live in `tests/test_schemas/`.
 - `build.zig` defines build/test steps; `Justfile` wraps common tasks.
 - `zig-out/` and `.zig-cache/` are build artifacts.
 
 ## Build, Test, and Development Commands
 - `just build` builds the project (`zig build`).
 - `just release` builds optimized (`zig build -Doptimize=ReleaseSafe`).
 - `just test` runs all tests with summary output (`zig build test --summary all`).
+- `just test-serialization` runs serialization-focused suites.
+- `just test-rpc`, `just test-rpc-level0`, `just test-rpc-level1`, `just test-rpc-level2`, `just test-rpc-level3` run RPC suites by level.
 - `zig build test-message`, `zig build test-codegen`, `zig build test-integration`, `zig build test-real-world`, `zig build test-union` run focused suites.
+- `zig build test-serialization` runs all non-RPC serialization suites.
+- `zig build test-rpc-level0`, `zig build test-rpc-level1`, `zig build test-rpc-level2`, `zig build test-rpc-level3` run cumulative RPC levels.
 - `zig build test-capnp-testdata` and `zig build test-capnp-test-vendor` run Cap’n Proto fixture suites.
 - `just fmt` formats `src/` and `tests/` (`zig fmt`).
 - `just check` compiles without linking (`zig build check`).
@@ -27,8 +35,8 @@
 - Files are `snake_case.zig` (examples: `message.zig`, `integration_test.zig`).
 
 ## Testing Guidelines
-- Tests use Zig’s built-in `test` blocks in `tests/*.zig`.
-- Name new test files `*_test.zig` and group by feature area (message, codegen, integration).
+- Tests use Zig’s built-in `test` blocks in `tests/**/*.zig`.
+- Name new test files `*_test.zig` and group by area (`tests/serialization` or `tests/rpc/level0..level3`).
 - Run `just test` before submitting changes; add targeted tests for new behavior.
 
 ## Commit & Pull Request Guidelines

CHANGELOG.md

@@ -9,21 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Wire format** (`src/message.zig`, `src/message/*`): Full Cap'n Proto binary
+- **Wire format** (`src/serialization/message.zig`, `src/serialization/message/*`): Full Cap'n Proto binary
   format support including segment management, pointer encoding/decoding
   (struct, list, far, capability), text/data serialization, and packed encoding.
   Key types: `Message`, `MessageBuilder`, `StructReader`, `StructBuilder`, and
   typed list readers/builders for all primitive types.
 
-- **Schema types** (`src/schema.zig`): In-memory representation of Cap'n Proto
+- **Schema types** (`src/serialization/schema.zig`): In-memory representation of Cap'n Proto
   schema graphs mirroring `schema.capnp` -- `Node`, `Field`, `Type`, `Value`,
   and supporting types.
 
-- **Schema parsing** (`src/request_reader.zig`): Parser for
+- **Schema parsing** (`src/serialization/request_reader.zig`): Parser for
   `CodeGeneratorRequest` messages received from the Cap'n Proto compiler plugin
   protocol over stdin.
 
-- **Schema validation** (`src/schema_validation.zig`): Validation and
+- **Schema validation** (`src/serialization/schema_validation.zig`): Validation and
   canonicalization of schema graphs with configurable traversal limits and
   nesting depth.
 
@@ -32,7 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   structs, enums, constants, unions, groups, nested types, default values, and
   schema manifests with JSON serde exports.
 
-- **Reader convenience** (`src/reader.zig`): High-level `Reader` type for
+- **Reader convenience** (`src/serialization/reader.zig`): High-level `Reader` type for
   segment-framed message reading, including packed-format support and
   stream-based message reading.
 

CLAUDE.md

@@ -36,9 +36,9 @@ Requires **Zig 0.15.2** (use `mise install` to set up toolchain).
 
 Four-layer design, each building on the previous:
 
-**Wire Format** (`src/message.zig` + `src/message/*`, ~2000 LOC) — Core Cap'n Proto binary format: segment management, pointer encoding/decoding, struct/list/text/data serialization, packing, far pointers. Key types: `MessageBuilder`, `Message`, `StructBuilder`, `StructReader`.
+**Wire Format** (`src/serialization/message.zig` + `src/serialization/message/*`, ~2000 LOC) — Core Cap'n Proto binary format: segment management, pointer encoding/decoding, struct/list/text/data serialization, packing, far pointers. Key types: `MessageBuilder`, `Message`, `StructBuilder`, `StructReader`.
 
-**Schema** (`src/schema.zig`, `src/request_reader.zig`, `src/schema_validation.zig`) — Schema type definitions (Node, Field, Type, Value), CodeGeneratorRequest parsing from stdin, schema validation and canonicalization.
+**Schema** (`src/serialization/schema.zig`, `src/serialization/request_reader.zig`, `src/serialization/schema_validation.zig`) — Schema type definitions (Node, Field, Type, Value), CodeGeneratorRequest parsing from stdin, schema validation and canonicalization.
 
 **Code Generation** (`src/capnpc-zig/`) — Generates idiomatic Zig Reader/Builder types from Cap'n Proto schemas. `generator.zig` is the main driver; `struct_gen.zig` generates field accessors; `types.zig` maps Cap'n Proto types to Zig types.
 

HANDOFF_CONTEXT.md

@@ -7,11 +7,11 @@ Purpose: Resume decomposition work quickly without re-reading the entire RPC sta
 ## Current branch state (important)
 
 Modified/new RPC files in working tree:
-- `src/rpc/peer.zig` (modified)
-- `src/rpc/peer_forward_orchestration.zig` (modified)
+- `src/rpc/level3/peer.zig` (modified)
+- `src/rpc/level3/peer/forward/peer_forward_orchestration.zig` (modified)
 - `src/rpc/mod.zig` (modified)
-- `src/rpc/peer_third_party_adoption.zig` (new)
-- `src/rpc/peer_provide_join_orchestration.zig` (new)
+- `src/rpc/level3/peer/third_party/peer_third_party_adoption.zig` (new)
+- `src/rpc/level3/peer/provide/peer_provide_join_orchestration.zig` (new)
 
 ## Stable verification baseline
 
@@ -25,23 +25,23 @@ Use those as minimum gate before/after additional slices.
 ## What was extracted recently
 
 1. Third-party adoption/await lifecycle
-- Module: `src/rpc/peer_third_party_adoption.zig`
+- Module: `src/rpc/level3/peer/third_party/peer_third_party_adoption.zig`
 - Entry points:
   - `adoptThirdPartyAnswer(...)`
   - `handleThirdPartyAnswer(...)`
   - `handleReturnAcceptFromThirdParty(...)`
 - `peer.zig` now delegates adoption/await orchestration to this module.
 
 2. Provide/accept/join orchestration
-- Module: `src/rpc/peer_provide_join_orchestration.zig`
+- Module: `src/rpc/level3/peer/provide/peer_provide_join_orchestration.zig`
 - Entry points:
   - `handleProvide(...)`
   - `handleAccept(...)`
   - `handleJoin(...)`
 - `peer.zig` now delegates provide/accept/join flow orchestration.
 
 3. Forward/tail coordination centralization
-- Module: `src/rpc/peer_forward_orchestration.zig`
+- Module: `src/rpc/level3/peer/forward/peer_forward_orchestration.zig`
 - `finishForwardResolvedCall(...)` now mutates forward/tail maps directly and returns a completion directive.
 - Added callback-factory helpers for control-path callback signatures.
 
@@ -51,16 +51,16 @@ Use those as minimum gate before/after additional slices.
 ## Key navigation anchors
 
 - Forward call/return orchestration path:
-  - `src/rpc/peer.zig` around `forwardResolvedCall(...)` and `onForwardedReturn(...)`
-  - `src/rpc/peer_forward_orchestration.zig`
+  - `src/rpc/level3/peer.zig` around `forwardResolvedCall(...)` and `onForwardedReturn(...)`
+  - `src/rpc/level3/peer/forward/peer_forward_orchestration.zig`
 
 - Provide/accept/join path:
-  - `src/rpc/peer.zig` around `handleProvide(...)`, `handleAccept(...)`, `handleJoin(...)`
-  - `src/rpc/peer_provide_join_orchestration.zig`
+  - `src/rpc/level3/peer.zig` around `handleProvide(...)`, `handleAccept(...)`, `handleJoin(...)`
+  - `src/rpc/level3/peer/provide/peer_provide_join_orchestration.zig`
 
 - Third-party adoption path:
-  - `src/rpc/peer.zig` around `handleThirdPartyAnswer(...)`, `adoptThirdPartyAnswer(...)`, return-accept adapter
-  - `src/rpc/peer_third_party_adoption.zig`
+  - `src/rpc/level3/peer.zig` around `handleThirdPartyAnswer(...)`, `adoptThirdPartyAnswer(...)`, return-accept adapter
+  - `src/rpc/level3/peer/third_party/peer_third_party_adoption.zig`
 
 ## Next practical slice (if continuing decomposition)
 

Justfile

@@ -10,6 +10,30 @@ release:
 test:
     zig build test --summary all
 
+# Run serialization-focused tests (message/codegen/schema/interop)
+test-serialization:
+    zig build test-serialization --summary all
+
+# Run all RPC tests
+test-rpc:
+    zig build test-rpc --summary all
+
+# Run Cap'n Proto RPC level 0 tests (framing/protocol/cap-table)
+test-rpc-level0:
+    zig build test-rpc-level0 --summary all
+
+# Run Cap'n Proto RPC level 1 tests (promises/pipelining)
+test-rpc-level1:
+    zig build test-rpc-level1 --summary all
+
+# Run Cap'n Proto RPC level 2 tests (runtime plumbing)
+test-rpc-level2:
+    zig build test-rpc-level2 --summary all
+
+# Run Cap'n Proto RPC level 3+ tests (advanced peer semantics)
+test-rpc-level3:
+    zig build test-rpc-level3 --summary all
+
 # Build e2e reference images
 e2e-build:
     just --justfile tests/e2e/Justfile build

PROGRESS_REPORT.md

@@ -19,18 +19,18 @@ Scope: Active workstream to close P1/P2 recommendations from `QUALITY_REPORT.md`
 ## P1/P2 Checklist
 
 1. P1-4: Split `peer.zig` into focused modules. **In progress (near-complete)**
-   - `src/rpc/peer.zig` reduced from monolith to orchestrator + state holder.
+   - `src/rpc/level3/peer.zig` reduced from monolith to orchestrator + state holder.
    - Extracted submodules include:
-     - `src/rpc/peer/call/*`
-     - `src/rpc/peer/forward/*`
-     - `src/rpc/peer/provide/*`
-     - `src/rpc/peer/return/*`
-     - `src/rpc/peer/third_party/*`
+     - `src/rpc/level3/peer/call/*`
+     - `src/rpc/level3/peer/forward/*`
+     - `src/rpc/level3/peer/provide/*`
+     - `src/rpc/level3/peer/return/*`
+     - `src/rpc/level3/peer/third_party/*`
    - Latest slice:
-     - `src/rpc/peer/peer_state_types.zig` extracted for provide/join state types.
+     - `src/rpc/level3/peer/peer_state_types.zig` extracted for provide/join state types.
 
 2. P1-5: Add allocation-size limits to reader path. **Done**
-   - `src/reader.zig` uses bounded `max_total_words` checks and overflow-safe arithmetic.
+   - `src/serialization/reader.zig` uses bounded `max_total_words` checks and overflow-safe arithmetic.
 
 3. P2-6: Add comments in critical paths. **In progress**
    - Message packing/unpacking and far/double-far pointer resolution comments added.
@@ -55,6 +55,6 @@ Latest full run in this branch state:
 
 ## Next Execution Order
 
-1. Finish remaining P1 decomposition slice(s) that reduce `src/rpc/peer.zig` readability risk without API churn.
+1. Finish remaining P1 decomposition slice(s) that reduce `src/rpc/level3/peer.zig` readability risk without API churn.
 2. Complete P2 comments pass over remaining complex pointer/state-machine sections.
 3. (Done) Vendored `vendor/ext/libxev` removed; libxev is now sourced exclusively via `build.zig.zon` URL+hash.

README.md

@@ -207,10 +207,19 @@ The project includes comprehensive tests:
 # Run all tests
 just test
 
-# Run specific test suites
-zig build test-message      # Message tests
-zig build test-codegen      # Codegen tests
-zig build test-rpc          # RPC tests
+# Run broad test groups
+zig build test-serialization # Serialization-focused suites
+zig build test-rpc           # All RPC suites
+
+# Run RPC suites by Cap'n Proto level (cumulative)
+zig build test-rpc-level0    # Framing/protocol/cap-table
+zig build test-rpc-level1    # Promises/pipelining
+zig build test-rpc-level2    # Runtime plumbing
+zig build test-rpc-level3    # Advanced peer semantics (level 3+)
+
+# Run specific focused suites
+zig build test-message       # Message tests
+zig build test-codegen       # Codegen tests
 just e2e                    # Cross-language interop harness
 ```