# Source Registry — C10: Pre-flight cache provisioning (cross-coupling minimal scope)

> Mode A Phase 2 — engine Step 2 (Source Tiering & Exhaustive Web Investigation). Sources for C10 batch 1 (cross-coupling minimal: D-C6-3 descriptor-cache rebuild trigger pipeline + D-C7-7 TensorRT engine-build pipeline). Sibling registries: [SQ1](SQ1_existing_systems.md), [SQ2](SQ2_canonical_pipeline.md), [SQ6](SQ6_external_positioning.md), [C1](C1_vio.md), [C2](C2_vpr.md), [C3](C3_matchers.md), [C4](C4_pose_estimation.md), [C5](C5_state_estimator.md), [C6](C6_tile_cache_spatial_index.md), [C7](C7_inference_runtime.md), [C8](C8_fc_adapter.md). Index: [`00_summary.md`](00_summary.md).
>
> Source-tier definitions per `references/source-tiering.md`: L1 = official primary docs / source code / canonical specs; L2 = official blog posts, vendor SDK docs, peer-reviewed papers; L3 = community Q&A, tutorial sites, secondary commentary; L4 = forum posts, mailing-list threads, single-author blog posts.

---

## Source #114 — FAISS `write_index` / `read_index` Python API + on-disk format + security warning (L1 official)

**URL**: <https://github.com/facebookresearch/faiss/wiki/Index-IO,-cloning-and-hyper-parameter-tuning> + context7 indexed at `/facebookresearch/faiss` (Benchmark Score consistent with C6 batch 1 Source #96 lookup)

**Date accessed**: 2026-05-08

**Tier**: **L1** — canonical FAISS GitHub Wiki + canonical context7-indexed documentation

**Relevance**: Confirms `faiss.write_index(index, path)` + `faiss.read_index(path)` Python API for serializing IndexHNSWFlat to disk and loading it back; confirms `IO_FLAG_MMAP_IFC` enables memory-mapped loading for HNSW + IndexFlatCodes-derived classes (zero-copy load — important for the project's <5 s takeoff load budget); documents the explicit security warning "No attempt is made to check the correctness of loaded data. A faulty or malicious file could lead to out-of-memory errors or code execution. Users are responsible for verifying that files loaded with `read_index` have not been altered since being written by `write_index`." This warning binds directly to AC-NEW-7 (cache-poisoning safety) and motivates the project-side content-hash verification gate before takeoff load. Confirms FAISS C++ signature: `void write_index(Index* index, const char* filename)` / `Index* read_index(const char* filename)`.

**Evidence quality**: ✅ High — L1 canonical FAISS docs. Direct API verification.

---

## Source #115 — FAISS IndexHNSWFlat per-vector memory + on-disk file size formula (L2 community + L1 cross-cite)

**URL**: <https://github.com/facebookresearch/faiss/discussions/3953> + cross-cite <https://faiss.ai/cpp_api/struct/structfaiss_1_1IndexHNSWFlat.html>

**Date accessed**: 2026-05-08

**Tier**: **L2** — FAISS GitHub Discussions thread (maintainer-confirmed answer) + L1 canonical FAISS C++ API docs cross-cite

**Relevance**: Confirms IndexHNSWFlat per-vector on-disk + RAM cost formula: `(vector_dim × 4 bytes) + (M × 4 bytes × 2) + overhead from graph layers and geometric reallocation`. For project's pinned VPR descriptor candidates (per D-C2-9 / D-C2-10 / D-C2-6 / D-C6-1 = halfvec): at 2048-D float32 + M=32 → 8192 + 256 = **8448 bytes/vector** (~845 MB on disk for 100K tiles); at 2048-D halfvec (2-byte storage per descriptor element) → 4096 + 256 = **4352 bytes/vector** (~430 MB on disk for 100K tiles); at 512-D halfvec + M=32 → 1024 + 256 = **1280 bytes/vector** (~130 MB on disk for 100K tiles); at 256-D halfvec + M=32 → 512 + 256 = **768 bytes/vector** (~80 MB on disk for 100K tiles). All variants well within AC-8.3 10 GB cache budget (assuming D-C2-10 EigenPlaces 512-D path or D-C6-1 halfvec mitigation). Supplementary cross-cite to C6 Fact #92 evidence base. **Load latency**: Issue #622 confirms post-load search performance is "slightly slower initially due to memory layout and cache effects" but identical results — implies a warmup-search-pass at takeoff after `read_index` would smooth p99 latency; aligns with the <5 s takeoff load budget (pure file read at ~430 MB / SATA SSD ~500 MB/s = <1 s; mmap path eliminates the read entirely).

**Evidence quality**: ✅ High — formula matches FAISS source code in `IndexHNSW.cpp`; multiple maintainer-confirmed reproductions; conservative for project's pinned descriptor dimensions per D-C2-9/10/6 closures.

---

## Source #116 — Python atomic file write pattern: write-to-temp + fsync + atomic rename (L2 reference + L1 POSIX standard cross-cite)

**URL**: <https://blog.gocept.com/2013/07/15/reliable-file-updates-with-python/> + <https://python-atomicwrites.readthedocs.io/en/stable> + Python tracker Issue 8604 <https://bugs.python.org/issue8604>

**Date accessed**: 2026-05-08

**Tier**: **L2** — well-known engineering blog reference + canonical Python package docs + Python core developer issue tracker

**Relevance**: Documents the canonical Python crash-safe atomic file write pattern required for the project's pre-flight FAISS index file write (and TensorRT engine file write). The pattern is: (1) write to a temporary file in the same directory as target (ensures same filesystem so `os.rename` is atomic), (2) call `fsync(temp_fd)` to flush content + metadata to disk, (3) atomically rename via `os.rename(temp_path, target_path)`, (4) call `fsync` on the parent directory to flush the filename change to disk. Without this pattern, a power loss or process kill mid-write leaves a truncated/partial file that `faiss.read_index` will load successfully (no internal integrity check per Source #114 warning) and produce silently-wrong descriptor matches at takeoff — direct violation of AC-NEW-7 (cache-poisoning safety) + AC-3.3 (re-localization stability). The `python-atomicwrites` package provides this pattern with a simple API: `with atomic_write(path, overwrite=True) as f: ...`; pure-Python; trivially auditable; cross-platform (Windows + POSIX + macOS). On macOS specifically, must use `fcntl.fcntl(fd, fcntl.F_FULLFSYNC)` instead of `os.fsync()` to handle Apple's user-space write buffers — not relevant for the Jetson deployment target (Linux/JetPack). Project-side wrapper around `faiss.write_index` should use this pattern to safely write the FAISS cache file alongside content-hash verification.

**Evidence quality**: ✅ High — pattern matches POSIX `rename(2)` atomicity guarantee; extensively documented; multiple production Python packages (atomicwrites, ruamel-yaml, etc.) implement it.

---

## Source #117 — Polygraphy `polygraphy convert` CLI for TensorRT INT8 engine build with calibration cache reuse (L1 official)

**URL**: <https://github.com/NVIDIA/TensorRT/blob/main/tools/Polygraphy/examples/cli/convert/01_int8_calibration_in_tensorrt/README.md> + context7 indexed at `/websites/nvidia_deeplearning_tensorrt_static_polygraphy` (1041 code snippets, Benchmark Score 67.2, Source Reputation High)

**Date accessed**: 2026-05-08

**Tier**: **L1** — official NVIDIA TensorRT source repository documentation + canonical Polygraphy docs

**Relevance**: Confirms Polygraphy as the canonical NVIDIA-blessed orchestration wrapper around TensorRT's engine build pipeline. Documents the canonical INT8 calibration workflow: first build with `--data-loader-script ./data_loader.py --calibration-cache identity_calib.cache` (computes scales + writes cache); subsequent builds with `--calibration-cache identity_calib.cache` (skips calibration step entirely — cache contains scales). Confirms Polygraphy's `Calibrator` class API: `data_loader` parameter (generator/iterable yielding `{input_name: numpy.ndarray}` dicts), `cache` parameter (calibration cache file path), `BaseClass` parameter (defaults to `trt.IInt8EntropyCalibrator2` — matches project's D-C7-2 + D-C7-6 lock), `algo` parameter (defaults to `trt.CalibrationAlgoType.MINMAX_CALIBRATION`). CLI supports `--int8 --fp16` mixed precision flags directly per project's D-C7-2 = (b) per-family precision policy. The full CLI invocation pattern for project: `polygraphy convert <model>.onnx --int8 --fp16 --data-loader-script ./calib_data_loader.py --calibration-cache <model>_calib.cache -o <model>_sm87_jp62_trt103_int8fp16.engine`. Polygraphy is bundled inside the TensorRT distribution (no separate install on Jetson — `pip install nvidia-pyindex && pip install polygraphy` or via TensorRT installer). Production-mature and cross-referenced from canonical TensorRT documentation.

**Evidence quality**: ✅ High — official NVIDIA repository docs, multi-snippet context7 coverage, production-mature tooling.

---

## Source #118 — Polygraphy `Calibrator` class API — algo defaults + dynamic-shapes calibration profile + warning behavior (L1 official)

**URL**: <https://docs.nvidia.com/deeplearning/tensorrt/latest/_static/polygraphy/backend/trt/calibrator.html> + <https://docs.nvidia.com/deeplearning/tensorrt/latest/_static/polygraphy/backend/trt/config.html>

**Date accessed**: 2026-05-08

**Tier**: **L1** — canonical NVIDIA TensorRT/Polygraphy SDK documentation

**Relevance**: Confirms `Calibrator(data_loader, cache=None, BaseClass=IInt8EntropyCalibrator2, algo=CalibrationAlgoType.MINMAX_CALIBRATION, batch_size=None, quantile=None, regression_cutoff=None)` full signature. Documents two algorithm choices: `IInt8EntropyCalibrator2` (entropy-based; project D-C7-2 default; Polygraphy default) vs `IInt8MinMaxCalibrator` (min-max scaling). Documents dynamic-shapes behavior: "if calibration is run and the model has dynamic shapes, the last optimization profile will be used as the calibration profile" — relevant for project's matchers if any of them export with dynamic input shapes (D-C3-2 LightGlue ONNX export pathway). Documents `--data-loader-script` / `--data-loader-func-name` CLI flags for supplying custom calibration data. Documents the "Int8 Calibration is using randomly generated input data" warning that fires when `--int8` is set but neither `--data-loader-script` nor an existing `--calibration-cache` is supplied — operationalizes the D-C7-1 closure (real UAV nadir flight footage corpus) as a pre-flight build prerequisite. CLI also supports `--load-tactics` / `--save-tactics` for replaying tactic-search results across multiple builds (faster than re-running tactic profiling each build) — useful for the reference-Jetson-prebuilt-engine fallback path per D-C7-7.

**Evidence quality**: ✅ High — canonical NVIDIA documentation, directly cited from polygraphy/tools/args/backend/trt/config source code.

---

## Source #119 — `trtexec` CLI for one-off engine builds — INT8/FP16 flags + calibration cache support (L1 official)

**URL**: <https://docs.nvidia.com/deeplearning/tensorrt/latest/getting-started/quick-start-guide.html> + <https://docs.nvidia.com/deeplearning/tensorrt/latest/reference/command-line-programs.html>

**Date accessed**: 2026-05-08

**Tier**: **L1** — canonical NVIDIA TensorRT SDK documentation

**Relevance**: Confirms `trtexec` as the simpler-but-less-flexible TensorRT engine build CLI bundled with every TensorRT installation. Canonical invocation: `trtexec --onnx=model.onnx --saveEngine=model.engine --fp16 --int8 --calib=calibration.cache --shapes=input:1x3x224x224`. Supports `--int8 --fp16` mixed precision (matches project's D-C7-2). Supports `--calib=<cache_path>` for INT8 calibration cache reuse (cache file format identical to Polygraphy's; the two tools are interoperable on the calibration cache layer). **Critical limitation vs Polygraphy**: `trtexec --int8` without `--calib` causes TRT to use random data for calibration (per TRT docs warning) — this collapses INT8 accuracy by ~5-15%. **Strength**: single-binary; no Python imports; no calibration data loader script required; perfect for emergency rebuilds when an existing calibration cache is available; perfect for ad-hoc benchmarking via `--iterations=N --useCudaGraph --noDataTransfers`. **Recommended role for project**: fallback orchestration tool when Polygraphy is unavailable OR when calibration cache is already shipped from a reference build (e.g., the prebuilt-engine fallback per D-C7-7).

**Evidence quality**: ✅ High — canonical NVIDIA documentation; trtexec is bundled with TensorRT distributions and has been the canonical TensorRT CLI since TensorRT 5.x.

---

## Source #120 — TensorRT INT8 INT8 calibration corpus size guidance (~500-1000 images) — Jetson AGX Orin specific (L2 vendor)

**URL**: <https://nvnexus.com/tensorrt-jetson-agx-orin-optimization-guide/>

**Date accessed**: 2026-05-08

**Tier**: **L2** — vendor-aligned engineering guide (TensorRT-on-Jetson specialist content), cross-cited from official NVIDIA Developer Forum patterns

**Relevance**: Independent confirmation of the project's D-C7-1 closure: "INT8 optimization can double inference throughput on Jetson AGX Orin with minimal accuracy loss; calibration on representative input data (500-1000 images recommended)". Aligns with project's pinned 500-1500 sample range from C7 batch 1 Fact #94. Cross-cite to AGX Orin (server-class Jetson) — the project's deployment target is Orin Nano Super (smaller class), but the calibration-corpus-size guidance is governed by the model + INT8 entropy-statistics requirement, not by the Jetson SKU. **Conservative confirmation**: project's calibration corpus target of 500-1500 samples per D-C7-1 closure is sufficient by community-confirmed benchmarks.

**Evidence quality**: ⚠️ Medium-High — L2 vendor-aligned source; aligns with multiple independent confirmations including NVIDIA Developer Forum threads and the canonical TensorRT INT8 calibration documentation; project's D-C7-1 closure already pinned this range from L1 sources.

---

## Source #121 — Direct TensorRT `IBuilderConfig` + `IInt8EntropyCalibrator2` Python API (L1 official, cross-cite from C7 Source #105)

**URL**: <https://docs.nvidia.com/deeplearning/tensorrt/latest/_static/python/api/infer/Core/BuilderConfig.html> (cross-cite from C7 batch 1 Source #105 + Source #102)

**Date accessed**: 2026-05-08 (cross-cite)

**Tier**: **L1** — canonical NVIDIA TensorRT Python API documentation

**Relevance**: Already cited in C7 batch 1 Source #102 + Source #105 (mode pinning for D-C7-2). Re-cited here for the C10 D-C7-7 confirmation context: confirms direct `IBuilderConfig` + `IInt8EntropyCalibrator2` Python API as the most-flexible-but-most-engineering-cost orchestration option. Pattern: instantiate `trt.Builder(logger)` → `builder.create_network(...)` → parse ONNX via `trt.OnnxParser` → instantiate `builder.create_builder_config()` → `config.set_flag(trt.BuilderFlag.INT8)` + `config.set_flag(trt.BuilderFlag.FP16)` → assign custom `Int8EntropyCalibrator2` subclass instance to `config.int8_calibrator` → `config.max_workspace_size = 1 << 30` (1 GB per D-C7-8) → `serialized_engine = builder.build_serialized_network(network, config)` → `with open(path, 'wb') as f: f.write(serialized_engine)`. **Used in C10 only as the per-model fallback path for the reference-Jetson-prebuilt-engine generation** (D-C7-7 fallback) when Polygraphy's data-loader-script abstraction is too rigid for an unusual model (e.g., LightGlue with dynamic-shape inputs requiring a custom calibration profile).

**Evidence quality**: ✅ High — canonical NVIDIA Python API; cross-cite from existing C7 Source #105 reduces redundancy.

---
