gps-denied-onboard/_docs/03_implementation/reviews/batch_49_review.md

Code Review Report

Batch: 49 — AZ-526 (Hygiene — consolidate _iso_ts_from_clock) Date: 2026-05-13 Verdict: PASS_WITH_WARNINGS

Findings

#	Severity	Category	File:Line	Title
1	Low	Scope	_docs/02_tasks/todo/AZ-526_hygiene_iso_ts_from_clock_consolidation.md § AC-4	AC-4 wording contradicts § Scope (instance-method delegations)

Finding Details

F1: AC-4 wording contradicts § Scope (instance-method delegations) (Low / Scope)

• Location: _docs/02_tasks/todo/AZ-526_hygiene_iso_ts_from_clock_consolidation.md, AC-4 vs § Scope / § Constraints.
• Description: AC-4 says grep "def _iso_ts_from_clock|def iso_ts_from_clock" src/ must yield "matches only inside helpers/iso_timestamps.py; zero matches in c2_vpr/, c12_operator_orchestrator/". But § Scope and § Constraints both explicitly mandate that FaissBridge._iso_ts_from_clock(self) and OperatorReLocService._iso_ts_from_clock(self) "become one-line delegations" — meaning two def _iso_ts_from_clock lines remain inside class bodies. Strict reading of AC-4 fails; reading aligned with Scope/Constraints passes.
• Implementation followed Scope/Constraints (delegations preserved). The AST-based test test_ac4_az526_no_module_level_iso_ts_from_clock_outside_helper enforces the spirit of AC-4 by scanning only top-level FunctionDef nodes (so nested ClassDef methods are not flagged).
• Suggestion: amend AC-4 to read "Then matches at module level appear only inside helpers/iso_timestamps.py; zero free-function matches in c2_vpr/, c12_operator_orchestrator/. Instance-method one-line delegations are permitted per § Scope." Recorded as drift; no code change needed.
• Task: AZ-526.

Phase Summary

Phase 1 — Context Loading

Read task spec AZ-526, cumulative review 46-48 (F1, F3), _docs/02_document/module-layout.md § shared/helpers/iso_timestamps, and AZ-508 precedent. Mapped 8 changed files (2 helper, 4 component, 1 test, 2 doc) to AZ-526.

Phase 2 — Spec Compliance

• AC-1: iso_ts_from_clock importable from helper. PASS (test_az526_ac1_import_and_call_returns_str).
• AC-2: Format matches ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{9}Z$. PASS (test_az526_ac2_format_matches_canonical_ns_regex, test_az526_ac2_fromisoformat_truncated_roundtrip_yields_utc).
• AC-3: Nanosecond fraction preserved verbatim for ns=1_234_567_890_123_456_789. PASS (test_az526_ac3_nanosecond_fraction_preserved_verbatim, test_az526_ac3_sub_second_distinguishability).
• AC-4: All four call sites import from helper; no module-level stray defs. PASS with F1 drift (see above). Tests test_ac4_az526_no_module_level_iso_ts_from_clock_outside_helper, test_az526_ac4_all_four_call_sites_import_from_helper, test_az526_ac4_no_module_level_local_iso_ts_from_clock_body_in_callers.
• AC-5: tests/unit/test_az272_fdr_record_schema.py runs unmodified. PASS (33 tests, 0 modifications).
• AC-6: tests/unit/test_az270_compose_root.py::test_ac6 passes. PASS (8 tests, all green).

Phase 3 — Code Quality

• iso_ts_from_clock body is 4 lines (excluding docstring). SRP satisfied.
• Each migrated instance method is now a single return iso_ts_from_clock(self._clock) — readable and intent-preserving.
• Stale meta-rule comment in _faiss_bridge.py deleted (was: "Inlined here rather than importing a shared helper because every other component … defines the same one-liner locally" — that justification is no longer true).
• The two module-level callers (net_vlad.py, ultra_vpr.py) import iso_ts_from_clock as _iso_ts_from_clock, preserving call-site shape with no behavioural change.
• No dead code introduced; the datetime, timezone imports unused after the body deletion were removed from operator_reloc_service.py.
• Tests follow AAA convention with explicit Arrange / Act / Assert markers.

Phase 4 — Security Quick-Scan

No SQL, no shell, no eval / exec, no dynamic deserialisation, no user-controlled paths. The helper is a pure datetime formatter over an injected protocol method. Out of scope.

Phase 5 — Performance Scan

The helper is O(1) — two arithmetic operations (divmod, int()) plus a strftime and an f-string. Functionally equivalent to the inlined version it replaces; one extra Python function-call frame per call site, dominated by the I/O cost of FdrClient.enqueue (the surrounding caller). Not in any hot path.

Phase 6 — Cross-Task Consistency

Single-task batch. N/A.

Phase 7 — Architecture Compliance

• Layer direction: helpers/iso_timestamps.py imports gps_denied_onboard.clock.Clock under TYPE_CHECKING. Both modules are Layer-1 per module-layout.md Allowed Dependencies table. The runtime from datetime import datetime, timezone is stdlib. No upward import. PASS.
• Public API respect: the four callers import from gps_denied_onboard.helpers.iso_timestamps, which is the Public API surface declared in module-layout.md § shared/helpers/iso_timestamps. PASS.
• No new cyclic dependencies: helpers → clock; clock/interface.py only imports typing. No reverse path possible. PASS.
• Duplicate symbols: net reduction (4 module-level / instance-method copies of _iso_ts_from_clock → 1 canonical + 2 thin delegations). PASS.
• Cross-cutting concerns not locally re-implemented: this IS the consolidation; the cumulative-46-48 F1 + F3 findings are closed by this batch. PASS.

Verdict Rationale

One Low / Scope finding (AC wording drift relative to the spec's own Scope/Constraints) — does not block. No Critical, High, or Medium findings. Verdict: PASS_WITH_WARNINGS.