ProfileCaptureSchema class

Schema + validator for Sleuth profile-mode captures.

A Sleuth capture is a DevTools Chrome Trace Event Format export with a hand-annotated sleuthMetadata wrapper. DevTools does not auto-emit device, OS, or Flutter-version information, so the wrapper is a deliberate deviation from vanilla exports: it pins the capture to a known reference device and scenario so the audit gate can verify the evidence is provably from a pinned environment.

parse is the single entry point. It:

  1. UTF-8 decodes raw bytes (rejects non-UTF-8).
  2. Strips a UTF-8 BOM if present.
  3. Normalises CRLF line endings to LF.
  4. JSON-decodes.
  5. Validates required top-level + metadata keys.
  6. Enforces pinned-device / pinned-OS / pinned-Flutter policy.
  7. Asserts expectedMagnitude.{min, observed, max} are numeric and satisfy min <= observed <= max.
  8. Parses captureDate as ISO-8601.

validateBracket runs the triad rule on three captures bracketing a threshold: below < threshold, at within a ±10% band, above > threshold.

Both entry points throw FormatException with a precise message on any violation so the audit gate can surface actionable failures.

Annotations
  • @experimental

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

findScenarioSpan(List events, String contextLabel) → (int, int)
Public wrapper around the scenario-span finder so audit invariants can reuse the schema's exactly-one-pair strictness instead of replicating loose name-only matching that drifts. Takes a free-form contextLabel (path or capture identifier) for the error message; the schema's own callers pass file.path.
parse(List<int> rawBytes) → Map<String, Object?>
Decodes raw capture bytes, normalises encoding, and validates the schema. Returns the parsed sleuthMetadata object for convenient downstream access; the full JSON root is recoverable via json['sleuthMetadata']'s container.
parseFile(File file) → Map<String, Object?>
Convenience wrapper that reads a file and calls parse. Adds a scenario-name ↔ file-path cross-check the byte-only parse cannot run (it has no path context). Captures placed in _fixtures/ subdirectories are skipped — those are negative-test fixtures with deliberately unrelated scenarios.
validateBracket({required File belowFile, required File atFile, required File aboveFile, required num threshold, required String unit, double atTolerance = defaultAtTolerance, double aboveCeilingMultiplier = defaultAboveCeilingMultiplier, bool requireDetectorTraceRecord = false, String? stableId, String? severityLabel, bool requireUniqueDetectedAtMicros = false, String? observedAxisArgKey, double observedAxisTolerance = 0.25, String observedAxisReduction = 'max'}) → void
validateBracketSpec(BracketSpec spec, {required File belowFile, required File atFile, required File aboveFile}) → void
Spec-driven bracket validation entry point. Audit-side iteration over DetectorMetadata.additionalBrackets calls this once per spec; the public validateBracket(...) is preserved for existing test/audit call sites that pass named args.

Constants

allowedRoles → const Set<String>
Allowed values for sleuthMetadata.role — exact, case-sensitive allowlist. Replaces the v0.18.2 filename-suffix heuristic for below-leg detection. Strict union enforcement: typos like 'Below', 'BELOW', 'sub' fail fast at parse time so audit-side role-driven logic can rely on the value being exactly one of these three strings.
allowedTracePhases → const Set<String>
Chrome Trace Event Format phase codes accepted in a capture. The superset includes sync (B/E/X), async (b/e/n/i/I), metadata (M), counter (C), and flow (s/f/t) phases. Unknown phases fail the schema so a fabricated export cannot sneak through with ph: 'z' entries.
approvedDevicePairs → const Map<String, Set<String>>
Pinned device → approved OS versions map. Reference-device policy is documented in doc/reference_devices.md. The matrix rotates once per calendar year in a dedicated release — not silently.
approvedFlutterMajorMinor → const String
Baseline Flutter major.minor pin. Always a member of approvedFlutterMajorMinors; triads recorded before the set gained further members carry this version.
approvedFlutterMajorMinors → const Set<String>
Flutter stable major.minor versions a capture may be recorded under. Rotated together with the device matrix. The three legs of a bracket must still share one exact flutterVersion.
approvedUnits → const Set<String>
Allowed values for expectedMagnitude.unit. Time units are recognised by _unitToMicroseconds and participate in the trace-vs-observed cross-check; non-time units pass the shape/positivity/invariant checks and skip the cross-check (a trace cannot certify bytes or frame counts). New units are a schema change — bump when adding.
defaultAboveCeilingMultiplier → const double
Validates a three-capture bracket against threshold in unit.
defaultAtTolerance → const double
Default bracket tolerance for the _at capture — observed may lie anywhere in [threshold, threshold * (1 + defaultAtTolerance)].
maxObservedToSpanRatio → const double
Trace-vs-observed cross-check: a capture that pairs a hand-authored expectedMagnitude.observed with a trace whose scenario-marker span is orders of magnitude smaller than the claim almost certainly describes a fabricated export. For time-unit magnitudes (ms, us, s, ns) we bind the span to the two scenario-marker instant events (see scenarioBeginMarker / scenarioEndMarker), convert the claimed observed into the same unit (microseconds), and reject if the claim exceeds the span by more than maxObservedToSpanRatio. For non-time units (bytes, frames, requests, …) no cross-check is attempted — the trace cannot meaningfully certify those.
minTraceEvents → const int
Minimum number of trace events a runtimeVerified capture must contain. Flutter profile-mode runs emit thousands of events per second; an export with a handful of entries is either truncated, captured outside profile mode, or synthetic. Set conservatively low so that very short scenarios still pass but an empty wrapper fails. The anchor fixture contains ~20 hand-rolled events; real captures run into the thousands.
minWorkPhaseEvents → const int
Minimum count of work-phase events a capture must contain. Anchor and dormant-bracket fixtures have 5–8 work events; real profile-mode runs emit thousands. Set conservatively so short scenarios still pass while wrappers composed of metadata/instant events fail.
requiredMetadata → const Set<String>
Keys that must appear inside the sleuthMetadata wrapper.
requiredTopLevel → const Set<String>
Keys that must appear at the top level of a capture export.
scenarioBeginMarker → const String
Canonical name for the "begin" scenario-marker instant event. Exactly one must appear in a time-unit capture. Its ts is the start of the scoped work window used for the trace-vs-observed cross-check.
scenarioEndMarker → const String
Canonical name for the "end" scenario-marker instant event. Exactly one must appear in a time-unit capture. Its ts is the end of the scoped work window used for the trace-vs-observed cross-check.
workTracePhases → const Set<String>
Phase codes that represent actual captured work — durations the detector under test can observe. Metadata (M), instant (i/I), counter (C), and flow (s/f/t) phases do NOT count: a capture composed entirely of those phases has no runtime evidence, only annotations.