Performance Lens and Provenance-linked Results

1. The real problem: one number, multiple computations

An executive slide says signup performance improved 14%, yet the new export uses a different reporting identity and an extra country filter, while the prior query was not retained. Putting the two values side by side creates a neat but non-auditable comparison. This lesson rebuilds the identity of each result before interpretation.

2. Lesson boundary

This lesson owns Provenance-Linked Performance Result Packet v1. It does not redesign the prior lesson's event taxonomy or metric regime, and it does not absorb the next lesson's Capacity Advisor. It proves neither causality nor production authorization; it only establishes whether a result is reproducible and comparable.

3. What a Performance Lens means

A lens states the exact performance question: conversion, acquisition efficiency, search visibility, or another bounded view. A similarly named metric under a different lens is not automatically a valid comparator. performance_lens is recorded before seeing the result so interpretation does not shift after the number is known.

4. Separate Metric Regime from the label

A label such as “Users” is insufficient. metric_regime_id binds definition, semantic version, and aggregation rules. If the regime changes between results, direct comparison requires an explicit auditable bridge; otherwise the state is NOT_COMPARABLE.

5. Query identity must be complete

query_spec is more than a report name. Date window, dimensions, metrics, filters, and segment are part of computation identity. If the prior filter set is missing, equivalence cannot be proven. A guess does not replace evidence; the result remains UNVERIFIED.

6. Reporting identity is not decorative metadata

Google Analytics documents that reporting identity can change user deduplication and counts for the same date range. Blended, Observed, Device-based, or an equivalent identity therefore belongs in the packet. A changed identity with an unchanged chart label invalidates direct comparison unless a valid bridge exists.

7. Source snapshot and freshness

A result binds to source_snapshot and extraction time. Very recent data may still be processed and aggregated. Re-querying data while reusing an old snapshot timestamp creates false lineage. Such evidence becomes STALE_EVIDENCE or UNVERIFIED, not “close enough.”

8. Transformation lineage

Every transform between source and result must be traceable: normalization, join, exclusion, derived metric, or aggregation. derived_from names input entities and transformation_steps names activities. Keeping only the final value destroys reproducibility.

9. Entity, Activity, and Agent in provenance

We borrow W3C PROV concepts: a snapshot or dataset is an Entity; a query or transform is an Activity; and the responsible system, analyst, or pipeline is an Agent. This vocabulary does not define MAKNOW policy, but it makes derivation and attribution explicit.

10. Do not erase uncertainty

A result without uncertainty looks more certain than the evidence permits. Sampling, thresholding, processing lag, or provenance gaps can matter. Unknown uncertainty is never coerced to zero. If it is decision-relevant and unresolved, the packet remains INSUFFICIENT_DATA or DEFERRED.

11. Comparability gate

VERIFIED requires equivalent lens, regime, query identity, reporting identity, snapshot/freshness, and derivation. A known difference may become BRIDGED only with explicit mapping and evidence. Semantic or filter mismatch without a bridge is NOT_COMPARABLE; incomplete evidence is UNVERIFIED.

12. Decision cannot exceed comparability

VERIFIED means the results are comparable under this contract. It does not prove causality or authorize an action. This lesson emits bounded decisions such as SUPPORT_BOUNDED_PLANNING, SUPPORT_WITH_BRIDGE, DO_NOT_COMPARE, or a rebuild/refresh path. Execution authority remains outside scope.

13. Worked example: the claimed 14% gain

The current result is 114 and the prior result is 100, but the prior query specification is incomplete and the current result adds a country filter. The apparent +14% does not pass the comparability gate. Query identity is unequal and the prior result cannot be reproduced, so the packet emits UNVERIFIED and DO_NOT_COMPARE until the old query is rebuilt.

14. Negative cases

Four shortcuts must fail: change reporting identity while keeping the chart label; remove the prior filter set; re-query recent data while reusing an old snapshot timestamp; and keep the value while deleting derivation lineage. None may be upgraded to VERIFIED by best guess.

15. Transfer: search performance

The transfer uses the same search-performance source but a different extraction time and page filter. Provenance is rebuilt from scratch. Because filter scope changed, the apparent improvement remains NOT_COMPARABLE until the comparator is rebuilt under the same scope. The planning decision is DO_NOT_COMPARE, not a copied baseline conclusion.