gps-denied-onboard/_docs/03_implementation/batch_48_cycle1_report.md

Batch 48 / Cycle 1 — Implementation Report

Date: 2026-05-13 Tasks: AZ-508 — ISO-timestamp helper consolidation (2pt) Total complexity: 2 points Result: PASS (per-batch code review) Jira tracker state: AZ-508 transitioned To Do → In Progress (prior session) → In Testing (this batch)

Scope

Hygiene PBI from cumulative reviews batches 28–30 (Finding F3) and batches 31–33 (Finding F2). Consolidates the duplicated private _iso_ts_now() one-liners across c6_tile_cache and c7_inference into a single Layer-1 helper at src/gps_denied_onboard/helpers/iso_timestamps.py (iso_ts_now() -> str, RFC 3339 UTC microsecond Z-suffix). Closes F2 before the upcoming C2 batches (AZ-339 / AZ-340) and the C4/C3 batches (AZ-358 / AZ-349) would have added the 8th and 9th copies of the helper.

Spec Drift Resolution (User-Approved Choose A)

The task spec assumed:

• 5 call-sites needing migration.
• AC-2 format regex \.\d{6}\+00:00$.
• "FDR records standardize on +00:00 per test_az272_fdr_record_schema.py".

On-disk reality at Batch 48 start:

• 3 call-sites: c6's three callers had already been locally consolidated under src/gps_denied_onboard/components/c6_tile_cache/_timestamp.py (export iso_ts_now, same Z-suffix format); tensorrt_runtime.py carries no local _iso_ts_now definition.
• All 3 existing helpers produce %Y-%m-%dT%H:%M:%S.%fZ (Z suffix).
• The canonical FDR ts fixture is _TS = "2026-05-11T00:00:00.000000Z" (also Z suffix). The +00:00 strings in that test file belong to other DTO fields (manifest generated_at_iso, observed_at_iso), not the FDR ts envelope.

Picking the spec's +00:00 literally would have silently changed FDR record ts bit-shape — explicitly Excluded by the spec ("no schema change") and would have broken AC-5 (FDR schema tests pass unmodified).

User selected Choose A: Z-format helper, byte-identical to existing 3 helpers + FDR _TS fixture; AC-2 regex corrected in the spec; drift documented in this report and in the spec's preamble.

Files Changed

Production (new)

• src/gps_denied_onboard/helpers/iso_timestamps.py — iso_ts_now() -> str. Stateless free function; stdlib datetime + timezone only; format datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ").

Production (modified)

• src/gps_denied_onboard/helpers/__init__.py — re-exports iso_ts_now through the helpers package facade (alphabetical insertion in both the import block and __all__).
• src/gps_denied_onboard/components/c6_tile_cache/cache_budget_enforcer.py — import path c6_tile_cache._timestamp → helpers.iso_timestamps (one-line edit; call-sites untouched).
• src/gps_denied_onboard/components/c6_tile_cache/postgres_filesystem_store.py — same path swap (2 call-sites untouched).
• src/gps_denied_onboard/components/c6_tile_cache/freshness_gate.py — same path swap (2 call-sites untouched).
• src/gps_denied_onboard/components/c7_inference/onnx_trt_ep_runtime.py — removed local def _iso_ts_now; added top-of-file from gps_denied_onboard.helpers.iso_timestamps import iso_ts_now as _iso_ts_now (preserves the _iso_ts_now symbol at 2 call-sites); removed the now-unused from datetime import datetime, timezone.
• src/gps_denied_onboard/components/c7_inference/thermal_publisher.py — same pattern (1 call-site preserved); removed the now-unused from datetime import datetime, timezone.

Production (deleted)

• src/gps_denied_onboard/components/c6_tile_cache/_timestamp.py — the c6-internal consolidation shim is no longer needed; the three c6 callers now import directly from helpers.iso_timestamps. The Layer-1 helper supersedes the Layer-2 component-local one.

Tests (new)

• tests/unit/test_az508_iso_timestamps.py — 9 tests:
  • test_ac1_import_and_call_returns_str (AC-1)
  • test_ac2_format_matches_canonical_regex (AC-2 format)
  • test_ac2_fromisoformat_roundtrip_yields_utc_aware_datetime (AC-2 parseability)
  • test_ac3_two_successive_calls_are_non_decreasing (AC-3)
  • test_ac4_no_other_iso_ts_now_definition_exists_in_src (AC-4 AST-walk over src/)
  • test_ac4_c6_and_c7_callers_import_from_helpers (AC-4 explicit call-site sweep — 5 files)
  • test_ac6_helper_uses_stdlib_only (AC-6, stdlib whitelist)
  • test_helper_is_layer_1_no_component_imports (Constraint § Layer-1 discipline)
  • test_helper_public_surface_is_minimal (defensive: __all__ is exactly ["iso_ts_now"])

Docs (modified)

• _docs/02_document/module-layout.md — appended ### shared/helpers/iso_timestamps row to the helpers section.
• _docs/02_tasks/todo/AZ-508_hygiene_iso_timestamps_consolidation.md — drift note added to the description; AC-2 regex corrected from \+00:00$ to Z$.
• _docs/03_implementation/reviews/batch_48_review.md (new) — per-batch code review (PASS).
• _docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md — replay-attempt timestamp + reason updated (PyPI shows gtsam==4.2.1 but requires_dist: numpy<2.0.0; block unchanged).

Acceptance Criteria Coverage

AC	Description	Status	Test
AC-1	Helper exists, importable, callable, returns str	PASS	test_ac1_import_and_call_returns_str
AC-2	Format regex match + fromisoformat round-trip	PASS	test_ac2_format_matches_canonical_regex, test_ac2_fromisoformat_roundtrip_yields_utc_aware_datetime
AC-3	Lexicographic monotonicity under normal clock	PASS	test_ac3_two_successive_calls_are_non_decreasing
AC-4	All call sites migrated; no stray definitions	PASS	test_ac4_no_other_iso_ts_now_definition_exists_in_src, test_ac4_c6_and_c7_callers_import_from_helpers
AC-5	FDR schema tests pass unmodified	PASS	tests/unit/test_az272_fdr_record_schema.py runs unchanged (35 tests pass)
AC-6	No new third-party dependencies	PASS	test_ac6_helper_uses_stdlib_only + pyproject.toml unchanged
AC-7	AZ-270 layering lint passes	PASS	tests/unit/test_az270_compose_root.py::test_ac6_only_compose_root_imports_concrete_strategies

Test Results

• Focused suite (tests/unit/test_az508_iso_timestamps.py + test_az272_fdr_record_schema.py + tests/unit/c6_tile_cache/ + tests/unit/c7_inference/): 216 passed, 53 environment-skipped, 0 failed in 7.97s. Environment-gated skips (Docker compose for c6 integration, CUDA / TensorRT / Jetson hardware for c7) — unchanged from Batch 47.
• Focused per-helper: 9/9 new AZ-508 tests PASS in 1.36s.
• Layering lint: AZ-270 + AZ-507 lints PASS (no cross-component import violations introduced).
• Lint: ruff check clean on every file authored or modified by this batch. 3 pre-existing ruff findings (B905, RUF022, RUF023) in onnx_trt_ep_runtime.py left untouched per coderule.mdc "fix pre-existing lints only if in the modified area".

Architectural Decisions

1. Layer-1 helper supersedes the c6 internal _timestamp.py. The c6-internal consolidation shipped earlier (cumulative review 28–30 F3) was a Layer-2 stop-gap pending the cross-component consolidation. With the Layer-1 helper now in place, the c6 shim is redundant and was deleted; the three c6 callers now import the cross-component helper directly. This collapses two abstractions into one.

2. Preserve _iso_ts_now symbol at c7 call-sites via import alias. The c7 modules each have 1–2 in-method _iso_ts_now() call-sites. Rather than edit every call-site, the new module-level from gps_denied_onboard.helpers.iso_timestamps import iso_ts_now as _iso_ts_now keeps the local symbol name unchanged → minimal diff per c7 file and minimal risk of accidentally missing a call-site. Matches the task spec's preferred form (Scope § Included bullet 2).

3. Stdlib-only helper, no Clock dependency. The helper is wall-clock metadata about when an FDR record envelope was emitted — explicitly NOT a payload field that might need an injectable Clock for tests. The task spec calls this out (Excluded § "Any change to flight_clock / wall_clock"), and the new module docstring reiterates it so future contributors do not route age_seconds-style fields through it.

4. AST-walk AC-4 test instead of a grep gate. AC-4 originally contemplated a CI-level grep -rn "def _iso_ts_now" src/ gate. The in-repo test in test_az508_iso_timestamps.py uses an AST walk instead — it catches both def _iso_ts_now AND def iso_ts_now defined anywhere outside the helper, with file paths in the assertion message, and runs as part of the standard unit suite (no separate CI hook needed). The same test also enforces the consumer-side import discipline so the regression surface is "the import or the test breaks", not "a stray definition lingers".

Carried-over Findings (from prior batches)

• F1 from cumulative review 43–45 / Batch 46 / Batch 47: closed by this batch. _iso_ts_now is now in exactly one place.
• F2 from Batch 46 / Batch 47 (spec→impl drift on C7 API names for AZ-339 / AZ-340 / AZ-358 / AZ-349): NOT addressed in this batch; belongs to a spec-hygiene PBI to be filed before AZ-339 starts.
• D-CROSS-CVE-1 opencv pin leftover: replay attempted at Batch 48 bootstrap; PyPI shows gtsam==4.2.1 (newer than 4.2 referenced in the leftover) but still pins numpy<2.0.0. Block unchanged; leftover timestamp updated.

New Findings (per Batch 48 code review)

None.

Jira Tracker

• AZ-508 was already In Progress at Batch 48 start (transitioned in a prior /autodev session per the state file). Read-back via getJiraIssue confirmed status.name == "In Progress" before any source edits. Will transition In Progress → In Testing after this batch's commit lands.
• Task spec archived to _docs/02_tasks/done/AZ-508_hygiene_iso_timestamps_consolidation.md as part of the implement skill Step 13.

Next

With AZ-508 closed, the carried-over F1 from batches 43–47 is resolved and the next C2 / C4 / C3 batches can ship without re-adding the helper. Top Batch 49 candidates (per Batch 47's "Next" list, updated):

• AZ-339 — MegaLoc + MixVPR strategies (5pt). Same skeleton as UltraVPR (B47) but two strategies; F2 spec-hygiene PBI may want to ship first.
• AZ-340 — SelaVPR + EigenPlaces + SALAD strategies (5pt). Closes the C2 alternative-backbone buffet.
• AZ-358 — C4 OpenCV/GTSAM pose estimator (5pt). Changes pace from C2-heavy streak; opens C4.
• AZ-389 — C5 internal orthorectifier for mid-flight tiles (3pt).
• Spec-hygiene PBI for F2 (C7 API drift in AZ-339 / AZ-340 / AZ-358 / AZ-349 specs) — strongly recommended before AZ-339.

Per autodev orchestrator: Batch 48 is the third batch since the last cumulative review (batches 43–45). The implement skill Step 14.5 triggers a cumulative review batches 46–48 before Batch 49 starts.