Skip to content

feat: let a group require a form to be completed when a session starts - #1933

Open
joshunrau wants to merge 4 commits into
DouglasNeuroInformatics:mainfrom
joshunrau:feat/session-instrument
Open

joshunrau wants to merge 4 commits into
DouglasNeuroInformatics:mainfrom
joshunrau:feat/session-instrument

Conversation

@joshunrau

Copy link
Copy Markdown
Collaborator

A group manager can now make one form part of starting a session. Start Session shows the form after the session details, and the session and the form's record are created together or not at all. Three fixes to session timestamps come with it. This is the first of two PRs for #1546.

Closes #1675. Closes #1029. Closes #1717.

Changes

  • The setting. A group's settings gain a Session Instrument: one form the group can access, or None. Anyone who can manage the group sets it on the group's manage page. The select offers only the forms ticked in the group's instrument list, and tells two same-titled forms apart by their internal names.
  • The manage page reads the group fresh. It used to seed its form from the group as it was at sign-in, and a save sends back every setting it was seeded with, so a save could undo a change made since. It now seeds from GET /v1/groups/:id, which its loader fetches, and a save writes its response back to that query.
  • Start Session. With a session instrument set, Start Session shows that form after the session details. A Back control returns to the details exactly as they were typed. The session is created only when the form is submitted, and the record is dated as the session is; an in-person session is dated at that moment. Switching group drops a pending form.
  • The endpoint. POST /v1/sessions moves to a new StartSessionModule (OpenAPI tag StartSession) and accepts an optional sessionInstrumentAnswers: { data, instrumentId }. Its refusals:
    • 422 for each of these, all checked before any subject or session is created:
      • a session in a group that requires a form, sent without its answers or with another form's;
      • answers for a group that requires none;
      • answers to an instrument that is not a form;
      • answers the form's schema rejects.
    • 403 when the caller lacks create InstrumentRecord.
    • If the record then fails to save, the session is deleted, and so is the subject if this request created it.
  • Guards on the setting.
    • An update that would take the form out of the group's accessible instruments is refused with 400.
    • A newly set instrument must be a form.
    • A group cannot be created with one.
    • A new edition of the form takes over the setting only if that edition is a form, and only once the edition is saved.
  • Timestamps.

Decisions

  • A module of its own. The route lives in its own module, which imports Groups, Instruments, InstrumentRecords, Sessions and Subjects, as SummaryModule does. SessionsService cannot inject InstrumentRecordsService without a cycle, and this avoids a forwardRef. libnest tags an operation by its controller's class, so POST /v1/sessions now sits under StartSession in /spec.json, apart from GET /v1/sessions.
  • In-process callers are exempt. SessionsService.create still takes $CreateSessionData. The gateway synchronizer, CSV upload and demo seeding create sessions in process, so they cannot pass a record and are not asked for one.
  • The rollback is unscoped. The session, and a subject this request created, are deleted without the caller's ability, because the caller may lack delete Session, and the ids are rows this request just created. SessionsService.createMany rolls back the same way. Whether the subject is new is checked with an unscoped SubjectsService.exists, since a scoped lookup would miss a subject in another group and the rollback would then delete it.
  • Fresh group data. Start Session reads the session instrument from a fresh GET /v1/groups/:id that its loader prefetches. The store's currentGroup comes from the login token, so it would miss a setting changed since sign-in.

Risks

Adversarial review

Reviewed at commit d5d749d. pnpm check: green.

Findings

  1. apps/api/src/instruments/instruments.service.ts:159 — The session instrument moved to a new edition before that edition was saved, so a failed upload left groups requiring an instrument that does not exist — Run both group updates only after the insert succeeds.
  2. apps/api/src/start-session/start-session.service.ts:70 — When the record failed to save, the rollback deleted the session but kept the subject the request had just created — Also remove a subject this request created.
  3. apps/web/src/routes/_app/group/manage.tsx:605 — The edition label could never fire, since the page lists only the latest edition of each form, so two same-titled forms both read "Title (1)" — Tell colliding titles apart by something that differs between forms.
  4. apps/web/src/routes/_app/group/manage.tsx:991 — The page seeded the session instrument from the group as stored at sign-in and sent it on every save, so a stale page reverted it, the move to a new edition included — Seed the form from a fresh group query.
  5. apps/api/src/groups/groups.service.ts:244 — Choosing a session instrument the group cannot access was refused with a message about removing it — Give that case its own message.
  6. packages/schemas/src/session/session.ts:31 — sessionInstrumentRecord named the request's result, but the field carries the form's answers — Rename it.
  7. apps/api/src/start-session/start-session.controller.ts:12 — POST /v1/sessions is tagged "StartSession" in /spec.json, apart from GET /v1/sessions under "Sessions" — Keep both routes under one tag.
  8. apps/web/src/components/StartSessionForm/StartSessionForm.tsx:36 — StartSessionFormData declared sessionDate required while its schema makes it optional — Declare it optional.

Fixed

    1. Both group updates run after the insert, and a test pins that a failed insert updates no group.
    1. The rollback also deletes the subject when SubjectsService.exists found none before the session was created.
    1. Same-titled forms are told apart by their internal names.
    1. The page seeds from GET /v1/groups/:id, fetched by its loader, and a save writes its response back to that query.
    1. Choosing an instrument the group cannot access gets its own message.
    1. Renamed to sessionInstrumentAnswers.
    1. Declared optional.

Declined

    1. libnest sets an operation's tag from its controller's class after spreading the ApiOperation metadata (docs.generator.js:87), so the tag can only follow the class. The handler moved to its own controller to break the SessionsModule/InstrumentRecordsModule cycle, and naming that class SessionsController would give the app two controllers of one name. The path is still listed once in /spec.json.

Attestation

I, Claude Opus 5.5, attest that the review block above reports the adversarial review as it ran on the commit named, with every finding it returned.

🤖 Generated with Claude Code

joshunrau and others added 4 commits November 19, 2026 10:33
…e page loaded

The Start Session form computed the current date once, at module scope, and used it as the
in-person session date, the upper bound for a retrospective date and the reference for the
group's minimum age. Every session started later in the same page load was backdated to when
the page first opened. Each check now reads the clock when the form is validated, and the
in-person default is built at submission.

Closes DouglasNeuroInformatics#1675

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A retrospective session's date is now a date and time, so the time of collection is kept
(for MouseODC, the time of day is a proxy for hormonal variation). The date is required: a
blank one used to be read as the moment the form was submitted, and a time typed without a
date was lost.

Closes DouglasNeuroInformatics#1029

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… time of day

The export projected each row's timestamp from the day the record was inserted, so a
retrospective session, a bulk upload or a remote assignment exported with the wrong date, and
every row lost its time. It now takes the record's own date, and both it and the session date
keep their full ISO timestamp.

Closes DouglasNeuroInformatics#1717

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A group manager can choose one form instrument as the group's Session Instrument. Start
Session then shows that form after the session details, with a Back control, and the session
is created only once the form is submitted: POST /v1/sessions carries the answers and creates
the session and a record of them, dated as the session is, or neither. If the record fails to
save, the session is deleted, and so is the subject if this request created it. The server
refuses a session in such a group without the answers, and answers for a group that requires
none.

The setting follows a new edition of the form once that edition is saved, an update that would
take the form away from the group is refused, and a group is never created with one. The
gateway synchronizer, CSV upload and demo seeding create sessions in process and are not asked
for it.

The group's manage page now reads the group fresh rather than as it was at sign-in, since a
save sends back every setting it was seeded with and so could undo a change made since.

Refs DouglasNeuroInformatics#1546

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added the Status: Waiting on Review Automated: unreviewed, pushed since the last review, or review re-requested label Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Waiting on Review Automated: unreviewed, pushed since the last review, or review re-requested

Projects

None yet

1 participant