validationMetadata property

  1. @override
DetectorMetadata get validationMetadata
override

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',
);