# Batch 65 — Cycle 1 Report

**Date**: 2026-05-16
**Tasks**: AZ-389 (C5 orthorectifier → C6 mid-flight tile candidate emission)
**Verdict**: COMPLETE — PASS (self-reviewed)

## Summary

Closes the AZ-389 gap inside the C5 state estimator by introducing a
component-internal orthorectifier that emits at most one tile-aligned
JPEG candidate per nav-camera frame to C6 via the existing
`TileStore.write_tile` API.

The implementation respects the AZ-507 cross-component import rule
(enforced by `test_az270_compose_root.test_ac6_only_compose_root_imports_concrete_strategies`):
c5_state never imports c6_tile_cache. The composition root's
`runtime_root.state_factory` carries a new
`_C6MidFlightIngestAdapter` that wraps the C6 `TileStore`, builds the
canonical `TileMetadata` (`TileSource.ONBOARD_INGEST`,
`FreshnessLabel.FRESH`, `VotingStatus.PENDING`), hashes the JPEG
bytes, and translates `FreshnessRejectionError` into a `None` return
so the orthorectifier silently swallows freshness rejection per
AC-NEW-3 (opportunistic emission).

The orthorectifier runs entirely on the existing state-ingest thread
(Invariant 1) — no new threads, no additional locks. It is wired
opt-in: `config.components['c5_state'].orthorectifier.enabled = false`
keeps the legacy steady-state path bit-for-bit unchanged. Both
`GtsamIsam2StateEstimator` and `EskfStateEstimator` participate
through new `attach_orthorectifier(...)` and `set_latest_nav_frame(...)`
extension methods (concrete only — the `StateEstimator` Protocol
surface is unchanged so existing implementations and tests continue
to satisfy it).

## Architecture decisions

* **Per-frame, per-estimator hook** — the hook fires after the
  EstimatorOutput is built inside `current_estimate()`. The buffered
  nav frame supplies the source pixels; the orthorectifier passes
  duck-typed pose + cov to its kernel and rate-limits itself to one
  tile per `frame.frame_id` (AC-4).
* **No new C6 API** — uses `TileStore.write_tile(blob, metadata)`,
  the same atomic file + metadata insert that the C11 download path
  already uses. The composition-root adapter is the only new
  component-bridge.
* **Quality gates as cheap pre-checks** — covariance Frobenius gate,
  inlier-floor gate, source-label gate (only `SATELLITE_ANCHORED`
  passes), and once-per-frame rate limit run BEFORE the OpenCV
  warp/encode work.
* **Best-effort kernel** — any exception inside the warp / JPEG
  encode path or any non-`FreshnessRejectionError` writer failure is
  swallowed with a WARNING log and `None` return; the steady-state
  `current_estimate` output is never disturbed.
* **AC-7 first-emission INFO log** — emitted exactly once per
  flight, subsequent emissions log at DEBUG.

## Files added / modified

### Added (2)

- `src/gps_denied_onboard/components/c5_state/_orthorectifier.py` —
  the `MidFlightTileWriter` Protocol cut, `OrthorectifierThresholds`
  dataclass, and `Orthorectifier` class with the homography
  construction (`_ground_plane_homography`,
  `_compose_tile_to_image_homography`, `_invert_se3`,
  `_quat_to_rotation_matrix`).
- `tests/unit/c5_state/test_az389_orthorectifier.py` — 22 tests
  covering AC-1..AC-9 plus the inlier-floor gate plus the
  composition-root `_C6MidFlightIngestAdapter` translation rules
  plus `OrthorectifierConfig` validation.

### Modified (4)

- `src/gps_denied_onboard/components/c5_state/config.py` — new
  `OrthorectifierConfig` dataclass nested as
  `C5StateConfig.orthorectifier`. Disabled by default; tunable
  thresholds + tile / zoom / JPEG knobs.
- `src/gps_denied_onboard/components/c5_state/gtsam_isam2_estimator.py`
  — orthorectifier state fields, `attach_orthorectifier` +
  `set_latest_nav_frame` extension methods, `_maybe_emit_mid_flight_tile`
  hook in `current_estimate()`, and `create()` factory now accepts
  the optional `mid_flight_tile_writer` / `camera_calibration` /
  `flight_id` / `companion_id` params.
- `src/gps_denied_onboard/components/c5_state/eskf_baseline.py` —
  same set of changes, plus `_latest_vio` cache (ESKF historically
  did not retain the full VIO DTO).
- `src/gps_denied_onboard/runtime_root/state_factory.py` —
  `_C6MidFlightIngestAdapter` class + `build_state_estimator` now
  accepts optional `tile_store` / `camera_calibration` /
  `flight_id` / `companion_id` and forwards them to the strategy
  factory when AZ-389 is enabled.

## Task Results

| Task   | Status | Files Modified                                                                                                                  | Focused tests | AC Coverage  | Issues |
|--------|--------|---------------------------------------------------------------------------------------------------------------------------------|---------------|--------------|--------|
| AZ-389 | Done   | 1 added + 4 modified under `src/`; 1 added under `tests/unit/c5_state/`; task spec moved `_docs/02_tasks/todo/` → `done/`        | 22/22 pass    | 9/9 covered  | None   |

## AC Test Coverage: 9/9 covered

| AC   | Test                                                                                                                                                                                       | Status  |
|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
| AC-1 | `test_ac1_homography_projects_origin_to_principal_point` + `test_ac1_homography_projects_offset_within_one_pixel` + `test_compose_tile_to_image_homography_is_centred_on_camera`           | Covered |
| AC-2 | `test_ac2_cov_norm_above_threshold_blocks_emission` + `test_ac2_cov_norm_below_threshold_emits`                                                                                            | Covered |
| AC-3 | `test_ac3_non_satellite_anchored_blocked` (parametrised over `VISUAL_PROPAGATED` / `DEAD_RECKONED`)                                                                                        | Covered |
| AC-4 | `test_ac4_same_frame_id_processed_only_once` + `test_ac4_distinct_frame_ids_each_emit`                                                                                                     | Covered |
| AC-5 | `test_ac5_writer_called_with_onboard_ingest_metadata` + `test_adapter_calls_write_tile_with_onboard_ingest_metadata`                                                                       | Covered |
| AC-6 | `test_ac6_jpeg_bytes_decode_to_expected_shape_and_quality` + adapter-side `content_sha256_hex == hashlib.sha256(jpeg_bytes).hexdigest()` assertion                                         | Covered |
| AC-7 | `test_ac7_first_emission_logs_info_subsequent_logs_debug`                                                                                                                                  | Covered |
| AC-8 | `test_ac8_missing_inputs_silent_return_none` (parametrised over `frame` / `pose_estimate` / `cov_6x6`)                                                                                     | Covered |
| AC-9 | `test_ac9_writer_returning_none_swallowed` + `test_ac9_writer_raising_swallowed_with_warning` + `test_adapter_translates_freshness_rejection_to_none`                                       | Covered |

## Code Review Verdict: PASS (self-reviewed)
## Auto-Fix Attempts: 0
## Stuck Agents: None

## Cross-batch verification

- `tests/unit/c5_state/` — 216 / 216 pass (all pre-AZ-389 tests still
  pass — Protocol surface unchanged, factory signature is
  backward-compatible via default `None` params).
- `tests/unit/test_az270_compose_root.py` — 8 / 8 pass; the
  cross-component import lint still holds against the new
  `_C6MidFlightIngestAdapter`.
- `tests/unit/test_runtime_root_env_gate.py` +
  `tests/unit/test_az401_compose_root_replay.py` +
  `tests/unit/test_ac3_compose_files.py` — 38 / 38 pass.
- `tests/unit/c6_tile_cache/` — 126 / 126 in-process tests pass
  (Postgres-backed tests skipped; require Docker).

## Notes / leftovers

- The Jira description for AZ-389 still references the
  pre-AZ-559 `tile_store.put_mid_flight_candidate` API surface; the
  local task spec was rewritten against `write_tile` per the
  History section. Logged as tracker hygiene; not blocking.
- During investigation of the existing C11 download adapter
  (`runtime_root/c11_factory.py::_C6DownloadAdapter.write_tile_for_download`)
  we noticed it calls both `tile_store.write_tile(blob, metadata)`
  and `metadata_store.insert_metadata(metadata)` sequentially —
  given that `PostgresFilesystemStore.write_tile` is itself atomic
  (file write + metadata insert in a single transaction) the second
  call is a probable redundancy. Out of scope for AZ-389; recorded
  here for a future hygiene ticket.

## Next Batch: All product-implementation tasks complete — proceed to Step 15 (Product Implementation Completeness Gate).