12 KiB
Wave 14: The outbox keeps every change, and the sign-in limit cannot destroy it
Items: D26, D27, B5 (finish), BL-061
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
divwithonclick(CLAUDE.md, accessibility). The sign-in action is an<a>or a<button>. - Status text goes in an
aria-liveregion. The badge already hasrole="status". Keep it. - Server work is needed for T14.2 (one new field). Do not store session data in
localStorageas 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, seeBL-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 newtests/outbox_check.py
Do:
- In
flush(), treat401as held, not dead. Stop the run. Do not add totries. 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 throughProjectData.syncStatus()(add a field, for exampleheld: true). - Keep
403as a permanent refusal, but say why in the reason text ("you no longer have access to this project"). Keep409(archived project) and the other4xxas they are. - When the person signs in again (the page loads with a good session, or
wp-auth-readyfires), clear the held state and flush at once. Theonlineevent, the 20 second timer and the tab-focus trigger must not clear it early: a held queue sends only after a good session check. - Make
qWrite()returntrueorfalse. If it fails,enqueue()must tell the caller and raise thedevice fullstate. 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. - Give each queued change an
owner(the signed-in username) when it is queued. At flush time, ifWP_USERis 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.) - Make sure
auth-guard.jsdoes not delete the queue when it sends a person tologin.htmlafter a401. It must keepwp_sync_outbox_v1.
Done when:
- a queue of N changes meets a
401: all N are still in the queue, none is dead,triesdid 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
403marks 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.pycovers each case above and fails whenflush()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/andhtml/ - Files:
server/app.py(whoami()),html/auth-guard.js,html/wp-format.js(line 223 writes the cache), tests
Do:
- Add one field to
/api/auth/me:session_expires_at(theexpclaim of the session, as a UTC time). Read the claim from the token thatget_current_useralready validated. Do not add a database column. When T13.1 lands, this field is the currentexpand moves with each refresh. - In
auth-guard.js, storesession_expires_atinwp_auth_cache. Replace the fixed12 * 3600 * 1000with 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.htmlwhile it has no network, because that page cannot load an Okta sign-in without a network; - online, a
401goes tologin.htmlas now, and the outbox is kept (T14.1).
- offline, the app opens while the current time is before
- Stop sliding the window. A page load must not extend
wp_auth_cache. Only the server can extend a session. - 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-liveregion as the badge.
Done when:
/api/auth/mereturnssession_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: B5 and BL-061 the sync badge shows the true state and gets out of the way
- Items:
B5(finish),BL-061 - Depends on: T14.1
- Blocks: nothing
- Surface:
html/ - Files:
html/project-data.js(renderSyncBadge),html/wp-chrome.cssor the shared token file,tests/a11y_check.py,tests/autosave_check.py(it reads the badge strings)
Do:
- Show these states, each with its own words that name the project, never a draft save:
sending,retrying,held for sign-in(with a link or button "Sign in"),not saved on this device(store full),rejected(with the reason), andall sent(hides after a short time). - 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. Removepointer-events:nonefor the states that have controls. - 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. - Keep text contrast at 4.5:1 or better in every state.
- Update the tests that read the badge text (
autosave_check.pyreads its symbols;a11y_check.pyreads 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-061named) - no badge on the console pages
- the contrast check passes for every state
autosave_check.pyanda11y_check.pypass
T14.4: verify the wave and release T13.1
- Items:
D26,D27,B5,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, andtests/session_idle_check.pyruns (it no longer skips) - the wave 13 exit line about D18 is ticked
Open questions (needs Matt before T14.1 and T14.2 start)
- 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).
- 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? - 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?
- 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
mainandD18is fully accounted for