Move image reading onto the episode as reading cases

[edwardhorsford]

Moves image reading data off the appointment and onto the episode, as reading cases, and gives past rounds enough detail to be worth looking at.

Why

Reads lived on appointment.imageReading, keyed by user, with the arbitration read implied by happening to be third. That shape doesn't survive contact with arbitration: reads can be withdrawn (deferring after giving an opinion does exactly that), which shifts positions and makes "the third read" mean nothing.

Production models this as reading cases — taking mammograms triggers a case, and the reads belong to the case rather than the episode directly. One case per set of images, so a technical recall's re-screen produces a second case.

What changed

Reading cases. episode.readingCases[], one per image set, keyed to the appointment that produced it. Reads are an ordered array, each carrying its own readType (first / second / arbitration), settled when the read is written — because once there's a manual step in front of arbitration, whether a read was an arbitration read depends on where the case had got to at the time, and nothing can recover that afterwards.

getOutcome split in two. It returned a mix of process states (not_read, arbitration_pending) and clinical answers (normal, technical_recall) in one string. Now:

• getReadingCaseState — where the case has got to: awaiting_first_read, awaiting_second_read, arbitration_required, in_arbitration, concluded
• getReadingCaseOutcome — what it found, or null while reading is still under way

arbitration_required and in_arbitration are deliberately separate. Reads disagreeing makes arbitration necessary; a case only becomes arbitratable once someone releases it. Nothing performs that release yet, so nothing reaches in_arbitration — the state exists so the vocabulary is whole rather than growing a value later across every call site. Deferral already works this way: the act is recorded, and the state is read back from its presence.

Module split, one-directional. reading-cases.js is pure case logic and takes a case. episodes.js owns getting cases out of session data and writing them back, because both go through the episode. reading.js is the appointment- and session-shaped layer above — sessions, backlogs, progress — which is why most of its helpers now take data. Cases are resolved once, at the edges: the reading workflow middleware sets res.locals.readingCase, and list-building attaches it per row.

Episode stage comes from the latest case, which fixes the known technical-recall bug where a re-screen didn't supersede the reading that asked for it.

Past rounds are worth looking at now. Each screened historic episode carries a summary reading case and a stand-in appointment (summaryAppointments[]) holding the medical information recorded that day. Both sit on the episode rather than in data.appointments, so they can't drift into a clinic list or a reading queue — there's nothing to open, and the episode page's links deliberately go nowhere. Detail is conditioned on the outcome the round was already seeded with: a round that ended in treatment was recalled for assessment, most clear rounds were read normal, and a few went to arbitration.

Seed profiles reach history. episodes.historicOutcomeWeights existed as a hook nothing set, so "All normals" still generated past referrals for treatment. Now wired, and historic medical information follows the profile's probabilities too.

Bugs found on the way

• Lazy reading sessions were destroyed by resuming them. /resume looped topUpSession until it stopped adding, to replace slots taken by other readers — but that call grows a session toward its target size, so it loaded every remaining case at once. A session went from 1 case to 10 on a single resume. Pre-existing.
• The technical-recall seeding was mistyping a read as arbitration, caught by the new checkEpisodes assertions.
• Two intermittent e2e failures, both pre-existing: full names were built without middle names, and controls low inside a modal can't be scrolled into view (the dialog is overflow: clip and scrolls via an inner element).

Verification

npm test green — lint, 104 routes with no server errors, and 7 journeys, run repeatedly to shake out the flakes above. Three new reading journeys went in first, as a net under the refactor: technical recall, defer + unflag, and the second-reader comparison. Between them the reading journeys now cover all four ways a reader can leave a case. A fourth journey pins the lazy-session fix.

Data regenerates clean with no checkEpisodes warnings, and no appointment retains imageReading.

Deliberately not here

• The arbitration flow itself — the gate, the arbitration read, the resolution step. The data shape and state vocabulary are ready for it.
• The reading backlog / case views. The state values map 1:1 onto the planned tabs.
• Medical information building across a participant's rounds. Each round still generates independently, so history isn't yet coherent round to round; that needs a wider change to generators the live appointment flow also uses.
• Deferral and priors storage — written up separately as a spike rather than changed here.