producer: the explicit bind-policy gate + the builder-register pin (review-002 C-3, D-2, S-1, N-2)

- C-3: Socks5ProducerBuilder.bind_policy(bool) — the substrate-free
  entry's explicit BIND gate, defaulting to the accept seam's
  presence; seam presence is never the sole gate
- D-2: RegisterMode::ProducerBuilder + an integration test wiring the
  full builder through .register(...) serving all three commands
- S-1: run_datagram_stage's doc names the hot-Ok(None) residual
- N-2: wire.md §UDP ASSOCIATE carries the inline-send backpressure line

Verified: cargo test (352 green), clippy/fmt/doc clean, wasm checks clean.
This commit is contained in:
glm-5.3-flash committed 2026-09-24 18:04:55 +00:00
1 parent 53739b20cb
commit ff81f2d27b
5 files changed
+393 -17

No files matched your search

@@ -1,7 +1,7 @@
---
id: implementation/fix-producer-gate-policy
name: "Fix — producer BIND gate policy + register coverage + stage doc lines (review-002 C-3, D-2, S-1, N-2)"
status: pending
status: completed
depends_on: []
scope: narrow
risk: medium
@@ -66,21 +66,21 @@ ride the same files
## Acceptance Criteria
- [ ] The substrate-free entry's BIND gate is an explicit policy
- [x] The substrate-free entry's BIND gate is an explicit policy
input (with-gate entry or builder field); `accept.is_some()`
remains only as the backward-compat default, never the sole
gate
- [ ] Test: accept factory wired + explicit `can_bind=false` ⇒ BIND
- [x] Test: accept factory wired + explicit `can_bind=false` ⇒ BIND
refused 0x02; CONNECT/ASSOCIATE still serve
- [ ] The pump handler's identity-derived gate is unchanged (the
- [x] The pump handler's identity-derived gate is unchanged (the
existing identity matrix stays green)
- [ ] Integration test: full builder (`dial` + `egress` + `accept`)
- [x] Integration test: full builder (`dial` + `egress` + `accept`)
through `.register(...)` serving all three commands over the
harness topology
- [ ] `run_datagram_stage`'s doc names the hot-`Ok(None)` residual
- [ ] wire.md §UDP ASSOCIATE carries the inline-send backpressure
- [x] `run_datagram_stage`'s doc names the hot-`Ok(None)` residual
- [x] wire.md §UDP ASSOCIATE carries the inline-send backpressure
line
- [ ] `cargo test` green; clippy/fmt clean; both wasm checks clean
- [x] `cargo test` green; clippy/fmt clean; both wasm checks clean
## References
@@ -94,8 +94,66 @@ ride the same files
## Notes
> Agent fills this during implementation.
- **C-3 shape chosen: the builder field** (`.bind_policy(bool)`),
not a separate `serve_socks5_over_with_gate` entry — the review's
sketch allowed either; a builder field keeps the entry's signature
untouched (one `serve_socks5_over` shape), rides the existing
builder chain, and the policy is resolved once at `build()`
(`self.bind_policy.unwrap_or(self.accept.is_some())` —
`Option<bool>` on the builder, `bool` on the built producer). The
free function `serve_socks5_over` (already gate-explicit) and the
pump handler (identity-derived, ADR-006) are untouched.
- **D-2 vehicle: a new `RegisterMode::ProducerBuilder`** in
`tests/harness.rs` wiring the full builder chain
(`.dial().egress().accept()` + the optional `.bind_policy()`)
through `Socks5Producer::register` — the harness's registration
block gains a third arm (same `ChannelCore` +
`register_openable_with_establisher` shape as the others, via the
delegated method). The integration test
(`producer_builder_registers_and_serves_all_three_commands` in
`tests/core-integration.rs`) serves CONNECT + ASSOCIATE + BIND
over the topology and asserts the identity witness (proving the
builder-delegated establisher ran). C-3's gate tests live in the
producer unit suite (`builder_bind_policy_false_refuses_bind_
while_connect_associate_serve`, `builder_default_bind_policy_
follows_accept_presence`) — the substrate-free entry is a unit
shape; the builder-through-register surface is the integration
one.
- **The `bind_policy(false)` test** pins: 0x02 on BIND with the
accept factory wired, the factory never called (no phantom
listener), the in-stream `AuthenticationRejected` session error,
and CONNECT + ASSOCIATE still serving the same producer.
**The default test** pins the backward-compat reading: accept
wired + policy unwired ⇒ BIND serves (factory ran); accept
unwired + policy unwired ⇒ 0x02.
- **S-1/N-2 are doc lines only** (per the review's recommendation —
posture notes, not backoff/budget code): a residual paragraph on
`run_datagram_stage` (hot-`Ok(None)` = a yielding busy-wait,
bounded by the egress's own correctness, accepted-uncovered by
design) and a bolded inline-send sentence on the wire.md §UDP
ASSOCIATE producer-egress bullet.
## Summary
> Agent fills this on completion.
All four items landed (C-3, D-2, S-1, N-2). `Socks5ProducerBuilder`
gained `.bind_policy(bool)` — the substrate-free entry's explicit
BIND gate, defaulting to the accept seam's presence (the built
producer resolves it to a plain `bool`); `Socks5Producer::
serve_socks5_over` now consults the policy instead of
`accept.is_some()`. The pump handler's identity-derived gate is
byte-identical (the identity matrix stayed green untouched). Two
unit tests pin the policy (explicit-closed refuses 0x02 with the
factory un-called while CONNECT/ASSOCIATE serve; the
presence-default both ways). A new harness mode
(`RegisterMode::ProducerBuilder`) plus one integration test wires
the full builder through `.register(...)` and serves all three
commands end to end — the spec'd assembly shape is no longer
unexercised. Doc lines: `run_datagram_stage` names the hot-`Ok(None)`
residual (S-1); wire.md §UDP ASSOCIATE carries the inline-send
backpressure bound (N-2). Verification: `cargo test` 352 green (125
lib + 38 associate + 41 bind + 40 connect + 41 integration + 30
harness + 37 differential + 3 doctests, 2 ignored — the two new
unit tests and the one new integration test added to the review's
348 baseline), `cargo clippy --all-targets -- -D warnings` clean,
`cargo fmt --check` clean, `cargo doc --no-deps` clean, both wasm
checks (`cargo check` + `clippy -D warnings`, wasm32) clean.