1# Performance measurement
2
3vev measures the current session and attachment stack with process-local runtime
4marks and harness-owned end-to-end boundaries. Measurement does not alter
5rendering, pacing, transport policy, wire bytes, or `ProtocolVersion`.
6
7## Canonical matrix
8
9The canonical matrix is [`testdata/perf/manifest.json`](../testdata/perf/manifest.json):
10
11- topologies `1x4`, `4x1`, `4x4`, and `8x1`;
12- `120x40` terminal content with 10,000 history rows per pane;
13- idle, active output, all/inactive output, interactive flood, copy search,
14  resize sweep, snapshot/output/resize, and attach/restore/tab switch;
15- local, SSH stdio, direct UDP, UDP with 25/100 ms latency, and UDP with 0%/1%
16  loss.
17
18The matrix contains 252 scenarios (4 topologies × 9 workloads × 7
19transports). Inapplicable scenarios stay present with an explicit reason.
20Multiple-attachment scenarios measure shared session mutations together with
21independent attachment views and output streams.
22
23A connection handshake is bounded by 15 seconds. A command request is bounded
24by 10 seconds. These limits apply during measurement as well as normal use.
25
26## Trace schema and clocks
27
28Every process JSONL record has exactly these fields:
29`schema`, `process_id`, `component`, `scenario`, `run`, `sequence`, `request_id`,
30`epoch`, `kind`, `tick`, `bytes`, `fragments`, `retransmits`, `pending`,
31`ack_rtt_nanos`, and `valid`.
32
33Schema 1 is represented by:
34
35```json
36{"schema":1,"process_id":"p","component":"daemon","scenario":"s","run":1,"sequence":1,"request_id":1,"epoch":1,"kind":"diff_start","tick":0,"bytes":0,"fragments":0,"retransmits":0,"pending":0,"ack_rtt_nanos":0,"valid":true}
37```
38
39The concrete JSONL observer stamps `tick` with its process-local injected
40monotonic clock; producers supply no timestamp. Components in one OS process
41share that observer. The harness owns a separate monotonic clock for the
42input-injection to successfully-flushed-terminal-bytes boundary. Ticks from
43different processes or clock domains are never ordered or subtracted. Records
44correlate through scenario, run, sequence, request, and epoch IDs.
45
46Process-local spans cover capture, compose, diff, queue wait, acknowledgement
47blocking, emit, adapter send, and adapter receive. Bytes, fragments,
48retransmits, pending work, and acknowledgement RTT remain diagnostics rather
49than duration inputs. Reports retain raw records, counts, p50/p95/p99, and max
50where applicable.
51
52## Running the matrix
53
54Use a clean build and at least a 10-second warmup, a 30-second measured
55interval, and ten independent repetitions:
56
57```sh
58go build -o /tmp/vev ./
59rm -rf testdata/perf/results
60go run ./cmd/vev-perf-harness \
61  --vev-bin /tmp/vev \
62  --manifest testdata/perf/manifest.json \
63  --out testdata/perf/results \
64  --warmup 10s --duration 30s --repetitions 10
65```
66
67Each run writes `manifest.json`, `raw-harness.jsonl`, one trace per launched
68process, `runs.json`, and `summary.json`. The process manifest records process
69identity, role, scenario/run, clock domain, and its exclusive trace path.
70
71The harness injects at most one measured event per second. A sample requires
72both input injection and successful terminal flush inside the measured
73interval; warmup, straddling, and failed events remain raw diagnostics. Reject
74results with missing or unmatched boundaries, invalid correlation,
75nonmonotonic same-process sequence, negative same-domain duration, fewer than
7610 complete in-interval pairs, invalid denominators, cross-process tick math,
77less than 30 seconds measured, or fewer than 10 repetitions.
78
79Before a full run, validate the manifest and harness:
80
81```sh
82jq -e '(.topologies|length)==4 and (.workloads|length)==9 and (.transports|length)==7 and (.scenarios|length)==252' testdata/perf/manifest.json
83go test ./cmd/vev-perf-harness
84```
85
86For a bounded local check, add `--scenario 1x4-idle-local`. The harness still
87validates the complete manifest before selecting that scenario. Do not commit
88result directories; raw traces and run manifests are the measurement evidence.
89
90## In-process checks
91
92These commands measure local daemon or VT work only, not end-to-end transport
93latency:
94
95```sh
96go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkDaemonHistory' -benchtime=1x -benchmem
97go test ./pkg/renderer ./pkg/vt ./internal/adapters/ipc -run '^$' -bench=. -benchmem
98go test ./internal/usecase/daemon -run '^$' -bench '^BenchmarkComposeCapturedFloatingFrameCached$' -benchmem
99```