rootnode-academy/docs/PHASE8_ENROLLMENT_OPERATIONS.md

# Phase 8 — Enrollment Operations, Guardian Communications & Website Integration

Phase 8's mission: turn Phase 7's business/product backend into an OPERABLE enrollment system —
Offering → Registration → Guardian/Adult Contact → Agreements → Communications → Review →
Confirmation → Enrollment → Cohort → Account Activation → Classroom/Lab Access — without direct
database manipulation, ahead of RootNode's first commercial launch (Winter Break Camp). Not a
payment phase — everything is built around where a future payment step will plug in.

## Baseline

Confirmed at start: branch `main`, clean tree, HEAD = `origin/main` = Phase 7's
`df5e39f767a6af3ba50daabde5de97fa1b1a5f3b`.

## What was built

- **Migrations 035/036** — registration-stage notifications (nullable `student_id` +
  `registration_id` on `notification_events`), a `'registrant'` agreement-acceptance type,
  `offering_agreement_requirements`, a real unique index on `external_reference` (website
  registration idempotency), and the notification_type CHECK widening (see "bugs found" below).
- **`offerings.js` extended**: `assertRegistrationOpen()` (server-authoritative registration
  windows), `addAgreementRequirement`/`getRegistrationAgreementStatus` (required vs. accepted vs.
  missing), a conversion-time block on missing required agreements, `computeOfferingReadiness()`
  (server-derived launch checklist), and `createRegistrationFromIntegrationEvent()` (the
  website's idempotent submission path, mirroring `enrollment.js`'s established pattern exactly).
- **`notifications.js` extended**: a guardian-email fallback in `resolveRecipient()`, and a
  parallel `enqueueForRegistration()`/`resolveRegistrationRecipient()` pair for the pre-account
  registration stage — same table, same worker, same masked admin view, no second system.
- **Five new templates** (`registrationReceived`, `registrationConfirmed`,
  `registrationNeedsAction`, `agreementRequired`, `campOperationalUpdate`) — HTML + text,
  RootNode-branded, no tracking, no marketing content.
- **`public-offerings-routes.js`** (new) — the unauthenticated, explicitly-allowlisted offering
  read API the website will consume.
- **`POST /api/integrations/registrations`** (new, in the existing `integration-routes.js`) —
  the website's registration submission contract, same shared-secret boundary as
  `/api/integrations/enrollments`, fully idempotent.
- **Admin UI**: a real `/admin` → Offerings section (`OfferingsView.jsx`) — list, create, detail
  (overview with valid-transitions-only buttons, launch readiness, required agreements,
  registrations/roster) and registration detail (lifecycle, agreement status, communication
  history, convert-to-enrollment). Reuses the existing `Admin.module.css`/`adminApi` conventions
  exactly — no new UI framework or pattern introduced.

## Two real bugs found and fixed during this phase's own testing (before any commit)

1. **`notification_type` CHECK constraint mismatch** — the five new registration-stage
   notification types were wired into `notifications.js`/`notification-worker.js` before the
   database's own CHECK constraint was widened to accept them. Every `enqueueForRegistration()`
   call was silently failing (caught by the deliberate "a notification failure never blocks the
   real action" try/catch) until a comprehensive smoke test surfaced it directly. Fixed in
   `036_phase8_notification_types.sql`. Also hardened: every previously-silent
   `.catch(() => {})` around a notification call now at least logs the error, so a future
   regression like this surfaces immediately instead of silently vanishing.
2. **A registration-insert/seat-reservation/notification ordering bug** — adding a
   `registration_received` notification right after the registration row's insert (but before
   the seat reservation that could still fail and roll the row back) meant a failed reservation's
   cleanup DELETE could hit a foreign-key violation against the notification row it had just
   created. Found via `e2e-phase7.js`'s own regression rerun. Fixed by reordering
   `createRegistration()` to validate → reserve the seat → insert → notify, strictly in that
   order, and simplifying the admin route accordingly (see `docs/OFFERING_AND_REGISTRATION_
   MODEL.md` for the full before/after).

## Cascading regression fixes (stale test assumptions, not new bugs)

Enforcing real registration-window checks (Step 21) broke `e2e-phase7.js`'s own `offeringB`
(created in Phase 7, never transitioned out of `draft`, registered against successfully only
because no such enforcement existed yet) and a new age-guidance offering created the same way.
Fixed by publishing/opening both before registering, matching the new, correct requirement. A
third `e2e-phase7.js` test's own file-allowlist check needed widening to permit the new, entirely
legitimate `public-offerings-routes.js` reference to age-guidance fields (display-only, never
authorization).

## Testing

`platform/test/e2e-phase8.js` — 16/16 passing (fresh stack): offering CRUD/transitions/
readiness, registration open/closed enforcement, capacity + concurrent final-seat race through
the real registration endpoints, the public serializer's safety (no internal/PII fields), website
integration idempotency (sequential replay + concurrent duplicate), adult/minor registration
paths, student-identity preservation on conversion, required-agreement conversion blocking with
version snapshotting even after the live definition's version later changes, offering→cohort
membership, a real activation token + queued notification on conversion, guardian recipient
resolution, RBAC (offering/location visible to any instructor, guardian/registration detail
admin-only), organization/location `access_notes` stripping, and confirmation ROOT_ V1 self-paced
and classroom flows are unaffected.

## Winter Break commercial-path rehearsal

`infra/scripts/drills/test-phase8-winter-camp-registration.js` — 12/12 passing against a real,
freshly-built stack, with no payment code anywhere: admin configures a real offering (location,
capacity, instructor, required agreement), the website integration submits a REAL minor
registration (a real guardian created/matched, a confirmation notification queued), guardian
acceptance is recorded through the supported application flow, a future payment confirmation is
SIMULATED via a plain admin transition, the registration converts to a real enrollment and real
cohort membership, the account activates with a real one-time token, an adult registers and
converts independently, two students genuinely compete for the final seat (both correctly
rejected once capacity was already exhausted — no overbooking), the instructor runs a real
classroom session and Prepares Labs, and the minor student completes real ROOT 01 orientation
plus a REAL Lab task (`linux-inspect-hardware`) inside a real disposable Lab container, with the
instructor then seeing the real progress.

## Regression

Fresh-stack reruns after every fix: `e2e-phase7.js` 17/17, `e2e-phase6f.js` 17/17, `e2e-phase5b.js`
32/32 (enrollment.js's `resolveOrCreateStudent` gained an optional, default-off `returnToken`
param in Phase 7, re-verified unaffected here), `e2e-phase5c.js` 29/29 (notifications.js was
directly extended this phase — every existing Phase 5C notification type/flow reconfirmed
byte-for-byte unaffected). `e2e-phase5a.js` not independently rerun: its own checks are embedded
in and reconfirmed by both 5B's and 5C's "Phase 5A ... still works unmodified" assertions, and no
code Phase 5A itself owns was touched.

## Frontend build

`npm run build` clean — the new `OfferingsView.jsx` compiles without warning; the only new
warning is the pre-existing "chunk larger than 500kB" advisory, unchanged in cause from every
prior phase.

## Real Lab result

Both rehearsals (Phase 7's from the prior phase, re-verified here, and this phase's own) drive a
real disposable Lab container through a genuine `linux-inspect-hardware` scenario setup/validate
cycle — confirmed passing for real, not simulated, in the Winter Break commercial-path rehearsal.

## Security/privacy findings

The public offerings API was built with an explicit field allowlist from the start (never
`SELECT *`) — `e2e-phase8.js` asserts directly that `access_notes`, `organization_id`,
`location_id`, `created_by`, `reserved_seats`, `capacity`, and `metadata` never appear in a
public response, and that a fully-booked offering reports `"full"` rather than a raw seat count
(avoiding a scraping/timing vector against a public, unauthenticated endpoint). No new security
weakening was introduced; the two bugs found above were both silent-failure/ordering bugs, not
authorization gaps.

## Legal-review requirements — unchanged, restated

See `docs/STUDENT_GUARDIAN_DATA_MODEL.md`'s list in full, still entirely unresolved by this
phase's work: the actual legal text of any participation/media/liability agreement,
jurisdiction-specific minor-consent requirements, data-retention/deletion policy, and whether
emergency-contact fields need additional encryption at rest. `agreement_definitions.body_summary`
remains a plain-language placeholder, never legal text.

## Documentation

New: `PHASE8_ENROLLMENT_OPERATIONS.md` (this document), `WINTER_BREAK_CAMP_OPERATIONS.md`,
`REGISTRATION_AND_GUARDIAN_COMMUNICATIONS.md`, `OFFERING_ADMIN_GUIDE.md`. Updated:
`ROOTNODE_ACADEMY_BUSINESS_AND_PRODUCT_ARCHITECTURE.md` (BUILT NOW/PHASE 8 BUILT/FUTURE table),
`OFFERING_AND_REGISTRATION_MODEL.md` (the two ordering bugs, launch readiness, registration
enforcement), `STUDENT_GUARDIAN_DATA_MODEL.md` (guardian communications now wired),
`WEBSITE_ENROLLMENT_INTEGRATION.md` (the real, live registration contract with worked examples),
`platform/README.md` (test list). Reviewed, no change needed: `docs/ENGINEERING_SOP.md`,
`docs/LAB_ARCHITECTURE.md`, `docs/REMOTE_AND_SELF_PACED_ARCHITECTURE.md`,
`docs/RUNBOOK_GOOGLE_WORKSPACE_EMAIL.md` (the existing provider adapter needed no changes — the
new templates render through the exact same delivery path).

## Known limitations

- The website's own registration UI does not exist yet in this repository (rootnodeacademy.com
  is built separately) — the contract is ready and tested, nobody has built the website-side
  form against it yet.
- Agreement acceptance is not exposed on the website registration endpoint itself — currently a
  separate admin-recorded (or future self-service) step after submission.
- `registration_needs_action` has no automatic trigger — an admin action, deliberately, since
  "needs action" covers many distinct real reasons an admin should state explicitly rather than
  the platform guessing one.
- No waitlist was built — a `waitlisted` registration status was considered and deliberately
  deferred; the existing `cancelled`-releases-a-seat mechanism plus manual re-registration covers
  the real, near-term operational need without adding a new status machine branch this phase
  didn't have concrete evidence would be used.
- No payment processing — every "payment confirmed" step in both rehearsals is a plain admin
  transition, exactly as authorized.

## Remaining blockers before opening Winter Break registration to the public

1. Real dates, venue, capacity, and price are still undecided (not invented by this phase).
2. The agreement's actual legal text requires professional review.
3. No payment processing exists yet.
4. The website's own registration form doesn't exist yet.

None of these are platform readiness gaps — the platform is ready to operate the flow the moment
those four external decisions/assets exist.

## Commits

See `git log` for this phase's exact commit sequence (migrations/backend, admin UI, tests +
rehearsal, docs) — grouped per `docs/ENGINEERING_SOP.md`'s existing convention.

## Recommended Phase 9

Real payment integration (Stripe or equivalent) wired into the registration-confirmation step;
the actual website-side registration form; agreement-acceptance exposed on the public
registration contract once the legal text is finalized; and, informed by real Winter Break Camp
operational experience, whether a waitlist is actually worth building.