prep docs and service updates

docs/airgap/prep/2025-11-20-controller-scaffold-prep.md

@@ -0,0 +1,20 @@
+# Controller Scaffold Prep — PREP-AIRGAP-CTL-56-001 / 56-002
+
+Status: Draft (2025-11-20)
+Owners: AirGap Controller Guild · DevOps Guild
+Scope: Provide the controller scaffold + status API contract so AIRGAP-CTL-56-001/56-002 can proceed.
+
+## Deliverables included
+- Service scaffold described in `docs/airgap/controller-scaffold.md` (project layout, DI wiring, config keys, auth scopes).
+- Baseline status/seal endpoints sketch:
+  - `GET /system/airgap/status` → `{sealed, policy_hash?, staleness_seconds?, time_anchor_id?, bundle_id?}`
+  - `POST /system/airgap/seal` (body: `{policy_hash, reason}`) → returns new state; requires `airgap:seal` scope.
+- Determinism & offline posture: no external calls; state persisted via `airgap_state` store; timestamps UTC; subject ordering deterministic.
+
+## Next steps for implementation
+- Generate controller project under `src/AirGap/StellaOps.AirGap.Controller` per scaffold.
+- Wire Authority scope checks (`airgap:seal`, `airgap:status:read`).
+- Add sealed-mode guard middleware and timeline events per `docs/airgap/sealed-startup-diagnostics.md` once integrated.
+
+## Handoff
+Use this prep doc to satisfy PREP-AIRGAP-CTL-56-001 and PREP-AIRGAP-CTL-56-002. Update if scope changes; otherwise move tasks to DONE.

docs/airgap/prep/2025-11-20-staleness-drift-prep.md

@@ -0,0 +1,25 @@
+# Staleness & Drift Prep — PREP-AIRGAP-CTL-58-001-BLOCKED-ON-57-002
+
+Status: Draft (2025-11-20)
+Owners: AirGap Controller Guild · AirGap Time Guild
+Scope: Capture the staleness/drift requirements for controller status once seal/unseal telemetry (57-002) is available.
+
+## Inputs
+- Time anchor ingestion from Time service (Roughtime/RFC3161) via `time_anchor_id`, `drift_seconds`, `staleness_budget_seconds`.
+- Bundle metadata from importer (bundle_id, manifest hash, generated_at).
+
+## Proposed status enrichments
+- Add fields to `GET /system/airgap/status`:
+  - `staleness_seconds_remaining`
+  - `bundle_id`
+  - `time_anchor_id`
+  - `drift_seconds`
+- Compute `staleness_seconds_remaining = staleness_budget_seconds - drift_seconds` (floor at 0).
+- Determinism: calculations purely from stored numbers; no wall-clock calls beyond persisted anchor timestamps.
+
+## Observability
+- Metrics: `airgap_staleness_seconds{tenant}` (gauge), `airgap_drift_seconds{tenant}`.
+- Timeline events emitted when budgets breached: `airgap.staleness.threshold`.
+
+## Handoff
+Use this prep note to satisfy PREP-AIRGAP-CTL-58-001. After integrating sealed-startup telemetry and time anchor verification, implement the above fields and metrics, then mark the implementation task DOING.