[randomizedcoder]

Adds an opt-in TCP route-treatment control plane: ClickHouse socket evidence produces destination-specific hypotheses, operators approve gradual per-location canaries, and agents apply and withdraw verified route overrides through goip. xtcp2 stays observe-only unless this is deployed; route application is disabled by default and needs explicit agent configuration.

The nearby-traffic profile requests CUBIC, a 5 ms minimum RTO, quick ACK, and initial send and receive windows of 100 segments.

The branch is the original feature commit followed by eighteen commits that apply an architecture review item by item, so the history reads as the review being addressed, then eight follow-up commits (F1-F5) for the review's TODOs. docs/status-tcp-controller.md maps each review item to its commit, records the design notes per item, and lists the open TODOs.

Shape

• pkg/treatment is the shared contract only: domain types, IDs, limits and validators. No I/O, no gRPC, no SQL.
• pkg/treatment/identity parses SPIFFE identities, builds the mTLS config, and provides the unary and stream interceptors that resolve the caller once and enforce the role each RPC declares as a proto option. A test fails when any registered RPC lacks a role.
• pkg/treatment/experiment is the pure decision core (Evaluate, Advance, cohort allocation) plus an explicit (status, event) transition table; every pair has a row, and outcomes are an Outcome enum rather than strings.
• pkg/treatment/reconcile holds the reconciler, the journal, the Backend interface and a Mode type. The journal is a journal-specific prototext message, so neither the RPC proto nor the domain model is an on-disk format. The journal lock waits, bounded by the caller's context; only xtcp2-treatmentctl -mode=status stays non-blocking.
• pkg/treatment/agent is a library used two ways. cmd/xtcp2-treatment-agent runs it standalone. cmd/xtcp2 embeds it behind the treatment build tag (-treatmentConfig). The untagged daemon reads the standalone agent's journal snapshot through pkg/treatment/attribution (-treatmentAttribution) and links no gRPC credentials or TLS. The watchdog (xtcp2-treatmentctl) is a separate process in both modes and can only withdraw.
• One location rule: the daemon and its agent refuse to start when their locations differ, a daemon without a location adopts the agent's, and records are no longer rewritten per host.
• pkg/treatment/controller is thin gRPC handlers and orchestration (Maintain, Discover) over ports. controller/store defines the repository interfaces (Agents, Experiments, Evidence, Holds, Audit, Metrics) and a Tx boundary that takes the mutation lock. store/postgres holds every SQL string, on a relational schema, through pgx v5 via database/sql (lib/pq removed). store/memory backs the handler tests and store/storetest is the conformance suite both stores pass. Evidence is stored once with a content digest; audit payloads are the only JSONB.
• controller/evidence defines the Source and CandidateSource ports; ClickHouse is one adapter implementing both.
• Evidence is bound to sessions: each agent process draws a collection nonce, writes it into its journal header (where a telemetry-only daemon stamps it into records) and reports it with its boot ID at check-in. The controller keeps every (agent_id, boot_id, collection_id) it has heard, at most eight per agent per window, and the analysis query measures only records stamped with one of them; the rest are counted per host as unbound_sockets and shown to the reviewer. Discovery proposes only enrolled hosts.
• Experiments.List and Get load in a fixed number of statements (six for any list size), pinned by a statement-counting test.
• The proto lives in proto/xtcp_treatment/v1 (treatment.proto, agent.proto, operator.proto) with buf.validate rules that mirror the Go validators and a per-RPC role option. It is wire-only; pkg/treatment/wire converts at the gRPC boundary and a test checks the proto rules against the validators.
• internal/goip/actuate holds the route backend, built on a typed xtcpnl.RuleWrite builder parallel to RouteWrite; the argv parser is out of the mutation path.
• Scale: the notification scan is a watermark over desired_updated_at stamped with the store clock, check-ins rewrite algorithm and record rows only when the report digest changes, and Maintain and Discover run under a housekeeping lease so one replica does periodic work while the others skip.
• TestTreatmentImportBoundaries enforces the layering with go list -deps: the untagged daemon links no database/sql, pgx, ClickHouse or controller code; the reconciler and watchdog link no gRPC credentials; identity is a leaf.
• Socket protobuf, ClickHouse and Parquet records carry treatment attribution and the observed congestion algorithm, stamped through a nil-checked, zero-allocation hook.
• Nix: seven-guest VM integration test with Go orchestration (repeated netem RTT changes, discovery, reviewed canaries, rollback, cooldown), unit and race harnesses with PostgreSQL and ClickHouse fixtures, benchmark target, NixOS module and package wiring for the four binaries.

Docs

• docs/tcp-controller.md: deployment, rollout, recovery, database, trust boundaries and threat model (what a host can and cannot assert about evidence, and how the analysis query, sample minimums, freshness, human review and immutable evidence bound it), names and surfaces, and SIGHUP meaning "reconcile now" only.
• docs/tcp-controller-testing.md: test contracts, a coverage table generated by the unit target, and remaining gaps.
• docs/benchmarks/tcp-controller/postgres-indexes.txt: produced by nix build .#bench-tcp-controller-postgres-indexes.
• docs/status-tcp-controller.md: item-to-commit table, per-item notes, and open TODOs (gRPC stubs still reachable through the flat-record package, evidence window parameters approaching ClickHouse's URL limit at 10,000 agents, ipmeta-bootstrap -help exit code, regenerating every proto with the pinned generators).
• docs/README.md now states that xtcp2 changes nothing on the host except through this opt-in, human-reviewed controller.

Validation

All on the branch head:

• nix build .#checks.x86_64-linux.lint-baseline: pass (all three golangci tiers, zero findings). The comprehensive tier's 107 findings on the new code were fixed by restructuring, with no //nolint, exclusions or threshold changes.
• nix build .#test-tcp-controller-unit: pass (PostgreSQL repository conformance for every method, handler tests on the in-memory store, ClickHouse SQL counter-delta test, import-boundary test, state-machine and wire round-trip tables).
• nix build .#test-tcp-controller-race: pass.
• nix run .#test-tcp-controller-vm -- --accel=auto: pass, all 8 sentinels (netem RTT change and discovery, reviewed canary, controller restart persistence, holds, evidence binding, harmful-treatment rollback, watchdog expiry, overall). In the binding stage, records copied under a fake boot and nonce for one cohort host came back as 32 unbound sockets while its 32 bound sockets were measured as before.
• nix build .#checks.x86_64-linux.cli-help-smoke-<binary>: pass for the four treatment binaries.
• nix build .#bench-tcp-controller-postgres-indexes: pass.
• go test -tags treatment ./cmd/xtcp2/: pass (embedded agent mode).

Operational limits

Promotion and stable-treatment replacement require operator review. The actuator supports host-namespace IPv4 /32 and IPv6 /128 overrides with simple baseline routing; established sockets can retain previous settings. Route conflicts are refused, and disabling the owned lookup after an apply failure can itself fail. Discovery examines its ten busiest candidates before filtering existing treatments, which can defer other candidates. The schema is pre-release: tables and indexes are created by Migrate with no ALTER path yet. Evidence is bound to sessions the agents report over mTLS, but the nonce travels in the same unauthenticated telemetry, so a reader of the topic can copy a live session; see the threat model section for what that does and does not prove.

🤖 Generated with Claude Code