core: the cross-cutting integration suite + docs sync

The batch-1 closing task: nine cross-cutting integration tests
(tests/core-integration.rs) pinning the whole protocol core end to
end over the channels harness, plus the architecture-sync docs pass.

Tests:
- One registration, all three commands: CONNECT + ASSOCIATE + BIND
  interleaved live on the one channels/socks5/sub op; a teardown
  ends only its own session (mux/demux isolation) — the POC #2/#5
  regression guard, complete.
- Concurrency: nine concurrent mixed-command sessions (raw topology)
  and six through the typed consumer sessions (consumer-side
  topology) — the mux/demux pinned in both channel-id allocation
  directions; fresh round-trips after the burst; no channel leaks.
- Teardown matrix (wire.md §Sentinels and lifecycle): CONNECT
  half-close, ASSOCIATE EOF, BIND client-gone (a parked accept so
  the quiet-wait exit is deterministic) — each followed by fresh
  sessions of every command (no connection poisoning).
- Identity/scope matrix (ADR-006 end to end): open-only (CONNECT +
  ASSOCIATE serve, BIND refused 0x02 at the command gate), bind-only
  fail-closed at the open gate for all commands (the spec drift the
  task's phrasing carried, reconciled — ADR-006's open gate requires
  socks5:open unconditionally), both-scopes (everything, granted
  explicitly); the CF-006 witness asserted per row.
- The readiness contract re-pinned under concurrent load: a
  hot-Ok(None) egress across concurrent associations does not starve
  the datagram stage's channel branch.

Docs sync: README Current State ("the protocol core is implemented"
+ the landed inventory; the decomposition residue gone); consumer.md
§Wiring reconciled to the landed session signatures; ADR-006
§Consequences states the grant asymmetry explicitly; lib.rs crate
docs describe the landed surface.

Verification: cargo test 302 green; --all-features green; clippy
--all-targets -D warnings clean; fmt --check clean; both wasm checks
clean; cargo doc --no-deps clean. Batch boundary holds: no
local/composed code, the default crate is protocol-only.
This commit is contained in:
glm-5.3-flash committed 2026-09-24 07:44:54 +00:00
1 parent c57451545d
commit 1ad8d9d489
6 files changed
+1196 -37

No files matched your search

+24 -13
View File
@@ -1,10 +1,10 @@
---
status: draft
last_updated: 2026-09-22 (the targeted fork — ADR-013; the module is
`src/rfc1928/`; the vendor posture retired. The vendor extraction
amendment ADR-011 §Amendment 2026-09-21; Phase 1 initial draft
2026-09-20 — the OQ-SK ledger promoted into ADRs 001-012 and
open-questions.md)
last_updated: 2026-09-24 (the protocol core landed + the cross-cutting
integration suite; the rfc1928 doc's targeted fork 2026-09-22; the
vendor extraction amendment ADR-011 §Amendment 2026-09-21; Phase 1
initial draft 2026-09-20 — the OQ-SK ledger promoted into ADRs
001-012 and open-questions.md)
---
# alksocks — Architecture
@@ -20,16 +20,27 @@ architecture spec docs and the ADRs.
## Current State
Phase 1 (Architecture) — initial draft. Phase 0
(`docs/research/phase-0.md`) is converged (2026-09-14) and
POC-complete (all numbered POCs passed or were dropped with the
scope decision); the OQ-SK ledger's Phase 1 inputs are collected and
promoted into ADRs 001–012. All docs are `draft` — they transition
Phase 1 (Architecture) — the **protocol core is implemented**. Phase
0 (`docs/research/phase-0.md`) is converged (2026-09-14) and
POC-complete (all numbered POCs passed or were dropped with the scope
decision); the OQ-SK ledger's Phase 1 inputs are collected and
promoted into ADRs 001–013. All docs are `draft` — they transition
to `reviewed` when their open questions resolve and the architecture
review passes. The RFC 1928 core is implemented (the targeted fork,
review passes.
The landed core (the protocol-only batch; no `local`/`composed` code
exists yet): the RFC 1928 core in `src/rfc1928/` (the targeted fork,
ADR-013 — the vendor group's six tasks landed and passed the
extraction review); the remaining layers follow the decomposition
phase.
extraction review), the ASSOCIATE datagram frame codec (`src/wire.rs`,
ADR-003), the open-op params + typed error surface (`src/params.rs` /
`src/error.rs`, ADR-001), the three seam types (`src/egress.rs`,
ADR-004), the producer half (`src/producer.rs` — the session-gate
establisher, the command-dispatch pump, the three commands, the scope
gates), and the consumer half (`src/consumer.rs` — the
connect/associate/bind session types with teardown ownership). The
batch-1 cross-cutting integration suite (`tests/core-integration.rs`)
pins the core's whole behavior end to end; the `local` and
`composed` provider groups follow (batch 2).
## Documents
+15 -5
View File
@@ -1,6 +1,8 @@
---
status: draft
last_updated: 2026-09-20 (Phase 1 initial draft)
last_updated: 2026-09-24 (the landed session signatures reconciled —
`&ChannelClient` constructors, `impl ToTargetAddr` datagrams, the
`Option`-shaped `recv_datagram`; Phase 1 initial draft 2026-09-20)
---
# alksocks — The Consumer Half
@@ -120,12 +122,12 @@ address) is assembly-layer configuration.
```rust
let session = Socks5ChannelSession::connect(
&mut channel_client, target)?;
&channel_client, target).await?;
let (mut read, mut write) = session.split(); // post-reply payload pipe
let assoc = AssociateSession::associate(&mut channel_client)?;
assoc.send_datagram(dst, &bytes).await?;
let (src, bytes) = assoc.recv_datagram().await?;
let assoc = AssociateSession::associate(&channel_client).await?;
assoc.send_datagram(dst, &bytes).await?; // frames once, ADR-003
let (src, bytes) = assoc.recv_datagram().await?.expect("a datagram");
let door = FrontDoor::builder()
.credentials(cred_table) // RFC 1929 mapping, ADR-005
@@ -134,6 +136,14 @@ let door = FrontDoor::builder()
door.serve(channel_client).await?;
```
The landed session signatures: the constructors take `&ChannelClient`
(shared — many sessions ride one client, the concurrency posture);
`send_datagram` takes `impl ToTargetAddr` (the CONNECT session's
target-construction posture, ADR-012); `recv_datagram()` returns
`Result<Option<(TargetAddr, Bytes)>, SocksSessionError>` — `None` is
the channel EOF (the association's clean end), never an empty
datagram (F-2: an empty payload is a legal datagram).
## Design Decisions
| ADR | Decision | Summary |
@@ -3,7 +3,8 @@
## Status
Accepted (2026-09-20, Phase 1; scope gates POC-validated in shape —
POC #1 (`socks5:open`), POC #5 (`socks5:bind` at command dispatch))
POC #1 (`socks5:open`), POC #5 (`socks5:bind` at command dispatch);
consequence asymmetry pinned by the integration suite, 2026-09-24)
## Context
@@ -60,7 +61,14 @@ distinction at command dispatch from the per-call opener identity.
- Two grants, clean separation: `socks5:open` (egress) and
`socks5:bind` (ingress listeners) — never implied by each other
(the alktunnels ADR-006 Amendment 1 posture: a capability on its
own scope).
own scope). The implication asymmetry is pinned by the integration
suite (`tests/core-integration.rs`, the identity/scope matrix):
`socks5:open` alone serves CONNECT + ASSOCIATE and is refused BIND
(0x02) at the command gate; `socks5:bind` alone grants *nothing*
on the op — the open gate's `required_scopes = ["socks5:open"]`
fails closed for every command (the establisher never runs, no
phantom channel); both scopes, granted explicitly, serve
everything. A BIND-capable deployment grants both.
- BIND's security boundary is enforced even though BIND rides the
same op (ADR-001): the command gate is the mechanism, and it is
POC-validated (POC #5).