Lumen/SPIKE-01-INDEXEDDB-IOS.md

# SPIKE-01 — IndexedDB + iOS Reliability

- **Phase:** Architecture Validation
- **Date:** 2026-08-30
- **Decision under test:** ADR-004 (IndexedDB as primary local storage; A/B
  slot layout) and the storage foundations of ADR-006.
- **Environment limitation (declared up front):** No iOS hardware or iOS
  Simulator is reachable from this Linux dev box. Nothing iOS-specific below
  was observed here. iOS items are labelled **INFERRED** (from WebKit's own
  published storage policy) or **UNVERIFIED** (needs a physical iPhone). This
  spike does **not** pretend otherwise.

## 1. Question

Is IndexedDB, organized as A/B dataset slots + a system-meta store + a
user-data store, a sound foundation for Lumen on iOS Safari and Android
Chrome, across large datasets, large map assets, crashes, restarts, storage
pressure, and eviction?

## 2. Workload being validated

| Dimension | Lumen value (budget, ARCH §10.6) |
|---|---|
| Structured section JSON | ≤ 3 MB total |
| Map assets (WebP) | ≤ 28 MB |
| Other assets | ≤ 6 MB |
| Total dataset | ≤ 40 MB target / 50 MB ceiling |
| Worst case on device (A/B + shell + user) | ≈ 2×40 MB + 1 MB + ε < 90 MB |
| Object stores | `files`, `assets` per slot DB; `meta` in system DB; `favorites`, `prefs`, `diag` in user DB |
| Largest single record | ≤ 6 MB (per-file cap, ARCH §10.6) |

## 3. Findings, item by item

Each item is labelled. Citations are to vendor/spec documentation current as of
2026 (see DISCOVERY Appendix B for the underlying sources).

### 3.1 Large festival datasets (tens of MB)
- **INFERRED.** IndexedDB is explicitly the browser's intended store for large
  structured data; quotas on both targets are expressed as a fraction of disk
  (WebKit: up to ~60% of disk per origin for browser apps since Safari 17;
  Chromium similar). A 40 MB dataset is a tiny fraction of any realistic quota.
- Risk is not quota *size*; it is *eviction policy* (see 3.9) and *write
  interruption* (3.10).

### 3.2 Multiple object stores / multiple databases
- **CONFIRMED (spec):** multiple databases and multiple object stores per
  origin are standard; transactions are scoped to one database.
- **INFERRED:** our layout (two slot DBs + system DB + user DB) is well within
  normal use. Note: there is **no cross-database transaction** — the A/B design
  already accounts for this (activation is a single-DB transaction on the
  system DB; see SPIKE-02).

### 3.3 Large map assets (multi-MB Blobs in IDB)
- **INFERRED.** IDB stores Blobs; multi-MB records are supported. We cap single
  records at 6 MB to bound transaction duration and memory.
- **UNVERIFIED (both platforms):** sustained read-back performance of ~28 MB of
  WebP blobs into object URLs, and behavior when writing them near quota. Must
  be measured on real devices (Android low-end and iPhone).

### 3.4 Transaction behavior
- **CONFIRMED (spec):** IDB transactions are atomic per database; a transaction
  either fully applies or does not. `oncomplete`/`onerror`/`onabort` signal the
  outcome. Versionchange transactions can block reads/writes.
- **INFERRED:** keeping transactions short (one file + its progress record per
  transaction) avoids pathological lock holding and keeps the A/B flip cheap.

### 3.5 Atomicity
- **CONFIRMED (spec):** within one database, a transaction is all-or-nothing.
  This is exactly what ADR-006's activation flip relies on (single transaction
  on `lumen-system`).
- **CONFIRMED (spec):** atomicity does **not** span databases. The architecture
  must not assume it does (SPIKE-02 validates the ordering that makes this safe).

### 3.6 Browser termination (tab/process killed)
- **INFERRED.** If the process dies mid-transaction, the transaction does not
  commit; durable state reverts to the last committed transaction. This is the
  standard crash-consistency model for IDB and is what EXP-2's crash points
  simulate.
- **UNVERIFIED (iOS):** exact behavior when Safari force-quits or iOS jetsam
  kills the PWA process mid-write is expected to follow the same model but must
  be observed on device.

### 3.7 Service worker termination
- **CONFIRMED (architecture):** dataset staging runs in the **page** context,
  not the SW (constraint C-21), so SW termination cannot interrupt dataset
  writes. The SW only handles shell caching.
- **INFERRED:** iOS aggressively terminates idle SWs; because our design keeps
  no dataset state in the SW, this is a non-issue for data integrity.

### 3.8 Browser restart / phone restart
- **INFERRED.** Committed IDB data survives browser and device restart; the SW
  and caches re-register/rehydrate on next launch. Boot-time light verification
  (SPIKE-05) is the mechanism that confirms this at runtime.
- **UNVERIFIED (iOS):** post-restart cold-start latency and SW re-registration
  timing on real iPhones.

### 3.9 Storage pressure & eviction
- **CONFIRMED (WebKit policy):** storage is **best-effort**. Under pressure,
  WebKit evicts on an LRU basis across origins; `navigator.storage.persist()`
  is a *request* granted by heuristic (home-screen install helps), not a
  guarantee. Eviction is **per-origin and all-or-nothing** (IDB + Cache + SW
  registration together).
- **CONFIRMED (Chromium policy):** similar best-effort LRU eviction; installed
  PWAs with persistence granted are skipped first.
- **INFERRED:** an installed PWA with `persist()` granted and regular use is
  unlikely to be evicted during a festival weekend, but **nothing guarantees
  it**. Therefore eviction is treated as an expected failure mode with a
  recovery path (RECOVERY state + embedded emergency baseline), never as an
  impossible one.

### 3.10 Interrupted writes
- **CONFIRMED (spec):** an interrupted/uncommitted write leaves prior committed
  state intact. Combined with per-file staging transactions (SPIKE-02), an
  interrupted download can leave a slot *partially staged* but can **never**
  corrupt the active dataset.
- **INFERRED:** resume logic keyed on committed per-file progress records
  recovers cleanly; EXP-2 exercises this.

### 3.11 Read consistency
- **CONFIRMED (spec):** reads inside a transaction see a consistent snapshot;
  reads outside a transaction see the latest committed state. Our read paths
  (DatasetStore) read committed state; there are no mid-update reads of the
  inactive slot by features.

### 3.12 iOS Safari specifics
- **INFERRED (WebKit documented):** 7-day ITP cap applies to *Safari-tab* usage
  and is **exempt for home-screen-installed** PWAs; Safari 17+ quota is a disk
  fraction; eviction all-or-nothing.
- **UNVERIFIED:** all of the above *as experienced by our specific app* — install
  exemption in practice, `persist()` grant rate, near-quota write behavior, Blob
  read-back speed, post-restart rehydration. Requires physical iOS.

### 3.13 Android Chrome specifics
- **INFERRED (Chromium documented):** generous disk-fraction quotas; LRU
  eviction under pressure; installed PWAs + `persist()` favored.
- **UNVERIFIED:** low-end-device IDB write throughput and Blob handling for a
  40 MB dataset; behavior under actual storage pressure on a 32–64 GB device
  nearly full.

## 4. Defensive protocol derived from this spike

These rules are the "changes" attached to ACCEPT-WITH-CHANGES and are carried
into the ADR-004 addendum:

- **P1:** One short transaction per staged file (bytes + progress record commit
  together). No transaction spans an `await` of non-IDB work.
- **P2:** Activation is exactly one transaction on the system DB.
- **P3:** Every IDB call is wrapped; `QuotaExceededError` aborts staging and
  keeps the active dataset (never a crash).
- **P4:** Pre-stage free-space check via `navigator.storage.estimate()`; refuse
  to stage if free < 2× package size.
- **P5:** Single record ≤ 6 MB (bounds transaction memory/duration).
- **P6:** Request `navigator.storage.persist()` once after READY; never rely on
  the grant.
- **P7:** Boot-time light verification assumes storage may have vanished
  (eviction) — detection, not prevention.
- **P8:** No dataset state in the Service Worker.

## 5. Must test on physical devices before production

### iOS (iPhone, iOS 16.4 low bound + latest)
1. Fresh install → full prep of a real-size (~40 MB) package → force-quit and
   reboot → data intact, boot ≤ budget.
2. Leave unused in Safari *tab* for > 7 days vs installed PWA → confirm tab
   data evicted, installed data survives.
3. `navigator.storage.persist()` grant outcome when installed.
4. Write dataset while device storage is nearly full → observe
   QuotaExceededError handling (no crash, active preserved).
5. Kill app mid-download repeatedly → resume completes; active never partial.
6. Blob read-back: open map with ~28 MB assets → time-to-interactive.

### Android (2021 mid-range, Chrome ~110 + latest)
7. Same fresh-install/reboot cycle with 40 MB package.
8. Storage-pressure eviction simulation (devtools / fill disk) → RECOVERY path.
9. IDB write throughput for 40 MB staging; per-file transaction timing.
10. Map asset Blob read-back performance on low-end GPU/RAM.

## 6. Verdict

**ACCEPT WITH CHANGES.**

- IndexedDB is the correct primary store (structure, transactions, Blob
  support, quota scale all fit). No alternative (OPFS, SQLite-WASM,
  localStorage) is better for this workload (see ADR-004).
- The A/B layout is sound and its atomicity claims are validated at the
  design-logic level by EXP-2 (SPIKE-02).
- **Changes:** adopt defensive protocol P1–P8 (added to ADR-004).
- **Condition:** the physical-device tests in §5 are mandatory before the
  storage layer is declared production-ready. Until then the decision stands as
  the best-supported choice, with the platform-specific behaviors above
  explicitly **UNVERIFIED**, not confirmed.