cvmmap-streamer/docs/compat_matrix.md

# Compatibility Matrix

This document defines the complete protocol, codec, and RTMP mode compatibility matrix for cv-mmap streamer. It explicitly separates mandatory (blocking) checks from optional (non-blocking) checks.

## Mandatory Checks (Blocking for Release)

These checks must ALL pass for a release to be considered valid. They require no external servers and run entirely in standalone mode.

### Protocol/Codec Matrix

| Row | Protocol | Codec | RTMP Mode | Test Command | Evidence |
|-----|----------|-------|-----------|--------------|----------|
| 1 | RTP | H.264 | N/A | `./scripts/acceptance_standalone.sh` (row 1) | task-14-acceptance.txt |
| 2 | RTP | H.265 | N/A | `./scripts/acceptance_standalone.sh` (row 2) | task-14-acceptance.txt |
| 3 | RTMP | H.264 | enhanced | `./scripts/acceptance_standalone.sh` (row 3) | task-14-acceptance.txt |
| 4 | RTMP | H.265 | enhanced | `./scripts/acceptance_standalone.sh` (row 4) | task-14-acceptance.txt |
| 5 | RTMP | H.265 | domestic | `./scripts/acceptance_standalone.sh` (row 5) | task-14-acceptance.txt |

**Pass Criteria:**
- Exit code 0 from `acceptance_standalone.sh`
- JSON summary shows `total=5 pass=5 fail=0 skip=0`
- All tester processes receive expected packet/frame counts

### Fault Scenarios

| Scenario | Description | Test Command | Evidence |
|----------|-------------|--------------|----------|
| Torn Read | Coherent snapshot rejects torn frames | `./scripts/fault_suite.sh` | task-15-fault-suite.txt |
| Sink Stall | Backpressure containment under slow consumer | `./scripts/fault_suite.sh` | task-15-fault-suite.txt |
| Reset Storm | Stream reset recovery | `./scripts/fault_suite.sh` | task-15-fault-suite.txt |

**Pass Criteria:**
- Exit code 0 from `fault_suite.sh`
- All fault scenarios PASS status
- No violations of latency/drop thresholds

## Invalid Combinations (Explicitly Rejected)

These combinations are rejected at startup with clear error messages and non-zero exit codes.

| Combination | Error | Exit Code |
|-------------|-------|-----------|
| RTMP + H.264 + domestic mode | H.264 does not support domestic mode | 1 |
| RTP without --rtp-endpoint | Missing required RTP endpoint | 1 |
| RTMP without --rtmp-url | Missing required RTMP URL | 1 |
| --rtmp-mode without H.265 codec | Domestic mode requires H.265 | 1 |

## Optional Checks (Non-Blocking)

These checks are provided for interoperability validation but are NOT required for release acceptance. If the environment is unavailable, these should be skipped.

### Server Smoke Tests

| Server | Protocols | H.265 Support | Status |
|--------|-----------|---------------|--------|
| SRS 6.0+ | RTMP, HTTP-FLV, HLS, WebRTC | Enhanced-RTMP | Optional |
| ZLMediaKit | RTMP, HTTP-FLV, HTTP-TS, RTSP, WebRTC | Enhanced + Domestic | Optional |

**Skip Conditions:**
- Docker not available
- Port 1935 in use by another service
- Server container fails to start
- Network isolation prevents connection

**Expected Behavior When Skipped:**
- Script exits with status 0 (SKIP)
- Evidence file notes the skip reason
- Mandatory acceptance still proceeds

## RTMP H.265 Dual Mode Details

### Enhanced-RTMP Mode (Recommended)

**Specification:** [Enhanced RTMP](https://github.com/veovera/enhanced-rtmp)

**Characteristics:**
- Video codec header byte: `0x90` (sequence) / `0x91` (frame)
- FourCC: `hvc1` or `hev1`
- Standardized, widely supported
- FFmpeg 6.0+ native support
- OBS 29+ support
- SRS 6.0+ native support
- ZLMediaKit default mode

**When to use:**
- Greenfield deployments
- Modern CDN ingestion
- Cross-platform compatibility requirements

### Domestic Extension Mode (Legacy Compatibility)

**Specification:** Proprietary FLV extension using codec-id 12

**Characteristics:**
- Video codec header byte: `0x1c` (keyframe) / `0x2c` (inter)
- FLV codec-id: 12 (non-standard)
- Legacy Chinese CDN compatibility
- Requires explicit config in ZLMediaKit (`enhanced=0`)
- Not supported by all players

**When to use:**
- Legacy CDN requirements
- Existing domestic-mode infrastructure
- Backward compatibility with older systems

### Mode Selection Decision Tree

```
Is codec H.265?
├── No (H.264) ──> Use enhanced mode only (domestic invalid)
└── Yes (H.265)
    ├── Target is modern CDN/player? ──> enhanced
    ├── Target requires domestic mode? ──> domestic
    └── Unknown? ──> enhanced (safer default)
```

## Validation Commands

### Verify Mandatory Matrix

```bash
cd downstream/cvmmap-streamer
./scripts/acceptance_standalone.sh
echo "Exit code: $?"
```

### Verify Individual Row (RTP H.264)

```bash
# Terminal 1: Tester
./build/rtp_receiver_tester \
    --port 51040 \
    --expect-pt 96 \
    --packet-threshold 1 \
    --timeout-ms 10000

# Terminal 2: Simulator + Streamer
./build/cvmmap_sim \
    --shm-name test_rtp_h264 \
    --zmq-endpoint "ipc:///tmp/test_rtp_h264.ipc" \
    --label rtp_h264 \
    --frames 320 \
    --fps 200 \
    --width 640 \
    --height 360 &

./build/cvmmap_streamer \
    --run-mode pipeline \
    --codec h264 \
    --shm-name test_rtp_h264 \
    --zmq-endpoint "ipc:///tmp/test_rtp_h264.ipc" \
    --queue-size 1 \
    --gop 30 \
    --b-frames 0 \
    --ingest-max-frames 120 \
    --rtp \
    --rtp-endpoint "127.0.0.1:51040" \
    --rtp-payload-type 96 \
    --rtp-sdp /tmp/test_rtp_h264.sdp
```

### Verify Invalid Combination Rejection

```bash
# Should fail with clear error
./build/cvmmap_streamer \
    --codec h264 \
    --rtmp-mode domestic \
    --shm-name test \
    --zmq-endpoint "ipc:///tmp/test.ipc"

echo "Exit code: $?"  # Expected: 2 (invalid mode matrix)
```

## Evidence Locations

All test evidence is written to `.sisyphus/evidence/`:

| Evidence File | Description |
|---------------|-------------|
| task-14-acceptance.txt | Latest acceptance run pointer |
| task-14-acceptance-summary.json | Acceptance summary JSON |
| task-14-acceptance/RUN_ID/ | Per-run logs for each matrix row |
| task-15-fault-suite.txt | Latest fault suite run pointer |
| task-15-fault-suite-summary.json | Fault suite summary JSON |
| task-15-fault-suite/RUN_ID/ | Per-run logs for each scenario |