Access cutoff: single warning email, no in-app signal, undocumented tenant-wide blast radius (#494 follow-up)

[guillermoscript]

Follow-up to #493 / #494 — found while verifying the epic's delivered state (2026-07-24).

Problem

The access cutoff shipped as a tenant-wide hard block announced by a single email. The blast radius was never stated in the epic, and there is no communication between the one warning and the moment access stops.

Gaps

1. One email, ever. reconcileAccessCutoff (lib/billing/access-cutoff.ts:112-127) sends accessCutoffWarningTemplate only on the schedule transition. Nothing runs at T-7, T-1, or on the day access actually stops. If that single message bounces or lands in spam, the school's first signal is students losing access 14 days later. Send failures are caught and logged (access-cutoff.ts:122-124) but nothing retries or surfaces them.

2. No in-app signal to anyone. Students hit notFound() or a generic "no access" state with no indication that the school's account is the cause. Admins see the cutoff date only if they visit the billing page.

3. The blast radius is undocumented and very blunt. The cutoff is tenant-wide: has_course_access() returns false for every student in the tenant once access_cutoff_at passes. A free-plan school that enrolls its 51st student (50-student limit) loses access for all 51 — not the one over the line, and not just new enrollments. That trade-off is a defensible choice, but #493 §1.1 offered "read-only mode past N days over limit, or a hard student-count cutoff" and never recorded which one was taken or how wide it reaches. docs/MONETIZATION.md:239-243 describes the mechanism without stating that it is all-or-nothing for the whole tenant.

Wanted

• Add reminder emails as the cutoff approaches, and one when it takes effect.
• Show a persistent in-app banner to tenant admins while a cutoff is scheduled, and give students a specific "your school's account needs attention" state instead of a generic denial.
• Document the tenant-wide blast radius explicitly in docs/MONETIZATION.md, or narrow enforcement (e.g. cut off only the most recently enrolled students over the limit) if all-or-nothing is not the intended rule.

[guillermoscript]

Plan of attack

Surveyed the delivered #494/#509 code before planning. Two of the three gaps are real and untouched; part of gap 2 turns out to have been closed by #509 already, so this issue's scope narrows there.

Root cause

reconcileAccessCutoff() (lib/billing/access-cutoff.ts:113-131) treats notification as a one-shot side effect of a state transition rather than as an ongoing obligation for the duration of a scheduled cutoff. It only fires inside if (decision.action === 'schedule'), and decideAccessCutoffAction() returns 'schedule' exactly once per cutoff (the !currentCutoffAt guard on line 44 makes every later call return 'none'). So the design has exactly one opportunity to tell anyone, 14 days before enforcement, and no record of whether it worked — the try/catch on lines 127-129 swallows a failed send with a console.error and the loop moves on, leaving access_cutoff_at set and the admin uninformed.

Nothing else in the system re-checks. The daily sweep (app/api/cron/enforce-plan-limits/route.ts) calls reconcileAccessCutoff() for every tenant, but for a tenant with a cutoff already scheduled that call is a deliberate no-op — which is correct for scheduling and wrong for communication.

The in-app half has an asymmetry: the student side was in fact closed by #509, which added /dashboard/student/access-suspended (a page that names the school's billing state as the cause and states the enrollment is intact) and routes every refusal caused by the tenant cutoff there via requireCourseAccess(). The admin side is what is missing: getSubscriptionStatus() already returns accessCutoffAt (app/actions/admin/billing.ts:87), but nothing outside /dashboard/admin/billing reads it, so an admin who never visits that page gets no in-app signal at all.

Gap 3 is a documentation gap, not a code one. has_course_access() (migration 20260724130000) gates on t.access_cutoff_at IS NULL OR t.access_cutoff_at > now() with no per-student predicate, so the rule genuinely is all-or-nothing per tenant. docs/MONETIZATION.md describes the mechanism accurately but never states the blast radius in those terms.

Approach

1. A reminder ladder with a persisted send ledger.

New table access_cutoff_notifications (tenant_id, cutoff_at, stage, sent_at, recipient_count) with UNIQUE (tenant_id, cutoff_at, stage). Keying on cutoff_at rather than just tenant_id means a cleared-then-rescheduled cutoff correctly gets a fresh set of notifications, and the unique constraint makes the whole thing idempotent under repeated cron runs.

Four stages: scheduled (immediate, what ships today), reminder_7d, reminder_1d, enforced (first run after the cutoff actually takes effect). A new pure function dueCutoffNotificationStages({ cutoffAt, sentStages, now }) decides which stages are due — pure and now-injectable, matching the existing decideAccessCutoffAction split so it is unit-testable with no DB.

Failure handling is the point of the ledger: a stage row is written only when at least one recipient send succeeded. A stage whose sends all failed simply stays unrecorded, so the next daily cron retries it — which is the retry the issue asks for. The cron response gains remindersSent / reminderFailures counters so a systemic email outage is visible in the cron log rather than silent.

app/api/cron/enforce-plan-limits/route.ts gains a second step per tenant: after reconciling, if a cutoff is scheduled, send whatever stages are due. This reuses the sweep that already exists rather than adding another cron entry to the GitHub Actions schedule landed in #513.

The email template becomes stage-aware (accessCutoffWarningTemplate({ stage, ... })) so the T-7/T-1 notices escalate in urgency and the enforced notice is written in the past tense — "access is now paused" rather than "will be".

2. A persistent in-app banner for tenant admins.

components/shared/access-cutoff-banner.tsx, rendered from app/[locale]/dashboard/layout.tsx alongside the existing VerifyEmailBanner and gated on role === 'admin' — the same slot, so it appears on every admin dashboard page rather than only on billing. Non-dismissible while a cutoff exists (dismissing a countdown to losing all student access defeats the purpose), with two states: scheduled (days remaining + what will happen + "Manage billing") and active (access is currently paused + how to restore it). Copy states the blast radius plainly — every student, all courses — so the banner and the email tell the same story. New i18n keys under components.accessCutoffBanner in messages/en.json and messages/es.json.

The data comes from one indexed single-row read on tenants (the idx_tenants_access_cutoff_at partial index from 20260724130000 already exists), executed only when the viewer is an admin.

3. Document the blast radius explicitly.

docs/MONETIZATION.md gets a "Blast radius" subsection under the existing post-downgrade enforcement section, stating in plain terms that the cutoff is tenant-wide and all-or-nothing; that a free-plan school enrolling its 51st student loses access for all 51, not just the one over the line; what is not affected (enrollments, entitlements, purchases, staff/author access, preview lessons); and that this was the chosen option from #493 §1.1 with the per-student narrowing recorded as considered and rejected.

On the issue's "or narrow enforcement" alternative: I'm taking the documentation route deliberately. Narrowing to "cut off only the most recently enrolled students over the limit" would need a per-student ordering rule inside has_course_access(), would make a student's access depend on the join order of their peers, and would be a product decision beyond a follow-up sub-task. If you want the narrowing instead, say so and I'll split it into its own issue rather than smuggle it in here.

Risks

• Email volume. The sweep now sends up to three additional emails per cutoff per admin. The unique constraint is the only thing preventing repeats, so it has to be enforced in the database, not in application logic — hence the constraint rather than a "have we sent this?" read-then-write.
• A cleared-then-rescheduled cutoff re-notifies from stage one. Intended: a new 14-day window is genuinely new information. It does mean a tenant oscillating around its limit could receive repeated scheduled emails; the cutoff_at key at least keeps each one tied to a real, distinct deadline.
• Layout-level query. Added to a layout that wraps every dashboard page. Restricted to admins and a single indexed row read, but it is on the render path for every admin navigation.
• Migration must reach both databases. Local via supabase db push and the cloud project, matching how 20260724130000 was deployed.
• Clock-boundary stages. reminder_1d and enforced are adjacent; if the cron runs at an awkward hour a tenant could receive both in one sweep. The stage list is computed and sent in order, which makes that coherent rather than contradictory, but it is worth knowing.

Test plan

Unit (npm run test:unit):

• New tests/unit/access-cutoff-notifications.test.ts covering dueCutoffNotificationStages: nothing due at T-10; reminder_7d due at T-7 and not re-sent once recorded; reminder_1d due at T-1; enforced due once the cutoff has passed; a stage that failed to send (absent from sentStages) is returned again on the next run; a rescheduled cutoff with a different cutoff_at yields a full fresh ladder.
• Existing tests/unit/access-cutoff.test.ts and tests/unit/access-cutoff-call-sites.test.ts must stay green — decideAccessCutoffAction's contract is unchanged.

Manual / QA:

• Push the migration to the local DB; set a test tenant over its plan limit and confirm access_cutoff_at is scheduled and a scheduled row lands in access_cutoff_notifications.
• Hit /api/cron/enforce-plan-limits with the CRON_SECRET bearer token repeatedly and confirm no duplicate rows and no duplicate emails.
• Backdate access_cutoff_at to T-7, T-1 and to the past, re-running the cron at each, and confirm exactly one new row and one email per stage.
• Log in as a tenant admin and confirm the banner appears on a non-billing admin page (e.g. /dashboard/admin/courses) in both the scheduled and active states, in en and es.
• Log in as a student of the same tenant past the cutoff and confirm the existing /dashboard/student/access-suspended page still handles the student side (regression check on Lesson/exercise/exam pages have no access gate — #494 cutoff is a no-op there and any tenant member can read paid content #509, not new work).

npm run typecheck, npm run lint and npm run build before the PR. Judging lint by new errors on changed files only — the repo carries a known pre-existing lint baseline.

[guillermoscript]

Shipped in #520. Two corrections to the plan above, both from what implementation and QA turned up:

The ladder sends at most one rung per sweep, not a list. The plan described computing due stages "in order" and flagged the clock boundary as a known risk. In the code that risk is designed out instead: dueCutoffNotificationStage() returns a single stage — the most urgent rung whose trigger point has been reached and which the ledger has not recorded — so an undelivered early rung is superseded rather than queued behind an urgent one. Two contradictory messages in one inbox ("you have 7 days" beside "access is now paused") is a worse outcome than one missing message. The retry property is unchanged: a rung nobody received is still unrecorded and still the most urgent reached rung on the next sweep. The plan also named a separate sendDueCutoffNotifications() function; it ended up as a notifyDueStages option on reconcileAccessCutoff() so the sweep does one fetch of tenant/plan/usage instead of two.

Gap 1 was worse than the issue described. The issue says send failures are "caught and logged but nothing retries or surfaces them". In fact lib/email/send.ts returns false rather than throwing — both when Mailgun is unconfigured and when the API call fails — so #494's try/catch around the send caught nothing that ever happened. A dead mail provider produced a silent no-op indistinguishable from a successful send. Delivery is now judged on that boolean, which is what makes the ledger's "only record what was actually delivered" rule meaningful.

One unrelated bug fixed in passing: the new banner and the #509 student page both formatted dates with toLocaleDateString(undefined), which on the server resolves to the Node process locale rather than the request's — /es pages rendered English dates. Caught in browser QA, not by any test.