mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 21:41:13 +00:00
Update autodev state, architecture documentation, and glossary terms
Transitioned the autodev state to phase 21, reflecting the completion of Step 5 and the drafting of Step 6 epics. Revised the architecture documentation to clarify the roles of the Tile Manager and its components, ensuring accurate representation of the system's operational flow. Updated glossary entries for Flight State and Operator to incorporate recent changes and enhance clarity on component interactions and responsibilities.
This commit is contained in:
@@ -0,0 +1,36 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user