pwa(updates): make service-worker upgrades transactional, multi-client safe & edit-loss-proof

[qnbs]

Parent

Part of #478 — PWA first-class excellence/hardening.

Why this matters

A PWA can update much faster than packaged native software, but that advantage becomes dangerous if a new Service Worker/app shell activates while users have dirty editors, old IndexedDB schemas, local-AI workers, or multiple tabs alive.

The differentiator should be rapid updates without sacrificing writing-session durability.

Core invariant

A PWA update may never knowingly discard acknowledged edits or create an app-code/storage-schema combination that the product has not admitted.

Do not use unconditional skipWaiting() + reload semantics as a substitute for an update protocol when dirty clients exist.

Proposed update state machine

NO_UPDATE
→ UPDATE_DISCOVERED
→ DOWNLOADED_WAITING
→ CLIENTS_ASSESSED
→ SAFE_TO_ACTIVATE | USER_ACTION_REQUIRED
→ ACTIVATING
→ RELOADING/RECONNECTING
→ VERIFIED
→ RECOVERY_REQUIRED (exceptional)

Persist only the minimal metadata needed for recovery/troubleshooting; the Service Worker must not become project-data authority.

Client coordination

Use clients.matchAll() plus the typed multi-context coordination layer from #480 where appropriate.

Before activation determine:

• number of live clients;
• dirty/unsaved project state;
• active storage migration;
• active backup/export critical section;
• local-AI/model download state where interruption matters;
• whether new code requires a storage migration incompatible with old clients.

A background tab must not silently force all other tabs to reload.

Update UX

Safe immediate update

If no dirty/critical state exists:

• show lightweight “Update ready”;
• allow Update now;
• optionally activate at next clean launch according to policy.

Dirty session

If acknowledged edits or critical work exist:

• clearly show update is waiting;
• offer Save & update after confirmed durable save;
• offer Later;
• never fake a successful save merely to activate.

Multiple clients

Explain when another WorldScript window is preventing activation. Coordinate rather than racing.

Schema/version compatibility

Define an app-code/storage compatibility contract.

Examples:

• current and previous shell may coexist only if schema/API compatibility allows it;
• irreversible migration cannot begin while old incompatible clients remain admitted;
• migration journal/version identifies recovery state;
• new client encountering old schema follows a tested migration path;
• old client encountering newer incompatible schema fails safely rather than writing stale structures.

Coordinate with existing IndexedDB encryption migration/journal architecture; do not create a second conflicting migration authority.

Cache strategy

Separate:

• immutable hashed build assets;
• app shell/navigation fallback;
• runtime assets;
• model artifacts (pwa(ai): turn WebGPU/worker local inference into a zero-install offline AI differentiator #483/pwa(storage): engineer a durable IDB+OPFS storage tier with persistence, quota & recovery UX #482);
• network-only AI/provider endpoints.

Never cache sensitive AI prompts/responses or credential-bearing URLs.

Large local-AI artifacts must not be invalidated merely because the app shell version changes unless compatibility requires it.

Failed update recovery

Exercise:

• missing/corrupt new asset;
• activation succeeds but navigation fails;
• user goes offline between download and activation;
• storage migration fails;
• stale waiting worker;
• old cache remains;
• browser kills a client mid-update.

Recovery should prefer a known-valid cached shell when safe, or provide a deterministic recovery screen that preserves local project data.

Do not recommend “clear site data” before export/recovery options.

Deployment parity

WorldScript has GitHub Pages and Vercel surfaces. Validate:

• correct Service Worker scope/base path;
• update discovery on both;
• asset URL/base-path behavior;
• navigation fallback;
• no deployment-specific stale-cache trap;
• version/build identity visible for diagnostics.

CI / automated evidence

Build a deterministic browser test harness for:

1. install version N;
2. create/edit project and cross save boundary;
3. publish/simulate version N+1;
4. discover waiting worker;
5. exercise dirty and clean clients;
6. activate;
7. verify edits and project reopen;
8. repeat with multiple tabs;
9. repeat offline during activation;
10. repeat with a representative schema migration fixture.

Also statically test generated precache composition/policies where practical.

Acceptance criteria

• Explicit PWA update state machine exists.
• Dirty clients block unsafe activation/reload.
• Multiple clients coordinate activation.
• App-code/storage-schema compatibility is explicit.
• Provider/AI sensitive traffic is never runtime-cached.
• Large model artifacts have independent lifecycle from app-shell caches.
• Failed/interrupted updates preserve recoverable project state.
• Pages and Vercel update behavior are smoke-tested.
• Automated N→N+1 lifecycle tests exist.
• User never needs destructive site-data deletion as normal update recovery.

Non-goals

• delaying every update until all tabs are closed forever;
• forcing immediate reload;
• making Service Worker the storage migration authority;
• caching AI/provider traffic for perceived offline support;
• invalidating all origin storage on each release.

[qnbs]

Architecture refinement / in-place update-state refactor — 2026-08-24

This issue should be treated as a correctness refactor of the existing PWA update path, not permission to build a second update manager.

Current seed and current risk

Existing update/install authority begins in:

• public/sw.js;
• register-sw.ts;
• current PWA update/install UI.

The current implementation calls skipWaiting() during SW install and reloads on controllerchange, with comments relying on autosave safety. That is insufficient as a final protocol for dirty editors, multiple clients, active migrations, model downloads, or incompatible schema transitions.

Required convergence

Refactor these existing paths into one authoritative update state machine. Reuse:

• app/persistenceCoordinator.ts;
• app/persistedStateFlush.ts;
• encryption migration/journal state;
• pwa(concurrency): make multi-tab editing safe with Web Locks, BroadcastChannel & lifecycle ownership #480 multi-context ownership/coordination;
• existing SW registration and update UX.

Do not keep an old automatic activation path active alongside a new coordinator.

Save semantics

If update admission requires Save & update, the save must complete according to the actual durable persistence contract. A queued/debounced/best-effort request is not enough. Failure must keep the update waiting and preserve the old valid app/session state.

App-code / storage compatibility

Define an explicit compatibility tuple/version policy rather than inferring safety from app version alone. Old and new clients may coexist only for combinations that are deliberately admitted. Irreversible migration cannot begin while an incompatible old writer remains admitted.

Cache/model independence

App-shell version changes must not automatically invalidate downloaded model artifacts or other expensive origin data unless compatibility requires it. Keep model/artifact lifecycle under #482/#483 rather than SW shell-cache naming.

Acceptance additions

• Unconditional install-time activation/reload is removed from the final dirty-client path.
• One update state machine is authoritative; legacy activation code is retired/deprecated.
• Dirty-state decision uses confirmed persistence state, not optimistic UI state.
• Migration/backup/model-download critical sections have explicit interruption policy.
• Multiple clean/dirty clients are covered deterministically.
• N→N+1 and representative storage-schema transition fixtures are tested.
• Pages/Vercel base-path and scope parity remain part of acceptance.