Lumen/SPIKE-05-OFFLINE-READY.md

# SPIKE-05 — Offline Ready Model

- **Phase:** Architecture Validation
- **Date:** 2026-08-30
- **Decision under test:** the readiness state machine in ARCH §12 (R1–R7).
- **Outcome:** model confirmed; predicate formalized, tightened (time
  independence, optional sections), and failure-state taxonomy completed.

## 1. What READY must actually guarantee

Deriving from the product promise ("everything attendees need works with zero
connectivity"), READY must guarantee, **from local evidence only**:

1. The app can launch and render without network (shell complete).
2. Emergency information is available (floor always; dataset section if present).
3. The schedule is browsable and Now/Next computable (schedule section present;
   note: computable even with a wrong clock — a clock problem is a warning,
   never a readiness failure).
4. The map is usable (map section + its required assets present).
5. Festival info is readable (info section present).
6. The dataset is authentic and untampered (signature + hashes verified).
7. The dataset is compatible with this shell (schema envelope).
8. The claim itself is evidenced (a stored verification record matching the
   active version, not a memory of success).

## 2. The exact predicate (normative)

```
OFFLINE_READY ⟺
    C1  shell_valid:            every precache entry present in the current shell cache
    ∧   C2  dataset_present:    active slot exists for the active edition
    ∧   C3  authenticity:       manifest signature verified against embedded key set
                                (recorded verification matches active packageVersion)
    ∧   C4  integrity:          all manifest-listed files present, sizes match;
                                hashes verified at staging (recorded), spot-check at boot
    ∧   C5  schema_compatible:  package schemaVersion ∈ shell.supportedRange
                                ∧ package.appCompatibility satisfied by APP_VERSION
    ∧   C6  required_sections:  every section with required=true present and parseable:
                                {emergency, schedule, map, info, assets-inventory}
    ∧   C7  required_assets:    every asset referenced by a required section present
                                (size-verified; hash verified at staging)
    ∧   C8  emergency_floor:    embedded baseline present (trivially true; asserted
                                so a broken build cannot silently lose the floor)
```

**Rules of evaluation:**

- **Time independence (new, F-1):** the predicate must not consult any clock.
  A device with a wildly wrong clock must still be able to know it is READY.
  (No expiration fields exist in the package — SPIKE-04 F-2 — so nothing tempts
  a time check.)
- **Optional sections never gate READY (new, F-2):** sections with
  `required=false` (future announcements, i18n packs) report their own presence
  in the status detail but cannot demote READY.
- **Evidence-based:** C3/C4 rely on the stored verification record (SPIKE-02
  F-2) keyed to the active `packageVersion`; if the record is absent or
  mismatched, a full re-verification is required before READY can be claimed.
- **All-or-nothing for READY; everything else is enumerated.**

## 3. State taxonomy (complete)

| State | Definition | User sees | Primary action offered |
|---|---|---|---|
| `READY` | C1–C8 all true | Green chip "OFFLINE READY ✓" | None (status detail on tap) |
| `PARTIAL(list)` | Shell valid; one or more required sections/assets missing, none corrupt; e.g., prep interrupted | Amber chip; status screen enumerates exactly what is missing and what still works | "Continue setup" (resumes staging) |
| `NOT_READY` | Shell valid; no dataset staged or active (fresh install) | Neutral chip "Get festival data" | Preparation flow |
| `RECOVERY(reason)` | Previously-verified state now fails checks: storage evicted (`missing`), verification mismatch (`corrupt`), incompatibility after app/dataset skew (`incompatible`) | Red chip; honest explanation of what happened | "Restore festival data" (re-prep; needs connectivity) — emergency floor works meanwhile |
| `BASELINE_ONLY` | Storage unavailable (private mode, blocked website data, quota 0) and app cannot persist anything | Distinct notice: offline saving unavailable; emergency info still here | Install / normal-mode / free-space guidance |
| `FAILED(op)` | A specific operation failed and no automatic recovery applied (activation transaction repeatedly failing, IDB errors) — distinct from RECOVERY because the *cause is an error, not missing data* | Error screen with plain cause + diagnostics entry | Retry; if persistent, re-prep; diagnostics share option |

Notes:
- The brief's example predicate listed `schedule_present`, `map_present`,
  `festival_info_present`, `emergency_baseline_present` individually. This
  model keeps them (C6/C8) but wraps them in the required-section mechanism so
  future optional sections don't require predicate surgery.
- `FAILED` is the added state: RECOVERY means "data is gone/wrong"; FAILED
  means "an operation errored". Keeping them separate keeps user messaging and
  diagnostics accurate.

## 4. Evaluation cadence and cost

| When | What | Cost target |
|---|---|---|
| Every boot | Light check: C1 (cache list), C2 (slot existence), C4-light (sizes + verification-record match), C5 | ≤ ~150 ms; no hashing |
| After staging completes | Full: all hashes + schema (C3–C7 full) | Seconds; once per update |
| Activation | Record written atomically with the flip; readback spot-check (pending flag, SPIKE-02 F-3) | ms |
| User-initiated "Check my data" | Full re-verification | Seconds, with progress |
| After any IDB error | Full re-verify of active slot; quarantine on failure | Seconds |

## 5. Edge cases adjudicated

| Case | State | Why |
|---|---|---|
| Eviction between install and festival | RECOVERY(missing) | Light check finds no slot; floor still works |
| Verification record present but files gone | RECOVERY(missing) | Sizes check fails |
| Files present but record missing (e.g., partial restore) | PARTIAL → full re-verify path | READY cannot be claimed without evidence |
| New shell, dataset schema too old | RECOVERY(incompatible) with "update data when online" guidance; floor + status usable | C5 false |
| Wrong device clock | **READY unaffected**; separate clock warning (SPIKE-08) | Time independence |
| Optional announcements section missing | READY | F-2 |
| Private browsing, nothing persistable | BASELINE_ONLY | Storage probes fail early |
| Activation failed twice | FAILED(activation) | Distinct from data loss |

## 6. Cross-checks

- Consistent with SPIKE-02 (verification record + readback pending flag).
- Consistent with SPIKE-04 (`required` flag, no expiration).
- Consistent with SPIKE-06 (floor assertion C8; emergency never depends on READY).
- Consistent with SPIKE-07 (prep levels map onto PARTIAL/READY transitions).

## 7. Verdict

**ACCEPT (with formalization).** The ARCH §12 model was directionally correct;
it is now normative: predicate C1–C8, time independence, optional-section rule,
and the full six-state taxonomy including `FAILED`. Changes are refinements of
the design document, not a direction change; no ADR-level reversal.