# C6 Freshness Gate — Active-Conflict Reject + Stable-Rear Downgrade

**Task**: AZ-307_c6_freshness_gate
**Name**: C6 Freshness Gate
**Description**: Implement the freshness gate that runs at every `write_tile` and `insert_metadata` call site: looks up the target `(lat, lon)`'s sector classification from `sector_boundaries`, reads the per-classification rule from `tile_freshness_rules` (`max_age_seconds`, `action`), and either raises `FreshnessRejectionError` (active_conflict + stale → reject) or stamps `freshness_label = DOWNGRADED` (stable_rear + stale → downgrade) before the row lands. Replaces the pass-through `_evaluate_freshness` hook the `PostgresFilesystemStore` ships in AZ-305. Reads the rules table once at construction (rules are per-flight; the flight is the lifetime). Caches sector boundaries in an in-memory R-tree (operator sets ≤ a few hundred per flight). Emits an FDR record on every rejection and every downgrade.
**Complexity**: 2 points
**Dependencies**: AZ-303_c6_storage_interfaces, AZ-304_c6_postgres_schema, AZ-305_c6_postgres_filesystem_store, AZ-263_initial_structure, AZ-269_config_loader, AZ-266_log_module, AZ-273_fdr_client_ringbuf
**Component**: c6_tile_cache (epic AZ-250 / E-C6)
**Tracker**: AZ-307
**Epic**: AZ-250 (E-C6)

### Document Dependencies

- `_docs/02_document/contracts/c6_tile_cache/tile_metadata_store.md` — Invariants I-2 (active_conflict reject) and I-3 (stable_rear downgrade) are the canonical statement of this task's behaviour.
- `_docs/02_document/contracts/c6_tile_cache/tile_store.md` — defines `FreshnessRejectionError` and `FreshnessLabel`.
- `_docs/02_document/contracts/shared_fdr_client/fdr_record_schema.md` — `kind="c6.freshness.rejected"` / `kind="c6.freshness.downgraded"` envelopes.
- `_docs/02_document/contracts/shared_logging/log_record_schema.md` — INFO log shape on rule load + WARN log shape on rejection / downgrade.

## Problem

Without a real freshness gate:

- AC-8.2 (active_conflict ≤ 6 mo, stable_rear ≤ 12 mo) is unenforced — stale tiles in active sectors land silently and downstream consumers cannot tell them apart.
- AC-NEW-6 (system rejects/downgrades stale tiles) collapses — the test C6-IT-02 / C6-IT-05 cannot pass.
- The pass-through hook in `PostgresFilesystemStore` (AZ-305) accepts every freshness label as-is — an attacker could feed `freshness_label=FRESH` for a 10-year-old tile and bypass the safety budget.
- The cache-poisoning safety budget (AC-NEW-7) loses one of its layers — the rule-evaluation point is a defence boundary, not a label-trust point.
- Operator sector classifications (set via C12) have no read consumer at the C6 layer — the classifications would be data-only, never policy.

This task wires the rule-evaluation logic into the AZ-305 store's `_evaluate_freshness` hook.

## Outcome

- A `FreshnessGate` class at `src/gps_denied_onboard/components/c6_tile_cache/freshness_gate.py` with a single public method `evaluate(metadata: TileMetadata) -> TileMetadata` that returns either:
  - The same `metadata` if FRESH applies (no policy intervention).
  - A new `metadata` with `freshness_label=DOWNGRADED` if stable_rear-stale.
  - Raises `FreshnessRejectionError` if active_conflict-stale.
- Constructor signature: `__init__(self, *, postgres_pool: psycopg_pool.ConnectionPool, fdr_client: FdrClient, logger: Logger, clock: Clock)`. The `clock` injection lets tests advance time deterministically.
- At construction:
  1. Reads `sector_boundaries` once, builds an in-memory R-tree (using `rtree` library — already pinned by description.md or added here if not; check requirements file).
  2. Reads `tile_freshness_rules` once, caches the two rules in a frozen dict `{SectorClassification: FreshnessRule}`.
  3. Emits an INFO log: `kind="c6.freshness.loaded"` with `n_sectors`, `rules`.
- `evaluate(metadata)`:
  1. Computes `tile_age_seconds = now - metadata.capture_timestamp` via the injected `clock`.
  2. Queries the R-tree for the sector containing `(metadata.tile_id.lat, metadata.tile_id.lon)`. If multiple sectors match (overlap), the smallest by area wins (deterministic tie-break).
  3. If no sector matches → treats as `STABLE_REAR` default (per data_model.md convention; documented as the implicit default).
  4. Looks up the rule for that classification.
  5. If `tile_age_seconds <= rule.max_age_seconds` → returns `metadata` unchanged (FRESH).
  6. Else if `rule.action == 'reject'` → emits FDR `kind="c6.freshness.rejected"` and WARN log; raises `FreshnessRejectionError(tile_id, age_seconds, classification, rule)`.
  7. Else if `rule.action == 'downgrade'` → emits FDR `kind="c6.freshness.downgraded"` and INFO log; returns `dataclasses.replace(metadata, freshness_label=FreshnessLabel.DOWNGRADED)`.
- The `PostgresFilesystemStore`'s `_evaluate_freshness` hook is replaced — instead of `return metadata.freshness_label`, it now calls `freshness_gate.evaluate(metadata).freshness_label`. This is a wiring change in AZ-305's class — implemented as a small constructor argument addition (`freshness_gate: Optional[FreshnessGate] = None`) so AZ-305 remains testable in isolation.
- The composition root constructs `FreshnessGate` and passes it to `PostgresFilesystemStore` AFTER the migration runner (AZ-304) has populated the rules table.

## Scope

### Included

- `FreshnessGate` class with `evaluate(metadata)` method.
- Construction-time R-tree build over `sector_boundaries`.
- Construction-time rules-table cache.
- FDR emission on every rejection and every downgrade.
- WARN log on rejection (per `tile_store.md` § log table); INFO log on downgrade (downgrade is recoverable, not an error).
- The smallest-area tie-break for overlapping sector boundaries (deterministic, documented).
- The implicit STABLE_REAR default for `(lat, lon)` outside any sector.
- A constructor `Optional[FreshnessGate]` arg on `PostgresFilesystemStore` so AZ-305 stays unit-testable without this gate.
- Composition-root wiring (the factory `build_tile_store` becomes `build_tile_store(config, freshness_gate)`).
- A standalone CLI `python -m c6_tile_cache.freshness_gate explain <lat> <lon> <capture_iso>` for operators to dry-run the gate.

### Excluded

- Sector-boundary CRUD — owned by C12 operator tooling.
- Tile-freshness-rule CRUD beyond the migration's seeded defaults — operators can edit at the DB level today; a future task adds an admin API.
- Rule reload mid-flight — out of scope this cycle. The flight is the lifetime; rules change requires a process restart.
- Cross-sector pose-error voting (the parent-suite D-PROJ-2 voting layer) — that lives in `satellite-provider`.
- Time-of-day or seasonal freshness adjustments — not in description.md, out of scope.
- Per-tile freshness override (operator manually marks one tile fresh) — out of scope; operator workaround is to delete + re-insert with a fresh capture_timestamp.

## Acceptance Criteria

**AC-1: Active-conflict stale tile is rejected**
Given a sector classified `ACTIVE_CONFLICT` with the default 6-month rule, and a tile inside it with `capture_timestamp = now - 7 months`
When `evaluate(metadata)` is called
Then `FreshnessRejectionError` is raised with a message naming the tile_id, the age, and the rule; ONE FDR `kind="c6.freshness.rejected"` record is emitted; ONE WARN log is emitted

**AC-2: Active-conflict fresh tile passes**
Given the same sector and a tile with `capture_timestamp = now - 5 months`
When `evaluate(metadata)` is called
Then the call returns `metadata` unchanged; no FDR record is emitted; no WARN log is emitted

**AC-3: Stable-rear stale tile is downgraded**
Given a sector classified `STABLE_REAR` with the default 12-month rule, and a tile inside it with `capture_timestamp = now - 13 months`
When `evaluate(metadata)` is called
Then the returned `TileMetadata` has `freshness_label = FreshnessLabel.DOWNGRADED`; the rest of the metadata is unchanged; ONE FDR `kind="c6.freshness.downgraded"` record is emitted; ONE INFO log is emitted

**AC-4: Stable-rear fresh tile passes**
Given the same sector and a tile with `capture_timestamp = now - 10 months`
When `evaluate(metadata)` is called
Then the call returns `metadata` unchanged; no FDR; no log

**AC-5: Tile outside all sectors defaults to STABLE_REAR**
Given a tile at `(lat, lon)` not contained in any `sector_boundaries` row
When `evaluate(metadata)` is called with a 13-month-old `capture_timestamp`
Then the result is `freshness_label = DOWNGRADED` (the implicit STABLE_REAR default applies); FDR `kind="c6.freshness.downgraded"` is emitted

**AC-6: Overlapping sectors resolve by smallest area**
Given two `sector_boundaries` rows: a 1°×1° ACTIVE_CONFLICT box and a 0.1°×0.1° STABLE_REAR box, with the smaller box fully inside the larger
When `evaluate(metadata)` is called for a tile inside the smaller (and thus also the larger) box
Then the STABLE_REAR rule applies (smallest area wins); a 13-month-old tile is downgraded, NOT rejected

**AC-7: Rules and sectors are loaded once at construction**
Given a `FreshnessGate` instance
When 10000 `evaluate` calls are made
Then no `sector_boundaries` or `tile_freshness_rules` SELECT is observed (verifiable via psycopg query log capture); only the construction-time SELECT pair is observed

**AC-8: FreshnessRejectionError carries diagnostic fields**
Given an active_conflict rejection
When the test inspects the raised exception
Then `exc.tile_id`, `exc.age_seconds`, `exc.classification`, `exc.rule` are populated; the exception message starts with `"Tile rejected by freshness gate"`

**AC-9: FDR record envelopes match contract**
Given a rejection or downgrade
When the FDR record is captured
Then the record matches `_docs/02_document/contracts/shared_fdr_client/fdr_record_schema.md` shape with the documented `kind`, `producer_id="c6_tile_cache.freshness"`, payload `{tile_id, age_seconds, classification, rule_action, rule_max_age_seconds}`

**AC-10: Composition wiring change works end-to-end**
Given a `PostgresFilesystemStore` constructed WITH a `FreshnessGate` argument
When `write_tile` is called with a stale active_conflict tile
Then `FreshnessRejectionError` is raised; no JPEG / row / sidecar is written (verifiable via filesystem + DB inspection); the rejection FDR is emitted via the same `FdrClient` AZ-305 already holds

## Non-Functional Requirements

**Performance**
- `evaluate` p99 ≤ 100 µs (R-tree point-in-rect lookup is sub-microsecond; the hot bottleneck is the `now - capture_timestamp` arithmetic and the FDR emission, both fast).
- Construction takes ≤ 50 ms even for a few-hundred-sector flight (R-tree build is O(N log N) on a small N).

**Compatibility**
- `rtree` Python library — verify the project pin already includes it; if not, this task adds it (compatible with the project's existing geospatial stack).
- `dataclasses.replace` is stdlib.

**Reliability**
- Construction failure is fail-fast: a malformed `tile_freshness_rules` row (e.g., unknown `action` enum value) raises a `ConfigSchemaError` extension at construction; the composition root catches and aborts startup with a clear operator message.
- The gate is idempotent — calling `evaluate` on the same `metadata` twice returns deep-equal results (no hidden state changes).
- The injected `Clock` MUST be the same singleton used by AZ-305's `record_lru_access` and AZ-302's thermal publisher (already a project-wide singleton).

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|-------------|-----------------|
| AC-1 | Active-conflict + 7-month tile | FreshnessRejectionError; one FDR; one WARN log |
| AC-2 | Active-conflict + 5-month tile | Returns unchanged; no FDR; no WARN |
| AC-3 | Stable-rear + 13-month tile | Returns with freshness_label=DOWNGRADED; one FDR; one INFO |
| AC-4 | Stable-rear + 10-month tile | Returns unchanged; no FDR; no log |
| AC-5 | Tile outside all sectors + 13-month | Defaults to STABLE_REAR; downgraded |
| AC-6 | Overlapping sectors (smaller STABLE_REAR inside larger ACTIVE_CONFLICT) | Smaller wins; downgrade, not reject |
| AC-7 | 10k evaluate calls + query-log capture | Only construction-time SELECTs observed |
| AC-8 | Inspect raised FreshnessRejectionError fields | tile_id, age_seconds, classification, rule populated |
| AC-9 | FDR record shape on reject and downgrade | Matches schema deep-equal |
| AC-10 | E2E PostgresFilesystemStore + FreshnessGate write | FreshnessRejectionError; no fs/db effects |
| NFR-perf-evaluate | Microbench evaluate × 100k | p99 ≤ 100 µs |
| NFR-reliability-malformed-rule | Inject `tile_freshness_rules` row with `action='unknown'` | ConfigSchemaError at construction |

## Constraints

- The R-tree is built ONCE at construction; mid-flight sector boundary changes are NOT honoured (process restart required).
- The implicit STABLE_REAR default for tiles outside all sectors is documented and is the safer default (downgrade, not reject — operator may add an explicit `whole_world` ACTIVE_CONFLICT sector if they want fail-closed behaviour).
- Tie-break for overlapping sectors is "smallest area wins" — deterministic and documented; bbox area is computed via `(max_lat - min_lat) * (max_lon - min_lon)` (degrees² — adequate for ranking, not for actual area).
- The gate raises `FreshnessRejectionError` (defined in AZ-303); this task does NOT define new error types.
- The gate's `evaluate` method MUST be idempotent and side-effect-free except for FDR + log emissions; future code-review treats internal state mutation as a `Reliability` finding (High).
- `Clock` injection is mandatory — no `time.time()` direct calls; tests assert deterministic output by advancing the fake clock.
- This task does NOT introduce new third-party dependencies beyond `rtree` (verify in requirements).

## Risks & Mitigation

**Risk 1: R-tree library API drift across pins**
- *Risk*: `rtree` minor version bump changes API; constructor calls fail at runtime.
- *Mitigation*: Pin recorded in requirements; the wrapper isolates `rtree` to this single class; future breaks fail-fast at construction.

**Risk 2: Sector-boundary update mid-flight is silently ignored**
- *Risk*: Operator updates sector_boundaries via SQL during a flight; the gate's R-tree is stale; new tile classifications use old boundaries.
- *Mitigation*: Documented constraint — process restart required for boundary changes. Operator workflow: pre-flight sector setup is C12's responsibility; in-flight boundary changes are not in scope.

**Risk 3: STABLE_REAR-default for tiles outside all sectors is too lenient**
- *Risk*: A tile from an unmapped area lands as DOWNGRADED rather than rejected, leaking past the safety budget.
- *Mitigation*: Documented as the safer default (operator adds explicit ACTIVE_CONFLICT whole_world sector for fail-closed). FDR `kind="c6.freshness.downgraded"` carries the classification, so the FDR-trace shows operators which tiles fell through. A future task could add a `config.tile_cache.freshness_gate.no_sector_default` config field — out of scope this cycle.

**Risk 4: Smallest-area tie-break interacts badly with adversarial sector layouts**
- *Risk*: An operator (or attacker) inserts a tiny STABLE_REAR sector inside a large ACTIVE_CONFLICT box to bypass rejections.
- *Mitigation*: Sector boundary CRUD is C12-only and operator-authenticated (per architecture's threat model). The smallest-area rule is documented; if abused, the operator audit log (set_by_operator + set_at columns in `sector_boundaries`) surfaces the change.

**Risk 5: Clock-injection mistake — fake clock used in production**
- *Risk*: Composition root accidentally wires `FakeClock` instead of `WallClock` to the gate; freshness ages are computed against a fixed time; everything looks fresh forever.
- *Mitigation*: AZ-265's `Clock` interface owns the WallClock vs. fake choice via the same composition-root selection that owns thermal-state polling. The factory's per-binary CMake `BUILD_*` flags already separate live (WallClock) from replay (TlogDerivedClock); test wiring is the only place fakes appear. Code review's wiring check (Phase 6 / Architecture) is the canonical guard.

## Runtime Completeness

- **Named capability**: per-sector freshness gate enforcing AC-8.2 / AC-NEW-6 (description.md / E-C6 / data_model.md).
- **Production code that must exist**: real `FreshnessGate` class with R-tree-backed sector lookup, real `tile_freshness_rules` query at construction, real `dataclasses.replace` for the downgrade label, real FDR emission on every reject and downgrade, real WARN/INFO logs.
- **Allowed external stubs**: tests MAY use a fake `Clock`, fake `FdrClient`, fake `Logger`, and an in-memory psycopg fake (testcontainer is also fine — both are equivalent under AZ-304's schema fixture); production wiring uses real WallClock + real AZ-273 `FdrClient` + real AZ-266 `Logger` + real Postgres pool.
- **Unacceptable substitutes**: a hardcoded "everything is fresh" pass-through (defeats the entire point); a Python in-memory boundary list ignoring `sector_boundaries` (would diverge from the operator's source of truth in C12); `time.time()` direct calls without Clock injection (would break test determinism); skipping the R-tree and doing a linear scan over sectors (works at small N but invites future regression at larger N — R-tree is pre-emptively the right shape per coderule.mdc's "the simplest solution that satisfies all requirements, including maintainability").

## Contract

This task implements behaviour mandated by `_docs/02_document/contracts/c6_tile_cache/tile_metadata_store.md` § Invariants I-2 + I-3. No new contract file — the gate is a policy implementation behind an existing Protocol surface (`PostgresFilesystemStore.write_tile / insert_metadata` already raise `FreshnessRejectionError` per the contract; this task supplies the rule-evaluation logic).