feat(pwa): add managed pinned application updates

[Vyachean]

Status

Draft — the managed-update core is implemented, and the recovery architecture is now complete in the single canonical document. PR 169 is not implementation-complete until the recovery flow and its required proof are present.

Goal

Add managed pinned application updates for stable (/) and develop (/branch/develop/) with Automatic and Manual modes, immutable per-release archives, controlled activation, rollback between managed releases, and explicit worker-owned recovery.

Canonical architecture

docs/managed-pinned-updates.md is the single source of truth.

Accepted model:

• one persisted active release and at most one candidate;
• candidate phases available | ready | activating | failed;
• complete release identity: releaseNumber, appVersion, buildId, buildDate;
• browser-native Service Worker lifecycle without skipWaiting() or clients.claim();
• one short OperationQueue and one preparation/cleanup-only PreparationCoordinator;
• activation commits only after durable BOOT_OK;
• failed activation keeps the previous managed release selected;
• only one navigation owns an activation attempt;
• reconciliation effects are declarative, attempt-local, and response-ordered;
• owned requests never fall back to live deployment bytes;
• stable and develop are isolated managed channels; ordinary manual branches retain Workbox; PR previews remain non-PWA.

Recovery architecture

The worker must provide a self-contained diagnostic recovery page for:

• absent controller state;
• invalid controller state;
• unavailable controller storage;
• a valid but unrestorable active release.

State-loss recovery:

• never infers a release from caches;
• requires explicit Install latest version;
• fully validates and prepares exact latest before writing state;
• recreates initial Automatic state;
• treats latest as a new baseline without an older trusted rollback target;
• never clears user data.

Known-active recovery:

• Retry reattempts exact active restoration;
• exact latest equal to active restores that release without changing lifecycle state;
• strictly newer latest becomes ready candidate and passes the ordinary clean-launch and BOOT_OK activation flow;
• older latest, conflicting identity, and superseding ready/activating are forbidden.

Diagnostics use stable allowlisted categories only. Raw state, exception messages, stack traces, paths, tokens, and user content are forbidden. Recovery commands use the existing 120-second long-operation semantics and remain idempotent under retries and concurrent windows.

Initial Workbox transition

legacy Workbox /sw.js
→ verified managed release 1 becomes the initial managed baseline
→ full rollback guarantees begin with managed release 2

Release 1 and any later state-loss recovery baseline must contain no irreversible user-data migration. If such a baseline cannot finish boot, navigation reconciliation must still be able to discover and activate a corrected newer release.

Remaining before merge

1. Implement the recovery section of docs/managed-pinned-updates.md without changing valid-state update, activation, publisher, or user-data ownership.
2. Add unit, worker, browser, accessibility, concurrency, timeout, and product-data preservation proof required by the architecture.
3. Run on one unchanged final workspace:

pnpm verify --full --only managed-updates
pnpm verify:release

4. GitHub verify is green on the exact final head.
5. Final complete resulting-diff review finds no blocker.
6. Operator UI/accessibility acceptance covers settings, notifications, activation, rollback, and both recovery modes.
7. Mark the PR ready only after those checks.

Merge

Target: develop.

Method: squash merge after final approval.

[github-actions]

Preview deployment

• Application: https://mioframe.github.io/pr/169/
• Storybook: https://mioframe.github.io/pr/169/storybook/

This comment is updated automatically on every push to this PR.