Files
Project-SDE-WP-Suite/docs/waves/wave-14.md

183 lines
12 KiB
Markdown

# Wave 14: The outbox keeps every change, and the sign-in limit cannot destroy it
**Items:** `D26`, `D27`, `BL-061` (`B5` is context only: its wording rules stay, and this wave does not widen it)
**Depends on:** wave 13 merged (it is, except T13.1). Independent of wave 15.
**Decision record:** `docs/waves/decisions-2026-10-17.md` (D26 and D27 are **proposed**; they need Matt's OK, see "Open questions")
**Unblocks:** `T13.1` (idle timeout). T13.1 must not reach `main` before T14.1 and T14.2 are done.
**Branch rule:** one task for each pull request. Cut each branch from `main`.
## Why this wave exists
The outbox in `html/project-data.js` queues each save in `localStorage` and sends it later. A crew in the field
can work with no signal, and the changes go out when the network returns. The code was checked on 2026-10-17
against the 8 hour session limit (D25) and the idle timeout that T13.1 adds. It has four faults that lose or hide
work. They are small now. The idle timeout would make them common.
| # | Fault | Where | Result |
|---|---|---|---|
| 1 | A `401` (session ended) or `403` is treated like any other `4xx`. The change is marked **dead** and is never sent again. | `project-data.js`, `flush()` | A crew that works past the session limit, or past an idle timeout, comes back online and every queued change is rejected for good. The badge says "rejected by the project". The change is not lost from the device, but nothing can send it. |
| 2 | `qWrite()` swallows a storage error. | `project-data.js`, `qWrite()` | If the device storage is full, a change is **not queued and nobody is told**. |
| 3 | The queue belongs to the browser, not to a person. A queued change has no owner. | `project-data.js`, `enqueue()` | On a shared device, person B signs in and the queue of person A is sent under the name of person B. |
| 4 | The offline sign-in window is a fixed 12 hours in the browser. | `auth-guard.js`, around line 183 | It does not follow `AUTH_SESSION_HOURS` (8 since D25). It also slides: every online page load resets it. The browser and the server disagree about when the session ends. |
Also: the sync badge sits over page controls (`BL-061`) and cannot be used with a keyboard or a finger. The
badge is a `div` with `pointer-events:none`. A badge that must ask a person to sign in again needs a real link or button.
## Rules for this wave
- Do not use a `div` with `onclick` (`CLAUDE.md`, accessibility). The sign-in action is an `<a>` or a `<button>`.
- Status text goes in an `aria-live` region. The badge already has `role="status"`. Keep it.
- Server work is needed for T14.2 (one new field). Do not store session data in `localStorage` as the source of truth.
- Colors, spacing and type come from the shared tokens. Do not add a raw hex value to a page stylesheet.
- Frontend checks: run the app on a throwaway SQLite database, check at 390 px and 1440 px, capture before and after
screenshots, run the smoke test (use `http://127.0.0.1`, see `BL-071`).
- Do not fix other problems you see. Log them in `docs/waves/backlog.md`.
---
### T14.1: D26 a sign-in problem never destroys a queued change
- **Items:** `D26`
- **Depends on:** nothing (first task)
- **Blocks:** T14.2, T14.3, T13.1
- **Surface:** `html/`
- **Files:** `html/project-data.js`, `html/auth-guard.js`, a new `tests/outbox_check.py`
**Do:**
1. In `flush()`, treat `401` as **held**, not dead. Stop the run. Do not add to `tries`. Do not mark any change
dead. Keep the whole queue in its order. Set a "held for sign-in" state that the badge can read through
`ProjectData.syncStatus()` (add a field, for example `held: true`).
2. Keep `403` as a permanent refusal, but say why in the reason text ("you no longer have access to this project").
Keep `409` (archived project) and the other `4xx` as they are.
3. When the person signs in again (the page loads with a good session, or `wp-auth-ready` fires), clear the held
state and flush at once. The `online` event, the 20 second timer and the tab-focus trigger must **not** clear it
early: a held queue sends only after a good session check.
4. Make `qWrite()` return `true` or `false`. If it fails, `enqueue()` must tell the caller and raise the
`device full` state. The change stays in the page memory and the form stays open. The badge says the change is
**not saved on this device**. Do not drop it silently.
5. Give each queued change an `owner` (the signed-in username) when it is queued. At flush time, if `WP_USER` is not the
owner, hold that change and name the owner in the message. Do not send it. Do not discard it. (See open question 1.)
6. Make sure `auth-guard.js` does not delete the queue when it sends a person to `login.html` after a `401`. It must
keep `wp_sync_outbox_v1`.
**Done when:**
- [ ] a queue of N changes meets a `401`: all N are still in the queue, none is dead, `tries` did not change, and the badge state is "held"
- [ ] after a good sign-in, all N changes reach the server in their original order, and the queue is empty
- [ ] a `403` marks only that change dead, with a reason that names the cause
- [ ] a full device store (a forced `QuotaExceededError`) is reported to the caller and the badge. No change disappears silently
- [ ] a change queued by person A is not sent when person B is signed in; it is sent after A signs in
- [ ] `tests/outbox_check.py` covers each case above and fails when `flush()` is put back to the old rule (a mutation check)
- [ ] the full suite passes, at 390 px and 1440 px
---
### T14.2: D27 the offline sign-in window follows the server
- **Items:** `D27`
- **Depends on:** T14.1
- **Blocks:** T13.1
- **Surface:** `server/` and `html/`
- **Files:** `server/app.py` (`whoami()`), `html/auth-guard.js`, `html/wp-format.js` (line 223 writes the cache), tests
**Do:**
1. Add one field to `/api/auth/me`: `session_expires_at` (the `exp` claim of the session, as a UTC time). Read the claim from the
token that `get_current_user` already validated. Do not add a database column. When T13.1 lands, this field is the
current `exp` and moves with each refresh.
2. In `auth-guard.js`, store `session_expires_at` in `wp_auth_cache`. Replace the fixed `12 * 3600 * 1000` with a rule
that uses it. The rule for this wave (see open question 2):
- offline, the app **opens** while the current time is before `session_expires_at`;
- after that time, offline, the app still opens in a **read and queue** mode: the person can see cached data and add
changes, which go to the outbox and are held (T14.1) until a good sign-in. The app does not go to `login.html`
while it has no network, because that page cannot load an Okta sign-in without a network;
- online, a `401` goes to `login.html` as now, and the outbox is kept (T14.1).
3. Stop sliding the window. A page load must not extend `wp_auth_cache`. Only the server can extend a session.
4. Show the person which mode they are in. One line: "Working offline. Sign in again when you have a signal to send your changes."
Use the same `aria-live` region as the badge.
**Done when:**
- [ ] `/api/auth/me` returns `session_expires_at`, and it matches the token (`tests/` check, no database change)
- [ ] the fixed 12 hours is gone from `auth-guard.js`
- [ ] opening the app offline before the time works; opening it offline after the time gives read-and-queue mode and does not redirect
- [ ] online with a dead session: redirect to `login.html?next=...`, queue kept, changes sent after sign-in
- [ ] a page load does not extend the cached window
- [ ] the mode line is announced by a screen reader (`aria-live`) and fits at 390 px
---
### T14.3: D26 and BL-061 the sync badge shows the true state and gets out of the way
- **Items:** `D26`, `BL-061`
- **Depends on:** T14.1
- **Blocks:** nothing
- **Surface:** `html/`
- **Files:** `html/project-data.js` (`renderSyncBadge`), `html/wp-chrome.css` or the shared token file, `tests/a11y_check.py`, `tests/autosave_check.py` (it reads the badge strings)
**Do:**
1. Show these states, each with its own words that name the **project**, never a draft save (the `B5` rule that wave 4 set): `sending`, `retrying`,
`held for sign-in` (with a link or button "Sign in"), `not saved on this device` (store full), `rejected` (with the reason),
and `all sent` (hides after a short time).
2. Make the badge usable: the "Sign in" and "Dismiss" controls are `<a>` or `<button>` elements with a visible focus ring
and a touch target of at least 44 px. Remove `pointer-events:none` for the states that have controls.
3. Keep the badge clear of page controls (`BL-061`): do not show it on pages that have no outbox work (the console
pages), and place it so that it does not cover the bottom-right action buttons at 390 px or 1440 px.
4. Keep text contrast at 4.5:1 or better in every state.
5. Update the tests that read the badge text (`autosave_check.py` reads its symbols; `a11y_check.py` reads the element).
**Done when:**
- [ ] each state shows in a browser test, with its text, at 390 px and 1440 px
- [ ] "Sign in" works with the keyboard and by touch, and goes to `login.html?next=...`
- [ ] the badge covers no control on the User Directory at 1440 px or the bulk bar at 390 px (the two places `BL-061` named)
- [ ] no badge on the console pages
- [ ] the contrast check passes for every state
- [ ] `autosave_check.py` and `a11y_check.py` pass
---
### T14.4: verify the wave and release T13.1
- **Items:** `D26`, `D27`, `BL-061`, `T13.1`
- **Depends on:** T14.1, T14.2, T14.3
- **Blocks:** nothing
**Do:** Run the full suite, the smoke test and `seed_demo.py`. Then test the real case by hand on a phone or tablet:
sign in, set the device to airplane mode, make three changes in Field View, wait until the session limit has passed
(use `AUTH_SESSION_HOURS=1` on a test stack with a clock change, or a forced expiry), turn the network on, and check that the badge shows
"held for sign-in", that signing in sends all three, and that the server has them. Then rebase `feat/waves-11-13`
T13.1 (`6cde6e3`) onto `main`, run `tests/session_idle_check.py` and the same hand test with the idle timeout on, and merge T13.1 as its own pull request.
**Done when:**
- [ ] the hand test passes on one iPhone and one Android device (or the failure and the reason are written here)
- [ ] the full suite and the smoke test pass on the final tree
- [ ] T13.1 is on `main`, and `tests/session_idle_check.py` runs (it no longer skips)
- [ ] the wave 13 exit line about D18 is ticked
---
## Open questions (needs Matt before T14.1 and T14.2 start)
1. **Shared devices.** If person B signs in on a device that holds unsent changes from person A, what must happen?
Proposed: hold A's changes, name A in the badge, send them when A signs in. Do not send them as B and do not discard them.
Other choices: allow B to discard A's changes after a confirmation; or send them as B (not proposed, wrong author in the log).
2. **Offline window.** Proposed for this wave: the app opens offline until the session ends, and after that works in read-and-queue mode.
The 7 day offline window (`BL-062`, Q2) is a **later** wave. Do you accept this order, or must 7 days come first?
3. **Device full.** Proposed: do not drop the change, keep it in the page memory, and tell the person. Is "tell the person and keep the
form open" enough, or must the app also stop new edits?
4. **Idle time.** T13.1 proposes 30 minutes. It is a proposed value, not a decision. It matters here because every minute of idle
time offline ends the session on the server side.
## Wave 14 exit criteria
- [ ] a session that ends while changes are queued loses none of them
- [ ] a full device store is never silent
- [ ] a change is sent only under the signed-in person who made it
- [ ] the offline window follows the server (no fixed 12 hours in the browser)
- [ ] the badge shows the true state, is usable, and covers no control
- [ ] T13.1 is merged to `main` and `D18` is fully accounted for