wgcloak/docs/DEVELOPMENT_STATE.md

# Development state

End-of-day checkpoint: 2026-09-15. Branch: `main`. Baseline commit:
`313ab00` (`checkpoint: implement wgcloak v1 foundations`). Work after that
checkpoint remains uncommitted in the shared worktree. Several agents have
edited files in parallel; use the inventory below and review the complete diff
before committing.

## Implemented behavior

- The package now has a reusable Rust library (`src/lib.rs`) and a thin binary
  (`src/main.rs`). Integration tests import `wgcloak` instead of compiling
  production modules through `#[path]`; module unit tests run once in the
  library test target.
- Client and server runtime paths support authenticated direct UDP, QUIC
  DATAGRAM, HTTP/3 CONNECT-UDP with HTTP Datagrams, and TLS/TCP length-framed
  fallback. TLS client connections use normal certificate-chain and hostname
  verification. For encrypted transports, shared-secret authentication occurs
  before server backend-session activation.
- Client `auto` uses its configured transport order and bounded connection
  probes, stops on authentication rejection, and reconnects with jittered
  exponential backoff from 250 ms through 30 s. Successful connections reset
  the backoff. The client control `reconnect` command forces another attempt.
- The server runs enabled listeners concurrently, rejects incompatible UDP
  listener port conflicts, and aggregates listener/session statistics. Sessions
  are isolated and use per-session backend UDP sockets. Admission limits cover
  active sessions, per-IP sessions, pending handshakes, and authentication
  attempts.
- The Unix control socket uses a private runtime directory and mode `0600`,
  refuses an active socket, and removes only a verified stale socket. `status`,
  `stats`, and `shutdown` are supported; `reconnect` is client-only. Config and
  certificate/key reload are not implemented. The CLI/control reload request
  returns an explicit unsupported response.
- The local client UDP listener currently tracks one most-recent application
  peer; concurrent local source peers can replace the return target.
- Direct UDP keepalives are one-way. Silent peer loss may not be detected
  immediately; a local transport error or explicit client reconnect is the
  recovery path covered by tests.

## Verification checkpoint

Before the final config and client-ID edits, the full gates passed:

- `cargo fmt --all -- --check`
- `cargo check --all-targets`
- `cargo clippy --all-targets -- -D warnings`
- `cargo test --all-targets --quiet` — 76 tests passed.

After those edits, the config-focused suite passed 12/12, the client-ID focused
transport tests passed, and the current `cargo check` passes. Rerun the full
gates after these edits before treating the tree as audited. The broader
encrypted daemon-runtime end-to-end proof described below is not yet created or
complete; focused transport and HTTP/3 runtime tests do not replace it.

## Remaining work, prioritized

1. Add and complete encrypted daemon-runtime end-to-end proof: local UDP
   application traffic through client runtime, encrypted transport, server
   runtime, and UDP echo backend, including auth rejection, session isolation,
   status/stats, and bounded shutdown. Exercise each encrypted mode where
   practical; do not mistake lower-level transport tests for daemon proof.
2. Rerun formatting, all-target check, strict all-target Clippy, and the full
   suite after the final config/client-ID edits; then review the complete diff
   and reconcile acceptance evidence with `docs/IMPLEMENTATION_CHECKLIST.md`.
3. Add fuzz and benchmark targets for parsers, framing, protocol/auth paths,
   and transport overhead; record the environment and baseline.
4. Decide and document a practical maximum datagram-size cap, with config and
   boundary tests tied to transport overhead and MTU constraints.
5. Confirm whether configuration and certificate/key reload are required by
   the spec/product scope. Until implemented and tested, they remain explicitly
   unsupported; do not imply hot reload in CLI or deployment docs.

## First recovery tasks

1. Inspect current client/server orchestration and transport test APIs, then
   create the encrypted daemon-runtime echo test without duplicating transport
   internals.
2. Re-run the four full gates above against the current tree; resolve any
   compile, lint, or test regressions before adding further features.
3. Review spec milestones and the 17 completion criteria, and record evidence
   for each criterion in the coordinator checklist. Keep fuzzing, benchmarks,
   datagram-cap decision, and reload scope visible as open items.

## Current worktree inventory

Captured with `git status --short` for this checkpoint. These are shared-tree
changes; ownership is not implied by this list.

Modified files:

- `Cargo.lock`, `Cargo.toml`
- `README.md`
- `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT_STATE.md`,
  `docs/IMPLEMENTATION_CHECKLIST.md`, `docs/OPERATIONS.md`, `docs/PROTOCOL.md`,
  `docs/TROUBLESHOOTING.md`
- `examples/client.advanced.toml`, `examples/server.advanced.toml`,
  `examples/server.minimal.toml`
- `packaging/systemd/wgcloak-client.service`,
  `packaging/systemd/wgcloak-server.service`
- `src/cli.rs`, `src/client/mod.rs`, `src/client/supervisor.rs`, `src/config.rs`,
  `src/control.rs`, `src/main.rs`, `src/protocol/auth.rs`,
  `src/protocol/direct.rs`, `src/server/mod.rs`, `src/stats.rs`,
  `src/transport/direct_udp.rs`, `src/transport/http3.rs`,
  `src/transport/mod.rs`, `src/transport/quic.rs`
- `tests/control.rs`, `tests/direct_udp.rs`, `tests/http3.rs`,
  `tests/integration_transports.rs`, `tests/quic.rs`, `tests/supervisor.rs`,
  `tests/tls_tcp.rs`

Untracked files:

- `src/lib.rs`, `src/server/limits.rs`
- `tests/http3_integration.rs`, `tests/http3_runtime.rs`, `tests/limits.rs`,
  `tests/reconnect.rs`, `tests/runtime_lifecycle.rs`