Measure and optimize format detection performance

## 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](https://github.com/Sam-Bolling/CSAPI-Live-Testing/issues/10) (Multi-Format Parsers)

**Work Item ID:** 36 from [Remaining Work Items](https://github.com/Sam-Bolling/CSAPI-Live-Testing/blob/main/docs/remaining-work-items.md)

**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:**
```typescript
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:**
```typescript
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:**
```typescript
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)**
```typescript
// 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**
```typescript
// 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**
```typescript
// 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()`:
> ```typescript
> 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 #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:**
```yaml
- 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 #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):
```json
{
  "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 #32 (Issue #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 #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 #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 #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)

Measure and optimize format detection performance #59

Description

Problem

Context

Detailed Findings

1. No Performance Benchmarks Exist

2. Format Detection Workflow (Performance-Critical Path)

3. Header Detection Performance

4. Body Inspection Performance

5. Detection Strategy Performance

6. Unknown Optimization Opportunities

7. Integration Context

8. No Optimization History

9. Parser System Context

Proposed Solution

1. Establish Benchmark Infrastructure (DEPENDS ON #55)

2. Create Comprehensive Format Detection Benchmarks

3. Create Memory Usage Benchmarks

4. Analyze Benchmark Results

5. Implement Targeted Optimizations (If Needed)

6. Document Performance Characteristics

7. Integrate with CI/CD

Acceptance Criteria

Benchmark Infrastructure (4 items)

Header Detection Benchmarks (5 items)

Body Inspection Benchmarks (7 items)

Combined Strategy Benchmarks (4 items)

Detection Precedence Benchmarks (4 items)

Scale Benchmarks (4 items)

Memory Benchmarks (4 items)

Performance Analysis (5 items)

Optimization (if needed) (4 items)

Documentation (7 items)

CI/CD Integration (4 items)

Implementation Notes

Files to Create

Files to Modify

Files to Reference

Technology Stack

Performance Targets (Hypothetical - Measure to Confirm)

Optimization Guidelines

Dependencies

Testing Requirements

Caveats

Priority Justification

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions