parse static method

Map<String, Object?> parse(
  1. List<int> rawBytes
)

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.

Throws FormatException with a precise message on any violation.

The inverse-ratio half of the trace-vs-observed cross-check is skipped when the capture's sleuthMetadata.role is 'below'. Below-leg semantics intentionally pair a tiny expectedMagnitude.observed (sub-threshold workload, e.g. 0.5 ms) with a normal-sized scenario span (~250 ms including flushTimelineNow + dwell), producing inverse-ratios well above the 100× ceiling that would otherwise rightly catch fabricated at/above captures. Sub-threshold roles have no markers-bracket-the-work invariant; the _requireNoIssueTraceRecord check protects below-leg honesty.

Implementation

static Map<String, Object?> parse(List<int> rawBytes) {
  final decoded = _decodeUtf8(rawBytes);
  final normalised = _stripBomAndNormaliseLineEndings(decoded);

  // Duplicate JSON keys are rejected before jsonDecode collapses them.
  // RFC 8259 §4 permits duplicates; Dart's `jsonDecode` silently takes
  // the last write. Without this check an attacker (or a well-meaning
  // contributor with an editor glitch) can craft a fixture that shows
  // one value to a person reading the file and certifies a different
  // value to the schema validator.
  _detectDuplicateKeys(normalised);

  final Object? root;
  try {
    root = jsonDecode(normalised);
  } on FormatException catch (e) {
    throw FormatException('Capture is not valid JSON: ${e.message}');
  }
  if (root is! Map<String, Object?>) {
    throw const FormatException(
      'Capture root must be a JSON object, not an array or primitive.',
    );
  }

  for (final key in requiredTopLevel) {
    if (!root.containsKey(key)) {
      throw FormatException(
        'Missing required top-level key: "$key". '
        'Expected: ${requiredTopLevel.toList()..sort()}.',
      );
    }
  }
  _validateTraceEvents(root['traceEvents']);

  final sleuthMetadata = root['sleuthMetadata'];
  if (sleuthMetadata is! Map<String, Object?>) {
    throw const FormatException('"sleuthMetadata" must be a JSON object.');
  }
  for (final key in requiredMetadata) {
    if (!sleuthMetadata.containsKey(key)) {
      throw FormatException(
        'Missing required sleuthMetadata key: "$key". '
        'Expected: ${requiredMetadata.toList()..sort()}.',
      );
    }
  }

  _validateDevicePolicy(sleuthMetadata);
  _validateFlutterVersion(sleuthMetadata);
  _validateCaptureCommandAndScenario(sleuthMetadata);
  _validateExpectedMagnitude(sleuthMetadata);
  _validateCaptureDate(sleuthMetadata);
  final role = sleuthMetadata['role'];
  if (role is! String || !allowedRoles.contains(role)) {
    throw FormatException(
      'Invalid `sleuthMetadata.role`: ${role == null ? 'null' : '"$role"'}. '
      'Must be exactly one of ${allowedRoles.toList()..sort()} '
      '(case-sensitive). This field drives the below-leg inverse-ratio '
      'bypass. A typo falls back to enforcement and shows up as a '
      'false-positive failure.',
    );
  }
  // Below-leg semantics: sub-threshold workload paired with normal-
  // sized scenario span (workload + flushTimelineNow + dwell). The
  // inverse-ratio half false-positives on this shape — its 100×
  // ceiling is meant to catch fabricated at/above captures
  // (markers bracketing unrelated work). _requireNoIssueTraceRecord
  // is the actual contract for below-role honesty.
  final isBelowRole = role == 'below';
  _crossCheckTraceVsObserved(
    root['traceEvents'] as List,
    sleuthMetadata,
    skipInverseRatio: isBelowRole,
  );

  return sleuthMetadata;
}