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:
- UTF-8 decodes raw bytes (rejects non-UTF-8).
- Strips a UTF-8 BOM if present.
- Normalises CRLF line endings to LF.
- JSON-decodes.
- Validates required top-level + metadata keys.
- Enforces pinned-device / pinned-OS / pinned-Flutter policy.
- Asserts
expectedMagnitude.{min, observed, max}are numeric and satisfymin <= observed <= max. - Parses
captureDateas 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 passfile.path. -
parse(
List< int> rawBytes) → Map<String, Object?> -
Decodes raw capture bytes, normalises encoding, and validates the
schema. Returns the parsed
sleuthMetadataobject for convenient downstream access; the full JSON root is recoverable viajson['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.additionalBracketscalls this once per spec; the publicvalidateBracket(...)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_unitToMicrosecondsand 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
thresholdinunit. - defaultAtTolerance → const double
-
Default bracket tolerance for the
_atcapture — 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.observedwith 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
runtimeVerifiedcapture 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
sleuthMetadatawrapper. -
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
tsis 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
tsis 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.