# Docs: replay_protocol.md + architecture.md + orchestrator-test README (AZ-835 C6)

**Task**: AZ-842_replay_protocol_and_orchestrator_docs
**Name**: Docs: replay_protocol.md Invariant 12 + AZ-777 Phase 3+ superseded note + orchestrator-test README (AZ-835 C6)
**Description**: Sixth and final building block of Epic AZ-835. Capture the route-driven flow in the authoritative documents so future implementers, operators, and reviewers understand what changed and why.
**Complexity**: 3 SP (cycle-4 rescope: was 2 SP)
**Dependencies**: AZ-894 (CSV adapter — HARD; replay_protocol.md sub-section describes the new single-canonical-clock flow); AZ-895 (auto-sync deprecation — HARD; replay_protocol.md sub-section describes the tlog adapter's new audit-only role); AZ-896 (CSV format docs — SOFT; replay_protocol.md cross-links to the format spec); AZ-777 (closed/superseded by this Epic); AZ-835 (parent Epic)
**Component**: `_docs/02_document/contracts/replay/replay_protocol.md` + `_docs/02_document/architecture.md` + `tests/e2e/replay/README*.md`
**Tracker**: AZ-842 (https://denyspopov.atlassian.net/browse/AZ-842)
**Parent Epic**: AZ-835

Jira AZ-842 is the authoritative spec; this file is the in-workspace mirror.

> **Cycle-4 rescope (2026-05-26)**: dropped the AZ-841 (un-xfail) soft
> dependency — AZ-841 was deferred to backlog in cycle-4 Step 9 scope
> review (see `_docs/02_tasks/backlog/AZ-841_unxfail_az777_tier2_tests.md`).
> Expanded scope from "AZ-835 epic docs only" to also cover the cycle-4
> replay-input redesign narrative: AZ-894 (CSV-driven single-canonical-clock
> adapter), AZ-895 (tlog adapter → audit-only after auto-sync deprecation),
> AZ-896 (CSV format spec). The replay_protocol.md edits now describe BOTH
> the route-driven AZ-835 flow AND the cycle-4 CSV-driven replay path,
> which together supersede the legacy tlog+auto-sync surface.
> Complexity bumped 2 → 3 SP to cover the added cycle-4 narrative.

## Modified files

### 1. `_docs/02_document/contracts/replay/replay_protocol.md` — Invariant 12 extension + Invariant 13 (NEW, cycle-4)

**1a. Invariant 12 — route-driven flow (AZ-835)**

Extend **Invariant 12** with an AZ-835 sub-section describing:

- The route-driven `operator_pre_flight_setup` fixture (AZ-839 / C3) flow: tlog → `RouteSpec` → `POST /api/satellite/route` → tile download → FAISS build → yield `PopulatedC6Cache`.
- Why route-driven supersedes the AZ-777 bbox approach (efficiency: ~100× fewer tiles; honesty: pre-commits to where the operator did fly).
- The C3 fixture's failure-handling contract (validation/terminal → re-raise; transient → retry up to 3 attempts using C11's existing backoff schedule).

**1b. Invariant 13 — single canonical clock (cycle-4, AZ-894 / AZ-895 / AZ-896)**

Add a new **Invariant 13** sub-section describing:

- The single-clock model production uses (single edge device, single clock at receipt) and why two-clock surfaces (e.g. `VioOutput.emitted_at_ns` from Jetson monotonic vs. `ImuWindow.ts_end_ns` from FC-boot) produce ESKF out-of-order regressions like AZ-848.
- The CSV-driven replay path (AZ-894) — `(video, CSV)` operator input, IMU + GPS-ground-truth on a single canonical clock derived from the CSV's `Time` column, no auto-sync.
- The CSV schema (delegate to `_docs/02_document/contracts/replay/csv_replay_format.md` produced by AZ-896 for the field-level spec).
- The tlog-replay adapter's new audit-only role (AZ-895): retained for FDR analysis and one-shot tlog→CSV export, removed from the test/demo critical path.
- Auto-sync deprecation (AZ-895): `--time-offset-ms` / `--skip-auto-sync-validation` CLI flags removed or marked deprecated with one-cycle warning.

### 2. `_docs/02_document/architecture.md` — satellite-provider entry extension

Append a sub-section to the existing satellite-provider entry noting that Epic AZ-835 + its C1-C5 children landed the full e2e real-flight validation path on top of AZ-777 Phase 1's wire + C11 contract adaptation. Mark AZ-777 Phase 3+ as superseded by Epic AZ-835 (pointer-only — the AZ-777 spec itself is updated in C5's wake during the AZ-777 closure step).

### 3. `tests/e2e/replay/README*.md` — orchestrator-test README

Either extend `tests/e2e/replay/README.md` or create a dedicated `tests/e2e/replay/README_AZ835.md` (prefer dedicated file if the existing README is already long). Short operator-facing content:

- How to run the new orchestrator test locally (env vars, Jetson SSH alias, expected runtime).
- What `(tlog, video, calibration)` triple to provide and where the reference Derkachi fixture lives.
- Where the verdict report is written and how to interpret it (PASS/FAIL on AZ-696 AC-3 threshold).
- Imagery-source caveat: Google Maps satellite (dev/research use only; production needs CC-BY migration on the satellite-provider side).

## Acceptance criteria

| # | Criterion |
|---|-----------|
| AC-1 | `replay_protocol.md` Invariant 12 has a new AZ-835 sub-section covering the route-driven flow, the bbox-supersedure rationale, and the failure-handling contract. |
| AC-1b | `replay_protocol.md` has a new Invariant 13 (cycle-4) sub-section covering the single-canonical-clock model, the CSV-driven replay path (AZ-894), the tlog adapter's audit-only role (AZ-895), and auto-sync deprecation. Links to `csv_replay_format.md` (AZ-896). |
| AC-2 | `architecture.md` satellite-provider entry has a sub-section noting Epic AZ-835's contribution and pointing at AZ-777 Phase 3+ as superseded. |
| AC-2b | `architecture.md` replay-input section explains the cycle-4 redesign: CSV adapter primary path, tlog adapter audit-only role, removal of auto-sync. References AZ-894 / AZ-895 / AZ-896 / AZ-897. |
| AC-3 | `tests/e2e/replay/README*.md` exists and a new contributor can run the orchestrator test on Jetson using only the README's instructions (no out-of-band knowledge required). |
| AC-4 | All three docs link to the Epic (AZ-835), its children (AZ-836 / AZ-838 / AZ-839 / AZ-840), and the cycle-4 redesign tickets (AZ-894 / AZ-895 / AZ-896 / AZ-897). AZ-841 reference omitted (deferred to backlog). |
| AC-5 | License attribution string ("Imagery © Google") and the dev-only caveat are present in the test README. |
| AC-6 | Cross-references in `_docs/02_tasks/_dependencies_table.md` and `_docs/02_tasks/done/AZ-777*.md` (once moved) point at this Epic / its children and at the cycle-4 redesign tickets. |

## Out of scope

- Updating consumer-facing API/contract docs in `../satellite-provider/` (parent-suite owns those).
- Migrating imagery source to a CC-BY provider (parent-suite, out of scope for this Epic).
- Writing additional tutorials beyond the orchestrator-test README.
- ADR creation — no new architectural decision; this Epic implements existing decisions.

## Risks

**Risk 1 — Scope creep into reformatting unrelated doc sections.** Resist; this ticket only adds what AC-1..AC-5 require.

## References

- Parent Epic: AZ-835 — https://denyspopov.atlassian.net/browse/AZ-835
- Replay protocol: `_docs/02_document/contracts/replay/replay_protocol.md` Invariant 12
- Architecture: `_docs/02_document/architecture.md` (satellite-provider section)
- Tests directory: `tests/e2e/replay/`
- AZ-777 spec (being superseded): `_docs/02_tasks/done/AZ-777_derkachi_c6_reference_fixture.md` (post-closure)
