Eve library

Offline continuity — reviewed source findings, 8 September 2026

Guide

Revision 1

On this page

This is the twenty-slide guide’s source and delivery review. Four complete PWA/offline documentation units have reviewed teaching assignments. Primary pin: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. The cited implementation files are byte-identical at authoring baseline 85f3a7aca42b4c773d5b5e96d38b201c8b9b1dc4. This is source continuity, not deployed behavior certification.

Read in full: web public/sw.js; pwa-service-worker.ts; pwa-runtime.ts; pwa-recent-content.ts; offline-shell-routes.ts; PwaBootstrap.tsx; manifest.json; offline library types, queue, cache, retry, storage, connectivity and index; offline/src/__tests__/offline.test.ts; pwa-service-worker.test.ts. The complete policy test was also reviewed, including classifier, marker and activation cases. Product Surfaces feature PWA/offline sections and high-level-architecture offline section read; entire source files are not yet assigned as fully reviewed.

Distinct implementations#

Product Surfaces describes queueBackgroundAction and mobile behavior as leaning on @oshun/offline. The pinned web worker implements its own IndexedDB queue and fetch replay. It does not import OfflineSyncQueue. Its delete/retry rules differ materially from the reusable library. Show both implementations separately and trace actual callers before saying a surface inherits the library's semantics.

The web helper posts OSHUN_QUEUE_ACTION and returns true; no message-port ack or await of IndexedDB persistence exists. The worker persists pending-actions with auto-increment local IDs, then broadcasts pending count and registers background sync if supported. Non-GET fetches are not automatically queued. No alternative replay trigger is implemented in this worker when Background Sync is absent.

Web replay reads before deleting and fetches with credentials include. Network throw stops the drain and preserves current/following actions. 2xx deletes and increments replayed. Every 4xx deletes WITHOUT incrementing replayed, including 401/403/429; there is no dead-letter record in this implementation. 5xx retains that action but continues to later actions; no per-object ordering fence, exponential backoff or retry ceiling is applied here. A network response followed by failed local deletion can repeat delivery; the caller/server's idempotency contract must settle duplicates. Pending zero alone is not proof all writes succeeded. The generic SW status contains only replayed/pending counts.

Install, update and restore#

Manifest is Lilith, four shortcuts (Tara, Nyx, Arete, Nisaba), standalone start /?surface=pwa; two screenshot labels retain stale six-room wording. Release admission follows brand/registry consumers, not labels.

Registration guard retries after failure, handles post-hydration registration, and exposes waiting workers only when another controller already controls the page. sw.js install calls skipWaiting immediately and precaches each asset best-effort. Activation deletes old oshun-* buckets, claims clients and broadcasts OSHUN_SW_UPDATE. The renderer must not teach that Keep reading prevents worker activation. PwaBootstrap's controllerchange handler avoids page reload without local or sibling-tab apply intent, and turns the prompt ready instead.

The prompt is deferred until cookie consent has a decision. Dismissal suppresses that update token. A waiting-phase apply saves route/scroll, sets and broadcasts intent BEFORE postMessage, then uses controllerchange or a four-second reload fallback. A ready-phase apply reloads directly. Sibling-tab intent can cause this tab to reload at controllerchange; sibling scroll is not saved by that handler.

Scroll restore stores path, timestamp and positive rounded Y in sessionStorage. It accepts the same path within 60 seconds, tolerates an initial missing query without deleting the snapshot, and retries every 120 ms up to six seconds until within 16 px (clamped to available scroll height). The first restore clears the persisted snapshot; later retries use the closure. This is scroll restoration, not recovery of unsaved in-memory edits, media position or an acknowledged write.

Standalone launch normalizes/sanitizes targets, excludes public shell paths and removes surface=pwa. LocalStorage plus a 30-day SameSite=Lax cookie retain the route; updatedAt is stored but not used for expiry validation in this helper. Loading/auth and explicit current location matter: /profile is preserved, specific deep links are preserved, signed-in root/public entry may restore the saved target, signed-out entry can route through welcome?redirect. An existing welcome redirect is respected. Storage operations themselves can still throw where the write method is not caught; do not promise failure-proof persistence.

What is cached#

Fetch classifier precedence: non-GET/non-http ignored; auth/session network-only; Nisaba passage-daily/notebooks path prefixes allowlisted; every other API-shaped request passes through network; media cache-first; warmable HTML and shell navigation network-first; other .js/.css/.json or _next assets stale-while- revalidate. This is a code policy, not a claim every deployed backend is safe or every endpoint current. Prefix matching includes descendants.

Nisaba cached reads return immediately while network revalidates, except that a Date header older than 24 hours makes them await network. No network response then gives 503 NISABA_OFFLINE_CACHE_EXPIRED; no cached item/network gives 503 NISABA_OFFLINE_CACHE_MISS. A missing/invalid Date does not trip the age branch; at exactly 24 hours the comparison is not expired. Network error HTTP responses are returned as responses; only thrown fetch/cache-chain errors become null. Do not teach a guaranteed 24-hour maximum without that qualification.

Shell navigation uses successful online response, then on thrown failure exact cached request (ignoreVary), then cached home with requested-URL marker and static recovery controls, then minimal offline HTML with status 200. Non-2xx HTTP responses return directly instead of entering this fallback. Exact-cache returns do not have the home-fallback marker injected. Home substitution does not establish that the requested object is available.

Media has a 200-entry cap; BFF allowlist 50; other runtime assets 100. Cache keys are deleted in cache.keys order; there is no read-time touch implementing true LRU. Static shell cache has no matching entry cap in this code. No fabricated cache-hit, storage-byte or performance measurements should appear on slides.

Recent content stores up to eight normalized path records, with title/summary, source and cachedAt; bootstrap records a route BEFORE warm success is known. Fallback merges those with Nisaba recent passages, sorts and dedupes by path; up to four recent routes contribute to warming alongside four core routes and the current eligible route. The warm helper returns a successful non-redirect HTTP count, not cache inspection. Bootstrap's ready flag means count > 0, not that every route/asset or recent record is recoverable. Repeating the same route signature reuses the previous warm result.

Shared queue and storage limits#

OfflineCache JSON-stores value, updatedAt and optional expiresAt. GET deletes expired entries; stats counts them without deleting. Missing TTL means no expiry. MemoryOfflineStorage is a Map; cross-process persistence requires another adapter. Cache/queue constructors accept storage, clock and (queue) ID seams.

OfflineSyncQueue stores whole active array at one key, dead letters at another. No transaction/lock wraps concurrent enqueue/process or cross-key moves. A fulfilled handler removes an item; caller decides what counts as fulfillment. Default retry is four total failed attempts with 1 s, 2 s, 4 s scheduled delays; formula grows by 2 up to 30 s under longer custom policies. Unclassified errors retry; caller classifier may send deterministic failures directly to dead letter. Dead letters retain whole item, message, attempts, reason and timestamp.

Within a process() pass, deferred/retry/dead items block later equal objectKeys. Keyless work is independent. A retry stays at its prior queue position and continues blocking next passes until due. Dead letters are not consulted to rebuild blockedKeys in a later pass. replayDeadLetters appends to active queue, resets attempts/due time, retains original id and createdAt, then removes the selected dead letters; it does not restore prior relative order. Reusing an ID only enables server idempotency when the actual transport sends and the server enforces it. Do not state global ordering or atomic exactly-once durability.

process saves the next active queue BEFORE saving new dead letters. Replay saves the active queue BEFORE removing dead letters. Failure/crash between those writes can lose a newly failed record or leave replayed copies in both stores. The tested happy persistence path remains useful; it is not a transaction or crash-atomic proof. canProcessQueue is a separate caller utility: online required, metered denied unless allowMetered true; process itself does not invoke it.

Member-data clearing#

Client marks that a member session may have cached bytes. On member-to-anonymous clear it posts OSHUN_CLEAR_MEMBER_DATA if a controller and marker exist, then removes the marker before any worker acknowledgement. Inaccessible localStorage reads assume a purge is needed. Pure anonymous transitions without a marker skip the purge to preserve public cached shell data.

Worker uses allSettled to delete BFF, static and media buckets and queued actions, then re-precaches public install routes. Runtime assets are retained. Individual purge failures are swallowed by allSettled and no result ack returns. This does not clear every localStorage/Iris/third-party cache; each owner needs its own cleanup. Cached authenticated HTML and media still demand shared-device review.

Authoring package · verified for stated technical scope#

Purpose: teach product, design and engineering readers how a member returns to reading, understands cached evidence, and follows a queued action to its owner. Prerequisite: v1-web-pwa. Home: Products → Oshun V1 → V1.0 → Member experience, after account controls. Guide ID: member-offline-continuity. The twenty-slide manuscript is in content/30-offline-continuity.json. The final narrated HTML and PDF have passed the affected technical review. The full V1 objective remains active in v1-completion.md.

Visual thesis: a calm paper field guide with readable native diagrams, explicit branch labels and terracotta relationships. Compare equal outcomes as peers; never highlight an ordinal row by default. Field specimens contain actual names without invented member records. Dense policies receive their own readable table.

Content plan: open with a reading return; explain distinct runtime owners, installation and update intent, route restoration, fetch precedence, freshness, document fallback, recent warming and cache limits; then follow web submission and replay before explaining library storage, records, retries, ordering, replay and crash boundaries. Close with session clearing and the original reader task.

Interaction thesis: preserve source disclosure, reduced-motion-aware navigation and workspace transitions. Diagrams and complete explanation remain usable in static PDF and mobile reading order. No shared renderer, CSS or player changes are planned.

Deliverables: canonical content and catalog membership after candidate review; source-unit assignments only for complete reviewed units; focused review config, HTML, twenty new recordings, PDF, catalog duration updates and a retained receipt. Preserve all 600 upstream tracks and all 61 pre-existing guide HTML files against the immutable baseline. Scope supporting code claims separately from full V1 source coverage. The four feature/architecture PWA and offline-substrate units have reviewed assignments, with their old manifest, common-queue and flush claims explicitly reconciled against code.

Acceptance: each slide explains one useful mechanism and has three developed paragraphs and three review questions. Inspect all rendered slides; keep age, rejection, missing acknowledgement and storage failure qualifications visible. Use pinned-source characterization fixtures for replay/status, expiry and queue ordering/crash boundaries. These fixtures do not certify a deployed device.

Verification: build the draft and run eve-oshun-deck.mjs --draft --draft-id v1-offline-continuity --layout-only; inspect actual desktop/mobile captures. Then run the configured guide review with four standalone and three embedded views, enlarged text, axe and deliberately removed evidence. Run center review with --guides member-offline-continuity --base-revision 949d68e86ef6477118d446e7f5c9d2e0b09aa4dc, the source-map PDF checker, relevant presentation unit tests, lint/format/build/coverage freshness and encoded narration verification. Export and inspect the exact final PDF. Use Python 3.11, one CPU narration worker and supervised serial expensive checks on this host.

Reader tasks: distinguish worker activation from page reload; interpret an unknown cache age; explain pending zero after rejection; follow same-object retry ordering and dead-letter replay; identify the missing clear acknowledgement. No human reader, normal-speed listening or new live-device session has yet been performed. Do not count automated or model optical review as that acceptance.

Recovery and publication: isolate work on the existing V1 task branch, stop only owned jobs, preserve valid partial audio and retain failures. Keep unpublished content in draft until candidate review; never advertise missing deliverables as ready. Commit with normal hooks and push to origin/main after applicable technical checks pass. Publication of this increment does not close the complete V1 task.

Candidate findings and corrections#

The twenty-slide desktop sequence and native-size slides 3, 7, 11 and 19 were inspected by the model after the draft browser/PDF pass. The web-enqueue return arrow originally combined pending-status broadcast with sync registration even though the latter goes to the browser, not the calling feature. Its final label now names only the pending-count broadcast; narration explains registration separately. Owner descriptions were shortened to preserve spacing between columns. The three ownership accents follow worker activation, stored action and unacknowledged client cleanup respectively: second, third and first columns. The first draft build rejected an undeclared owner emphasis; the corrected briefs give each accent its actual responsibility. No shared renderer changes.

Twelve pinned-source VM characterization tests passed for HTTP replay, cache-age edge cases, scoped clearing, library retry/order/replay and storage failure. These do not run browser IndexedDB or a deployed adapter. The delivery receipt records final rendered capture, PDF, narration and publication inputs.

The first final guide review caught recovery-state names that were present only in metadata, while the visible headings used different phrases. The document fallback headings now explicitly name network failure, exact cache miss and home cache miss. The complete final matrix is rerun against those corrected labels; narration text is unchanged. The failed report remains in the receipt.

Delivery checkpoint before integration#

The final candidate has 146 passing visual/accessibility checks and all three lost-content controls rejected. The center completed all fourteen focused navigation/playback/PDF checks, preserving 61 prior guide HTML files and four shared UI files byte for byte. All 597 prior recordings are unchanged; the twenty new tracks add 1,819.373 seconds. Model optical review inspected every final desktop slide, the full PDF sequence, native PDF pages 6, 7, 11 and 14, and mobile freshness, queue handoff and record specimens. Normal-speed human listening and willing-reader acceptance remain unperformed.

The final browser run binds formatted canonical JSON. Its rendered HTML and all 80 capture hashes match the visually inspected prior passing run exactly; the prior report remains retained with that boundary. The original coverage attempt was correctly rejected where supporting slides cited code but did not cite the assigned documentation unit. The final citations and assembled fingerprints now name the governing unit explicitly, and all four assignments pass.

Parallel Eve computer-use provider work at a0ab808324 changes no presentation files or cited offline implementations. Integrate it when publishing this package. The broader V1 review continues with Tara practice/session and workbench depth.

Integration after the remote presentation update#

The first push was rejected because origin/main advanced to 949d68e86ef6477118d446e7f5c9d2e0b09aa4dc, including three Eve operating-state slides and their reviewed assignment. Preserve that published guide, audio and PDF. The canonical catalog merges both additions; generated catalog, coverage, duration and narration metadata are rebuilt from those combined inputs. The offline guide HTML and twenty recordings remain unchanged. The final center baseline is this integration commit, containing 600 prior recordings and 61 prior guide HTML files; the original authoring baseline remains 85f3a7. Integration-specific center, browser-input, assignment and changed-contract checks bind the combined 620-slide library. Pre-integration reports retain their original scope and hashes in the receipt’s attempts directory.

The integration check preserves sixty browser captures and every PDF page render exactly. Only the twenty expanded sidebar captures change their Eve/library duration text; the offline slide region remains identical. The updated sidebar was inspected. The exact approved-addition set in the V2 rollback preservation test now includes the twenty reviewed offline slide IDs while retaining equality checks for all 597 baseline slide and narration records. All 31 affected integration tests pass after that explicit catalog update.