validationMetadata property
Metadata for this detector. Must be non-null on shipping detectors — the audit test gates this.
This getter belongs to package:sleuth/validation.dart and is outside
Sleuth's semver promise, also on main-API detectors that override it.
Implementation
@override
DetectorMetadata get validationMetadata => const DetectorMetadata(
tier: EvidenceTier.reproducerOnly,
additionalBrackets: [
BracketSpec(
stableId: 'excessive_repaint',
severityLabel: 'critical',
threshold: 30,
unit: 'percent',
coveredThresholds: {'excessive_repaint.critical'},
profileCapturePaths: [
'test/validation/captures/repaint/excessive_repaint_critical_below.json',
'test/validation/captures/repaint/excessive_repaint_critical_at.json',
'test/validation/captures/repaint/excessive_repaint_critical_above.json',
],
atTolerance: 0.5,
aboveCeilingMultiplier: 2.7,
requireUniqueDetectedAtMicros: true,
requireDetectorTraceRecord: true,
observedAxisArgKey: 'observedPaintPercent',
observedAxisTolerance: 0.25,
observedAxisReduction: 'max',
// Two in-band windows per leg, so one window that drifted into the
// band between sub-band windows cannot certify the bracket.
minInBandSamples: 2,
),
],
rationale:
'Hybrid detector. The reproducer pins all three families. '
'`excessive_repaint` measures the share of UI-thread wall time '
'spent inside VM-timeline PAINT scopes over each window of about 1 '
's, normalised by the measured window length. It warns above '
'`paintTimePercentThreshold` (default 10 %) and is critical above 3 '
'times that (30 %). `excessive_repaint_debug` is the debug-callback '
'aggregate paint rate, with animation-owned paints excluded. The '
'parametric `repaint_debug_<typeName>` family compares per-instance '
'likely-origin repaints/sec against `paintFrequencyThreshold`. The '
'likely origin is the deepest node marked as needing paint in each '
'layer, credited to the nearest app-created widget. The family is '
'declared via `parametricFamilies`, so a concrete '
'`repaint_debug_CustomPaint` credits the family through the `_` '
'separator matcher. A cross-harness reproducer exercises the '
'boundary from the VM through TimelineParser to the detector (raw '
'`List<TimelineEvent>` through `parseAndAssertShape`, and a real '
'`pumpWidget` for the debug and structural legs). A broad '
'`expect(issues, isEmpty)` pins animation-owner Gate B suppression, '
'so a regression cannot leak through any of the three emission '
'paths. `excessive_repaint` warning and critical are runtimeVerified '
'via capture triads on iPhone 12, iOS 17.5 and Flutter 3.47.x. The '
'critical legs target 0.8, 1.23 and 2.0 times 30 % and need two '
'in-band windows each. The workload '
'varies paint cost per frame with 32 distinct CustomPainter types '
'that repaint through a shared per-frame notifier, so BUILD stays '
'flat and the per-widget debug gate stays below its threshold. A '
'calibration pre-pass scales the paint operations to the leg '
'target. `peakObservedPaintPercent` moves only when a window closes '
'on its own and populates `expectedMagnitude.observed`, so the '
'audit-gate `\'max\'` axis reduction matches the emitted '
'`observedPaintPercent`. atTolerance 0.5 and observedAxisTolerance '
'0.25 absorb thermal drift in paint duration across a leg. '
'`excessive_repaint_debug` and `repaint_debug_<typeName>` remain '
'reproducerOnly, because there are no per-widget debug-path '
'captures. While a screen reader is on, the debug paint counts '
'leave out the framework\'s semantics-only widgets (`Semantics`, '
'`MergeSemantics`, `_GestureSemantics`, ...), which repaint as '
'pass-throughs. The VM PAINT axis is unchanged.',
reproducerPath: 'test/validation/repaint_reproducer_test.dart',
coveredStableIds: {'excessive_repaint', 'excessive_repaint_debug'},
parametricFamilies: {'repaint_debug'},
perStableIdTier: {'excessive_repaint': EvidenceTier.runtimeVerified},
coveredThresholds: {
'excessive_repaint.warning',
'excessive_repaint.critical',
},
profileCapturePaths: [
'test/validation/captures/repaint/excessive_repaint_below.json',
'test/validation/captures/repaint/excessive_repaint_at.json',
'test/validation/captures/repaint/excessive_repaint_above.json',
],
bracketThreshold: 10,
bracketUnit: 'percent',
bracketStableId: 'excessive_repaint',
bracketSeverityLabel: 'warning',
bracketAtTolerance: 0.5,
aboveCeilingMultiplier: 2.7,
observedAxisArgKey: 'observedPaintPercent',
observedAxisTolerance: 0.25,
observedAxisReduction: 'max',
);