Repository navigation
Classroom Token Hub v2.2.0
Deployed to production 2026-10-09 07:10 UTC as 5ebae62db (release workflow run 37897523165). No migration. Release record: docs/ops/audits/DEPLOY_2026-10-09_5ebae62db.md.
Everything merged to main since v2.1.1, released as 5ebae62db on 2026-10-09 at 07:10 UTC (record). Three untagged releases shipped part of it (SOP-DB-004 §X.4):
381a12d49(2026-10-05 01:25Z): support notifications (#1488), the backup-tool documentation (#1485) and the security fixes (#1486);35bad089a(2026-10-05 05:13Z): the sysadmin UI shell (#1489);1cdbf03da(2026-10-06 03:10Z): teacher-ticket routing (#1491).
The last two have no release record. Against 1cdbf03da, which production runs, this release changes application behavior in four places: #1522, the hall-pass settings gate and preset removal; #1526, under which a purchase needs the money, a collective goal is one buy-in per student, and a collective-goal purchase and the NSF fee can be reversed; #1527, which drops a cross-class query that ran on every page render; and #1528, which removes the sysadmin console's log viewers (logs are read in Grafana). The rest is documentation, tests and CI:
- the P0A migration contract (#1518, #1519, #1521);
- the P0B record (#1523);
- the every-PR deprecated-symbol guard (#1524).
There is no schema migration and no change to the application's Python dependencies (requirements.txt). The only dependency change is the docs-site npm update in #1486 (docs-site/package.json and package-lock.json, build-time only for the static docs site), which shipped in 381a12d49. MINOR under SOP-DB-004 §X.3, because #1522 changes a capability: hall passes are unavailable until the teacher saves settings.
Added
- P0B production-state reconnaissance and baseline (#1495).
docs/ops/audits/RECON_2026-10-06_P0B_PRODUCTION_STATE.mdrecords, from read-only aggregate queries against production at revisionf9a3c7d1e620(2026-10-06 06:08-06:11Z), the timestampedSOP-DB-004§IX.1.7 baseline (row counts per table and class; ledger equals posted snapshot in all 14 class/account pairs). It also records the persisted semantics and runtime writers each of U1-U14 would touch, and twoH5items the owner ruled on 2026-10-06. First, all 854 signature-v1 ledger rows storefeat_code = FEAT-LED-003(the settlement restamp fixed in81ea0fff5); their originating FEAT is taken from the linked creation audit event, and actor attribution is unavailable rather than system. Recording that ruling inDOM-OPS-002is left to U13. Second, 14 of 16 hall-pass logs storepolicy_uuid = 'default'; they are kept as historical facts with their policy terms unavailable, and the live writer is fixed separately in #1522. The queries are indocs/ops/audits/evidence/2026-10-06_p0b-recon/recon_readonly.sql. No PII was read and nothing in production changed. - Deprecated symbols are scanned on every pull request.
DEPRECATED_SYMBOLS.txtwas enforced only by the Schema Change Gate, which runs on pull requests touchingmigrations/versions/**or the model files and skipped the scan forNON-MODEL CHANGE. So a route, template or script that namedClassMembership,is_bundleorget_default_pass_typesmerged unscanned. The scan is now a pytest guard (tests/test_deprecated_symbols_guard.py, detector intests/guards/deprecated_symbols.py) thatpolicy-guardrails.ymlruns on every pull request and push tomainwithout a database. The Schema Change Gate runs the same guard in place of its inlinegrep. The scope now includes first-party JavaScript (*.jsunderapp/,templates/,scripts/andstatic/, excludingstatic/vendor/). Mutation proofs plant near-miss violations: an aliased import, a reflective string, a longer identifier, a template attribute,static/jsand the service worker. The guard also fails on an empty registry, or one that disagrees with SOP-DB-002 §VI. No symbol was added or removed (SOP-DB-002v2.3). - Optional IFTTT email alerts for direct teacher support filings and teacher-escalated student tickets (DOM-SUP-001 v1.8; FEAT-SUP-001 v1.1). The existing app sends one HTTPS request after commit, containing only a fixed event label, opaque ticket reference, and UTC timestamp. Delivery failure preserves ticket success. Setup: SOP-OPS-002 — Support IFTTT Notification Setup; no new worker or schema change.
- Compatibility ruling written into the governing documents.
INV-ARC-008v1.2 removes the "explicitly approved bridge code" allowance from §VI (Student ID Quarantine);DOM-OPS-002v1.11 §6.2A andSPEC-PROD-002v1.4 §VII state that historical diagnostics and reconstruction are read-side interpretation that creates no state;SOP-DB-004v1.2 §VII.8 andSOP-DOC-001v3.25 follow. Documentation only; no code or schema change. - Forward-only revision register, enforced.
migrations/forward_only_register.txtlists every Alembic revision whosedowngrade()raises or does nothing (34 today, including the three attendance/payroll recovery revisionsSOP-DEP-001§XIV named; the prose list had missed the rest).tests/test_forward_only_revision_register.pyderives the set frommigrations/versions(detector intests/guards/forward_only_revisions.py) and fails when the register is missing a revision or lists one that is not forward-only, so a new forward-only revision must be registered in the PR that creates it. Mutation proofs cover direct and conditionalraise, a raise hidden in a helper, no-op spellings, a missingdowngrade(), and a merge that does work; reversible downgrades and pure merges stay quiet.SOP-DB-004v1.1,SOP-DEP-001v2.8 andSOP-DEP-002v1.8 point at it;SOP-DEP-002andSOP-DEP-001no longer cite archivedSOP-DB-009or the nonexistentSOP-DEP-016as dependencies. The "does nothing" test is positive (noop.*or.executecall, directly or through same-module helpers), so logging or control flow around a no-op cannot hide it. The test runs in the migration PR workflow (check-migrations.yml, no database needed), which now also triggers on the register and guard files. No schema or runtime change. - SOP-DB-004: Live-v2 migration and semantic-versioning contract. Defines, for changes made after 2026-10-06, how a change is classified (Migration Class
M0-M4, Historical StateH0-H5, Risk), the compatibility rule for existing history (schema coexistence and version-keyed read interpretation allowed; dual-write, fallback and heuristic interpretation prohibited; unversioned history blocked for an owner ruling), the evidence required before, during and after cutover, the rollback decision (code redeploy only forM0/M1; otherwise snapshot restore or reviewed fix-forward), and when a release is MAJOR, MINOR or PATCH. Documentation only; no schema or code change.SOP-DB-001v1.7 drops "application supports both" from expand/contract Phase 1 to match. - Accessibility Gate: axe-core runs in Chromium on every template-affecting PR, and every changed template must have an accessibility render path. The per-PR check previously ran only the static
tests/test_accessibility.py, which skips every template that extends a layout (so it audited none of the app pages)..github/workflows/accessibility-gate.ymlnow also runstests/test_axe_app_pages.py,tests/test_axe_fixture_pages.pyandtests/test_axe_compliance.pywithAXE_REQUIRE_BROWSER=1(a missing browser fails instead of skipping) whenever a template, CSS, template-driven JS or the harness changes.scripts/check_axe_template_coverage.pyfails the PR when a changed template is neither rendered by the real-route sweep nor by a registered fixture state (directly, or via extends/include/import). Fixture states (tests/a11y_fixtures/) render a template from a deterministic presentation fixture through the real Jinja environment, CSS and JavaScript, under a guard that fails on any SQL statement, and are audited by axe; they prove a supported presentation state is accessible, not that a route assembles it. The route sweep gained the public auth pages, announcements, attendance log, class creation, payroll correction and the student store, rent and insurance pages; 54 fixture states cover the error pages, auth flows, student detail (every tab), claims, issues and the rest.tests/axe_coverage_exemptions.jsonis empty: all 102 templates are covered. SOP-TEST-002 v1.1 §X documents the contract, how to register a state, and the narrow exemption criteria. Gate tests, with mutation proofs:tests/test_axe_fixture_gate.py,tests/test_axe_template_coverage_guard.py. The check blocks merging only once it is marked required in branch protection.
Security
- CodeQL: roster import and unclaim no longer echo exception text.
/admin/upload-studentsand/admin/student/unclaimreturnedstr(error)from anyValueError. They now return a message only if it is inROSTER_ACTION_MESSAGES(app/feats/identity_feat.py), which lists the teacher-facing messages those FEATs raise; any otherValueErrorgets a generic message. Tests:tests/dom/identity/test_roster_action_messages.py, including a guard that fails when a FEAT raises a message missing from the list. - CodeQL: docs redirect to the external site.
_redirect_to_public_docspercent-encodes the reader-supplied path, refuses.and..segments, and checks the target still has the configured docs host. Tests intests/dom/docs/test_docs_platform_split.py. - Docs site npm advisories. The
docs-sitelockfile movesfast-urito 4.2.1,brace-expansionto 5.0.12 andhttp-cache-semanticsto 4.3.0, closing Dependabot alerts #78-#82 and #84 (supersedes #1458). Alert #83 (braces, no patched release) is build-time only for the static docs site and is left for dismissal.
Removed
- Log reading is gone from the sysadmin console; logs are read in Grafana (owner ruling 2026-10-07;
SPEC-OPS-0041.4).- Removed:
/sysadmin/combined-logs,/sysadmin/logs, the redirects/sysadmin/error-logs,/sysadmin/logs-testingand/sysadmin/network-activity, the Logs navigation link, and the dashboard's View Logs action and Recent Errors panel. Their templates and the service readersget_error_eventsandget_recent_error_eventsgo with them. - Why.
/sysadmin/logsdisplayed nothing in production even though its log file was being written. The combined-logs Network Activity tab only repeated the error rows. The full-suite run before this release also failed on hard-coded colours in the unused log template. - Unchanged: the
operational_eventstable and its writer.
- Removed:
Fixed
-
The store no longer lets a student spend money they do not have, and a collective goal is one buy-in per student (owner rulings 2026-10-07).
- What happened. On 2026-10-07 a student moved all of checking to savings, then bought 32 units of a $750 whole-class collective goal. The purchase posted $24,000 into a negative balance, a $25 non-sufficient-funds fee was added, and 32 buy-ins went to that one seat. The documents of the time prescribed exactly that: a purchase protection could not cover went through and drew the fee (
SPEC-ECON-0032.2 §4.5.1.1A,FEAT-LED-0000.3). Nothing limited a collective goal's quantity. - Now. A purchase proceeds only when checking, alone or with a full overdraft-protection transfer from savings, covers it. Otherwise it is refused before anything posts, with no fee, as a declined card purchase would be (
FEAT-STOR-0013.2,SPEC-ECON-0032.3,FEAT-LED-0000.5). The shop shows how much the student can spend, and the purchase dialog will not confirm a total above it. - Collective goals. A collective goal is bought one unit at a time, and a student holding a buy-in cannot buy another; the card reads Joined (
DOM-STORE-0015.5,SPEC-STORE-0011.6). The cap applies whatever holding limit is configured, as it already did for privileges. - The overdraft fee. No path in the app charges the fee any more. The store purchase was the only one, and bill payments never did. The teacher guide now says so.
record_nsf_fee_obligationhas no caller left; its removal is left to U11. - The 2026-10-07 transaction is not changed by this release. The owner is handling it.
- What happened. On 2026-10-07 a student moved all of checking to savings, then bought 32 units of a $750 whole-class collective goal. The purchase posted $24,000 into a negative balance, a $25 non-sufficient-funds fee was added, and 32 buy-ins went to that one seat. The documents of the time prescribed exactly that: a purchase protection could not cover went through and drew the fee (
-
A collective-goal purchase can be reversed, and Reverse appears only where it works. The teacher could not reverse the 2026-10-07 purchase: the button was shown, and every press failed with "Transaction could not be voided." The button and the action decided reversibility separately. The banking page accepted any active non-insurance purchase, the action accepted delayed-use items only, and the student page offered Reverse on almost every row, including rent payments, which are final (
SPEC-OPS-001§VII).- Reversing a collective-goal buy-in now refunds it and revokes every unit it granted, as
DOM-STORE-001§VIII.E permits. All units must still be active. The expiry sweep skips revoked buy-ins, so a reversed purchase cannot be refunded a second time when the goal lapses. - The banking page, the student page and the action share one gate (
resolve_purchase_resolution_eligibility). Delayed-use and collective-goal purchases are reversible. Immediate-use items, purchased hall passes, insurance and privileges are not; a privilege is in force from the moment it is bought (owner ruling 2026-10-07). - A refused reversal tells the teacher why, and an obligation-related charge says to use a manual credit instead.
- Reversing a collective-goal buy-in now refunds it and revokes every unit it granted, as
-
The 2026-10-07 NSF fee can be reversed. An NSF fee is not an obligation. It is a Ledger fee, a side effect of a negative balance: one debit, never assessed and later satisfied, so a waiver does not apply to it. It had been written through the obligation-assessment mechanism, with an assessment and a payment pointing at the debit, so the reverse path read it as obligation-related and refused it. Those
NSF_FEErecords are now treated as history, not obligation facts, and Ledger reverses the fee like any other (DOM-OBL-0013.3 §II.C). Rent, insurance-premium and late-fee payments remain final. The NSF records stay in place, and nothing is added to them.DOM-OBL-0013.3 also states that CTH charges no NSF or overdraft fee, and that a failed obligation payment leaves the obligation unpaid, accumulating, and subject to late fees.SPEC-ECON-0032.3 §4.5.1.1 is aligned with it. The full removal of the retired fee machinery follows in a later release.
-
Every page render no longer runs an unscoped payroll query.
wsgi.pyregistered a context processor,inject_payroll_status, that ranPayrollSettings.query.first()on every template render in production. It asked whether any class had payroll settings, a read across every class, and no template used the answer. It is deleted.- It also made four accessibility tests depend on test order. The fixture gate forbids database access while rendering, and the processor is attached only when
wsgiis imported, which twotests/domfiles do. The full suite therefore failedtest_axe_fixture_gate.py(3 tests) andtest_axe_fixture_pages.py, while each file passed on its own. A new gate test importswsgifirst, so the gate checks the hooks production actually runs.
- It also made four accessibility tests depend on test order. The fixture gate forbids database access while rendering, and the processor is attached only when
-
Three payroll-settings tests no longer depend on the date they run. They pinned the clock to a fixed date but enabled the payroll feature on the real clock first, so the feature's effective date fell after the pinned "now" once the calendar passed it. The feature is now enabled under the pinned clock.
-
Hall passes are unavailable in a class with no hall-pass settings. Such a class offered students the built-in destinations, accepted their requests, and on approval recorded
hall_pass_logs.policy_uuid = 'default', a reference that names no policy (DOM-POL-001§VII). FEAT-PROD-002 §III requires the class's settings to be evaluated before the log is written. The gate now applies at every step, through one check (require_hall_pass_settingsinapp/feats/prod.py), so a request can be made only when it could be approved. The student is offered no destinations and sees "Hall passes are not set up for this class yet" (/api/hall-pass/available-types, 409). A request is refused and queues nothing (submit_hall_pass_request, 409). Approving a request made before this change is refused, and the request stays pending for the teacher to reject (§III.A). The built-in destination preset (Bathroom, Water Fountain, Office, Nurse, Counselor) is removed outright, so nothing can display it:HallPassSettings.get_default_pass_typesis gone, andget_pass_types()no longer falls back to it.- The teacher's setup form starts empty ("No pass types configured. Add one to get started.").
- Changing only the queue limit no longer creates a settings row from the preset; with no settings it is refused (409).
- The student's break dialog hides the destination block unless saved destinations load, so in a class without settings it shows "Done for the day" alone.
Every production settings row has a non-empty destination list (2026-10-06), so the removed empty-list fallback served none of them.
get_default_pass_typesis registered as a deprecated symbol (SOP-DB-002v2.2), so any pull request that reintroduces it fails (SOP-DB-002v2.3). Two hall-pass verify tests that failed when run within about 30 minutes after class-local midnight now pin the resolver clock to mid-day of the class's local day. Nothing creates settings on the teacher's behalf: production has five classes with the feature on and no settings row, and they see this refusal until their teacher saves settings. The 14 existing'default'logs are kept unchanged as historical facts; their policy terms are unavailable (owner ruling, 2026-10-06; P0B record §5.2, #1495). -
A teacher's own support ticket no longer lands in the teacher's Student Issues queue. A ticket filed through Help & Support goes straight to system support, but
/admin/issuesselected by class only, so once sysadmin marked it Dev Resolved it appeared under "Teacher Final Review" beside real student tickets, under the teacher's own name. The queue, the issue detail page and the resolve, escalate and close actions now exclude tickets authored by a teacher seat (student_authored_clause()inapp/services/support_operator_access.py); those requests return 404. The ticket stays visible to its author on Help & Support. No schema change; existing records are untouched. Tests:tests/dom/support/test_teacher_ticket_not_in_student_queue.py. -
Accessibility defects the new fixture audit found.
error_503.htmlcountdown text was 4.41:1 on its green panel (now--alert-success-text).admin_recovery_prepare.html's "Return to recovery" link was distinguishable from surrounding text by colour alone (now underlined). The sysadmin system-log box used light-surface status colours on its dark background (timestamp 3.4:1, module 2.3:1, warning and error levels about 3.3:1; now light-on-dark pairs)..btn-outline-successtext was 4.32:1 on the tinted card headers it sits in (now--alert-success-text). -
Backup tool install sheet names the wrong
pg_dumpversion.infra/db-backup/README.mdsaidpg_dumpmust be at least the server's major version. A newer one fails verification:pg_dump17 writesSET transaction_timeout, which the PostgreSQL 14 verify database rejects, as the first v2.1.1 pre-release backup attempt showed. It now requires the same major version, and the Mac install line usespostgresql@14. The tool's own docstring (cth_db_backup.py) said the same and now matches. The tool also refuses, before anybackuporrestore, whenpg_dumporpg_restorehas a different major version from the source, verify or target database (require_matching_clients), and the host install line pinspostgresql-client-14. Tests:tests/test_db_backup_client_versions.py(a 17-against-14 pair is refused; confirmed red with the check loosened to accept newer clients).
Changed
-
Sysadmin UI brought in line with the v2 shell. The sysadmin
<main>no longer carries the teacher.main-contentclass, whose 2rem padding and 280px margin inset the page header and left a 20px gap beside the 260px sidebar (and oversized gutters on phones); it now shrinks (min-width: 0) so wide tables cannot stretch the page. Stat cards share one structure and stack icon-over-text below 576px so labels no longer squeeze to a word per line, and the warning icon uses the accent text token. Support Tickets and Logs get a single non-wrapping tab strip (.sysadmin-tabs, icons dropped on phones), guardian-gray pills instead of Bootstrap blue, stacked full-width filter fields with labels bound to their selects, and escalated tickets render as.sysadmin-ticketrows with.sysadmin-chiplabels that truncate instead of overflowing.<code>inside the sysadmin shell uses the body text colour: Bootstrap's pink measured 4.12:1 on hovered table rows (axecolor-contrast). Template and CSS only; no route or schema change. -
Version references point at v2.1.1. README, SECURITY.md, DEVELOPMENT.md and the post-launch tracker named v2.1.0 as the production release. The tracker's release table gains the 2026-10-03 and 2026-10-04 releases, and its items made stale by the 2026-10-04 window are updated from read-only host checks: the student-setup store checks are done, Loki is out of
/tmpwith a 14-day retention, Tempo and Alloy are stopped, the orphaned v1 Loki chunks are gone, and the first restore-verified backups exist.docs/ops/DATABASE_BACKUP_PLAN.md§1 names the newest recovery point.