# Common Helper — `Sha256Sidecar`

## Purpose

Atomic-write + SHA-256 content-hash sidecar pattern (D-C10-3). Every persistent artifact that takeoff-load (F2) verifies must be written atomically AND have a `.sha256` sidecar that the verifier can independently recompute. Centralising the pattern avoids two slightly-different implementations across C6 (FAISS index, tile metadata) and C7 (engine + calibration cache) and C10 (Manifest itself).

## Used By

- C6 — Tile Cache + Spatial Index (FAISS `.index`, descriptor sidecar; tile pixels do NOT use sidecars individually — there are too many; the Manifest covers the tile-tree hash collectively).
- C7 — Inference Runtime (engine cache files + INT8 calibration cache; D-C10-6 calibration-cache trust depends on this).
- C10 — Pre-flight Cache Provisioning (Manifest itself; aggregate hash of the cache root).

## Interface (sketch)

```
class Sha256Sidecar:
    @staticmethod
    def write_atomic(path: Path, payload: bytes) -> sha256
    @staticmethod
    def write_atomic_and_sidecar(path: Path, payload: bytes) -> sha256
    @staticmethod
    def verify(path: Path) -> bool                           # checks payload hash against sidecar
    @staticmethod
    def aggregate_hash(paths: list[Path]) -> sha256          # for Manifest covering many files
```

## Implementation Notes

- Backed by the `atomicwrites` package for atomic rename and Python's `hashlib.sha256` for digesting.
- Sidecars are written as `<path>.sha256` containing the hex digest (no JSON wrapper — keeps verification trivial).
- `aggregate_hash` is order-deterministic (sorts paths first) so two runs that read the same files yield the same aggregate.

## Caveats

- The atomic rename is filesystem-level — works on POSIX local filesystems, not on NFS / SMB / overlayfs. For production deployments the cache root MUST live on a local filesystem.
- The sidecar is NOT cryptographically signed; it protects against accidental corruption + file-replacement-after-staging, NOT against an attacker with write access to the cache root. Threat model treats the operator workstation as trusted; the companion's write access is restricted to F4 (mid-flight tile gen) which has its own per-flight signing key path.