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

Batch 37 — Cycle 1 Report

Date: 2026-05-13 Batch: 37 (single task — closes the C10 build-phase trilogy AZ-321/322/323/325) Tasks: AZ-325 (C10 CacheProvisioner orchestrator, 3pt) Status: complete; AZ-325 pending transition to "In Testing".

Scope

AZ-325 implements CacheProvisionerImpl — the public top-level F1 build orchestrator for E-C10. It composes EngineCompiler (AZ-321), DescriptorBatcher (AZ-322), and ManifestBuilder (AZ-323) into a single idempotent operation guarded by a filesystem lockfile and a post-build coverage walk.

This unblocks E-C12 OperatorTooling — c10 build becomes a one-liner — and provides the final assembly point for D-C10-1 idempotence and D-C10-3 ManifestCoverageError.

Architectural Decisions

1. Public surface lives in interface.py only

The contract _docs/02_document/contracts/c10_provisioning/cache_provisioner.md v1.1.0 defines CacheProvisioner Protocol + BuildRequest / BuildReport / BuildOutcome / SectorClassification DTOs + FileLockFactory Protocol. These all live in interface.py — the single public API surface for the component. The implementation (provisioner.py) imports the Protocols and DTOs from there and declares only the implementation classes in its own __all__. This matches the pattern established by AZ-321 / AZ-323 / AZ-324.

2. Build-identity hash byte-aligned with AZ-323

AZ-325's idempotence check has to match the manifest_hash AZ-323 wrote into the prior Manifest.json byte-for-byte. Re-implementing the hash formula here would risk drift. We instead import AZ-323's existing _compute_manifest_hash and _aggregate_tile_hash helpers directly and reconstruct the inputs the helper needs from a combination of the new BuildRequest (for tiles_coverage_sha256, calibration_sha256, sector/bbox/zoom/origin/flight) and the prior Manifest's recorded artifacts (engine SHA-256s, descriptor index SHA-256). The leading underscore on the helpers is acknowledged technical debt — it remains finding F1 from the batch 31–33 cumulative review, with a deferred hygiene PBI to extract a shared _build_identity module after AZ-324 ships. The decision is documented inline in provisioner.py:43-50.

3. Idempotence path performs zero compile / embed / write work

CP-INV-1 + AC-2 are explicit: a warm idempotent re-run must result in zero calls to compile_engines_for_corpus, zero calls to populate_descriptors, zero calls to build_manifest, and the on-disk Manifest.json must remain byte-identical (mtime unchanged). The orchestrator never instantiates a write path before the idempotence check returns — only tile_metadata_store.query_by_bbox (a read) + Manifest.json parse + SHA-256 of calibration_path are touched. All spies in the unit tests verify this.

4. Coverage rollback uses .prev snapshot, not in-memory bytes

_run_active_build snapshots the prior-good Manifest by renaming Manifest.json → Manifest.json.prev BEFORE the active phases run. Every error path (engine compile raise, descriptor batcher raise, manifest builder raise, ManifestCoverageError) calls _restore_prior_manifest which deletes the new partial Manifest and renames .prev back. This guarantees CP-INV-2 (failed build leaves cache no worse than at start) without holding bytes in memory across the whole build.

5. Lockfile uses filelock package (fcntl-backed on POSIX)

The FileLockFactory Protocol is the seam; the default FilelockFileLockFactory wraps filelock.FileLock (fcntl flock on POSIX → kernel auto-releases on process exit, satisfying the SIGKILL clause of AC-8; msvcrt locks on Windows). On acquisition timeout, the wrapper re-raises as the contract's typed BuildLockHeldError. Lockfile cleanup is best-effort — a leftover .c10.lock is harmless (filelock re-uses the file on next acquisition); the kernel-level advisory lock is what enforces mutual exclusion.

6. Diagnostic compile_engines_for_corpus is lock-free

AC-10 / CP-TC-11: the engine-only diagnostic passthrough does NOT acquire the lockfile. Operators run this for hardware-change scenarios where forcing a full transactional build would be overkill, and the lock-free path keeps it from contending with a concurrently-held lock from an unrelated build_cache_artifacts invocation (covered by test_diagnostic_engine_compile_does_not_acquire_lock).

7. C10ProvisionerConfig lives at the top of C10ProvisioningConfig

The new config dataclass (coverage_strict, lock_timeout_s, manifest_filename) is wired in as C10ProvisioningConfig.provisioner, matching the existing manifest / engine_compiler sub-block pattern. The composition root reads block.provisioner and passes it directly into the orchestrator's constructor.

Files Changed

Production code (new)

• src/gps_denied_onboard/components/c10_provisioning/provisioner.py — CacheProvisionerImpl (orchestrator) + _LockGuard + FilelockFileLockFactory.

Production code (modified)

• pyproject.toml — added filelock>=3.13,<4.0 (single new third-party dep, per task constraint).
• src/gps_denied_onboard/components/c10_provisioning/interface.py — replaced placeholder CacheProvisioner Protocol with v1.1.0 surface; added BuildOutcome, BuildRequest, BuildReport, SectorClassification, FileLockFactory.
• src/gps_denied_onboard/components/c10_provisioning/errors.py — added BuildLockHeldError, ManifestCoverageError.
• src/gps_denied_onboard/components/c10_provisioning/config.py — added C10ProvisionerConfig + integrated as C10ProvisioningConfig.provisioner sub-block.
• src/gps_denied_onboard/components/c10_provisioning/__init__.py — re-exported new public symbols.
• src/gps_denied_onboard/runtime_root/c10_factory.py — added build_cache_provisioner(config, *, engine_compiler, descriptor_batcher, manifest_builder, tile_metadata_store, host, precision, clock) composition-root factory.

Tests (new)

• tests/unit/c10_provisioning/test_cache_provisioner.py — 18 tests covering AC-1..AC-16 + NFR-perf-coverage-walk + test_diagnostic_engine_compile_does_not_acquire_lock supplemental. AC-12 (cold-build benchmark) is wired with pytest.skip() — runs manually on Tier-1 GPU host only.

Test Results

• 17 / 17 AZ-325 tests pass; 1 GPU-only test skipped as expected.
• 80 / 80 targeted runs pass on tests/unit/c10_provisioning/ (excluding the pre-existing AZ-322 faiss-import failure) + tests/unit/composition_root/.
• One pre-existing failure is unchanged from HEAD: tests/unit/c10_provisioning/test_descriptor_batcher.py::test_ac6_descriptor_id_mapping_matches_az306_scheme fails with ModuleNotFoundError: No module named 'faiss' because faiss is an optional Tier-1 dependency. Verified pre-existing by git stash + re-run on HEAD. Not introduced by AZ-325; tracked in _docs/_process_leftovers/2026-05-11_d_cross_cve_1_opencv_pin_deferred.md context.

Decisions Ledger

Decision	Rationale
Public surface centralised in interface.py	Mirrors AZ-321 / AZ-323 / AZ-324; one source of truth for contract Protocols + DTOs
Idempotence uses AZ-323's private hash helpers	Byte-for-byte agreement with the on-disk manifest_hash; refactor deferred to a hygiene PBI
.prev rollback over in-memory snapshot	Lower memory pressure for large Manifests; rename is atomic
filelock chosen over fasteners	Already idiomatic for the project size; fcntl-backed; SIGKILL-safe
Diagnostic passthrough is lock-free	AC-10; operator-controlled engine-only re-compile must not contend with a held lock
C10ProvisionerConfig is a sub-block of C10ProvisioningConfig	Matches existing manifest / engine_compiler pattern; keeps the config tree shallow

Notes

• build_cache_provisioner is wired but no integration test exists yet for the full real-AZ-321/322/323 pipeline (requires GPU + FAISS + TRT). E2E coverage lands with AZ-326 (T5 orchestrator) which composes the provisioner into the operator CLI.
• F1 from the batch 31–33 cumulative review (verifier importing private helper from manifest_builder) carries over; AZ-325 also depends on the same private helpers. The hygiene PBI to extract a shared _build_identity module is intentionally deferred — both consumers (AZ-324 verifier + AZ-325 provisioner) need the same helper, and a single refactor PBI after AZ-326 is cleaner than re-touching each consumer twice.
• The OKVIS2 cmake submodule failure (carryover from batch 35/36) remains and is independent of this batch.