Document the Rust-core / Xray boundary (ADR-0007) to stop data-plane confusion

[maybeknott]

Summary

This proposal set (Topology A/B Rust↔Xray SOCKS5 handoff, dial_upstream_via_xray_socks, TCP sequence-number injection, SNI spoofing, eBPF/XDP packet rewriting, "Rust as egress engine", CoherentMachineConductor) all rests on one assumption: that the Rust core forwards bytes to the internet. I verified against the actual source that it does not. So the right move is not to wire in a data plane — it's to document the boundary so this recurring confusion stops generating large, off-strategy rewrites.

What the source actually shows

• PolicyAwareTlsBackend (tls_orchestrator_backend.rs) — only models ALPN lock/bypass; no socket dialing.
• main.rs handle_client — reads + parses a ClientHello and runs a JA3 self-audit; never forwards upstream or hands off to Xray.
• The only TcpStream::connect in src/ is the client side of a unit test in ingress_loopback.rs.
• ingress_xdp_gateway.rs, ingress_android_tun.rs, cooperative_overlay.rs, scheduler.rs are models/fixtures, not loaded kernel programs or a live egress scheduler.

The proposal's own ingress_loopback.rs snippet even gets the type wrong (destination: self.destination_hint as non-Option), while the real code uses Option<SocketAddr> — a tell that it's working from an approximate mental model, not the repo.

What I changed (docs + one harmless doc-comment)

• docs/adr/0007-rust-core-is-validation-not-data-plane.md (new) — establishes that the Rust core is a validation/parsing/policy-modeling library + self-audit harness, explicitly not the data plane. Packet-injection / SNI-spoofing / raw-socket / eBPF-on-egress / "Rust as egress" are out of scope and would require a new ADR revisiting ADR-0001 plus a real threat-model review plus the consent-based privilege story from ADR-0002/0006. Notes that process_supervisor.py already gives atomic Rust+Xray lifecycle containment (Windows Job Object kill-on-close / POSIX group) without changing the byte path — so a "run both as one machine" conductor needs no data-plane change.
• docs/architecture.md — adds a "Rust core: validation library, not a data plane" section making the Xray = data plane / Rust = validate around it split visible in the primary architecture doc (it previously documented only the Xray runtime graph and never said what src/ is).
• src/ingress_xdp_gateway.rs — module doc-comment clarifying it is a model/fixture, not a loaded eBPF program (most misleading module name).
• docs/repository-structure.md — indexes ADR-0007.

Idea-by-idea disposition

Proposed item	Disposition
Shared ProjectState / CheckResult / RepairAction, listener-exposure warning, one next action	Already shipped (in main) — see scripts/core/readiness.py
Runtime evidence bundle + JA3 oracle	Already shipped in merged PR #3 (verified-session)
Process lifecycle conductor	Building block already exists (process_supervisor.py, atomic kill-on-close)
Topology A/B Rust↔Xray byte handoff, packet injection, SNI spoof, eBPF egress	Out of scope per ADR-0007 — contradicts the verified Rust-core role and ADR-0001
"Less surface area / one truth layer / sharper safety warnings" north star	Already the implemented direction; reinforced by documenting the boundary

Why docs, not code

The Rust core deliberately has no data plane (ADR-0001). Adding one would be a second competing runtime, raising exactly the complexity the feedback says to reduce, and would pull in raw-socket privileges that ADR-0002/0006 keep consent-based. The highest-leverage fix is to make the boundary explicit so future proposals are evaluated against it.

Testing

py -3 main.py test   ->  All 34 checks passed

Rust unchanged except a doc-comment (cargo absent in CI sandbox → Rust step skips as designed; comment is syntactically inert).

[qodo-code-review]

Review Summary by Qodo

Document Rust-core/Xray boundary (ADR-0007) to prevent data-plane confusion

📝 Documentation

Walkthroughs

Description

• Establishes Rust core as validation library, not data plane
• Clarifies boundary between Rust validation and Xray data plane
• Prevents recurring confusion about packet forwarding scope
• Adds module documentation to reduce misleading naming

Diagram

flowchart LR
  A["Rust Core<br/>Validation Library"] -->|config + evidence| B["Xray<br/>Data Plane"]
  C["Proposals:<br/>SOCKS5, Packet Injection,<br/>eBPF/XDP, SNI Spoofing"] -->|out of scope| A
  D["process_supervisor.py<br/>Lifecycle Management"] -->|atomic containment| B

Loading

File Changes

1. docs/adr/0007-rust-core-is-validation-not-data-plane.md 📝 Documentation +76/-0

New ADR clarifying Rust validation boundary

• New ADR establishing Rust core as validation/parsing/policy-modeling library, not data plane
• Documents that Rust does not forward bytes, perform SOCKS5 handshakes, or load eBPF/XDP programs
• Clarifies integration with Xray is config-and-evidence only, not in-band byte handoff
• Explains why packet-injection, SNI-spoofing, and "Rust as egress" proposals are out of scope
• Notes process_supervisor.py provides atomic lifecycle containment without changing byte path

docs/adr/0007-rust-core-is-validation-not-data-plane.md

---

2. docs/architecture.md 📝 Documentation +21/-0

Add Rust validation library architecture section

• Adds new section "Rust core: validation library, not a data plane"
• Explicitly states Rust is not on live traffic path and does not forward bytes to internet
• Defines clear split: Xray = data plane, Rust = parse/classify/model/self-audit
• Clarifies integration is config + evidence, never in-band byte handoff
• References ADR-0007 for full boundary details and scope exclusions

docs/architecture.md

---

3. src/ingress_xdp_gateway.rs 📝 Documentation +8/-0

Clarify XDP gateway is model, not live program

• Adds module-level documentation clarifying this is a validation model, not loaded eBPF/XDP program
• References ADR-0007 and ADR-0001 to establish Rust core is not data plane
• Warns against wiring raw-packet manipulation or kernel programs into this module
• Explicitly states data plane belongs to Xray

src/ingress_xdp_gateway.rs

---

View more (1)

4. docs/repository-structure.md 📝 Documentation +1/-0

Index ADR-0007 in repository structure

• Indexes new ADR-0007 in the adr/ directory listing

docs/repository-structure.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review