perf(CC-573): single streaming jq pass for pmctl run-stats

[screenleon]

CC-573 — pmctl run-stats single streaming jq pass

Problem

pmctl_run_stats_extract_line ran one jq -r per events.jsonl line.
Profile (jq-counting shim + wall clock):

N events	jq invocations	wall
100	102	3.0s
300	302	8.8s
900	902	30.2s

Linear at ~34ms/event. The real state store's events.jsonl (6642 lines)
made pmctl run-stats --json exceed a 2-minute foreground timeout
(~225s extrapolated). run-stats is v1.0 readiness evidence tooling (CC-358
DoD) and could not complete on real data. Same shape CC-364 removed from
pmctl trace tail.

Change

Scan phase is now one jq -R streaming pass over the concatenated
archive + active stream. It emits a TSV row per run.* event that passes
the --since bound (predicate identical to the former shell check:
dropped only when a bound is set AND ts is non-empty AND ts < bound); the
bash loop folds rows into the _rs_* maps with no per-line jq. New helpers
pmctl_run_stats_filter_program + pmctl_run_stats_scan_stream replace
extract_line / process_line / scan_path / scan_gzip_path.

Result: jq invocations 102/302/902 → 2/2/2; wall 3.0–30.2s → 0.19s
flat. Output byte-identical (jq -S normalized JSON + human) to
origin/main across a run with --since filtering and a rotated archive.

Behavior parity (unchanged)

--since lexicographic ISO-8601 filter, malformed-row silent skip
(run-stats has never counted them), archive-inclusive scan +
gzip-unavailable _meta fallback, --by-adapter, output schema, CLI.
fallback_used event signal (CC-358) untouched.

Reuse note

The archive-glob + gzip-check + concat-then-one-jq-pass idiom (~12 lines) is
now duplicated with pmctl-trace.sh. Extraction into a shared events-scan
primitive was considered and deferred: the two jq programs and output
consumers differ, and the gzip-unavailable signalling diverges (trace tail
read_archives=0; run-stats archive_scanned=false + _meta). At two
consumers the shared seam isn't clearly worth the callback indirection —
documented in the file header; revisit if a third consumer appears. No
ticket filed.

Tests

• case_run_stats_single_jq_pass — counting jq shim asserts the invocation
  tally is equal (and non-zero) for a 20-run and a 200-run partition
  (O(1) in event count).
• case_run_stats_streaming_matches_reference — heterogeneous fixture
  (valid terminals, partial, nonzero exit, cancelled, missing-terminal,
  fallback_used, pre---since row, two malformed lines, a non-run event,
  an archived-only run; three adapters) compared byte-for-byte (jq -S)
  against the golden JSON frozen from origin/main.
• test-pmctl-run-stats.sh 17 passed; full suite run-all-tests.sh
  105 passed, 0 failed, 0 skipped.

PR-gate

2 rounds. Round 1 GO with one critic advisory (medium: no field-level
equivalence oracle — CC-573's own Req 5); added the golden test; round 2
sequential, clean GO — critic / qa-tester / architecture / security all
approve, zero findings.

BACKLOG

CC-573 index row + body marked ✅ done with a Closure 2026-08-27 (pr:#547) note in this PR. validate.sh, test-pmctl-backlog,
test-archive-closed-backlog, test-schema-task-mirrors-backlog all pass.

🤖 Generated with Claude Code