The command consumes canonical sketchkit summary v1
files. After validating original inputs and normalizing the optional extensions
documented below, it combines each window independently using summary.Combine,
then checks cross-window compatibility using summary.Compatible. Each frequent-items state
is checked for totals consistent with its retained bounds before combination,
including replayed snapshots and measurements not displayed. Before must end at or before
after begins; durations and measurement settings must match.
Only cumulative snapshots are accepted. Replays do not add counts. The highest sequence per producer/process epoch replaces earlier snapshots, subject to the summary contract's checks. Nonoverlapping restart epochs contribute separately; conflicts and overlapping epochs are rejected. Historical windows are supported.
The same explicit expected producer set applies to both windows. Missing sources
and partial collection intervals require --allow-partial. That option permits an
observed comparison, not a claim of complete workload change. Empty inputs fail.
Expected IDs are exact summary producer_id values from trusted exporter
inventory, not input filenames or user/session identities.
Report JSON has version 1 and contains only:
- Selected window times, durations, snapshot counts, and coverage aliases.
- Allowlisted observed counters with signed arithmetic deltas and declared units.
- Available request/missing-usage counts; absent coverage fields are not inferred.
- Allowlisted distinct estimates and nominal HLL RSE (
1.04 / sqrt(2^p), using normal precision even for sparse state, not a per-input error guarantee). - Configured frequent-item weight totals, per-window error, candidate counts,
intervals, and tracked directions. Hashes appear only with
--show-hashes. - Counts of omitted measurement names and explicit interpretation notes.
Optional output measurements are not synthesized as zero. Unknown measurements remain subject to input compatibility checks but their names and values are not exported. Collector token-field diagnostic counters outside the allowlist are included in the omitted count; use the collector metrics for their detail.
All candidates from each no-false-negatives frequent-item query are unioned before output truncation. The default is 20 displayed rows; the maximum is 100. For each candidate, query both sketches' lower and upper bounds, including untracked bounds. Subtract endpoints to obtain the deterministic interval for observed weight change.
An interval entirely above zero is increased; entirely below zero is decreased;
exactly [0,0] is unchanged; all other intervals are uncertain. This direction
describes observed keyed weight.
A key outside the full candidate union has a change within
[-before.max_error, after.max_error]. Keys omitted only by the display limit do
not inherit that smaller untracked bound. Sorting uses descending maximum absolute
delta endpoint and then ascending hash for deterministic ties. Overlapping
intervals do not establish true rank order.
Legacy top_prompts is usually token-weighted by the connector; the report
preserves its generic configured-weight label for compatibility.
Release v0.3.0 also recognizes top_users, top_sessions,
top_users_requests, and top_sessions_requests. The unsuffixed names follow
the token-weighted exporter convention; _requests names follow the
request-weighted convention. Their units are attributed-reported-tokens and
attributed-model-attempts, respectively, not all application usage. Compatible
accounting declarations and top-k contract markers are required. The same
extension recognizes top_docs, top_mcp_sessions, top_mcp_methods, and
top_mcp_resources, plus their _requests variants and top_prompts_requests.
These optional names and the investigation's session share flags are not
supported by v0.2.0 binaries.
Each new known top-k sketch requires a zero-valued counter named
topk_contract.v1.<measurement>.<digest>, with the exporter's 32-character
lowercase hexadecimal contract digest. Legacy top_prompts does not require
this marker. Markers describe the measurement contract, not additive counts or
authenticated identity; they are not shown as usage counters.
If a known optional top-k measurement is absent from any input snapshot, v0.3.0
omits it across both windows, lists it in dropped_measurements, and counts
it as omitted. It does not treat missing attribution as zero. Every original
snapshot and every present measurement contract is validated first, including
superseded snapshots. Present but incompatible contracts still fail; omission
does not bypass scope, key, accounting, replay, or structural checks.
The runtime reads local files and writes stdout/stderr, offline and read-only. Transfer inputs through authenticated channels and follow Safe Use for producer and metadata trust.
Metadata and arbitrary measurement names can contain sensitive data. The report uses reviewed names and generated aliases rather than reflecting input. Error messages do not quote command arguments, filenames, or malformed JSON. Opt-in hashes follow the export privacy rules.
The input limits bound encoded bytes, file count, and directory entries, not a promise of constant CPU time or a measured maximum RSS. Parsing and canonical validation also allocate decoded sketch state. Linux and macOS are the initial supported operating systems; regular-file opening uses nonblocking/no-follow flags and a confined directory root.
Exit codes: 0 means a report or help was written; 1 means input, comparison,
or output failure; 2 means invalid command options. An explicitly allowed
partial report exits 0 and carries its partial state. Output write failure can
leave bytes already accepted by stdout; input/validation errors emit no report.
Use --format json for automation. A report is one JSON object followed by a
newline; diagnostics are on stderr. Top-level version identifies the report
contract, independently of the binary version and input summary version.
Within report v1, existing field meanings and types are preserved. Consumers should ignore added fields, handle new allowlisted measurement names, and reject unsupported major report versions. Removing or reinterpreting a field requires a new report version. Text layout, diagnostic wording, ordering of explanatory notes, and display rankings are not machine interfaces. Numeric counters and bounds can exceed JavaScript's exact integer range: use an integer-preserving JSON decoder rather than rounding them through floating point.
counters, distinct, concentration, and coverage alias lists are arrays even
when empty. token_coverage is absent when its input counters are unavailable.
hash is absent unless requested. Missing measurements are not implicit zeros.
Use each measurement's name rather than its array position. Aliases identify
only this comparison; they are not durable cross-report entity IDs.
The complete_observation_intervals boolean refers to the expected producer set
and declared observation intervals. Check token_coverage separately.
Coverage describes supplied observations, not proof of complete upstream delivery. Token counts retain each model's units rather than normalized compute. Use Reading The Results for billing and causality and Safe Use for trust requirements before acting on any report.