Plan 74 R4 Part 2

Part 2 of 6 of R4 — Teacher workspace (v0.10.0) · Previous · Next

T-R4.5 — The `/teacher` route tree

Depends on: — Touches: web/src/app/router.tsx, web/src/app/LegacyTeacherRedirect.tsx (new), web/src/features/auth/home.ts, web/src/app/guards/RequireWorkspace.tsx, web/src/app/boot/handoff.ts, web/src/features/auth/AccountMenu.tsx, web/src/layouts/AdminLayout.tsx (its nav links), web/src/features/*/pages/** → web/src/features/*/pages/teacher/** (the 22 teacher pages, moved), every web/src/features/** file linking to an /admin/… route, web/tests/** with /admin/… routes, web/tests/e2e/smoke.spec.ts, web/tests/e2e/theme.spec.ts, web/tests/e2e/support/live.ts, web/tests/units/student/shell.test.tsx, web/tests/units/student/imports.test.ts (it reads the router's adminTree by name) Size: L Delivered in parts: two, each one branch and one pull request T-R4.5a: the page moves. Depends on nothing in R4 T-R4.5b: the rename (router, redirect, link sweep in src and tests, the literal test). Depends on T-R4.5a As built:

T-R4.5a: 22 pages moved with git mv, each to features/<f>/pages/teacher/<same name>: assignments (AssignmentsListPage, AssignmentDetailPage, AssignmentFormPage), attempts (AssignmentAttemptsPage, AttemptReviewPage, GradingQueuePage), classes (ClassesListPage, ClassDetailPage), imports (ImportsGate, ImportsListPage, NewImportPage, ImportDetailPage, ImportReviewPage), media (MediaLibraryPage), question-bank (QuestionBankPage, QuestionEditorPage), question-groups (GroupsListPage, GroupEditorPage), students (StudentsListPage) and tests (TestsListPage, TestDetailPage, TestBuilderPage).
T-R4.5a: what stayed, against the Touches glob. features/*/pages/** would also move the student's pages (StudentHomePage, AssignmentIntroPage, StudentClassesPage, StudentSettingsPage, ResultPage, TakeTestPage), JoinPage and the four auth pages; they are not the teacher's and stay. auth/pages/AdminSettingsPage.tsx and app/pages/AdminDashboardPage.tsx stay too: T-R4.43 and T-R4.23 replace them, so a move would only be undone.
T-R4.5a: only paths changed. The 49 relative imports of the eleven pages that have them gained one ../ (not rewritten to @/, so the diff stays a path fix); router.tsx's 24 lazy imports and the 39 files under web/tests that import a page gained teacher/. Prettier re-wrapped the statements the longer path pushed past 88 columns and nothing else: 17 lazy: page(…) calls in the router, and one named import each in GroupEditorPage and TestBuilderPage. Every rename is at 92% similarity or more. Routes, links and layouts are untouched; /admin stays /admin until T-R4.5b.
T-R4.5a: the canary passed unedited. router-chunks.test.ts names by path the seven moved pages of the four features its ADMIN pattern lists (tests, question-bank, media, students), as before the move: features/tests/pages/teacher/TestsListPage.tsx imported eagerly turns it red. The fifteen moved pages of the other five features are not named by path, also as before: features/assignments/pages/teacher/AssignmentsListPage.tsx imported eagerly passes it, 12 of 12. T-R4.5b's pages/teacher/ pattern is the first to name them. tests/units/student/imports.test.ts, which reads the router's import("…") calls, also passes: prettier keeps each call on one line.
T-R4.5a: no test compares a teacher path with the page it loads, as at the base. Of the three that read the router (student/imports.test.ts, student/side-column.test.ts, take-test/focus-layout.test.tsx) none does; typecheck accepts any page behind any path, and the canary asks which chunk holds a module, never which path loads it. The proof here is that the base's adminTree and the moved one are identical once teacher/ and prettier's wrapping are stripped. The test belongs to T-R4.5b, which rewrites the table: pair each path (or index) with its import("@/…"), and allow a handle between the two, because every screen task adds one there.
T-R4.5b: the tree moved, the screens did not. router.tsx's teacherTree is the old adminTree at path: "teacher": the same TeacherWorkspace guard, the same lazy AdminLayout, the same 26 route objects in the same order, no handle. /teacher/assignments/:id/attempts stays a real route until T-R4.25. homePathFor and StudentArea send a holder of the teacher or the admin workspace to /teacher (a user with the admin workspace alone meets the guard's 403 there, as at /admin before; R5 changes that), and handoff.ts looks for the teacher frame at /teacher. AccountMenu's default Settings address, which only AdminLayout relies on, is /teacher/settings; auth/account-menu.test.tsx pins it.
T-R4.5b: the redirect is one route and one pure function. { path: "admin/*", element: <LegacyTeacherRedirect /> } sits at the top level beside authTree, outside RequireSession. The splat also matches the bare /admin, so the second route the plan names would be one no test could tell from its absence. app/legacyTeacherPath.ts maps the prefix (/admin to /teacher, /admin/<rest> to /teacher/<rest>, anything else null), in any letter case, because the router matches that way, and leaves the rest of the path as it was written; the element is a <Navigate replace> that keeps the query and the hash. It knows nothing of who asks: a signed-out visitor reaches /login with next already at the new address, and a student gets the 403 at /teacher/…. It is imported eagerly and lives until R5.
T-R4.5b: next= has no map. destinationAfterSignIn is unchanged: a next of /admin/x saved before the release comes back as written and reaches the redirect route by itself. legacy-teacher-redirect.test.tsx pins both halves, the second against the app's own route table with its lazy pages replaced by stubs.
T-R4.5b: the sweep was a script, kept outside the repository with its before and after lists: replace /admin wherever it is a route (the \/admin of a URL regex included), then prettier on exactly the files changed. web/src: 43 files, 114 hunks, two JSX links re-wrapped in ImportReviewPage. web/tests: 74 files, 212 hunks, two statements re-wrapped (attempts/papers.test.tsx, auth/permissions.test.ts). Two tests name the tree without a slash and follow it: student/imports.test.ts reads teacherTree, and student/side-column.test.ts walks "teacher". No case was removed and no assertion changed its meaning. 403 lines said /admin before (137 in src, 266 in tests); the sweep left 67, and 69 do now (8 in src, 61 in tests).
T-R4.5b: what still says /admin, and why. In web/src: the two API paths that keep the prefix (/admin/docs-session in features/auth/api.ts, /admin/users/{id} in features/students/api.ts), the generated lib/api/schema.d.ts, and the redirect's two files. In web/tests: the redirect's two tests, the literal test's planted lines, and the two old addresses at which teacher-landing.test.tsx expects no teacher frame. Outside web/, left alone: three comments in seed/01-dev.sql and seed/02-dev-assignments.sql; and, for T-R4.50, docs/setup/word-import-worker.md:16 (/admin/imports), the route lines of docs/plan/17-word-import.md and 18-word-import-ux.md, AGENTS.md, and spec §2 (line 503, the three route trees), §5.4 (lines 604 to 606), §6.4 (line 684), §8 and §10.4 (line 1220).
T-R4.5b: the literal test (tests/units/app/no-admin-routes.test.ts) reads web/src as text and fails, naming the file and the line, for any string or template literal that starts with /admin, in any letter case, followed by /, a quote, ?, #, an interpolation or the end of the line. That is wider than "route literals only": a prefix check or a route object is refused too. Allowed, each by an exact rule: the redirect's two files and lib/api/schema.d.ts by their full paths, and the two API paths by their whole literal, so a longer path or one built by hand is refused. The test proves itself on planted lines.
T-R4.5b: teacher-routes.test.ts pins the route table, the gap T-R4.5a recorded. It reads router.tsx as text, pairs each path or index of teacherTree with the module it imports, finds a route's parents by brace depth, and compares the result with the tree written out row by row (27 rows: the layout and the 26 routes). A handle between a path and its import changes no row, so a screen task that only adds one leaves the test alone; a task that changes a path, a page or the layout changes its row. A route with no import() (T-R4.25's redirect) is not a row. A second case pins the nesting by brace depth: every page sits in the layout's children and every import page in the gate's, so a page written beside either with its whole path fails although its row reads the same (T-R4.39's confirm page goes inside the gate). A handle changes no depth either.
T-R4.5b: the canary names every teacher page, which the Done-when line below still leaves to T-R4.4: the lead moved it here after T-R4.5a's review. ADMIN gained features/[^/]+/pages/teacher/; nothing was removed and no assertion changed. ClassesListPage imported eagerly passed the old pattern 12 of 12 and fails the new one in two cases, the first naming the file. T-R4.4 finds the page pattern present and adds layouts/TeacherLayout only.
T-R4.5b: specs changed and not run here; CI's "E2E" and "E2E (live API)" jobs are their first run. Stubbed: smoke, theme, settings, settings-navigation, group-authoring, group-preview, group-review, builder-group-recovery, rich-blanks, rich-options, rich-question-content. Live: admin-change-requests, audio-plays, author-and-publish, builder-groups, group-authoring, and support/live.ts (signInAsAdmin expects /teacher; assignToClass, which every student-side live spec uses, drives /teacher/assignments/new).
T-R4.5b: left to others. T-R4.4: the shell switch on handle.crumb, and the teacher skeleton (skeletonFor("/teacher") is null until it registers one; shell.test.tsx and theme.spec.ts's "console not yet rebuilt" case say so at the new address). T-R4.23: smoke.spec.ts's three sidebar cases, which now open /teacher in AdminLayout. T-R4.25: the redirect from /teacher/assignments/:id/attempts to the Students tab. T-R4.39: /teacher/imports/:id/confirm. T-R4.48: the file and component names that still say "Admin". T-R4.50: AGENTS.md and the spec. Done when:
Two pull requests: T-R4.5a the page moves (the 22 teacher pages; student and auth pages stay); T-R4.5b the router at /teacher, LegacyTeacherRedirect, homePathFor, the guard, handoff.ts, the sweep in src and in tests as two mechanical commits, and the literal test. A task that depends on T-R4.5 waits for T-R4.5b
Routes under the guard and, until its screen task, AdminLayout: /teacher, /teacher/assignments (/new, /:id, /:id/edit), /teacher/attempts/:id, /teacher/grading, /teacher/classes (/:id), /teacher/students, /teacher/tests (/:id, /:id/edit), /teacher/imports (/new, /:id, /:id/review), /teacher/question-bank (/new, /:id, /groups, /groups/:id), /teacher/media, /teacher/settings/:section?; a screen task adds handle.crumb and handle.width, which moves its route to TeacherLayout. /teacher/imports/:id/confirm is added by T-R4.39; the imports gate route stays
LegacyTeacherRedirect maps /admin/* web paths to /teacher/*, keeping query and hash: a prefix map; the attempts rule is added by T-R4.25 with the Students tab. It lives until R5 gives /admin to the Admin console. A next of /admin/x reaches the redirect route by itself
homePathFor sends a workspace.teacher holder to /teacher
router-chunks.test.ts: T-R4.5b adds features/[^/]+/pages/teacher/ to the teacher pattern, so every moved page is named by path (before it, an eager import of fifteen of the twenty-two passed). T-R4.4 adds layouts/TeacherLayout; T-R4.48 drops AdminLayout and AdminDashboardPage. features/students/ and features/media/ stay named whole: the narrower features/media/(pages/|components/(UploadPanel|AssetLibraryDialog)) this line once proposed was not adopted (router-chunks.test.ts:51), so T-R4.35 needs no edit
No /admin route literal remains in web/src outside the redirect's two files (LegacyTeacherRedirect.tsx and legacyTeacherPath.ts): a unit test reads every source line for an /admin address in any letter case, excluding lib/api/schema.d.ts and api() call sites, so R2's retained API paths (/admin/docs-session, /admin/users/{id}) do not trip it
smoke.spec.ts: its three sidebar cases open the index route and stay until T-R4.23 flips that route and removes them. The first route in the new shell (T-R4.23, or T-R4.25 when T-R4.19 is not merged as T-R4.4 merges) adds web/tests/e2e/teacher-shell.spec.ts; pnpm e2e green

T-R4.6 — Command palette

Depends on: T-R4.4, T-R4.5b, T-R4.13 Touches: web/src/features/search/CommandPalette.tsx, web/src/features/search/useCommandPalette.ts, web/tests/units/search/ Size: S Done when:

⌘/Ctrl+K toggles it, the search button opens it, Esc closes it; 560px panel at 12% from the top; placeholder "Search pages, tests, students…" (vi first)
Groups: Pages (in R4 only Dashboard, Assignments, Grading, Tests, Question bank, Students, Classes, Media, Settings, each filtered by the item's permission), Assignments (up to 4, status hint) and Students (up to 3, first class hint), then Tests (up to 4) and Questions (up to 3), which exist today; matching is accent-insensitive. Assignments needs q on listAssignments (T-R4.13); a Students result opens /teacher/students?q=
↑/↓ move, Enter opens and the "Nothing matches" line on no results are kept (DG-36)
Unit tests: keyboard navigation, no-results line, a destination the user lacks is absent

T-R4.7 — Profile fields and preferences

Depends on: — Touches: migrations/00085_add_users_profile_fields.sql, migrations/00086_add_users_preferences.sql, api/openapi.yaml, server/gen/openapi/, web/src/lib/api/schema.d.ts, server/internal/modules/identity/{domain/user.go,application/command/rename.go → update_profile.go,application/command/update_preferences.go (new),application/query/current_user.go,repositories/store.go,http/account.go}, server/internal/modules/classes/repositories/{postgres.go,lookup.go}, server/internal/modules/assignments/repositories/student.go, the dashboard's zone port, web/src/features/auth/useSession.ts, web/src/features/auth/profileSchema.ts, web/src/lib/theme.ts, web/src/lib/i18n/index.ts, web/src/lib/i18n/datetime.ts, docs/plan/20-data-model.md Size: M Done when:

add_users_profile_fields: display_name text (1–80 after trim), phone text (^[0-9+ ]{6,20}$), avatar_key text, locale text CHECK IN ('vi','en'), time_zone text (≤64). All nullable. Down drops the five columns
add_users_preferences: preferences jsonb NOT NULL DEFAULT '{}' with a CHECK that it is an object of at most 8192 bytes. Down drops it. An integration test inserts a user with the R3 column list and succeeds
Contract: CurrentUser (the caller, R2's split) gains optional displayName, avatarUrl, phone, locale, timeZone and preferences (UserPreferences: theme light|dark|system, compactTables, largerTestText, assignmentDefaults {durationMinutes 1–600, shuffleQuestions, showScore, blockCopyPaste, requireFullscreen}, all optional, additionalProperties: false). User (someone else) gains only displayName and avatarUrl, so one person's phone, locale, time zone and preferences never reach another
PATCH /auth/me (x-permission: self) takes {fullName?, displayName?|null, phone?|null, locale?, timeZone?} with minProperties: 1; an unknown time zone (time.LoadLocation) answers 400 VALIDATION_FAILED on timeZone; the response is the whole CurrentUser
PATCH /me/preferences (self) merges top-level keys and returns UserPreferences; a body over the cap answers 400. T-R4.10a adds the first /me/* operations and with them /me/ in httpx's private trees and its test; this task adds PATCH /me/preferences: R2's tree rule (/me/* accepts only self) and TestPermissionTreesMatchPaths cover it
Where a student sees the teacher (MyClass.teacherName, the assignment intro, the /join/preview teacherName), the name is display_name, falling back to full_name. The PR carries the leak review for /join/preview: a name the teacher chose for students, no new field
Web: after sign-in the session applies the server locale and theme and mirrors them to quizzivy.locale and quizzivy.theme; a stale local value never overrides the server; lib/i18n/datetime.ts exposes setDisplayTimeZone, with Asia/Ho_Chi_Minh as the default
Tests: identity unit tests for validation; repository integration tests for merge and the cap; a contract fixture test (ajv) that also asserts User carries none of phone, locale, timeZone or preferences; a web unit test that a server theme applies and mirrors; 20-data-model.md records both migrations

T-R4.7 — As built

Migrations 00085 and 00086 add nullable profile fields and bounded object preferences. Self-scoped PATCH preserves omitted profile keys, clears only the documented nullable fields, and merges preference top-level keys with atomic audits. Private fields appear only in CurrentUser; public display names fall back to full names. Join preview exposes the same student-facing name field and no private profile data.

The frontend applies acknowledged account locale/theme/display zone/larger-test-text over browser mirrors, preserves mounted drafts, and keeps explicit Retry on failed preference writes. Same-page actor generations, serialized cookie transports and checked global draft/cache cleanup prevent old-account results from affecting a replacement account. Refresh remains single-flight. A 20-second admission/transport status bound and 10-second cleanup status bound do not abandon raw ownership; a timed-out admission cannot later sign in automatically. Cross-tab cookie ordering remains outside this task.

Display consumers react to the accepted zone. Existing teacher wall-clock inputs and their rules preview retain fixed-HCM interpretation until Task43; full redesigned profile controls remain43 and photo operations8. Compact-table and assignment-default consumers are not claimed implemented here. Anonymous preferences stay local and omitted defaults are read without materializing server writes. Unsupported browser zones preserve the stored value, report compatibility and temporarily display HCM without persisting that fallback.

Independent source reviews, actual PG18.6 app/migrate profile/preference tests with checked fixture cleanup and retained audits, unchanged high-risk canaries, contract generation/type/lint, hosted CI and the 12-family native cookie/IndexedDB/presentation campaign passed. The native suite used real browser cookie/IDB mechanics with controlled HTTP fixtures; server authority has separate Go/live CI coverage. Five-width/two-theme image acceptance includes the separately captured phone account menus. Earlier failures and repairs remain in the takeover evidence. This completes Task7 within R4, not a production release.

T-R4.8 — Profile photo

Depends on: T-R4.7, T-R4.53 Touches: server/internal/platform/imagesafe/ (new), server/internal/modules/identity/{application/command/set_avatar.go (new),http/account.go}, server/internal/core/router/ratelimits.go, server/internal/core/wiring/identity.go, an object-store port in server/internal/modules/identity/application/ports, server/internal/core/router/tests/testdata/permissions.golden, api/openapi.yaml (IMAGE_DIMENSIONS is a new ErrorCode value), generated code Size: S As built (2026-10-10):

Touched beyond the list: core/adapters/photos.go (the identity port's implementation and the avatar limits), identity/{domain,repositories/avatar.go,application/{app.go,ports,command/remove_avatar.go, query/avatar_url.go,internal/support/avatar.go},http/avatar.go}, the pinned counts in core/router/tests/{permissions_test.go (116 to 118 gated operations),me_test.go (6 to 8 under /me/), group_authoring_test.go (11 to 12 body budgets),principal_limits_test.go}, and in server/tests/ the two isolation entries, a 300 x 300 body for them and profile_photo_flow_test.go. No migration: users.avatar_key has existed since 00085.
The checks run cheapest first, and nothing is decoded until the sixth: the request cap (2 MiB + 16 KiB for the multipart framing, 413 before the handler), the multipart file part (400), the read through a LimitReader of the limit plus one byte (413 MEDIA_TOO_LARGE: a file of exactly 2 MiB passes, one of 2 MiB and a byte does not), the file signature (PNG or JPEG, 415 MEDIA_TYPE_UNSUPPORTED; the part's Content-Type is never read), image.DecodeConfig (415 MEDIA_UNREADABLE), the sides, the memory estimate and, for a JPEG, the count of scans (415 IMAGE_DIMENSIONS), then the slot, the decode, the crop, the resample and the encode.
One imagesafe.Gate of two slots serves the process, built in wiring/identity.go and meant to be handed to R5's logo upload. The slot is taken after the file is read, so a slow uploader holds a connection and never a slot. A waiter leaves when its request context ends. No "busy" answer and no new code were added (decided): waiters stay bounded by the request context and the server's timeouts, each holding at most 2 MiB of encoded bytes.
imagesafe.MaxDecodedBytes is 48 MiB (decided; 64 was refused: Argon2 can hold 256 MiB of a 512 MB machine). The estimate comes from the header: the decoded image by colour model, and for a progressive JPEG the int32 coefficient block the standard decoder keeps per component (4 bytes a pixel per full-resolution component, read from image/jpeg). A progressive 4:4:4 JPEG at 2048 x 2048 needs 60 MiB, over about 1830 pixels a side; a progressive CMYK one over about 1450; both answer 415 IMAGE_DIMENSIONS before any allocation. 16-bit PNG at 2048 x 2048 (32 MiB), baseline JPEG and 4:2:0 progressive are admitted. A test holds the estimate between 0.8 and 1.6 times what the decoders really allocate for seven kinds of image. The bound for two slots is 96 MiB of image memory.
The box filter is exact area averaging in integers (centred square crop, any scale including a small image scaled up, premultiplied alpha, one pass), so a transparent pixel adds no colour and the result is the same on every machine. The output is always 256 x 256, encoded by the standard PNG encoder, which writes IHDR, IDAT and IEND only.
EXIF orientation is applied, then dropped (decided). The reader takes the first Exif APP1 segment, reads IFD0 only and never follows a next-IFD offset, so no chain can loop; an IFD that declares more than 256 entries or runs past the block, and any wrong byte order, magic, type, count or value, is ignored whole. The transform runs on the 256 x 256 result.
Both operations answer 200 CurrentUser, and every CurrentUser (login, Google sign-in and link, GET and PATCH /auth/me) carries avatarUrl, a presigned GET valid 24 hours, when the user has a photo. User (someone else) is unchanged: a list that shows other people's photos (admin Users, the roster) needs a key and a signature per row and gets them in its own task. The signed URL's path names its object (avatars/{userId}/{uuid}.png), which is no secret from its owner.
The write is one statement: a data-modifying CTE sets avatar_key, returns the old key and writes user.avatar_set or user.avatar_removed (the diff names no key). Concurrent writes chain: each deletes the key the other replaced. A failed write deletes the new object; a failed delete of the old one is logged and not returned. A crash between the put and the write, or a failed delete, can leave one unreferenced object that no response reaches; deleting a user does not delete the photo yet, and a sweep of the avatars/ prefix is the fix for both (R5's anonymisation, T-R5.17a, should delete it).
Rate limit: PUT /me/avatar is 10 an hour per user in PrincipalRateLimits(); DELETE is not limited. A deployment with no bucket answers PUT 501 and signs nothing; DELETE still clears the key.
Security review (2026-10-10, approve with changes; SR-472-1 to 4, all fixed in the PR). (1) The standard JPEG decoder makes a full pass over its coefficients for every scan, about 2.1 ms a scan at 2048 x 2048, with no scan limit and no way to cancel it, so a progressive file of 20,000 near-empty scans (18 bytes each) held a slot for 32 s and a 2 MiB one would for minutes. Only the input can bound that time: the SOS markers after the SOF are counted before the Gate and more than Limits.MaxScans (the constant MaxScans, 32; libjpeg's script writes 10 for colour and 6 for grey) answers IMAGE_DIMENSIONS; the same cap bounds a baseline file with many scans. (2) The PNG estimate counts an Adam7 file at 3/2 (the image and its largest pass) and a grey file with a tRNS chunk at what the decoder makes of it (4 bytes a pixel, 8 at 16 bits); the largest admitted shapes need exactly 48 MiB and the bound is inclusive, so MaxDecodedBytes did not move. (3) A recovered decoder panic is wrapped (ErrDecoderPanic) and logged at Warn by the adapter; no test forces a panic inside the standard decoders, so only the adapter's side is tested. (4) setAvatar takes 2 MiB + 16 KiB so that 2 MiB is reachable, and a nil multipart reader answers 400, not 501.
The web half is T-R4.43. A phone photo (4032 x 3024) is over 2048 on its long side and answers 415 IMAGE_DIMENSIONS, so the client downscales on a canvas to at most 2048 on the long side before it uploads (F-45). The server's limits do not change. Done when:
PUT /me/avatar (self, multipart, x-max-body-bytes 2 MiB): the type is sniffed (PNG or JPEG only, 415 otherwise); image.DecodeConfig runs before any decode and refuses under 200×200 or over 2048×2048 (415 IMAGE_DIMENSIONS); decoding runs under a semaphore of two; the image is downscaled to 256×256 with an in-repo box filter and re-encoded as PNG, which drops EXIF; stored at avatars/{userId}/{uuid}.png; the previous object is deleted best effort
DELETE /me/avatar (self) clears it; avatarUrl is a presigned GET valid 24 hours
platform/imagesafe is reusable by R5's logo upload; no new dependency
Rate limit: 10 an hour per user in PrincipalRateLimits(), keyed by ratelimit.PrincipalKey (T-R4.53)
Tests: a small PNG declaring 30000×30000 is refused before decoding; EXIF is gone after upload; a GIF answers 415; replacing a photo removes the old object

T-R4.9 — Signed-in devices

Depends on: — Touches: migrations/00102_add_refresh_tokens_geo_label.sql, server/internal/platform/uaparse/ (new), server/internal/modules/identity/{domain/session.go,application/command/revoke_session.go (new),application/query/list_sessions.go (new),repositories/{refresh_store.go,sessions.go (new)},http/{auth.go,sessions.go (new),geolabel.go (new)}}, api/openapi.yaml, generated code, server/internal/core/router/{router.go,ratelimits.go}, and the tables that pin the operations (permissions_test.go, testdata/permissions.golden, principal_limits_test.go) Size: M Done when:

add_refresh_tokens_geo_label: geo_label text (1 to 80 characters when set), nullable. Down drops the constraint and the column
At issue the label is built from CF-IPCity and CF-IPCountry only when CLIENT_IP_HEADER=CF-Connecting-IP and the request carries CF-Connecting-IP (headers Cloudflare overwrites). A rotation takes the label of its own request when that has one and copies the predecessor's only when it has none, so the list shows where the device last refreshed (W1-APPROACH item 7), not where it first signed in
platform/uaparse classifies a user agent into OS (Mac, Windows, iPhone, iPad, Android, Linux, ChromeOS) and browser (Chrome, Safari, Firefox, Edge, Opera, Samsung Internet); the device label is computed at read time, "Mac · Chrome" (DG-58); no dependency
GET /auth/sessions (self) returns {items}, one row per live family: {familyId, device|null, deviceKind, location|null, lastUsedAt, current}; current is the family of the refresh cookie, which the /auth path receives
DELETE /auth/sessions/{familyId} (self) revokes that family, bumps the caller's session epoch and calls Principals.Forget(userID); another user's family answers 404; the current family answers 409 SESSION_IS_CURRENT (sign out instead). POST /auth/sessions/revoke-others (self) revokes every other family and returns {revoked}; only when it revoked one does it bump the epoch and call Principals.Forget(userID). A request whose refresh cookie names no live session of the caller answers 401 from both writes and writes nothing. The current tab's next request gets a 401 and recovers through the single-flight refresh
Tests: rotation copies the label; revoked and expired families are not listed; a revoked device's access token fails on its next request on the same machine, and within R2's 10 s cache on any other; client.refresh.test.ts is green and untouched; another user's family answering 404 has a test of its own, because /auth is outside the isolation suite

As built:

Files beyond the list: application/app.go, domain/{errors,repository}.go, the login, google_sign_in and refresh commands and application/internal/support/{service,shared}.go (they carry GeoLabel beside UserAgent and IP), http/google.go, and the three tables that pin operations: permissions_test.go (116 to 119), permissions.golden and thePerActorLimits. The handlers are in http/sessions.go, not auth.go.
One transaction, one lock order. Both writes take the lock a rotation takes (SELECT … FROM app.users … FOR NO KEY UPDATE), then resolve the current family, then revoke, bump session_epoch, audit and commit; Principals.Forget runs after the commit, so a resolve between the two cannot cache the old epoch. Lock order is users, then tokens, as in Rotate, so a rotation in flight either commits first and its successor is revoked, or waits and meets the revoked family (RotateRevoked, a plain 401, not reuse). Audit rows: session.revoked (entity refresh_token_family, the family) and session.revoked_others (entity user, diff {"revoked": n}); neither carries a device or location label.
Order of answers: the cookie is checked first (401, so a caller who cannot be placed learns nothing about ids), then the id (404 for another user's, unknown, revoked and expired alike), then whether it is the current one (409).
The current family still refreshes after the bump: Rotate never reads the epoch and signs the new token with the freshly loaded one. A test pins it.
Q3 corrected: a revoke-others with nothing to revoke writes nothing, not even the epoch, so a no-op never 401s the caller's other tabs. The original text bumped always.
Contract: deviceKind is computer|phone|tablet|unknown (never null), device is null and deviceKind unknown when neither the system nor the browser is recognised, the list is capped at 100 with the current session first and the rest by lastUsedAt then familyId, location is one string, "City, CC". No x-resource on familyId: /auth is outside the scoped trees and the isolation suite, so server/tests/sessions_flow_test.go carries the cross-user 404. The 401 uses the existing UNAUTHORIZED code.
Rate limits: the two writes are in PrincipalRateLimits() (10 a minute and 60 an hour, 5 and 30), keyed by the user. The list takes none. None mints a credential, so theCredentialMinters is unchanged.
Location: identityhttp.WithGeoLabel follows WithRefreshCookie in the chain and does nothing unless CLIENT_IP_HEADER names CF-Connecting-IP, and then only for a request that carries that header. The city is percent-decoded, cut to printable text on one line, at most 70 characters; the country is two letters, XX dropped. The label is stored with the token, never logged and never put in audit_log.
uaparse answers from closed lists only. No part of the header reaches a result; a test walks random agents and requires every part to be a member of the lists. An iPad that asks for desktop sites sends a Mac agent and reads as "Mac · Safari".
Residual risks (R-06 in 30-risks.md): every epoch bump 401s all of the caller's open tabs at once; two tabs on one device may refresh inside one round trip, and the second trips reuse detection and revokes that device. Two revokes in quick succession can leave a retried request with a second 401, which shows the sign-in overlay (T-R4.43 disables the buttons while a revoke is pending). F-49 is the durable fix, a cross-tab refresh lock in the client.
Security review (SR-473-1, SR-473-2): a stale, already rotated cookie still names its family here, and does not trip reuse detection as it would on POST /auth/refresh. That is deliberate: a request racing a rotation still resolves, and the alternative (the head row only) would answer it 401 and leave the web to retry after its refresh. It widens nothing: the holder already acts as that device for the bearer's lifetime, and both writes are limited per user. Migration 00102 validates its CHECK inside the ALTER TABLE, under ACCESS EXCLUSIVE; at a school's size that scan is seconds at most. Past a few million rows the expand pattern applies (ADD COLUMN, ADD CONSTRAINT … NOT VALID, then VALIDATE CONSTRAINT).

T-R4.10a — Notifications: store and read API

Depends on: — Touches: server/internal/modules/notifications/ (new: domain, application/{command,query}, repositories, http), server/internal/core/wiring/notifications.go (new), server/internal/core/wiring/wiring.go, server/internal/core/router/{modules.go,server.go}, server/internal/core/router/router.go (the Server literal), server/internal/core/core.go, server/internal/core/jobs/prune.go, server/internal/platform/httpx/hardening.go and server/internal/core/router/tests/hardening_test.go, server/internal/core/router/tests/resource_contract_test.go, server/internal/core/router/tests/testdata/permissions.golden, the isolation world and an entry for each of the five operations (mark-read excused and blind), server/internal/modules/notifications/http/tests/language_test.go, web/tests/units/contract/openapi-contract.test.ts, migrations/00080_create_notifications.sql, migrations/00081_create_notification_preferences.sql, api/openapi.yaml, generated code. core/tests/messages_test.go finds the new package by itself Size: M As built:

Touched beyond the list, as T-R4.0 corrected it on the integration branch: core/router/tests/permissions_test.go (the count of gated operations, 97 to 102) and four new test files: core/router/tests/me_test.go (the tree through the router), core/jobs/tests/prune_test.go, core/tests/jobs_test.go (Serve starts both prunes; removing the line passed every test) and server/tests/notifications_flow_test.go (two users over HTTP, and the start-up path).
The contract is complete for the release. Nine kinds, five events, one closed NotificationParams, a typed NotificationTarget; the kind table in NotificationKind's description is checked against the Go type of each kind by a test. Operation ids: listNotifications, markNotificationsRead, getMySummary, getNotificationPreferences, updateNotificationPreferences, tag me. T-R4.10b and T-R4.22 add no contract line.
Notify is one statement. INSERT … ON CONFLICT (user_id, dedupe_key) DO UPDATE takes the new kind and target, sets read_at = NULL, and under domain.Add sums count and toGrade with the stored values in SQL; domain.Replace stores the new params. Merge is a closed enum whose zero value is refused. A producer passes command.Notify{UserID, Kind, Params, Target, DedupeKey, Merge}; wiring builds the module first and holds it as notificationsApp, so a port is notificationsApp.Commands.Notify. The target of a merged row is the newest notice's, whatever the sums are: a paper with an answer to mark (target grading) followed in the same bucket by one without (target assignment) leaves toGrade 1 and the target assignment. So T-R4.10b's rule on the integration branch, "target Grading when toGrade is above zero", cannot be chosen from one paper's toGrade, and a target read from the assignment's state after the commit races as a count read first would. That task decides whether this statement or the web (from params.toGrade) applies the rule (decided: the web applies it, T-R4.45a).
The switch is applied inside that statement, which the brief did not ask for and the plan needs: producers hold only the Notify port, so nothing else could apply it. The insert is skipped while the user's row for the kind's event has in_app = false. domain.Kind.Event maps the kinds: assignment.opened and assignment.extended fall under assignment.due_soon; class.joined and join_codes.rotated have no switch and are always written.
Params are a sealed set of Go types, one per kind (domain.Submitted, Flagged, Closing, Joined, CodesRotated, Opened, DueSoon, Extended, Ready), encoded through one struct that has exactly the contract's names. Notify refuses params of another kind and values outside the contract's bounds; times are stored in UTC.
A target names what its route needs: assignment and studentAssignment an assignmentId, attempt and result an attemptId; grading and classes need neither, and either id may accompany any route. Ids are canonical uuids.
Dedupe keys are free text of 1 to 200 characters. The format producers are expected to use is <what>:<id>[:<bucket>], for example submitted:{assignmentId}:{unix seconds / 900} and flagged:{attemptId}; nothing parses it.
The list is a keyset on the uuidv7 id. before is declared kind: none: it bounds the caller's own page and looks nothing up. The page is 20 by default and 50 at most; the store asks for one row more to answer nextBefore.
Mark-read answers 204 whatever matched. One command takes 1 to 100 ids, another marks all; an absent ids is the second, and an empty list is refused, so no id can never mean every row. read_at keeps its first value. No operation answers 403 or 404 for an id.
Preferences are all five switches for every role. GET fills inApp: true, email: false for a switch never saved; PUT takes each event exactly once in any order (the schema refuses an unknown event and any count but five, the handler a repeated one) and answers them in the enum's order.
updated_at moves by the trigger on both tables (spec §13.2), so a mark-read moves it too; created_at, the id and the place in the list never move on a merge.
Retention: jobs.PruneNotifications runs at start-up and daily under its own one-minute budget and deletes rows first written more than 180 days ago, strictly.
The isolation suite's case for mark-read is excused and blind, as planned, so the proof that one user cannot read or mark another's is elsewhere: the two-user integration tests in notifications/repositories/tests and the HTTP flow in server/tests/notifications_flow_test.go. The suite's snapshot of the other teacher now includes their notifications.
The migrations are named NNNNN_… and must be numbered before CI: goose refuses a file whose prefix is not a number. Neither depends on the other. Done when:
create_notifications: id uuid PK DEFAULT uuidv7(), user_id FK users ON DELETE CASCADE, kind text (dotted key, ≤64), params jsonb NOT NULL DEFAULT '{}' (object, ≤4 KB), target jsonb (object, ≤1 KB), dedupe_key text NOT NULL (≤200), created_at, updated_at, read_at; UNIQUE (user_id, dedupe_key); indexes (user_id, id DESC), (user_id) WHERE read_at IS NULL and (created_at). The app role gets SELECT, INSERT, UPDATE and DELETE by migration 00009's default privileges; no statement. Down drops the table
create_notification_preferences: (user_id FK CASCADE, event text, in_app boolean NOT NULL, email boolean NOT NULL DEFAULT false, updated_at, PRIMARY KEY (user_id, event)) with CONSTRAINT notification_preferences_event_check CHECK (event IN ('attempt.submitted','attempt.flagged','assignment.closing','assignment.due_soon', 'result.ready')), one key per switch of T-R4.44 and T-R4.45 (assignment.due_soon is the student's "Test due soon", which also governs assignment.opened and assignment.extended). R7 and R10 replace this constraint by name. A missing row means the deck's default. email exists now so R7 adds no column. Down drops the table
Contract, all x-permission: self: GET /me/notifications?before=&limit= → {items: [{id, kind, params, target, createdAt, readAt}], nextBefore}; POST /me/notifications/read {ids?} (≤100; absent means all); GET /me/summary → {unreadNotifications}; GET and PUT /me/notification-preferences → [{event, inApp, email}]. NotificationKind and the event keys are enums; target is a typed route (assignment, attempt, grading, classes, result, studentAssignment)
SecurityHeaders adds /me/ to its Cache-Control: no-store prefixes; TestSecurityHeadersOnSuccessFailureAndPreflight asserts no-store on one path per private tree (/auth, /app, /teacher, /admin, /me) and that /public/status keeps its own public max-age
Text is rendered by the web from kind and params in the reader's locale; params are a Go struct per kind, never markup. A name in params is a copy: R5's anonymisation (T-R5.17a) deletes or scrubs notifications that name an anonymised user
Notify upserts on (user_id, dedupe_key) and can merge counts into params; a merge of counts is computed inside the one INSERT … ON CONFLICT DO UPDATE statement, never from a row read first; an integration test of N concurrent calls on one dedupe key pins it
The daily prune in core/jobs/prune.go deletes notifications older than 180 days
The student-payload walk (R3's leak test) covers /me/notifications; the operations join the isolation suite's two-user /me/* pair (user A cannot read or mark user B's): the x-resource enum gains notification, and POST /me/notifications/read declares it for its ids body field
Tests: unit (upsert merge), integration (cursor paging, mark one and all, cap of 100 ids, preferences default), contract; 20-data-model.md records both tables and a new deviation row for params jsonb

T-R4.10b — Notifications: producers and due-time items

Depends on: T-R4.10a, T-R4.11, T-R4.12 Touches: server/internal/modules/{attempts,assignments,classes}/application/ports/ (new Notifier ports), server/internal/modules/attempts/application/{command/submit.go,command/finish.go,internal/support/integrity.go}, server/internal/modules/classes/application/command/enrol_new_member.go, server/internal/modules/classes/application/command/enrol_existing.go (the signed-in student's join), server/internal/modules/notifications/{application/command/materialise_due.go (new),repositories/due.go (new)}, server/internal/core/wiring/*.go, web/src/features/assignments/pages/AssignmentIntroPage.tsx, web/src/lib/i18n/locales/, web/tests/units/student/intro.test.tsx Size: M As built (2026-10-10):

No migration, no contract line. The unique key (user_id, dedupe_key) and the indexes class_members_user_idx, assignment_classes_class_idx and assignment_students_user_idx serve everything below; 00102 is not claimed. The contract changed in prose only: the descriptions of extendAssignment, setStudentOverrides, listNotifications and getMySummary say what notify and the due-time write now do.
Telling after commit is one helper. shared/cqrs.Announce runs a build that reads what a notice says and returns the Notify commands, then delivers them in order under a ten-second budget on a context that keeps the request's values and not its end. A failure is logged once with the count undelivered and never returned; a nil handler reads nothing. The Notifier ports in attempts, assignments and classes are the notifications Notify handler, as classes' already was. WithNotifier is the only wiring (core/wiring), so an application built without one tells nobody and every existing test is unchanged.
Who hears of a paper. visibility.PaperReaders is visibility.Papers read the other way: the assignment's creator, and the teacher of a target class when the student is a member of a class they teach, an account they created, or a named target of an assignment they created. The plan's "the teachers of its target classes" is read as the teachers of the target classes the student is in: otherwise a teacher of class Y would be told a paper they cannot open. A test holds PaperReaders equal to Papers over a world with every route to a student. Disabled teachers are not written to.
Attempts return what a write brought about. Submit, Save, Flush and ExpireIfDue return domain.Milestones{AttemptID, HandedIn, Flagged}; Finish is announced by its command with Graded. deriveFocusLoss reports the false-to-true move of flagged with RETURNING NOT old.flagged AND new.flagged, so the integrity policy flags a paper once and a later absence on a flagged paper tells nobody; the limit's own UPDATE flagged = true reports the same way. A teacher's flag and a warn policy never reach the code at all. A paper closed by time (timed_out) is a hand-in. The command then asks Briefing(attemptID, now) for the title, the student's name, the focus-loss count, whether an answer still waits for a mark (toGrade is 0 or 1 per paper, summed by domain.Add in SQL), whether the review policy shows the score under the student's own close, and the readers. A voided or missing attempt answers ErrNotFound and nothing is sent.
attempt.submitted is keyed submitted:{assignmentId}:{unix / 900} with Add; its target is the assignment (the web sends a positive toGrade to Grading, T-R4.45a). attempt.flagged is keyed flagged:{attemptId} with Replace and targets the attempt. class.joined is keyed joined:{classId}:{studentId}: EnrolResult gains StudentName and TeacherID, read in the enrolment's transaction, and both EnrolExisting and EnrolNewMember tell once it commits, not for a repeat join. classes.teacher_id is NOT NULL, so a class always has a teacher to tell.
result.ready on finish is sent when Finish succeeds and review_show_score AND (release = 'on_submit' OR now >= the student's close); a refused finish sends nothing and a second finish sends the same key again (the store keeps one row, unread again). The row holds the title; the target holds the attempt and the assignment; no score or band is read into it, and a test checks the stored JSON.
assignment.extended. extendAssignment with notify tells every enabled, student-like student of a published assignment whose own close the extension changed: those without an override and those whose override closes before the new close (an override at or after it keeps its close and hears nothing). setStudentOverrides with notify tells the students named when the request sets extendBy or closesAt and their override now closes after the assignment's own; attempts and time limit move no close and tell nobody. The key is extended:{assignmentId} with Replace, so the latest close replaces the earlier notice. The recipients are read after the commit, so a student is told the close in force then.
MaterialiseDue(userID, now) runs first in GET /me/summary and GET /me/notifications, behind an in-process throttle of five minutes per user (a failed run forgets its slot; a map above 4,096 entries drops the expired). It reads the due notices in one statement (Postgres.Due) and writes them in one (InsertAbsent, ON CONFLICT DO NOTHING under the same switch Upsert applies), so a row the user already holds stays as it is, read or not. A failure is logged by the transport and does not fail the read. Moments lie in (now − 7 days, now]:
- opened: greatest(opens_at, published_at), while the student's close is ahead;
- due soon: the student's close − 24 h and − 1 h (schedule.CloseOf with their override and the early close), the day's only while the hour's moment is still ahead, so a first read inside the last hour yields the hour's alone (decided at review, Q1), while the close is ahead, they have no hand-in (a submitted, timed-out or graded attempt, or one left in progress past its deadline) and have an attempt left (non-voided attempts below max_attempts plus their extra attempts), and the test was available at that moment;
- closing (teachers): the assignment's close − 1 h, with the number of enabled student-like members of its roster that visibility.Papers shows the user, who have no hand-in and whose own close is the assignment's (an override that reaches later leaves a student out); nothing when the count is 0;
- ready (students): the student's close for an after_close release that shows the score, for each handed-in attempt with no answer waiting for a mark. The keys of the reminders and of the closing notice name the close (DueSoonKey, ClosingKey), so a close that moves earns them again. A student is a target only if enabled and in app.student_like_roles. The read skips an assignment whose close is before the lookback, since no kind can still be earned from it; on 12,100 users, 3,000 assignments and 45,000 attempts a student's read runs in about 1.1 ms and touches about 150 buffers, a teacher's in about 1.2 ms (EXPLAIN at the size production will reach is T-R4.52's).
The Test intro reads the "Test due soon" switch through useDueSoonOn, only in the scheduled state; the line stays T-R3.8's while the switches are unread, unreadable or off.
Decisions the plan did not make (build the default; each is one line to change):
- result.ready at a close is sent for a paper that needs no marking, even if the teacher never "finishes" it; a paper waiting for marks is announced by Finish instead;
- attempt.submitted counts a timed-out paper, and a paper closed by the focus limit, as a hand-in;
- the audience of a paper is read after the commit, so a teacher who stopped teaching a class between the two is not told. Done when:
Each producing module declares a Notifier port typed as the notifications Notify handler (AGENTS: a cross-module need is a port typed as the other module's handler); calls run after the producing transaction commits, and a failure is logged, never returned
Teacher recipients are the assignment's creator and the teachers of its target classes, deduplicated, each subject to their preferences:
- attempt.submitted (default on): dedupe submitted:{assignmentId}:{15-minute bucket}, params {title, count, toGrade}, target the assignment; the web sends a positive toGrade to Grading for a reader who can grade (T-R4.45a, "As built")
- attempt.flagged (default on): when the integrity policy flags an attempt, dedupe flagged:{attemptId}, params {studentName, title, focusLost}, target the attempt sheet
- assignment.closing (default on): a due-time item at close − 1 h while someone has not handed in, params {title, notSubmitted}
- class.joined (no switch; the deck draws none): on a join by code
Student recipients:
- assignment.opened, assignment.due_soon (close − 24 h and − 1 h, while the student has not handed in and has attempts left) and assignment.extended (T-R4.12 with notify on), all under the "Test due soon" switch
- result.ready under "Result ready": on finish grading when the review policy shows the score now, or as a due-time item at close for after_close. It carries the attempt id and the title, never a score or band: the web shows the score from the result query, which applies the policy in force when it is read
MaterialiseDue(userID, now) runs inside GET /me/summary and GET /me/notifications, at most once per five minutes per user (in-process map); it inserts items whose trigger time lies in (now − 7 days, now] with ON CONFLICT DO NOTHING; there is no timer and no background job
Effective close times include per-student overrides (T-R4.12) and early closes
The Test intro's line under "Opens …" (student.intro.opensHint) becomes the deck's "We will notify you when it opens." for a student whose "Test due soon" switch is on, now that assignment.opened exists; with the switch off it stays T-R3.8's "You can start once it opens." (web/src/features/assignments/pages/AssignmentIntroPage.tsx, locales, web/tests/units/student/intro.test.tsx)
Tests: every producer (unit and integration); materialisation boundaries (exactly T − 24 h, closed early, extended, an override for one student); preferences off writes nothing; a teacher of class X receives nothing about class Y; no result.ready row holds a score
attempts/application/tests/events_test.go is green and untouched; attempts unit tests run before and after (high-risk area)

T-R4.11 — Assignment review options, the note to students and the live lock

Depends on: — Touches: migrations/NNNNN_add_assignment_review_options.sql, migrations/NNNNN_add_assignments_student_note.sql, api/openapi.yaml (ReviewPolicy, Assignment, AssignmentInput, StudentAssignmentDetail, ErrorCode, the student result schema), generated code, server/internal/modules/assignments/{domain/assignment.go,application/command/update.go,repositories/write.go,repositories/student.go}, server/internal/modules/attempts/{application/query/result.go,repositories/result.go}, the R3 student result page in web/src/features/results/, web/src/features/assignments/pages/AssignmentIntroPage.tsx (the note block), web/tests/units/student/intro.test.tsx Size: M As built (2026-10-08):

The migrations are 00099 and 00100, the next numbers after 00098 on work/redesign-r4 at 9ca8d64f. They were 00093 and 00094 when cut from d6c5f8cc and were renumbered when T-R4.62a landed 00097 and 00098 (T-5); renumber them again if another file lands first. 00099 adds review_release text NOT NULL DEFAULT 'on_submit' with the named check assignments_review_release_check and review_show_class_average boolean NOT NULL DEFAULT false; 00100 adds the nullable student_note with assignments_student_note_check (char_length(btrim(student_note, <the 25 whitespace code points of shared/answered>)) BETWEEN 1 AND 500, QA-11-2: btrim alone strips only the space, so a note of a tab or a newline passed the check while the command dropped it), added with the column. StudentNoteOf trims that same set, so the check, the answered rule and the Go trim agree; a test pins the three. Every default is a constant, so nothing is rewritten and the previous release's insert keeps its meaning. D-34 and D-35 record them (D-33 is T-R4.62a's).
Contract. ReviewRelease (on_submit, after_close); ReviewPolicy (responses) requires release and showClassAverage, and ReviewPolicyInput (AssignmentInput.review) makes both optional; AssignmentInput.maxAttempts has maximum: 99; studentNote is optional and nullable on AssignmentInput and on StudentAssignmentDetail, and required and nullable on Assignment; the result gains optional releasesAt and classAverage (0 to 100); ErrorCode gains ASSIGNMENT_LOCKED, the 409 of updateAssignment. No operation was added, so the permission golden, the operation count and the isolation table are unchanged.
The update is partial for the three new fields. release, showClassAverage and studentNote are json.RawMessage or optional on the wire; WriteInput carries ReleaseSet, ClassAverageSet and StudentNoteSet, and the UPDATE reads CASE WHEN $set THEN $value ELSE column END. The SPA's full-replace body therefore keeps the stored values, and studentNote: null clears the note. A create takes the defaults. The 500 characters are counted before trimming at the contract and after it in WriteInput.Validate; the command stores NULL for a note that is blank once trimmed of the same whitespace.
The lock is requireUnlocked, called right after lockForUpdate, before publishedTestFor and versionStillFree. While the stored row's derived status at in.Now is open, a change to testVersionId, durationMinutes or maxAttempts answers ASSIGNMENT_LOCKED, with or without attempts, whichever version it names; sending the stored value is not a change. A scheduled or closed assignment with attempts still answers VERSION_LOCKED, and its timing stays editable. The status flips exactly at opens_at (open) and closes_at (closed), and TestTheLockFlipsExactlyAtTheEdgesOfTheWindow pins both. Two existing tests re-pointed an open assignment; they now do it on a scheduled one.
after_close reads, in LoadResult(ctx, attempt, now), the stored policy and the close. Until now reaches it, the effective flags are all false, so the existing gates select no score, mark, key or explanation, and the grader's comment is not selected either (default for Thuong). releasesAt carries the close; review.release and review.showClassAverage are echoed as stored. The student card's score flag is review_show_score AND (review_release = 'on_submit' OR now() >= close); the intro's detail carries the stored flags, the release and the note. Pending manual answers and transcripts keep their own gates.
The close is least(closed_at, closes_at), not coalesce(closed_at, closes_at) as the approach wrote it: closing an assignment already past its window sets closed_at after closes_at, and DerivedStatus calls that closed at closes_at. shared/schedule gains CloseOf(override) (SQL), Close (Go), Override and Window.WithOverride; T-R4.11 passes no override and T-R4.12 fills it.
classAverage is the mean over targeted, enabled students (assignment_classes through class_members, or assignment_students, the roster rulesQuery uses) of each student's best score_earned / score_total among graded attempts, as a percent rounded to two decimals. voided, submitted, timed_out and not-started students count nothing; a student who left the class or was disabled counts nothing. It is absent below ClassAverageFloor (3) qualifying students, while the reader's result is withheld, before the assignment's close and with the switch off. The page prints at most one decimal.
LoadResult names two closes, readerClose and assignmentClose, both schedule.Close(closesAt, closedAt, nil) today. Withheld and releasesAt read readerClose; classAverageOf is told whether assignmentClose has passed. T-R4.12 passes a student's override to readerClose alone (R11-2).
The class average's plan, measured on a seeded scratch database (EXPLAIN (ANALYZE, BUFFERS) of classAverageOf's statement for an assignment that targets three classes and five named students, 125 students, 194 graded attempts; the database was dropped afterwards). No index was added.
- 3,000 students in 75 classes of 40, 300 assignments, 24,250 attempts (about 8 per student): the planner reads each of the 125 roster students through attempts_student_started_idx and filters the assignment and status. 2.7 ms, 1,604 buffers, all shared hits.
- The same with 3,000 assignments and 240,250 attempts (89 MB): attempts_assignment_status_idx (assignment_id, status) is the access path, one search that returns the 194 rows from 10 buffers. 1.8 ms, 634 buffers.
```
Aggregate                                        actual time=1.5  Buffers: shared hit=634
  GroupAggregate on at.student_id                rows=122
    Hash Join (at.student_id = m.user_id)        rows=194
      Index Scan using attempts_assignment_status_idx on attempts
                                                 rows=194  Index Searches: 1  shared hit=10
      HashAggregate over the roster              rows=125  shared hit=39
        Hash Join: Bitmap Index Scan on assignment_classes_pkey x Seq Scan on class_members (shared hit=35)
        Seq Scan on assignment_students          shared hit=1
    Index Scan using users_pkey                  rows=1  loops=194
Execution Time: 1.765 ms
```
- class_members is read by a sequential scan, because 3,000 rows are 35 buffers. With sequential scans disabled the roster goes through assignment_classes_pkey and class_members_pkey (class_id leads) with a Bitmap Index Scan of 40 rows per class, and the statement runs in 1.0 ms, so the primary key is the path once the table outgrows a page scan. That one is a diagnostic and not what the planner picks at this size.
Web. The intro draws the teacher's note between "Before you start" and the action, as the Student deck does (initials circle, "Note from {name}", the text), only when present, as plain text with its line breaks. The score sentence follows release ("after the test closes"), which T-R4.27a had listed; its preview shares studentRules.ts, and the rules input takes a release that may be absent. The result page says when a withheld result is released, in the lock line and the summary, and draws one muted line under its sentence, "Class average: 62%." The Student deck draws no class-average line; the Tech Lead was told. Fourteen test files that carry a review policy were swept in their own commit.
Review REV-11 (APPROVE WITH NITS) found no student leak, withholding at selection time, the lock under the row lock, and DDL, scoping and isolation unchanged. Its fixes: R11-2 above; R11-3, the plan above; R11-4, StudentAssignmentDetail.review says in the contract that the intro's flags are the stored ones and take effect only on the result; R11-1, the floor of 3, is recorded as an exposure in DG-137 and listed for Thuong's sign-off; R11-5, the Downs stay.
Verification VER-11 (PASS WITH FINDINGS) found withholding, the class average, the lock, the note, the web at 360 and 1280 in vi and en, the migrations and three mutants sound. Fixed here: QA-11-2, above (the check's whitespace); QA-11-3, clockTime takes the locale and writes the day as "12 Oct" in English, so the withheld result's "at 02:34, 12/10" no longer reads as December 10th (Vietnamese keeps "12/10"). Logged outside this task: QA-11-1, a NUL in any free-text field answers 500, which predates it; O1, the average shows with showScore off (T-R4.27a's brief); O2, the 500 characters are counted before the trim, which the contract says.
Not built here: the teacher's field for the note and the release switches (DG-71, T-R4.27a and the Settings tab), and the extension of the close by an override (T-R4.12). Done when:
add_assignment_review_options: review_release text NOT NULL DEFAULT 'on_submit' CHECK IN ('on_submit','after_close') and review_show_class_average boolean NOT NULL DEFAULT false; constant defaults, so no rewrite and no fill trigger. Down drops both
ReviewPolicy gains release and showClassAverage: a response schema with both required and a separate input schema with both optional; the MSW fixtures that carry a review policy (about 14 files) are swept in the same pull request as a mechanical commit. AssignmentInput.maxAttempts gains maximum: 99
While the derived status is open, a PATCH changing testVersionId, durationMinutes or maxAttempts answers 409 ASSIGNMENT_LOCKED (DG-65: only "Test & timing" locks)
With after_close, the result withholds score and answers until the effective close, using the existing withheld path
The student result gains an optional classAverage when showClassAverage is on, the window has closed and at least three target students have a graded attempt; it is an aggregate of best graded attempts. Leak review in the PR; the payload-leak key list is unchanged
add_assignments_student_note: student_note text (1–500 after trim), nullable, so the R3 binary keeps inserting. Down drops it. Assignment and AssignmentInput gain nullable studentNote; StudentAssignmentDetail gains it, and this task draws it on R3's Test intro between "Before you start" and the action, only when present (the Student deck's "Note from …": the teacher's initials, "Note from {teacherName}", the text). T-R3.8 left it out: the contract had no field to read. Leak review in the PR: text the teacher wrote for students, no new key on the payload-leak list. The authoring field is placed by a new DG entry (open item)
Tests: unit for the release rule and the three-student floor; integration for the lock and for the note round trip (teacher write, student read); a web unit test for the class average line (vi first)
The five canaries and the attempts module's unit tests run on the branch point and on the last commit, both runs in the PR (high-risk area)

T-R4.12 — Extensions and per-student overrides

Depends on: — Touches: migrations/00101_create_assignment_student_overrides.sql, api/openapi.yaml, generated code, server/internal/shared/schedule/close.go, server/internal/modules/assignments/{domain/{overrides,errors,repository}.go,application/{app.go,command/{extend,set_overrides,delete_override}.go,query/overrides.go},repositories/{overrides,student}.go,http/overrides.go}, server/internal/modules/attempts/{domain/repository.go,application/query/get.go,repositories/{store,result,review_review}.go} (12a); server/internal/shared/schedule/deadlines.go (new), server/internal/modules/assignments/{domain/overrides.go,repositories/{overrides,reopen,student,write}.go}, server/internal/modules/attempts/{domain/{attempt,commands,monitor,repository}.go,application/internal/support/service.go,http/admin_attempts.go,repositories/{store,monitor}.go}, server/internal/core/maintenance/windows.go (12b); server/tests/{join_and_take_flow,isolation_cases,isolation_world}_test.go, server/internal/core/router/tests/{permissions,resource_contract}_test.go and testdata/permissions.golden, docs/quizzivy-spec-v0.3.md, docs/plan/{20-data-model,60-backend-architecture}.md Size: L, shipped as two pull requests (decided when it started, 2026-10-10). Split:

12a (feature/t-r4-12a-overrides, migration 00101): the table, extendAssignment, setStudentOverrides, listStudentOverrides and deleteStudentOverride; the student's card and intro, startOrResumeAttempt and the result's reader close and attempt count under the student's override; the isolation entries, the permission golden and the join_and_take_flow_test.go case. Nothing in 12a writes app.attempts, so an attempt already in progress keeps the deadline it has until 12b.
12b: the recompute of in-progress deadlines under the assignment's lock and each attempt's row lock, the monitor's "Extended to …" and R1's maintenance extension over override close times. It is the part that writes attempts while a student is sitting, so it is reviewed on its own, with the concurrency tests the Senior Tester named.

Each "Done when" line below carries the pull request that closes it. As built (12a, 2026-10-10):

As built, the closed guard (F2 of #493's review, DG-160). updateAssignment could move the close of a window-closed assignment ahead, which made it open again as assignment.updated, without reopenAssignment's required reason and its assignment.reopened audit row. The web locks the Window card of a closed assignment (T-R4.26); the API now refuses it as well.

The rule. An assignment that is closed at the request's clock (in.Now, as the open lock judges it), by its window or by an early close, stays closed. schedule.Reopens is true, and the update answers 409 ASSIGNMENT_CLOSED, when the saved window would make it scheduled or open, or would start after the early close the row keeps. That last pair is one the schema refuses (closed_at >= opens_at), which answered a 500 before.
The code. ASSIGNMENT_CLOSED is the one extendAssignment and setStudentOverrides already answer for a closed assignment ("reopened, not extended"), so updateAssignment and reopenAssignment take complementary sets as extend and reopen do. ASSIGNMENT_LOCKED says the assignment is open and its test and timing are locked, which is the opposite case. No new code, so the contract change is text only (the description and the 409), and no operation, permission or isolation entry moves.
What stays allowed, and why. Everything that leaves it closed: the stored window (a review-options or note edit re-sends it), an earlier close, a close still in the past, closeNow, and every other field, which is how the plan has it (DG-65 locks only the open case). A later close on an assignment closed early also stays allowed: the early close is kept and never lifted by a save (closeNow is an action, TestClosingEarlyIsRecordedAndDoesNotReopen), so the assignment is still closed, nothing opens, and the review-options flow already saves that shape.
Found, and fixed below (F-63). closeNow beside a window that opens ahead answered a 500 from the same closed_at >= opens_at check on every status but a closed one.
Tests. domain/tests/reopens_test.go (the rule, edge by edge), repositories/tests/closed_guard_test.go (integration: the refusals write nothing and no audit row after the creation, the permitted saves, early close, and the instant the close passes; mutating the guard away fails three of the four), http/tests/language_test.go (the 409, in both languages) and server/tests/assignment_closed_guard_flow_test.go (e2e: refusal, permitted edits, reopen, then a later close on the open assignment).

As built, closeNow before the window opens (F-63). closeNow sets closed_at to the request's Now, and the schema requires closed_at >= opens_at (migration 00018), so three shapes answered a 500: a PATCH of a scheduled assignment with closeNow, a PATCH of an open one with closeNow and opensAt moved ahead, and a create with closeNow and a future opening.

Decision. The contract stands, so the code changes. A create ignores closeNow ("PATCH only"): Create clears it before validating and no longer writes closed_at at all (the column is gone from its INSERT, and so is Schedule.ClosedAtOf). WriteInput.Validate gains a pure rule, CloseNow && OpensAt after Now, answering 400 VALIDATION_FAILED with details.closeNow, which covers every status. The check is on the request's clock, the same value the update stores as closed_at, so it is exact.
What moved in the closed guard. On a closed assignment, "closed now beside a window that opens later" is the 400 and no longer the 409, because validation runs before the transaction. The 409 stays for a window that opens after an early close the row already keeps, with no closeNow.
Tests. domain/tests/close_now_test.go (the rule at a nanosecond ahead, now and behind), repositories/tests/close_now_test.go (the three PATCH shapes, the permitted close, a create that ignores closeNow for a scheduled, open, closed and draft window; with the rule removed the first test sees the 23514), and server/tests/assignment_closed_guard_flow_test.go (e2e: the 400 with details.closeNow, the create answering 201 and scheduled). The guard's test counts every audit row after the creation, so a refusal that wrote any is caught (F-63's nit).

T-R4.13 — Duplicate, item analysis and results export

Depends on: T-R4.7 Touches: server/internal/modules/assignments/{application/command/duplicate.go (new),domain/{assignment,commands,repository}.go,http/{assignments,duplicate}.go,repositories/{assignments,duplicate}.go}, server/internal/modules/attempts/{application/{app.go,ports/zones.go,query/{item_analysis,results_export}.go,internal/support/service.go},domain/{analysis,repository}.go,http/{item_analysis,results_export}.go,repositories/analysis.go}, server/internal/platform/tabular/csv.go (new), server/internal/core/{wiring/wiring.go,router/ratelimits.go}, api/openapi.yaml, generated code, server/internal/core/router/tests/testdata/permissions.golden, server/tests/{isolation_cases,results_flow}_test.go Size: M As built (2026-10-10):

No migration, no new ErrorCode. The contract gains three operations, DuplicateAssignmentInput, ItemAnalysis and ItemAnalysisItem, an optional Assignment.questionCount, and on listAssignments the shared q parameter and classId as a list. The pins move: 113 operations to 116, 14 teacher lists to 15 (item analysis, which declares x-resource-list: version-question), the Assistant's refusals stay 38 (it holds both permissions), and PrincipalRateLimits() gains GET /teacher/assignments/results.csv, 10 a minute and 60 an hour per actor (a heavy read that the plan did not limit; the 20000-row cap bounds one call, the limit bounds the calls). The permission golden gains the three lines and no other.
Duplicate is one INSERT … SELECT from the original, so a column the copy must carry is named once. The copy pins the same test and version, keeps the time limit, attempts, both shuffle flags, the five review options (release and showClassAverage included), the integrity policy and the note to students, opens at the caller's now and lasts closes_at - opens_at of the original, is a draft (published_at NULL, closed_at NULL) owned by the caller, and is assigned to classIds and to no student by name. An early close, the original's overrides and its attempts are not copied. classIds may be empty. The original must be reachable (visibility.AssignmentIDs, or any under scope.all) or the answer is 404; its version must be one the caller may assign, by publishedTestFor as createAssignment applies it, so a teacher who reaches an assignment through a class and does not own its test answers 409 TEST_NOT_PUBLISHED (open question); a class the caller does not teach answers 400 on classIds, as an unknown one does. Audited as assignment.duplicated with sourceId.
Item analysis ranges over papers, one per student the caller reaches (visibility.Papers): the student's latest attempt that is handed in (submitted, timed_out, graded) and not voided, so a retake replaces the first sitting, a voided retake changes nothing, and a paper still in progress is not counted. handedIn counts them. For each question of the pinned version, numbered across sections as the grading queue numbers them, answered counts the papers whose saved answer says something (answered.SaysSomething), and correctRate is the papers that earned the question's full points (final_score >= points, for an auto-marked and a manually marked answer alike) over the papers that have a mark for it. A question left unanswered counts against it; a manual answer with no mark yet counts for neither side; a question with no marked paper has a null rate and sorts last. Order: rate ascending, nulls last, then number. The prompt excerpt is the plain prompt with its whitespace collapsed, cut at 140 characters. Overdue attempts are closed before the read, as the monitor does.
The export writes the monitor's roster, not only the papers: one row per target student the caller reaches (the classes they teach, the individual targets they reach, everything under scope.all; a disabled student has none), so a student who has not started has a row with status "not started". A member who is not student-like (an Admin who takes tests and joined by code) has a row only once they have an attempt on the assignment, which is the grading queue's rule (a strict student, or an existing paper under the teacher's reach); the monitor draws its roster by the same rule since F-69, so the two list the same accounts. The attempt that stands for a student is the monitor's: the latest that is not voided, else the latest. Class is the names of the target classes the caller reaches that the student belongs to, sorted and joined by ; (empty for a student named alone). Version is the number. Score, Max and Percent (one decimal) are filled when the attempt is handed in and no manual mark is outstanding, so a paper awaiting its teacher has none; Submitted is in the caller's own zone (identity EffectiveZone through a new ports.Zones, wired with WithZones as the dashboard's is), the header names the zone, and a zone that cannot be resolved falls back to Asia/Ho_Chi_Minh (a fixed +07:00 when tzdata is missing) instead of failing the download. Headers, status words and Có/Không follow Accept-Language, Vietnamese by default. Overdue attempts are closed first.
Limits and refusals. Departure from the plan's "streams": the file is built in memory and written once, so the status is decided before the first byte; the bound that makes that safe is 20000 rows (the query reads one more to tell), a few megabytes at most. Over it is 422 VALIDATION_FAILED with details.ids. ids is 1 to 50 unique uuids (the schema, so 400 otherwise); one id the caller does not reach, or that does not exist, is 404 for the whole request, as a missing one answers, and nothing is read. Content-Disposition is not in the CORS exposed headers (httpx is outside this task), so the SPA names the file itself.
platform/tabular holds EscapeCell and a CSV writer (byte-order mark, CRLF, every cell escaped), with no dependency beyond the standard library. A cell whose first character after any leading spaces (space, no-break space, ideographic space) is =, +, -, @, a tab or a carriage return, or one of the four full-width forms ＝＋－＠, gets a leading '; the first two columns of that list are the plan's, the rest the verification strategy's. R5 extends the package with XLSX.
listAssignments. classId repeats (?classId=a&classId=b, at most 50) and keeps the assignments that target any of them; a class the caller does not teach contributes nothing, as before, and EveryTarget lifts that for a caller who holds scope.all and lists their own (T-R4.54's Own() is unchanged: it narrows who the rows belong to, the class filter narrows within them). q keeps the assignments whose test title, or the name of a target class the caller reaches, contains the text, accents and case ignored, with %, _ and \ literal; the facets follow q and the classes, as they followed classId. Every row, and every write's answer, carries questionCount, counted as TestVersion.questionCount counts.
Evidence. Transport tests on the stubbed queries pin the file (BOM, CRLF, headers, both languages, escaping, zones, the 404 and 422 answers, the null rate); integration tests drive the real queries, including exactly 20000 rows and 20001; an end-to-end flow exports, analyses and duplicates through the router. 25 mutants were run, each killed by a named test: in tabular a leading - unescaped, leading spaces not skipped, a row written unescaped; UTC times in the export; in Duplicate a published copy, the note not copied, the original's dates, a fixed window length, an unreached original readable; in the list q unescaped and only the first class; in the analysis pending marks in the denominator, the oldest attempt, "more than full", a voided paper, every student's paper, an unmarked question first; in the export an unreached assignment skipped, the cap off by one in each direction, a voided attempt standing, a score on a paper with marks outstanding, a disabled student, overdue attempts not closed, and the export unlimited per actor. The canaries that apply, publish_snapshot_test.go and TestTheSameClientSeqFromTwoSessionsBothPersist with the rest of their packages, and the attempts unit tests, passed on the branch point 63b05880 and on the head; no web source changed, so the three web canaries were not run. Done when:
POST /teacher/assignments/{id}/duplicate (teaching.assignments.write) {classIds} creates a draft with the same version, window length and rules; a duplicated draft opens now for the original's length; returns 201 Assignment
GET /teacher/assignments/{id}/item-analysis (teaching.grading) → {handedIn, items: [{questionId, number, type, promptExcerpt (≤140), answered, correctRate|null}]} sorted by correctRate ascending, nulls last. An auto-marked answer counts when correct; a manual one counts when it earned full points; an ungraded manual answer does not count. Item analysis declares x-resource-list
GET /teacher/assignments/results.csv?ids= (teaching.grading, ≤50 ids, ≤20000 rows) streams UTF-8 with a BOM and Content-Disposition: attachment; columns Assignment, Version, Class, Student, Email, Status, Score, Max, Percent, Submitted (actor's zone), Focus lost, Flagged
listAssignments gains q, classId as a list and questionCount on its items
x-resource: the duplicate's classIds body field declares class; the export's ids query declares assignment
Every cell goes through tabular.EscapeCell, which prefixes ' to a value starting with =, +, -, @, tab or CR; R5 extends the package with XLSX
Tests: escape cases (=HYPERLINK(…), +1, -2+3, @SUM(A1)), CSV integration, item analysis ordering, isolation for all three
The five canaries and the attempts module's unit tests run on the branch point and on the last commit, both runs in the PR (high-risk area)

T-R4.14 — Grading queue

Depends on: — Touches: api/openapi.yaml, generated code, server/internal/modules/attempts/domain/{repository,grading_queue}.go, application/{app.go,query/grading_queue.go,internal/support/grading_queue.go}, repositories/grading_queue.go, http/grading_queue.go, their new external public test siblings, the permission/resource/isolation inventories and web/tests/units/contract/grading-queue.test.ts. Existing Grade, Finish, Submit, Void, by-question reads and teacher serializers stay unchanged. Size: M As built:

One read-only SQL statement applies both existing reach predicates, counts the full filtered set, orders groups and takes the exact first200 items. Frozen teacher projections enrich that prefix without changing student delivery or Grade/Finish.
New public tests cover historical role reach, filters, both full-count/cap modes, frozen rich keys and media/context, checked rollback/failure cleanup, and actual concurrent Grade plus a fresh queue statement. Committed race fixtures use a second purpose database and retain their owned rows for whole-purpose disposal.
Server CI provisions that second database, binds its app role only to integration, and checks owner/OID and zero connections before ordinary disposal. The required integration command remains unchanged. This task adds no migration or dependency.
Local PG18.6 app-role queue/lifecycle and committed-race verification passed after correcting the audit-absence fixture column; the initial failure remains recorded. Exact-head hosted CI passed the whole regression, isolation, migration roundtrip and final canaries. A separately reviewed real-PG campaign killed 15 SQL variants under both app and migrate roles (30 observations); restored source and retained controls remained exact, and both fresh purposes were normally disposed. The rebuilt grading screen and Finish-recovery browser flow remain T-R4.28.

Done when:

T-R4.15 — Question level, skill and the eight-option cap

Depends on: — Touches: migrations/00087_add_questions_level_skill.sql, migrations/00088_add_test_version_questions_level_skill.sql, api/openapi.yaml, generated code, server/internal/modules/questions/{domain/question.go,domain/input.go,repositories/store.go,repositories/search.go,repositories/facets.go}, server/internal/modules/tests/repositories/{publish_snapshot.go,publish_group_snapshot.go,list.go}, the copy paths server/internal/modules/tests/repositories/{version_draft,duplicate,duplicate_graph,group_copy}.go and the questions duplicate command Size: M Done when:

add_questions_level_skill: level text CHECK IN ('pre_a1','a1','a2','b1','b2','c1','c2') and skill text CHECK IN ('grammar','vocabulary','reading','listening','writing', 'speaking') on questions, nullable (DG-62). Down drops both
add_test_version_questions_level_skill: the same two columns on test_version_questions, nullable, no backfill. Down drops both
Contract: QuestionLevel and QuestionSkill enums; QuestionInput and AdminQuestion gain nullable level and skill; listQuestions gains level[], skill[] and tagMatch=any|all (the default keeps today's meaning) and facet counts for levels and skills; options gains maxItems: 8 (DG-63)
Publish copies level and skill into the version rows, keeping the media.LockForVersionUse and questions.LockForDraftUse ordering unchanged
Test list rows gain skills, the distinct skills of the draft's questions
Rehearsal on a Neon branch reports questions with more than eight options; the cap applies to writes only
Tests: publish_snapshot_test.go green and untouched; a new test beside it shows that changing a bank question's level after publish leaves the version's level unchanged; facet and tagMatch integration; nine options answer 400
High-risk area: tests module unit tests run before and after

As built (2026-10-07): Nullable question and frozen-version metadata, self-excluding level/skill facets, tagMatch, draft skill summaries and copy/restore/publication propagation are complete. The eight-option cap applies to new authoring requests and included imported questions; stored reads and bodyless copies, restoration and publication preserve legacy longer arrays. Migrations 00087 and 00088 add nullable columns without backfill.

F-43 (2026-10-10): TestVersion gains a required skills, the version's counterpart of Test.skills: the sorted distinct non-null skill of the rows in test_version_questions, a group's members included. It is read with the rest of the version (versionColumns), so publishTest, listTestVersions and the publish's own read-back all answer it, and no migration is needed because 00088 already froze the column. Editing the draft or the bank after a publish does not move it (version_skills_test.go, beside the untouched publish_snapshot_test.go).

A fresh local PG18.6 purpose rehearsed up87/up88/down88/down87/re-up and the complete migration universe through 91. Synthetic nine-option bank and published rows retain their content; metadata starts NULL and enum checks reject invalid values. Twelve named public app/migrate integration parents and eight unchanged app-role snapshot/lock/event canaries pass. The legacy canaries' ignored cleanup residue is disclosed; normal disposal of their whole owned purpose is the actual cleanup. No append-only privilege was granted and no test was skipped or weakened. All six retained controls match their before/after full censuses.

A separate read-only Neon child of production actually reports 64 bank questions and 23 frozen questions, with zero oversized-option records in both populations. The complete oversized identity arrays are empty; this is a genuine historical limitation, not seeded production evidence. The nonsuper app role executes only repeatable-read read-only SQL on that child. Its 17 processes joined and its normal exact-ID deletion, absence and other provider metadata equality are independently verified. Cloud migration execution/timing remains the separate release gate; this task does not claim it. The first failed connection-purpose child also has separately guarded normal cleanup and verified absence; its original failure is preserved.

The accepted metadata code at 2659cf56773895d85767c9921c59e764bb13a7ff passed required CI 37590704418. The incoming accepted processing work changes no server, contract or migration input from that verified candidate. Combined exact-head CI is required before integration. This completion record is not a production release.

T-R4.16 — Test versions: publish base, usage, unpublished changes, diff and change note

Split (the Principal, 2026-10-08; recorded by T-R4.16a's pull request): T-R4.16a is the publish base, the usage counts and the change note, with the draft loader split the diff needs; T-R4.16b is the diff, its endpoint and unpublishedChanges. A task that depends on T-R4.16 waits for both halves.

T-R4.16a — Test versions: publish base, usage counts and change note

Depends on: — Touches: migrations/00092_add_test_versions_change_note.sql, api/openapi.yaml (TestVersion, Test, publishTest), generated code, server/internal/modules/tests/{domain/{publish,test}.go,application/command/publish.go,repositories/{publish_publisher,publish_load,publish_groups,group_store,group_mutation,duplicate,store,versions,usage (new)}.go,http/{publish,tests}.go}, server/internal/shared/schedule/schedule.go (new), server/internal/modules/assignments/repositories/{assignments,reopen}.go, docs/plan/20-data-model.md (D-32), the web fixtures the contract change forces Size: M As built (2026-10-08):

The migration is 00092, the next number after 00091 on work/redesign-r4 at 5821b264; renumber it if another file lands first. change_note text is nullable with no default, so the previous release's insert keeps working, and no row is backfilled. The check, test_versions_change_note_check, holds 1 to 200 characters and is part of the ADD COLUMN, so there is nothing to validate. The command trims the note and stores NULL for a blank one (PublishManager.ChangeNote), so the table never meets an empty string. D-32 records it.
testUpdatedAt is a field of TestVersion, because additionalProperties: false rules out a wrapper, and only publishTest's 201 carries it. It is the RETURNING updated_at of the UPDATE app.tests the publish already runs, so it is the value the 00015 trigger wrote inside the publish transaction. A save sent with it succeeds; a save sent with the pre-publish time answers STALE_WRITE (both are in publish_version_metadata_test.go). domain.Version.TestUpdatedAt is a pointer set only by Publish.
publishTest's body is optional, {changeNote} of at most 200 characters, null allowed, and the operation answers 400 VALIDATION_FAILED for a longer note, a wrong type or an unknown field. No operation was added, so the permission golden, the operation count and the isolation table are unchanged.
assignmentCount counts every app.assignments row that names the version, drafts included and whoever created them, through assignments_version_idx. DeleteVersion still relies on the foreign key's RESTRICT.
Test.assignments {live, scheduled, closed} is required on every Test: the list rows and getTest, and so every write's answer. It counts the non-draft assignments that name any version of the test, by the derived status, with live as open. The status rule is one constant, schedule.DerivedStatus in internal/shared/schedule, moved there from assignments/repositories (its list, facets and reopen) and read by tests/repositories/usage.go as well, because a repository may not import another module's repository. T-R4.11 and T-R4.12 change that window rule in that one place. TestATestCountsItsAssignmentsByDerivedStatus covers an early close that has passed, one that is still ahead, a passed window, a scheduled one and a draft.
The loader is split. loadDraft is gone. Publish and Duplicate call lockDraftContent (the row locks, in the order loadDraft took them) and then loadDraftSnapshot(ctx, tx, testID), which only reads. readLockedGroup takes the lock clause ("FOR SHARE OF g", "FOR UPDATE OF g" or none); the snapshot reads groups with none (GroupsPostgres.readUnlocked) and skips lockGroupReadOwner, because lockDraftContent has already share-locked every group of the test, the caller holds the test row, and appendDraftGroup still refuses a group of another section. GroupsPostgres.Get is unchanged. T-R4.16b adds loadVersion and the read-only diff transaction on top of it.
One existing test changed: publish_history_test.go compared the publish answer with the history row by value; it now clears TestUpdatedAt on its copy first. publish_snapshot_test.go and publish_lockorder_test.go are untouched. Done when:
add_test_versions_change_note: change_note text (≤200), nullable. Down drops it
publishTest takes an optional {changeNote} and its response gains testUpdatedAt, the test row's updated_at after the publish transaction, so the builder can keep saving without STALE_WRITE
TestVersion gains assignmentCount and changeNote; list rows gain assignments {live, scheduled, closed} counts for the card's "2 live" line
loadDraft is split into lockDraftContent and loadDraftSnapshot, with the lock clause an argument of readLockedGroup; Publish and Duplicate keep their locks and their order
Tests: the change note (trim, blank, absent, the history), testUpdatedAt against a following save, both counts per derived status, the constraint at its bounds with the previous release's insert still valid, the transport and the router contract; publish_snapshot_test.go green and untouched

Part 2 of 6 of R4 — Teacher workspace (v0.10.0) · Previous · Next

_{Generated from docs/plan/74-r4.md. Edit that file in the repository; changes made on this page are overwritten.}

Generated from the repository's documentation on every push to develop.

Home

Start here

Product

Implementation plan

Redesign (Phase R)

Setup and operations

Design

Team

Code READMEs

Plan 74 R4 Part 2

T-R4.5 — The /teacher route tree

T-R4.6 — Command palette

T-R4.7 — Profile fields and preferences

T-R4.7 — As built

T-R4.8 — Profile photo

T-R4.9 — Signed-in devices

T-R4.10a — Notifications: store and read API

T-R4.10b — Notifications: producers and due-time items

T-R4.11 — Assignment review options, the note to students and the live lock

T-R4.12 — Extensions and per-student overrides

T-R4.13 — Duplicate, item analysis and results export

T-R4.14 — Grading queue

T-R4.15 — Question level, skill and the eight-option cap

T-R4.16 — Test versions: publish base, usage, unpublished changes, diff and change note

T-R4.16a — Test versions: publish base, usage counts and change note

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

T-R4.5 — The `/teacher` route tree