Skip to content

Classroom Token Hub v2.2.0

Choose a tag to compare

@timwonderer timwonderer released this 09 Oct 07:15
Immutable release. Only release title and notes can be modified.
5ebae62

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:

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.md records, from read-only aggregate queries against production at revision f9a3c7d1e620 (2026-10-06 06:08-06:11Z), the timestamped SOP-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 two H5 items the owner ruled on 2026-10-06. First, all 854 signature-v1 ledger rows store feat_code = FEAT-LED-003 (the settlement restamp fixed in 81ea0fff5); their originating FEAT is taken from the linked creation audit event, and actor attribution is unavailable rather than system. Recording that ruling in DOM-OPS-002 is left to U13. Second, 14 of 16 hall-pass logs store policy_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 in docs/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.txt was enforced only by the Schema Change Gate, which runs on pull requests touching migrations/versions/** or the model files and skipped the scan for NON-MODEL CHANGE. So a route, template or script that named ClassMembership, is_bundle or get_default_pass_types merged unscanned. The scan is now a pytest guard (tests/test_deprecated_symbols_guard.py, detector in tests/guards/deprecated_symbols.py) that policy-guardrails.yml runs on every pull request and push to main without a database. The Schema Change Gate runs the same guard in place of its inline grep. The scope now includes first-party JavaScript (*.js under app/, templates/, scripts/ and static/, excluding static/vendor/). Mutation proofs plant near-miss violations: an aliased import, a reflective string, a longer identifier, a template attribute, static/js and 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-002 v2.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-008 v1.2 removes the "explicitly approved bridge code" allowance from §VI (Student ID Quarantine); DOM-OPS-002 v1.11 §6.2A and SPEC-PROD-002 v1.4 §VII state that historical diagnostics and reconstruction are read-side interpretation that creates no state; SOP-DB-004 v1.2 §VII.8 and SOP-DOC-001 v3.25 follow. Documentation only; no code or schema change.
  • Forward-only revision register, enforced. migrations/forward_only_register.txt lists every Alembic revision whose downgrade() raises or does nothing (34 today, including the three attendance/payroll recovery revisions SOP-DEP-001 §XIV named; the prose list had missed the rest). tests/test_forward_only_revision_register.py derives the set from migrations/versions (detector in tests/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 conditional raise, a raise hidden in a helper, no-op spellings, a missing downgrade(), and a merge that does work; reversible downgrades and pure merges stay quiet. SOP-DB-004 v1.1, SOP-DEP-001 v2.8 and SOP-DEP-002 v1.8 point at it; SOP-DEP-002 and SOP-DEP-001 no longer cite archived SOP-DB-009 or the nonexistent SOP-DEP-016 as dependencies. The "does nothing" test is positive (no op.* or .execute call, 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 State H0-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 for M0/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-001 v1.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.yml now also runs tests/test_axe_app_pages.py, tests/test_axe_fixture_pages.py and tests/test_axe_compliance.py with AXE_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.py fails 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.json is 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-students and /admin/student/unclaim returned str(error) from any ValueError. They now return a message only if it is in ROSTER_ACTION_MESSAGES (app/feats/identity_feat.py), which lists the teacher-facing messages those FEATs raise; any other ValueError gets 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_docs percent-encodes the reader-supplied path, refuses . and .. segments, and checks the target still has the configured docs host. Tests in tests/dom/docs/test_docs_platform_split.py.
  • Docs site npm advisories. The docs-site lockfile moves fast-uri to 4.2.1, brace-expansion to 5.0.12 and http-cache-semantics to 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-004 1.4).
    • Removed: /sysadmin/combined-logs, /sysadmin/logs, the redirects /sysadmin/error-logs, /sysadmin/logs-testing and /sysadmin/network-activity, the Logs navigation link, and the dashboard's View Logs action and Recent Errors panel. Their templates and the service readers get_error_events and get_recent_error_events go with them.
    • Why. /sysadmin/logs displayed 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_events table and its writer.

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-003 2.2 §4.5.1.1A, FEAT-LED-000 0.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-001 3.2, SPEC-ECON-003 2.3, FEAT-LED-000 0.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-001 5.5, SPEC-STORE-001 1.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_obligation has 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.
  • 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.
  • 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_FEE records are now treated as history, not obligation facts, and Ledger reverses the fee like any other (DOM-OBL-001 3.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-001 3.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-003 2.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.py registered a context processor, inject_payroll_status, that ran PayrollSettings.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 wsgi is imported, which two tests/dom files do. The full suite therefore failed test_axe_fixture_gate.py (3 tests) and test_axe_fixture_pages.py, while each file passed on its own. A new gate test imports wsgi first, so the gate checks the hooks production actually runs.
  • 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_settings in app/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_types is gone, and get_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_types is registered as a deprecated symbol (SOP-DB-002 v2.2), so any pull request that reintroduces it fails (SOP-DB-002 v2.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/issues selected 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() in app/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.html countdown 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-success text was 4.32:1 on the tinted card headers it sits in (now --alert-success-text).

  • Backup tool install sheet names the wrong pg_dump version. infra/db-backup/README.md said pg_dump must be at least the server's major version. A newer one fails verification: pg_dump 17 writes SET 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 uses postgresql@14. The tool's own docstring (cth_db_backup.py) said the same and now matches. The tool also refuses, before any backup or restore, when pg_dump or pg_restore has a different major version from the source, verify or target database (require_matching_clients), and the host install line pins postgresql-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-content class, 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-ticket rows with .sysadmin-chip labels 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 (axe color-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 /tmp with 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.