perf(CC-364): single streaming jq pass for pmctl trace tail

[screenleon]

CC-364 — pmctl trace tail single streaming jq pass

Problem

pmctl trace tail spawned two jq processes per event in the scan phase
(jq -c type check + jq -r @tsv field extract) plus one more per row in the
human emitter. --all was O(n) with a high constant — ~20s for 338 events.

Change

Scan phase is now one jq -R streaming pass over the concatenated
archive + active stream. It classifies each line (malformed / filtered-out /
kept) and emits kept rows as <ts>\t<line_no>\t<compact-json>, using jq's
cumulative input_line_number as the global read-order tiebreaker for events
sharing a timestamp. Both emit helpers stream through a single jq via cut -f3.

Measured: 400 events --all --json ~24s → 0.2s (~100x); jq invocation
count is now fixed (1 for --json, 2 for human) regardless of event count.

Behavior parity (unchanged)

--kind / --task / --subject / --id filters, inclusive lexicographic
--since/--until window (empty ts excluded when bounded), malformed-row
tolerance + trace: skipped N malformed row(s) warning, archive/active
chronological merge, -n / --limit / --limit 0 / --all semantics,
compact-JSON byte identity. Drops the five module-global _PMCTL_TRACE_*
vars and three now-dead scan helpers.

Reuse note

pmctl-run-stats.sh (CC-358) has the same archive+active events.jsonl scan
shape with a per-line jq spawn. Deliberately not refactored here — different
jq program + shell-side aggregation, out of CC-364 scope, and a shared
"event source" primitive would be a single-consumer abstraction until run-stats
is also converted. Left a pointer comment; no ticket exists yet for that
follow-up.

Tests

• case_trace_large_partition_streaming — 240 active events across 3 disjoint
  timestamp bands + 2 malformed rows; asserts count, non-decreasing merge
  order, skip warning. Active-only so it always executes.
• case_trace_tail_single_jq_pass — counting jq shim on PATH; asserts the
  invocation tally is equal (and non-zero) for a 20-event and a 200-event run,
  i.e. O(1) in event count. Fault-sensitive: a per-event regression makes the
  200-event tally ~10x the 20-event one.
• test-pmctl-trace.sh 14 passed; full suite run-all-tests.sh 105 passed,
  0 failed, 0 skipped.

PR-gate

3 rounds (round 1 NO-GO on two test-only qa-tester findings, rounds 2–3 GO;
rounds 2–3 sequential). Final round: critic / qa-tester / architecture /
security all approve, zero findings.

BACKLOG

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

🤖 Generated with Claude Code