avi/Lumen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Stage 1: project foundation (strict TS, lint boundaries B-1..B-7, directory structure, CI, boundary tests)

Browse source 
- dedicated git repo at /home/avi/Projects/Lumen (main)
- TypeScript strict (target ES2022, bundler, exactOptionalPropertyTypes, noUncheckedIndexedAccess)
- ESLint 9 + typescript-eslint strictTypeChecked + eslint-plugin-boundaries for B-1..B-7, no-restricted-globals/syntax for B-1/B-7
- Prettier 3.5
- Structure per IMPLEMENTATION-CONTRACT.md §4 (src/platform/idb|cache|sw, storage, data, sync/{transport,verifier}, domain/{emergency,schedule,map,festival,readiness,clock,favorites}, ui/{components,views,router,render}, app, emergency-baseline, assets, public, content, pipeline, tests, scripts)
- CI: .github/workflows/ci.yml (typecheck + lint + format + test)
- Boundary tests: tests/unit/boundaries.test.ts (4 tests) + scripts/check-boundaries.ts
- No feature code, no PWA/IDB/sync/mesh/accounts per contract Stage 1
This commit is contained in:
Lumen Stage1 2026-08-30 23:25:35 -05:00
commit c0bfd413ff
100 changed files with 9863 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

158
ASSUMPTIONS-AND-OPEN-QUESTIONS.md Normal file
View file

@ -0,0 +1,158 @@
# Lumen — Assumptions & Open Questions (Architecture Phase 1)
Companion to `ARCHITECTURE-DESIGN.md` and `ARCHITECTURE-DECISIONS.md`.
IDs carrying over from `DISCOVERY.md` keep their original IDs (`A-xx`,
`OQ-xx`); new items use `AQ-xx`. Status column: **Held** (working
assumption), **Validated** (evidence obtained), **Proposed** (needs a named
validation step before commitment).
---
## 1. Product Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| A-01 | Single-event V1; package keyed by edition so multi-event is a cheap later extension. | Held | DISCOVERY §7; ADR-005 edition field. |
| A-02 | Attendees 300–500; schedule ≤ ~1k events; total dataset ≤ 40 MB target / 50 MB ceiling. | Proposed (validation: pipeline gates defined, real-content proof pending) | Budgets enforced in pipeline with 5 gates (`SPIKE-04:189`, ARCH §10.6); validated at schema level in SPIKE-04; real-content dry run (AQ-19) remains. ARCHITECTURE-VALIDATION.md §7: YELLOW (content-dependent). |
| A-03 | English only; strings live in data, not code. | Held | i18n deferred (DD-6). |
| AMB-11 | Lost-person feature = informational procedure, not an active reunification workflow. | Held | DISCOVERY §8; revisit only on organizer demand. |
| AMB-12 | App keeps working post-festival on last dataset. | Held | Cheap and harmless. |
| AQ-01 | Default landing experience after first install is a Home with the four destinations and an explicit "Get festival data" preparation action (no forced onboarding wizard). | Proposed | Validate with first UX pass; low risk. |
| AQ-02 | Favorites are the only personalization in V1 (no notes, no custom ordering). | Held | Simplicity; DD-4 covers export later. |
| AQ-03 | The app is free to attendees with no paywall/gating of any kind. | Held | Core-promise framing; flag if organizers disagree (non-blocking). |
## 2. Technical Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| AQ-04 | IndexedDB on baseline iOS/Android is reliable enough for A/B slot use (transactions, Blobs, near-quota writes). | Validated (design-logic) / Proposed (device) | SPIKE-01 + SPIKE-02 16/16 PASS validate design-logic (spec CONFIRMED, P1–P8, F-1…F-4); physical-device matrix (`SPIKE-01:159`) remains for iOS jetsam atomicity, quota-near-full writes, Blob read-back on D1–D4. ARCHITECTURE-VALIDATION.md §7 YELLOW. |
| AQ-05 | A thin internal IDB wrapper suffices; no external DB library needed. | Validated (design-logic) / Proposed (implementation proof) | SPIKE-01 P1–P8 fit; wrapper friction not yet observed; confirm during early implementation. |
| AQ-06 | Bundled audited pure-JS Ed25519 verifier of a few KB is acceptable and auditable. | Proposed | Audit + bundle-budget check still required (ADR-013 YELLOW, ARCHITECTURE-VALIDATION.md §7); choice itself (pure-JS over WebCrypto Ed25519) validated by TQ-9. |
| AQ-07 | WebCrypto SHA-256 is available on all baseline devices. | Validated (high confidence) | Long-standing baseline API on iOS 16+/Chrome; confirm in device spike for completeness. |
| AQ-08 | Intl IANA timezone rendering for the festival zone works on baseline devices incl. DST edge behavior. | Validated (design-logic, V8/ICU) / Proposed (JSC device) | SPIKE-08 24/24 PASS on V8/ICU (ECMA-402); JSC parity on iOS 16.4 low-bound + latest + low-end Android remains UNVERIFIED queued for device matrix (`SPIKE-08:152`). F-3/F-4 incorporated into ADR-009. |
| AQ-09 | Page-context (document) downloads with per-file resume are more robust than SW-driven downloads on iOS. | Held | DISCOVERY PW-6; architecture codifies as C-21; confirmed-by-design, low residual risk. |
| AQ-10 | Total app JS ≤ 150 KB gz is achievable with vanilla TS at this feature surface. | Held | ADR-003; CI budget gate will prove it. |
| AQ-11 | Map base art fits ≤2 WebP levels within 28 MB at legible quality (overview ≤1600 px, detail ≤3072 px, total decoded ≤~35 MB). | Validated (design with budget) / Proposed (real art) | SPIKE-03 memory analysis proves budgets fit with margin (F-1, F-2, F-4); real art delivery (OQ-6, AQ-19) and device decode/fps remain UNVERIFIED (`SPIKE-03:116`). |
| AQ-12 | Build tooling can emit a precache manifest of hashed shell assets deterministically. | Validated (high confidence) | Standard capability of mainstream bundlers. |
| AQ-13 | One CDN origin can serve staging + production as separate origins/subdomains with independent storage. | Held | Origin-keyed storage makes this automatic (ADR-014). |
## 3. Browser Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| A-06 | Baseline: iOS Safari 16.4+, Android Chrome ~110+; older degrades to fallback page. | Held | DISCOVERY; ARCH §25. |
| B-01 | Installed home-screen PWAs on iOS are exempt from the 7-day ITP storage cap. | Validated (2026 sources) | WebKit policy; still must be confirmed on our test devices in SPIKE-1. |
| B-02 | iOS grants `navigator.storage.persist()` favorably to installed PWAs. | Held (heuristic) | WebKit grants by heuristic; never relied upon (ARCH §9.3). |
| B-03 | Eviction, when it happens, removes all origin storage at once (IDB + caches + SW registration). | Validated (platform docs) | Drives boot-verification detection design. |
| B-04 | Android Chrome auto-grants persistence for installed PWAs and has no 7-day cap. | Validated (high confidence) | Chrome policy. |
| B-05 | `beforeinstallprompt` exists on Android Chrome; iOS requires manual coach. | Validated | Drives install UX (ADR-002). |
| B-06 | Background Sync / Periodic Sync unavailable on iOS; nothing may depend on background execution anywhere. | Validated | C-19. |
| B-07 | Private browsing / "block all website data" modes make storage unavailable but do not crash guarded code. | Validated (design) / Proposed (device) | Guarded code + BASELINE_ONLY path designed (`ARCH §9.4`, `SPIKE-05:68`); must be exercised on D1–D4 device matrix (ARCHITECTURE-VALIDATION.md §4 T11). |
| B-08 | `tel:` links work from standalone PWA on both platforms. | Validated (design) / Proposed (device) | Standard + data-driven numbers (`SPIKE-06:81`); must be verified on D1/D2 standalone + D3/D4 (ARCHITECTURE-VALIDATION.md §4 T19, `SPIKE-01:171`). |
| B-09 | Service worker precache survives phone reboot on both platforms. | Validated (high confidence) | Still included in device matrix. |
| B-10 | HTTP response `Date` headers from the CDN are accurate enough to serve as the clock-offset source. | Held | CDN edge clocks are NTP-synced; sanity window guards (ADR-009). |
| B-11 | EU iOS region differences (push, home-screen behavior) do not affect our install/storage paths. | Held (monitor) | Push not used; install path is standard Add-to-Home-Screen. |
## 4. Festival-Operations Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| A-05 | Attendees have internet before the festival for install + prep. | Held (flagged) | Highest-risk assumption (RK-2); OQ-3 contingency. |
| A-16 | Organizers accept dynamic emergency updates require the device to come online. | Held | Runbook + physical channels. |
| O-01 | One designated human publisher exists for festival data, with a deputy. | Proposed | Required by ADR-005/014 ops model; confirm (AQ-16 below). |
| O-02 | Emergency content has a named approver (sign-off gate) before any publish. | Proposed | DISCOVERY A-08/OQ-2/OQ-7; confirm authority (AQ-17). |
| O-03 | Organizers will run pre-festival distribution (emails/QR/posters) and can state install steps. | Proposed | Product/ops plan; architecture provides the assets (coach screens, QR targets). |
| O-04 | Organizer connectivity during the festival is poor; they publish updates from wherever they find connectivity. | Held | Drives static/pull design (A-17, AMB-4). |
| O-05 | Physical redundancy (PA, signage, staff) is the urgent-emergency channel; the app is information access, not an alerting system. | Held | Liability-safe framing (DISCOVERY EM-7). |
| O-06 | A schema-freeze window (no breaking content changes) of ~7 days before the festival is acceptable. | Proposed | Runbook rule ARCH §18.6; confirm with organizers. |
## 5. Data-Source Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| A-04 | Organizers can supply schedule, map art, POIs, emergency info, and general info digitally. | Proposed | Intake templates to be issued; confirm with samples (OQ-6). |
| D-01 | Schedule arrives as rows with stable identifiers or enough structure for the pipeline to mint stable IDs once. | Proposed | Contractual for favorites (ADR-005); pipeline can mint + persist ID mapping if source lacks IDs (AQ-20). |
| D-02 | Map art arrives as raster image(s) with known pixel dimensions; POIs can be located on them. | Proposed | Matches ADR-008; if only vector/GIS exists, revisit representation (DD-9). |
| D-03 | Emergency contact values (numbers, locations, coordinates) are provided and stay valid through the event. | Proposed | Sign-off gate O-02; provenance labels at runtime. |
| D-04 | Content volume stays within budgets (≤1k events, ≤200 POIs, ≤30 info blocks). | Proposed | Pipeline gates reject overage; raise budgets by ADR amendment if genuinely needed. |
| D-05 | All times authors provide are expressible in the festival's single IANA zone. | Held | A-10; multi-zone venues would require ADR-009 amendment. |
| D-06 | Artist/event imagery is optional; if provided it fits the asset budget. | Held | Photo kind budgeted in assets.json; drop first if over budget. |
## 6. Security Assumptions
| ID | Assumption | Status | Basis / Notes |
|----|------------|--------|---------------|
| S-01 | The signing key can be kept offline with a documented custodian; signing happens only via the pipeline machine during publish. | Proposed | Key custody plan needed (AQ-21); ADR-013 depends on it. |
| S-02 | The CDN/hosting account is protected by the organizer's standard credential hygiene (2FA, limited publishers). | Proposed | Ops requirement; out of app scope. |
| S-03 | No PII is ever present in festival content, diagnostics, or user state beyond a favorite-list of public event IDs. | Held | Data-minimization posture (ADR-013). |
| S-04 | Attendees' devices are treated as untrusted-but-self-protecting: local tampering only harms that user; no multi-user device scenario is designed for. | Held | TH-8 analysis. |
| S-05 | Emergency numbers may differ by jurisdiction; the primary number is data-driven (A-14). | Held | Confirm jurisdiction (OQ-2 → AQ-22). |
---
## 7. Open Questions
Columns: **Blocks?** = does this block implementation start (as opposed to
blocking only content, deployment, or a specific subsystem)?
| ID | Question | Why it matters | Current assumption | Recommended default | Impact if wrong | How it can be validated | Blocks impl.? |
|----|----------|----------------|--------------------|---------------------|-----------------|--------------------------|---------------|
| OQ-1 | Festival name, location, dates, daily hours, IANA timezone? | Manifest metadata, time model, schedule day keys | Placeholder values in staging edition | Ask organizers now; encode in staging manifest | Wrong timezone breaks Now/Next display; wrong dates break sanity window | Organizer confirmation + pipeline validation fixture | No (staging placeholders suffice) |
| OQ-2 | Exact emergency contacts, muster points, venue address/GPS, procedures owner? | Emergency content is safety-critical | Data-driven fields with 911 default | Issue emergency content sheet with sign-off gate (O-02) | Wrong emergency data = worst-case product failure | Sign-off gate + review of sheet + device render test | No (blocks Emergency *content*, not scaffolding) |
| OQ-3 | Pre-festival distribution channels + on-site connectivity for a bootstrap station? | Bootstrap risk RK-2 | Pre-arrival online prep | QR campaign + install-guide asset; on-site station only if connectivity exists | Unprepared attendees → product promise degrades | Organizer marketing plan + site survey | No |
| OQ-4 | Who runs content updates during the festival, on what device? | Publish UX requirements | Publisher on laptop/phone via repo pipeline | Minimal publisher flow documented in runbook | Slow/failed corrections mid-festival | Dry-run publish exercise | No |
| OQ-5 | Existing domain/brand/hosting control? | Origin selection is hard to reverse (storage origin-keyed) | New dedicated subdomain | Decide production origin before first public staging link | Origin change strands installed users' data | Organizer DNS/hosting inventory | No (dev proceeds on provisional origin) |
| OQ-6 | What map artifacts can organizers actually produce? | Map architecture input (ADR-008 Proposed) | Illustrated raster art | Request raster art at ≥2048px long edge + POI list | Representation revisit (SVG path or tile-split) | Sample art delivery; SPIKE-3 with real art | No (placeholder art unblocks dev) |
| OQ-7 | Legal/liability review for emergency wording? | Emergency procedures text | Plain informational framing | Legal review of procedure strings before first production publish | Rework of emergency content late | Organizer legal review | No (content gate) |
| OQ-8 | Budget for hosting/CDN or free-tier only? | Provider selection (AQ-18) | Free-tier-capable static host | Pick provider satisfying HTTPS + custom origin + adequate bandwidth | Provider swap pre-launch (cheap before users) | Organizer budget confirmation | No |
| OQ-9 | Audience OS version distribution? | Baseline policy A-06 | iOS 16.4+/Chrome 110+ baseline | Ticketing survey if available | Baseline shift (likely downward → more degradation paths) | Survey or accept assumption | No |
| OQ-10 | Post-festival app lifetime expectations? | Content staleness UX | Keeps working on last dataset | "Festival ended" informational state post end-date | Minor UX rework | Organizer preference | No |
| OQ-11 | Simultaneous programming across stages? | Now/Next conflict UX | Yes | Per-stage Now + global Up Next with overlap handling | Simpler UI suffices | Schedule sample | No |
| OQ-12 | Quiet hours / overnight schedule relevance? | Day model, all-night rendering | Standard day keys | Render all events chronologically | None significant | Schedule sample | No |
| AQ-14 | Which static hosting provider? (custom domain, HTTPS, cache-header control, bandwidth for ~500 devices × ~40 MB prep + shell updates) | Deployment ADR-014 provider Proposed | Any mainstream static CDN | Decide before first external staging share; keep origin stable | Pre-user origin change is cheap; post-user is not | Provider evaluation vs requirements list | No |
| AQ-15 | Repo/VCS setup: dedicated repo for Lumen inside/next to the parent directory structure? | Development hygiene | New dedicated git repo at /home/avi/Projects/Lumen | Init dedicated repo at implementation start | Trivial to fix later | Owner preference | No |
| AQ-16 | Publisher + deputy identities and credential path? | ADR-014 ops | Named organizer + deputy | Define before first production publish | Publishing bottleneck mid-festival | Organizer staffing | No (blocks production publishing only) |
| AQ-17 | Emergency content approver identity/authority? | Sign-off gate O-02 | Organizer safety lead | Name approver before first emergency content publish | Late legal/safety rework | Organizer staffing | No (content gate) |
| AQ-18 | Production origin name (e.g., app.<festival>.tld)? | Storage is origin-keyed; hard to reverse | Provisional staging origin now; production chosen once | Choose deliberately before public launch | Origin migration strands device data | OQ-5 resolution | No (but must settle pre-launch) |
| AQ-19 | Realistic map art size/quality at 2 levels? | ADR-008 Proposed → Accepted; budgets | Fits ≤28 MB | Measure with real art; else drop detail level or re-split | Map budget amendment or representation tweak | SPIKE-3 + real art | No |
| AQ-20 | Does the source schedule have stable IDs, or must the pipeline mint+persist them? | Favorites stability across updates | Pipeline can mint via deterministic key (e.g., normalized title+stage+start) persisted in an ID map | Mint + persist mapping in content repo | ID churn breaks favorites | Inspect source schedule sample | No |
| AQ-21 | Signing key custody: who, where (offline), backup, rotation drill? | ADR-013 ops viability | Custodian + sealed backup | Written custody note + one rotation drill pre-festival | Key loss ⇒ shell update to rotate (runbook) | Ops exercise | No (blocks production signing) |
| AQ-22 | Jurisdiction/emergency number confirmation (911 vs other)? | A-14/S-05 | 911 default, data-driven | Confirm with organizers/venue | Wrong default number | OQ-2 answer | No |
| AQ-23 | Is a staging "dry-run festival" (test edition + test devices in the field) feasible before the real event? | Catches device/eviction/ops surprises | Yes, strongly recommended | Schedule a full dress rehearsal | Surprises surface during the real festival | Organizer planning | No (strongly advised) |
| AQ-24 | Device availability for the test matrix (iPhone iOS 16.4-ish, low-end Android 2021, latest of each)? | ARCH §26 feasibility | Borrow/cheap second-hand devices | Acquire before implementation mid-phase | Real-device gaps in verification | Procurement | No (blocks device-matrix testing, not coding) |
| AQ-25 | Will organizers ever need a second edition/year quickly (multi-edition cadence)? | Edition lifecycle & GC policy | Single edition V1 | Keep edition switch = normal update | Multi-edition tooling later | Organizer roadmap | No |
---
## 8. Cross-Reference: What Blocks What
| Blocker | Blocks | Does NOT block |
|---------|--------|----------------|
| OQ-2 emergency content sign-off | Emergency *content* publish | App scaffolding, emergency rendering, baseline generation mechanism |
| OQ-6 map artifacts | Final map representation confirmation (SPIKE-3) | Map service code against placeholder art |
| AQ-18 production origin | Public launch | All development on provisional/staging origin |
| AQ-16/AQ-21 publisher + key custody | Production publishing | Staging pipeline (test key) |
| AQ-24 test devices | Device-matrix validation | Unit/contract/integration harness work |
| A-05 truth (pre-festival internet) | Product promise strength | Architecture itself (re-prep + baseline floor absorb the failure) |
**Nothing above blocks the start of implementation** of shell, data layer,
sync/verification, and feature modules against staging fixtures — by design.
---
## 9. Validation Plan for Proposed Assumptions
| Assumption | Validation vehicle | Phase | Status after SPIKE-01…08 (2026-08-30, ARCHITECTURE-VALIDATION.md) |
|------------|--------------------|-------|-------------------------------------------------------------------|
| AQ-04 (IDB iOS behavior) | SPIKE-1: real-device storage/eviction harness | First implementation spike | Validated design-logic (SPIKE-01 16-item analysis + SPIKE-02 16/16 PASS); device tests `SPIKE-01:159` §5 remain — YELLOW |
| AQ-05 (wrapper sufficiency) | Implementation experience + review | Early implementation | Validated design-logic (P1–P8 fit); confirm in early impl |
| AQ-06 (Ed25519 verifier) | Library audit review + bundle check + verify-on-device test | Early implementation | Still Proposed — audit + bundle gate required (ADR-013 YELLOW) |
| AQ-08 (Intl zones) | SPIKE-8 fixtures on device matrix | Early implementation | Validated 24/24 on V8/ICU (SPIKE-08); JSC parity on D1/D2 + D3 remains — YELLOW |
| AQ-11 / D-02 (map art) | SPIKE-3 bake-off with real/representative art | Early implementation | Validated with tightened caps F-1 (1600/3072/35 MB); real art + device decode/fps remain |
| B-07/B-08 (private mode, tel:) | Device matrix scripted scenarios | Mid implementation | Design validated (guarded paths, `tel:` data-driven); device verification remains (ARCHITECTURE-VALIDATION.md §4 T11/T19) |
| A-02 budgets | Pipeline gates + real content dry run | Content intake | Schema/gates validated (SPIKE-04); real content proof pending (AQ-19) |
| O-01..O-06 ops assumptions | Organizer agreements + dress rehearsal (AQ-23) | Pre-festival | Still Proposed — outside architecture; track per §8 cross-reference |
| NEW — AQ-04…11 device matrix | ARCHITECTURE-VALIDATION.md §4 (19 groups × D1–D4) | Pre-production (before festival) | BLOCKING for production; not blocking for implementation start on provisional origin |
*End of assumptions and open questions. Any change to a Held assumption or a
blocker resolution should be recorded here with date and rationale.*