Measure and optimize format detection performance

[Sam-Bolling]

Problem

The format detection system (formats.ts - 162 lines with comprehensive header and body inspection) has no performance benchmarking despite being called on every parse operation. This means:

• No detection overhead data: Unknown cost of detectFormat() vs direct parser calls
• No strategy comparison: Unknown cost of header detection vs body inspection
• No confidence impact: Unknown performance difference between high/medium/low confidence paths
• No scaling data: Unknown cost when checking multiple formats in fallback scenarios
• No optimization data: Cannot make informed decisions about detection strategies

Real-World Impact:

• Parse overhead: Format detection happens before every parse - cumulative cost unknown
• Batch processing: Detecting formats for 1,000+ responses - acceptable latency unknown
• Embedded devices: CPU overhead must stay within limits
• Server-side: Detection throughput affects scalability
• Optimization potential: Cannot optimize without baseline measurements

Context

This issue was identified during the comprehensive validation conducted January 27-28, 2026.

Related Validation Issues: #10 (Multi-Format Parsers)

Work Item ID: 36 from Remaining Work Items

Repository: https://github.com/OS4CSAPI/ogc-client-CSAPI

Validated Commit: a71706b9592cad7a5ad06e6cf8ddc41fa5387732

Detailed Findings

1. No Performance Benchmarks Exist

Evidence from Issue #10 validation report:

Format Detection: formats.ts (162 lines, SHA: 5676c6d57fb704fcc19ef2ba6fb6877b126bc4cf)

Features:

• Automatic identification from Content-Type headers
• Supported formats: application/geo+json, application/sml+json, application/swe+json
• Fallback detection from response body structure
• Format precedence: GeoJSON → SensorML → SWE → JSON

Current Situation:

• ✅ Format detection works correctly (all claims confirmed)
• ✅ Handles both header and body inspection
• ✅ Confidence levels implemented (high/medium/low)
• ❌ ZERO performance measurements (no ops/sec, latency, overhead data)
• ❌ No detection strategy comparison (header vs body)
• ❌ No confidence level performance analysis

2. Format Detection Workflow (Performance-Critical Path)

From Issue #10, formats.ts analysis:

Main Detection Function:

export function detectFormat(
  contentType: string | null,
  body: unknown
): FormatDetectionResult {
  const headerResult = detectFormatFromContentType(contentType);

  // If we have high confidence from header, use it
  if (headerResult && headerResult.confidence === 'high') {
    return headerResult;
  }

  // Otherwise inspect the body
  const bodyResult = detectFormatFromBody(body);

  // If body gives us high confidence, use it
  if (bodyResult.confidence === 'high') {
    return bodyResult;
  }

  // Use header result if available, otherwise use body result
  return headerResult || bodyResult;
}

Performance Questions:

1. How expensive is header detection? Simple string parsing and comparison
2. How expensive is body inspection? Type checking and property access
3. Does high-confidence short-circuit save time? Early return vs full workflow
4. What's the cost of each format check? GeoJSON vs SensorML vs SWE detection

---

3. Header Detection Performance

From Issue #10:

export function detectFormatFromContentType(contentType: string | null): FormatDetectionResult | null {
  if (!contentType) {
    return null;
  }

  // Normalize: extract just the media type, ignore parameters
  const mediaType = contentType.split(';')[0].trim().toLowerCase();

  if (mediaType === CSAPI_MEDIA_TYPES.GEOJSON) {
    return { format: 'geojson', mediaType, confidence: 'high' };
  }

  if (mediaType === CSAPI_MEDIA_TYPES.SENSORML_JSON) {
    return { format: 'sensorml', mediaType, confidence: 'high' };
  }

  if (mediaType === CSAPI_MEDIA_TYPES.SWE_JSON) {
    return { format: 'swe', mediaType, confidence: 'high' };
  }

  if (mediaType === CSAPI_MEDIA_TYPES.JSON) {
    return { format: 'json', mediaType, confidence: 'low' };
  }

  return null;
}

Performance Characteristics:

• String operations: .split(), .trim(), .toLowerCase()
• 4 string equality comparisons (worst case)
• Object allocation for result
• Expected: Very fast (<0.01ms per detection)

Performance Questions:

• Cost of string normalization: Is .split().trim().toLowerCase() expensive?
• Cost of comparisons: Are 4 string comparisons significant?
• Memory allocation: Does result object creation cause GC pressure?

---

4. Body Inspection Performance

From Issue #10:

export function detectFormatFromBody(body: unknown): FormatDetectionResult {
  if (!body || typeof body !== 'object') {
    return { format: 'json', mediaType: 'application/json', confidence: 'low' };
  }

  const obj = body as Record<string, unknown>;

  // GeoJSON detection
  if (obj.type === 'Feature' || obj.type === 'FeatureCollection') {
    return { format: 'geojson', mediaType: CSAPI_MEDIA_TYPES.GEOJSON, confidence: 'high' };
  }

  // SensorML detection - look for type field with SensorML values
  if (typeof obj.type === 'string') {
    const type = obj.type;
    if (
      type === 'PhysicalSystem' ||
      type === 'PhysicalComponent' ||
      type === 'SimpleProcess' ||
      type === 'AggregateProcess' ||
      type === 'Deployment'
    ) {
      return { format: 'sensorml', mediaType: CSAPI_MEDIA_TYPES.SENSORML_JSON, confidence: 'high' };
    }
  }

  // SWE Common detection - look for type field with SWE values
  if (typeof obj.type === 'string') {
    const type = obj.type;
    if (
      type === 'Boolean' ||
      type === 'Text' ||
      type === 'Category' ||
      type === 'Count' ||
      type === 'Quantity' ||
      type === 'Time' ||
      type === 'DataRecord' ||
      type === 'Vector' ||
      type === 'DataChoice' ||
      type === 'DataArray' ||
      type === 'Matrix' ||
      type === 'DataStream'
    ) {
      return { format: 'swe', mediaType: CSAPI_MEDIA_TYPES.SWE_JSON, confidence: 'medium' };
    }
  }

  // Default to generic JSON
  return { format: 'json', mediaType: 'application/json', confidence: 'low' };
}

Performance Characteristics:

• Type checking: typeof body !== 'object', typeof obj.type === 'string'
• Property access: obj.type (potentially multiple times)
• 17 string equality comparisons (worst case: 2 GeoJSON + 5 SensorML + 12 SWE - 2 type checks)
• Object allocation for result
• Expected: Fast but slower than header detection (<0.1ms per detection)

Performance Questions:

• Cost of type checking: Are type guards expensive?
• Cost of property access: Is obj.type access expensive?
• Cost of 17 comparisons: Are all these string comparisons significant?
• Early exit benefit: How much faster is GeoJSON (2 checks) vs SWE (17 checks)?
• Type coercion overhead: Cost of body as Record<string, unknown>

---

5. Detection Strategy Performance

From Issue #10:

Format precedence: GeoJSON → SensorML → SWE → JSON

In detectFormat():

1. Try header detection (fast)
2. If header high confidence → return (short-circuit)
3. Otherwise try body inspection (slower)
4. If body high confidence → return
5. Prefer header result if available, otherwise body result

Three Detection Scenarios:

Scenario 1: High-Confidence Header (Best Case)

// Input: contentType = 'application/geo+json', body = { ... }
// Steps:
// 1. detectFormatFromContentType() → high confidence
// 2. Return immediately (body never inspected)
// Expected: Fastest path

Scenario 2: Low-Confidence Header + High-Confidence Body

// Input: contentType = 'application/json', body = { type: 'Feature', ... }
// Steps:
// 1. detectFormatFromContentType() → low confidence
// 2. detectFormatFromBody() → high confidence
// 3. Return body result
// Expected: Medium speed

Scenario 3: No Header + Body Inspection

// Input: contentType = null, body = { type: 'DataRecord', ... }
// Steps:
// 1. detectFormatFromContentType() → null
// 2. detectFormatFromBody() → SWE detection (12 comparisons)
// 3. Return body result
// Expected: Slowest path (most comparisons)

Performance Questions:

• Best case savings: How much faster is Scenario 1 vs Scenario 3?
• Typical case: What's the most common scenario in real usage?
• Worst case overhead: What if body is large and complex?

---

6. Unknown Optimization Opportunities

Potential Optimizations (Unverified):

1. Caching:

• Could cache detection results for identical content types?
• Could cache body structure for repeated parsing?
• Would caching overhead outweigh detection cost?

2. Early Exit Optimization:

• Could check most common formats first (GeoJSON likely most common)?
• Could stop after first match in body inspection?
• Would reordering checks improve average performance?

3. Comparison Optimization:

• Could use Set membership instead of multiple equality checks?
• Could use switch statement instead of if/else chains?
• Would these changes be faster?

4. Object Allocation Optimization:

• Could reuse result objects (object pooling)?
• Could use singleton patterns for common results?
• Would this reduce GC pressure?

Cannot optimize without benchmark data!

---

7. Integration Context

From Issue #10:

Parser Integration:
Every parser.parse() call invokes detectFormat():

parse(data: unknown, options: ParserOptions = {}): ParseResult<T> {
  const format = detectFormat(options.contentType || null, data);
  const errors: string[] = [];
  const warnings: string[] = [];
  
  try {
    // ... parse based on format ...
  } catch (error) {
    // ...
  }
}

Performance Impact:

• Called on every parse: Format detection overhead is per-parse, not per-batch
• No caching between parses: Each parse re-detects format even for same data structure
• Cannot skip: No option to provide pre-detected format directly

Usage Patterns:

• Single feature parsing: 1 detection per feature
• Collection parsing: 1 detection for collection + potentially N detections for features
• Batch processing: N detections for N responses
• Real-time streaming: Continuous detection overhead

Performance Questions:

• Cumulative overhead: At 1,000 parses, what's total detection time?
• Relative overhead: What % of total parse time is detection?
• Optimization value: Is detection overhead worth optimizing?

---

8. No Optimization History

No Baseline Data:

• Cannot track format detection performance regressions
• Cannot validate optimization attempts
• Cannot compare detection strategies
• Cannot document detection overhead for users
• Cannot decide when detection optimization is needed

---

9. Parser System Context

From Issue #10:

Total parser code: ~1,714 lines

• base.ts: 479 lines
• resources.ts: 494 lines
• swe-common-parser.ts: 540 lines
• formats.ts: 162 lines
• index.ts: 39 lines

Total tests: 166 tests (31 base + 79 resources + 56 swe-common)

Format Detection Usage:

• Used by all parsers: Every parser inherits parse() method that calls detectFormat()
• 9 parser classes: System, Deployment, Procedure, SamplingFeature, Property, Datastream, ControlStream, Observation, Command
• 3 formats supported: GeoJSON, SensorML, SWE Common (+ generic JSON)
• Format precedence order: Defined in detectFormat() logic

---

Proposed Solution

1. Establish Benchmark Infrastructure (DEPENDS ON #55)

PREREQUISITE: This work item REQUIRES the benchmark infrastructure from work item #32 (Issue #55) to be completed first.

Once benchmark infrastructure exists:

• Import Tinybench framework (from Add comprehensive performance benchmarking #55)
• Use benchmark utilities (stats, reporter, regression detection)
• Integrate with CI/CD pipeline
• Use shared benchmark fixtures

2. Create Comprehensive Format Detection Benchmarks

Create benchmarks/format-detection.bench.ts (~400-600 lines) with:

Header Detection Benchmarks:

• Detect GeoJSON from header (high confidence, early exit)
• Detect SensorML from header (high confidence, early exit)
• Detect SWE from header (high confidence, early exit)
• Detect generic JSON from header (low confidence, requires body inspection)
• Detect with missing header (null, requires body inspection)

Body Inspection Benchmarks:

• Detect GeoJSON Feature (2 comparisons - best case)
• Detect GeoJSON FeatureCollection (2 comparisons - best case)
• Detect SensorML PhysicalSystem (2 + 5 comparisons)
• Detect SensorML Deployment (2 + 5 comparisons)
• Detect SWE Quantity (2 + 17 comparisons - worst case)
• Detect SWE DataRecord (2 + 17 comparisons - worst case)
• Detect unknown format (all comparisons fail)

Combined Strategy Benchmarks:

• Scenario 1: High-confidence header (best case - no body inspection)
• Scenario 2: Low-confidence header + high-confidence body (medium case)
• Scenario 3: No header + body inspection (worst case)
• Scenario 4: Wrong content-type + body inspection (header overhead + body inspection)

Detection Precedence Benchmarks:

• GeoJSON detection (first in precedence)
• SensorML detection (second in precedence)
• SWE detection (third in precedence, most comparisons)
• Unknown format (all checks fail)

Scale Benchmarks:

• Single detection (baseline)
• 100 detections (typical batch)
• 1,000 detections (large batch)
• 10,000 detections (stress test)

3. Create Memory Usage Benchmarks

Create benchmarks/format-detection-memory.bench.ts (~150-200 lines) with:

Memory per Detection:

• Header detection memory (string operations + result object)
• Body inspection memory (type checking + result object)
• Combined detection memory (both strategies)

Memory Scaling:

• 100 detections: total memory, average per detection
• 1,000 detections: total memory, GC pressure
• 10,000 detections: total memory, heap usage

String Operations Memory:

• String normalization (split, trim, toLowerCase)
• String comparisons (equality checks)
• Media type constants (string literals)

4. Analyze Benchmark Results

Create benchmarks/format-detection-analysis.ts (~100-150 lines) with:

Performance Comparison:

• Header vs body inspection (speed difference)
• Best case vs worst case (early exit vs all checks)
• Format differences (GeoJSON vs SensorML vs SWE detection)

Identify Bottlenecks:

• Operations taking >20% of detection time
• Operations with >0.01ms latency per detection
• Operations with sublinear scaling
• Memory-intensive operations

Generate Recommendations:

• When to rely on headers (high confidence)
• When body inspection is necessary
• Optimal detection strategy
• Optimization opportunities (if any)

5. Implement Targeted Optimizations (If Needed)

ONLY if benchmarks identify issues:

Optimization Candidates (benchmark-driven):

• If string normalization slow: Cache normalized media types
• If comparisons slow: Use Set membership or Map lookup instead of if/else
• If object allocation expensive: Reuse singleton result objects
• If body inspection expensive: Check most common formats first

Optimization Guidelines:

• Only optimize proven bottlenecks (>10% overhead or <100,000 detections/sec)
• Measure before and after (verify improvement)
• Document tradeoffs (code complexity vs speed gain)
• Add regression tests (ensure optimization doesn't break functionality)

6. Document Performance Characteristics

Update README.md with new "Format Detection Performance" section (~100-150 lines):

Performance Overview:

• Typical detection overhead: X μs per detection
• Header detection: X μs (fast path)
• Body inspection: X μs (slower path)
• Throughput: X detections/sec

Detection Strategy Performance:

Best case (high-confidence header):    ~X μs  (header only)
Medium case (low-confidence header):   ~X μs  (header + body)
Worst case (no header + SWE):          ~X μs  (body with 17 comparisons)

Format Detection Overhead:

GeoJSON (2 checks):     ~X μs  (fastest body detection)
SensorML (7 checks):    ~X μs  (medium body detection)
SWE (17 checks):        ~X μs  (slowest body detection)
Unknown (all checks):   ~X μs  (all checks fail)

Best Practices:

• When possible: Provide accurate Content-Type headers to enable fast header detection
• High confidence: Header detection with correct media type is fastest
• Low confidence: Body inspection required for generic application/json content-type
• No header: Body inspection required, slightly slower but still fast
• Optimization: Format detection is typically <1% of total parse time

Performance Targets:

• Good: <10 μs per detection (<0.01ms)
• Acceptable: <100 μs per detection (<0.1ms)
• Poor: >1000 μs per detection (>1ms) - needs optimization

7. Integrate with CI/CD

Add to .github/workflows/benchmarks.yml (coordinate with #55):

Benchmark Execution:

- name: Run format detection benchmarks
  run: npm run bench:format-detection

- name: Run format detection memory benchmarks
  run: npm run bench:format-detection:memory

Performance Regression Detection:

• Compare against baseline (main branch)
• Alert if any benchmark >10% slower
• Alert if memory usage >20% higher

PR Comments:

• Post benchmark results to PRs
• Show comparison with base branch
• Highlight regressions and improvements

Acceptance Criteria

Benchmark Infrastructure (4 items)

• ✅ Benchmark infrastructure from Add comprehensive performance benchmarking #55 is complete and available
• Created benchmarks/format-detection.bench.ts with comprehensive detection benchmarks (~400-600 lines)
• Created benchmarks/format-detection-memory.bench.ts with memory usage benchmarks (~150-200 lines)
• Created benchmarks/format-detection-analysis.ts with results analysis (~100-150 lines)

Header Detection Benchmarks (5 items)

• Benchmarked GeoJSON header detection (high confidence)
• Benchmarked SensorML header detection (high confidence)
• Benchmarked SWE header detection (high confidence)
• Benchmarked generic JSON header detection (low confidence)
• Benchmarked missing header scenario (null input)

Body Inspection Benchmarks (7 items)

• Benchmarked GeoJSON Feature detection (2 comparisons)
• Benchmarked GeoJSON FeatureCollection detection (2 comparisons)
• Benchmarked SensorML detection (5 process types)
• Benchmarked SWE detection (12 component types)
• Benchmarked unknown format detection (all checks fail)
• Documented comparison count per format
• Identified fastest and slowest detection paths

Combined Strategy Benchmarks (4 items)

• Benchmarked Scenario 1: High-confidence header (best case)
• Benchmarked Scenario 2: Low-confidence header + body inspection (medium case)
• Benchmarked Scenario 3: No header + body inspection (worst case)
• Documented performance difference between scenarios

Detection Precedence Benchmarks (4 items)

• Benchmarked GeoJSON detection (first in precedence)
• Benchmarked SensorML detection (second in precedence)
• Benchmarked SWE detection (third in precedence, most checks)
• Verified precedence order affects performance

Scale Benchmarks (4 items)

• Benchmarked single detection (baseline)
• Benchmarked 100 detections (typical batch)
• Benchmarked 1,000 detections (large batch)
• Benchmarked 10,000 detections (stress test)

Memory Benchmarks (4 items)

• Measured memory per header detection
• Measured memory per body inspection
• Measured memory scaling (100, 1,000, 10,000 detections)
• Measured string operation memory overhead

Performance Analysis (5 items)

• Analyzed all benchmark results
• Identified bottlenecks (operations >20% of detection time or >0.01ms per detection)
• Generated performance comparison report (header vs body, best vs worst case)
• Created recommendations document (when to use each strategy)
• Documented current performance characteristics

Optimization (if needed) (4 items)

• Identified optimization opportunities from benchmark data
• Implemented targeted optimizations ONLY for proven bottlenecks
• Re-benchmarked after optimization (verified improvement)
• Added regression tests to prevent optimization from breaking functionality

Documentation (7 items)

• Added "Format Detection Performance" section to README.md (~100-150 lines)
• Documented typical detection overhead (μs per detection)
• Documented header vs body inspection performance
• Documented detection strategy performance (best/medium/worst case)
• Documented format-specific detection overhead (GeoJSON vs SensorML vs SWE)
• Documented best practices (when to use headers, when body inspection is needed)
• Documented performance targets (good/acceptable/poor thresholds)

CI/CD Integration (4 items)

• Added format detection benchmarks to .github/workflows/benchmarks.yml
• Configured performance regression detection (>10% slower = fail)
• Added PR comment with benchmark results and comparison
• Verified benchmarks run on every PR and main branch commit

Implementation Notes

Files to Create

Benchmark Files (~650-950 lines total):

1. benchmarks/format-detection.bench.ts (~400-600 lines)

   • Header detection benchmarks (5 scenarios)
   • Body inspection benchmarks (7 formats)
   • Combined strategy benchmarks (4 scenarios)
   • Detection precedence benchmarks (4 formats)
   • Scale benchmarks (4 sizes)

2. benchmarks/format-detection-memory.bench.ts (~150-200 lines)

   • Memory per detection (3 scenarios)
   • Memory scaling (3 sizes)
   • String operation memory

3. benchmarks/format-detection-analysis.ts (~100-150 lines)

   • Performance comparison logic
   • Bottleneck identification
   • Recommendation generation
   • Results formatting

Files to Modify

README.md (~100-150 lines added):

• New "Format Detection Performance" section with:
  • Performance overview
  • Detection strategy comparison table
  • Format-specific overhead table
  • Best practices
  • Performance targets

package.json (~10 lines):

{
  "scripts": {
    "bench:format-detection": "tsx benchmarks/format-detection.bench.ts",
    "bench:format-detection:memory": "tsx benchmarks/format-detection-memory.bench.ts",
    "bench:format-detection:analyze": "tsx benchmarks/format-detection-analysis.ts"
  }
}

.github/workflows/benchmarks.yml (coordinate with #55):

• Add format detection benchmark execution
• Add memory benchmark execution
• Add regression detection
• Add PR comment generation

Files to Reference

Format Detection Source File (for accurate benchmarking):

• src/ogc-api/csapi/parsers/formats.ts (162 lines)
  • CSAPI_MEDIA_TYPES constants
  • detectFormatFromContentType() function
  • detectFormatFromBody() function
  • detectFormat() function

Test Fixtures (reuse existing test data):

• src/ogc-api/csapi/parsers/base.spec.ts (has sample format detection tests)
• src/ogc-api/csapi/parsers/resources.spec.ts (has sample GeoJSON/SensorML/SWE data)

Technology Stack

Benchmarking Framework (from #55):

• Tinybench (statistical benchmarking)
• Node.js process.memoryUsage() for memory tracking
• Node.js performance.now() for timing

Benchmark Priorities:

• High: Header vs body comparison, detection strategy scenarios, format precedence
• Medium: Scale benchmarks, memory usage
• Low: Extreme scaling (>10,000), micro-optimizations

Performance Targets (Hypothetical - Measure to Confirm)

Detection Overhead:

• Good: <10 μs per detection (<0.01ms)
• Acceptable: <100 μs per detection (<0.1ms)
• Poor: >1000 μs per detection (>1ms)

Throughput:

• Good: >100,000 detections/sec (<10 μs per detection)
• Acceptable: >10,000 detections/sec (<100 μs per detection)
• Poor: <1,000 detections/sec (>1000 μs per detection)

Memory:

• Good: <100 bytes per detection
• Acceptable: <500 bytes per detection
• Poor: >1 KB per detection

Optimization Guidelines

ONLY optimize if benchmarks prove need:

• Detection overhead >1ms per detection
• Throughput <10,000 detections/sec
• Memory >1 KB per detection

Optimization Approach:

1. Identify bottleneck from benchmark data
2. Profile with Chrome DevTools or Node.js profiler
3. Implement targeted optimization
4. Re-benchmark to verify improvement (>20% faster)
5. Add regression tests
6. Document tradeoffs

Common Optimizations:

• Cache normalized media types (if string operations slow)
• Use Map/Set for format lookups (if many comparisons slow)
• Reuse singleton result objects (if allocation expensive)
• Reorder checks (if some formats more common)

Dependencies

CRITICAL DEPENDENCY:

• REQUIRES work item Update parser test count from 108 to 166 tests #32 (Issue Add comprehensive performance benchmarking #55) - Comprehensive performance benchmarking infrastructure
• Cannot start until benchmark framework, utilities, and CI/CD integration are complete

Why This Dependency Matters:

• Reuses Tinybench setup from Add comprehensive performance benchmarking #55
• Uses shared benchmark utilities (stats, reporter, regression detection)
• Integrates with established CI/CD pipeline
• Follows consistent benchmarking patterns

Testing Requirements

Benchmark Validation:

• All benchmarks must run without errors
• All benchmarks must complete in <30 seconds total
• All benchmarks must produce consistent results (variance <10%)
• Memory benchmarks must not cause out-of-memory errors

Regression Tests:

• Add tests to verify optimizations don't break functionality
• Rerun all format detection tests after any optimization
• Verify detection accuracy remains 100%

Caveats

Performance is Environment-Dependent:

• Benchmarks run on specific hardware (document specs)
• Results vary by Node.js version, CPU, memory
• Production performance may differ from benchmark environment
• Document benchmark environment in README

Optimization Tradeoffs:

• Faster code may be more complex
• Cached values increase memory usage
• Lookup tables add initialization overhead
• Document all tradeoffs in optimization PRs

Format Detection Context:

• Detection overhead typically <1% of total parse time
• Network latency typically dominates detection overhead
• Optimization may not be necessary unless benchmarks show >1ms detection time
• Focus on correctness over micro-optimizations

Priority Justification

Priority: Low

Why Low Priority:

1. No Known Performance Issues: No user complaints about slow format detection
2. Functional Excellence: Detection works correctly with comprehensive format support
3. Expected Overhead: Detection likely <1% of total parse time
4. Depends on Infrastructure: Cannot start until Add comprehensive performance benchmarking #55 (benchmark infrastructure) is complete
5. Educational Value: Primarily for documentation and optimization guidance

Why Still Important:

1. Baseline Establishment: Detect format detection performance regressions early
2. Optimization Guidance: Data-driven decisions about what (if anything) to optimize
3. Strategy Comparison: Understand header vs body inspection tradeoffs
4. Documentation: Help users understand detection overhead and best practices
5. Integration Context: Format detection happens on every parse - cumulative cost matters

Impact if Not Addressed:

• ⚠️ Unknown detection overhead (users can't estimate cost)
• ⚠️ No baseline for regression detection (can't track performance over time)
• ⚠️ No optimization guidance (can't prioritize improvements)
• ⚠️ Unknown strategy tradeoffs (can't recommend best practices)
• ✅ Detection still works correctly (functional quality not affected)
• ✅ No known performance bottlenecks (no urgency)

Effort Estimate: 6-10 hours (after #55 complete)

• Benchmark creation: 4-6 hours
• Memory analysis: 1-2 hours
• Results analysis: 1-2 hours
• Documentation: 1-2 hours
• CI/CD integration: 0.5-1 hour (reuse from Add comprehensive performance benchmarking #55)
• Optimization (optional, if needed): 2-4 hours

When to Prioritize Higher:

• If users report slow parsing (detection may contribute)
• If adding real-time detection features (need performance baseline)
• If optimizing for embedded/mobile (need overhead data)
• If detection overhead >1% of parse time (needs optimization)