From ae649b5ed785b573c32b1efee99f45fcfbde1d72 Mon Sep 17 00:00:00 2001 From: Matt Mabrey Date: Sat, 17 Oct 2026 13:27:28 -0700 Subject: [PATCH] Wave 14 spec (D26, D27, B5, BL-061) and the T13.1 gate; decisions 2026-10-17 --- docs/waves/decisions-2026-10-17.md | 30 +++++ docs/waves/wave-13.md | 7 ++ docs/waves/wave-14.md | 182 +++++++++++++++++++++++++++++ 3 files changed, 219 insertions(+) create mode 100644 docs/waves/decisions-2026-10-17.md create mode 100644 docs/waves/wave-14.md diff --git a/docs/waves/decisions-2026-10-17.md b/docs/waves/decisions-2026-10-17.md new file mode 100644 index 0000000..2b8128a --- /dev/null +++ b/docs/waves/decisions-2026-10-17.md @@ -0,0 +1,30 @@ +# Decisions: October 17, 2026 + +Status key: **Proposed** means the text is a recommendation. It needs Matt's OK before any build starts. + +## D26: a sign-in problem never destroys a queued change (Proposed) + +**Why:** The outbox (`html/project-data.js`) marks any `4xx` answer except `429` as dead. A `401` means the session ended, and it +gets the same treatment. With a session limit (D25, 8 hours) or an idle timeout (T13.1), a crew that works offline past the limit +comes back online and every queued change is rejected for good. The outbox also hides a full device store, and it sends a queued +change under whoever is signed in, not under the person who made it. + +**Proposal:** + +- `401` holds the queue. It does not mark anything dead and does not count as a try. The queue sends after a good sign-in. +- `403` stays a permanent refusal, with a clear reason. +- A full device store is reported. The change is never dropped silently. +- Each queued change has an owner. It is sent only when that person is signed in. + +**Tasks:** `T14.1`, `T14.3`. **Needs Matt:** open questions 1 and 3 in `wave-14.md`. + +## D27: the offline sign-in window follows the server (Proposed) + +**Why:** `auth-guard.js` allows the app to open offline for a fixed 12 hours after the last good check, and every page load resets that +time. The server session lasts 8 hours (D25). The two do not agree. + +**Proposal:** `/api/auth/me` returns `session_expires_at`. The browser stores it and does not extend it. Offline, the app opens until +that time. After that time, offline, it works in read-and-queue mode and does not redirect. Online, a `401` goes to sign-in and the +queue is kept. The 7 day offline window (`BL-062`) is a later wave. + +**Task:** `T14.2`. **Needs Matt:** open question 2 in `wave-14.md`. diff --git a/docs/waves/wave-13.md b/docs/waves/wave-13.md index 1b3b23b..ab1fcc5 100644 --- a/docs/waves/wave-13.md +++ b/docs/waves/wave-13.md @@ -477,3 +477,10 @@ console of `wp_api` (no `docker compose exec` prefix). `promote` changes an exis Effect on the live system: after the next deploy, sessions last 8 hours instead of 12. To get the same result before a deploy, set `AUTH_SESSION_HOURS` to `8` in the Portainer stack variables. + +## Gate for T13.1 (2026-10-17) + +T13.1 now has a written gate: `docs/waves/wave-14.md`. It lands in T14.4, after T14.1 (a `401` holds the outbox and does not +destroy it) and T14.2 (the offline window follows the server) are done. The reason is a fault found in the outbox on +2026-10-17: it marks a `401` as a permanent rejection, so an idle timeout would reject a crew's queued changes for good. +That fault already exists with the 8 hour limit, to a lesser degree. diff --git a/docs/waves/wave-14.md b/docs/waves/wave-14.md new file mode 100644 index 0000000..b895907 --- /dev/null +++ b/docs/waves/wave-14.md @@ -0,0 +1,182 @@ +# 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 `div` with `onclick` (`CLAUDE.md`, accessibility). The sign-in action is an `` or a `