# The notification system — working plan for an enterprise-grade rebuild

> **Status: PLAN — nothing in this file is implemented.** Every claim about the *current* system was read
> from the source and **measured against the live database on 2026-09-29**; every proposal is marked
> **PROPOSED**. When this plan and the code disagree, the code wins (`AGENTS.md` §12) — and this file must
> be updated as work lands, not left describing an intention.
>
> **Read first:** `NOTIFICATION_SYSTEM_WORKFLOW.md` (how the engine works — §5 pipeline, §16 traps) and
> `PROJECT_DOCUMENTATION.md` **§23** (the full audit, §23.1–§23.31). This file does not repeat them; it is
> the **change plan** for the four things the request names: categories, recipients, one consolidated
> seeder, and the enterprise hardening around them.
>
> **Revision 2 (2026-09-29).** The assessment families are now **scoped to eight named subjects** (§3.0).
> There are **no generic `assessment.*` notifications** and **no `exam.*` / `group-assignment.*`**
> ones. §3.0 is normative for every assessment row in the catalogue; the change log at the end records
> what moved.
>
> **Authority order:** source code → DB schema/migrations → tests → `PROJECT_DOCUMENTATION.md` →
> `NOTIFICATION_SYSTEM_WORKFLOW.md` → this plan.
>
> **The catalogue itself now lives in `NOTIFICATION_MATRIX.md`** (2026-09-29, rev 2.7, status **TARGET**).
> This plan file explains **why** and **in what order**; the matrix is the **what** — 19 categories → 312
> events → recipients per event, row by row, with a status per row, and it is the artefact the user
> edits before it becomes `database/seeders/notifications/Catalogue.php` (§3.3 below). Where this plan's
> §3.0.5 (scope → recipients) and §3.1–§3.2 (categories, resolver adopt/retire) sketch the rule, the
> matrix holds the resolved rows; if the two ever disagree, **the matrix wins** and this file is
> corrected.
>
> **The matrix's Rule 0 changes §3.0 here.** The scope is no longer a context detail — it is **in the
> event name** (`{base}.{scope}.{action}`), for every model with a `scope` column: `assessments`
> (per subject), `marathons`, `announcements`, `certificates`. So §3.0.2's flat `8 subjects × 7 actions =
> 56` becomes **138 rows** once the scopes are enumerated, and §3.0.5's scope→recipient table is now
> expressed as separate rows per scope. Two corrections the matrix makes to this plan: the
> **`competition` subject also owns the scheduler actions** (`locked`, `unlocked`, `assigned`) and
> `result.paper_entered` — those are the assessment type `competition`, not a separate model, so there is
> no standalone `competition` category; and **`marathon.approved` / `marathon.rejected` are never
> dispatched** by the application (only `notifications:validate` names them), so Q1's "enable" is now
> "drop". `certificate` and `announcement` join the taxonomy at 6 and 9 rows, and the plan's §3.1
> category count becomes **19**, and (§3.1) the target taxonomy is 19 → 19, regrouped — see the matrix's
> §3, which keeps `course` and `lesson` as their own categories rather than folding them into `content`.
>
> **Revision 4 (2026-09-29) points Workstream C at the readable catalogue.** `NOTIFICATION_EVENTS_MATRIX.md`
> is the plain-language twin of the matrix (*category → event → recipient*, 319 entries, a 51-key resolver
> glossary) and is now the file the seeder's data is written from; §3.3 has the shape.
>
> **Revision 6 (2026-09-29) fixes where enrolment exists.** Enrolment is a **marathon / competition**
> concept only — there is no enrolment, participation or eligibility leg for `training`, `self-training`
> or the `group-*` subjects — and the **enrolment role set** (the **eligible teacher** + the **joining
> students**) is the participant half of the four competition-family subjects: `marathon-competition`,
> `competition`, and the two `*-training` subjects (which read it from their **parent**). The matrix's
> **§2.6.3** is normative and holds the source evidence (`config/participation.php`, the `StudentEnrollment`
> docblock, the morph map, the three `canViewForRecord()` guards, the training resources); the matrix's
> §5.3 therefore carries `scope-participants` and **not** the participation keys. A student's **joining
> request** now reaches **both the event's owner and the student's teacher** (`student-teacher`, matrix
> §16.1 / Q18).

---

## 0. What "enterprise" means here — the six acceptance criteria

The rebuild is done when all six hold. They are the plan's spine; every phase below serves one of them.

| # | Criterion | Today |
|---|---|---|
| **E1** | **Every dispatched event has an active settings row.** A dispatch either delivers or is *reported*; nothing aborts silently. | **37 dispatched names have no row** (§2.1) and a missing row is a silent no-op |
| **E2** | **Every settings row corresponds to something the code dispatches.** No orphan catalogue. | **7 rows are never dispatched** (3 of them active, plus 2 group-submission rows — §2.2) |
| **E3** | **Every event's recipients are deliberate and testable** — a stated subject, and a decision-maker where a decision is made. | 22 of 34 resolvers are used; 12 are dead; several rows notify nobody relevant (§3.2) |
| **E4** | **One seeding file is the catalogue's source of truth**, idempotent, non-destructive, and it can be applied to an existing install. | 5 seeders, seed order is load-bearing, and running the first one alone deletes 104 events (§3.3, trap T3) |
| **E5** | **An administrator can maintain it through the UI.** | The settings editor **cannot save at all** (§3.4, trap T1) — this is a hard blocker |
| **E6** | **The catalogue is gated by a test/command that fails in CI**, so E1–E3 cannot regress. | `notifications:validate` is stale (asserts 30 resolvers / 53 events) and sends real messages |

---

## 1. The inventory as measured (2026-09-29)

| Figure | Value | How it was measured |
|---|---|---|
| Notification classes | **248 files** (the plan's own 2026-09-28 measurement — **291 today**, `NOTIFICATION_SYSTEM_WORKFLOW.md` §3) — 210 event/support classes (excl. `RecipientResolver/`, `Channels/`) + 34 resolvers + channel/base | `find app/Notifications -name '*.php'` |
| `notification_settings` rows | **209** (185 active / 24 inactive), 209 distinct names | live DB |
| Recipient groups | **301** — `database` 298, `mail` 96, `whatsapp` **0** | live DB |
| Channels with no template behind them | **0** (no `mail` group lacks `mail_subject`/`mail_body`) | live DB — the messaging data is *clean* |
| Rows whose later group has narrower channels than the first | 6 — `classroom.cancelled`, `classroom.scheduled`, `{marathon,competition}.participation.submitted`, `user.{program,teacher}.registered` | live DB — **verify, not necessarily wrong** (§3.2.4) |
| Groups per row | 145 rows with 1, 37 with 2, 26 with 3, 1 with 4 | live DB |
| **Categories** | **19** (`assessment` 53, `marathon` 28, `competition` 27, `subscription` 25, `user` 18, `plan` 12, `system` 7, `program` 6, `attendance` 5, `content` 4, `classroom` 4, `announcement` 3, `course` 3, `lesson` 3, `program_level` 3, `team` 3, `certificate` 2, `contact` 2, `message` 1) | live DB |
| Recipient resolvers | **34 registered, 22 used**, 12 never named by any group | provider + live DB |
| Engine dispatch sites | **~45 files**; 85 literal event names + 11 computed name templates | `grep` over `app/` |
| Assessment types in the code | **9** — `competition`, `marathon-competition`, `training`, `child-training`, `self-training` (`AssessmentResource::archivableTypes()`), plus `exam` and the three `group-*` (`AssessmentResource` type options) | source |
| Tests covering the subsystem | 5 files (the pipeline unit test is the real one); **no settings-screen test** | workflow doc §17 |

**The good news, and it is worth stating plainly:** the *message data* is in better shape than the
structure around it. No group is missing a channel's template, no group names an unregistered resolver,
no template renders `{scope}` except 2 rows, and dedup windows are set. The defects are **structural**:
who is in the catalogue, what category they sit in, and who receives them.

---

## 2. The gaps, as facts (E1 + E2)

### 2.1 Dispatched events with **no settings row** — 37 names, as-is (E1)

Each of these aborts at stage 2 (`SettingResolutionStage`) today: one log line, no delivery, and the
caller gets a batch id as if it had worked. Verified by reading each dispatch site.

| # | Event name(s) | Dispatched from | Why it matters |
|---|---|---|---|
| 1 | `assessment.deleted` | `Models/Assessment.php` (`dispatchAssessmentEvent('deleted')`) | the **generic** delete event has no row at all, while the typed `{type}.deleted` does |
| 2–4 | `group-homework.deleted`, `group-assignment.deleted`, `group-exam.deleted` | same site | the typed `deleted` family was seeded for six types only |
| 5–7 | `group-homework.updated`, `group-assignment.updated`, `group-exam.updated` | `Models/Assessment.php` (`'updated'`) | same hole on update |
| 8–9 | `marathon.enrollment.mode_changed`, `competition.enrollment.mode_changed` | `StudentEnrollmentService:306` | a student changing enrollment mode notifies nobody |
| 10–17 | `{marathon,competition}.seats_increase_{requested,updated,approved,rejected}` — **8 names** | `SeatChangeRequestService:142,271,353,394` | the whole seat-increase workflow is silent in both directions |
| 18 | `competition.result.paper_entered` | `Services/Assessment/PaperResultService:349` | a paper result is recorded and nobody is told |
| 19 | `subscription.trial.converted` | `SubscriptionService::endTrial($convertToPaid: true)` | a trial converted to paid notifies nobody |
| 20–21 | `subscription.upgrade.requested`, `subscription.downgrade.requested` | `PlanChangeWorkflow:97` | a plan-change request notifies nobody — the *approval* half (`subscription.plan.upgraded/downgraded`) does |
| 22–25 | `competition.starts.soon`, `competition.ends.soon`, `marathon-competition.starts.soon`, `marathon-competition.ends.soon` | `SendAssessmentUpcomingNotifications` | the command dispatches `{type}.{action}` for **every** type it finds; the seeder covers 7 of the 9 |
| 26–37 | `{training,self-training,child-training,group-homework,group-assignment,marathon-competition}.{completed,results.available}` — **12 names** | same command (lines 78–86) | likewise |

> **Under the revision-2 scope (§3.0) this list changes shape**: 3 of the 37 are on types that are
> **dropped** (`group-assignment.*`), 12 move into the **rename** (§3.0.5) and the rest are re-derived from
> the 8-subject matrix. §3.0.6 is the authoritative target list; this table stays as the **as-is**
> measurement the audit recorded.

### 2.2 Seeded events **never dispatched** — 9 rows (E2)

| Event name(s) | Category | Active? | Evidence |
|---|---|---|---|
| `data.exported`, `data.imported`, `data.import.failed` | `system` | **YES — 3 active** | `grep -rn "Notifications\\\\Data\\\\" app` finds only the class files' own declarations; no dispatcher |
| `subscription.invoice.generated` | `subscription` | **YES** | no reference outside the class file |
| `group-homework.submitted`, `group-assignment.submitted` | `assessment` | YES | no dispatcher builds `{type}.submitted` anywhere (`python3` scan of every `dispatch(` first argument) — the rows describe a submission step that was never wired |
| `plan.created`, `plan.updated`, `plan.deleted` | `plan` | already inactive | there is **no `Plan` model**; `ProgramPlan`/`StudentPlan`/`TeacherPlan` dispatch `program-plan.*` / `student-plan.*` / `teacher-plan.*` |

**PROPOSED:** disable the active ones with a recorded reason; wire `group-homework.submitted` if the
submission step is wanted (§7-Q6), drop `group-assignment.submitted` with its type (§3.0.3), and either
delete the 3 `plan.*` rows or keep them disabled as a documented alias set.

### 2.3 The dead `{type}.updated` family — 5 rows dispatched, unrenderable

`child-training.updated`, `exam.updated`, `marathon-competition.updated`, `self-training.updated`,
`training.updated` are **dispatched** but their rows are `is_active = false` **and** their resolved
classes do not exist. They abort at stage 2 today, so the missing class is never reached — but re-enabling
one without adding the class produces a per-recipient failure instead.

**Under revision 2** the family is re-scoped by §3.0: `exam.updated` disappears with the type;
`child-training.updated` becomes the two training families; `marathon-competition.updated`,
`self-training.updated` and `training.updated` are **kept and enabled** with a class (a change to a live
event is worth telling its owner) — so the answer to the old Q1 is "enable four, delete one".

### 2.4 Dead code the same audit surfaced

| Item | Detail | **PROPOSED** |
|---|---|---|
| 2 orphan event classes | `Exam\Attempt\Submitted`, `Exam\Attempt\TimedOut` — unreachable, because `exam.attempt.*` resolves through the `Attempt → AssessmentAttempt` merge to `Exam\AssessmentAttempt\*` | delete (the whole `exam.*` family goes with §3.0) |
| `scope_program_id` | column exists, 0 rows set, in no `$fillable`, read by nothing | drop the column, or implement it |
| `notification_settings.channels` | cast in the model, **not a column**; the legacy path's `$setting->channels` is therefore always `null` | remove the cast (part of the E5 fix) |
| `placeholders` | in `$fillable` + cast, **not a column** — this is what makes the editor throw | remove (part of the E5 fix) |

---

## 3. The four workstreams

### 3.0 **The assessment scope — exactly eight notification subjects** (normative)

Assessment notifications are **specific**: there is **no generic `assessment.*` family** and the only
types that notify are the eight below. Everything an assessment does produces at most one event, named
after the subject the user actually sees in the UI.

#### 3.0.1 The eight subjects

| # | Subject (the notification name prefix) | `assessments.type` | How the subject is derived | `scope` |
|---|---|---|---|---|
| 1 | `marathon-competition` | `marathon-competition` | the type alone | `system` / `program` / `teacher` |
| 2 | `marathon-competition-training` | `child-training` | **the parent's type** — parent is a `marathon-competition` | `teacher` |
| 3 | `competition` | `competition` | the type alone | `system` / `program` / `teacher` |
| 4 | `competition-training` | `child-training` | **the parent's type** — parent is a `competition` | `teacher` |
| 5 | `training` | `training` | the type alone | `system` / `program` / `teacher` |
| 6 | `self-training` | `self-training` | the type alone | `user` |
| 7 | `group-exam` | `group-exam` | the type alone | `team` |
| 8 | `group-homework` | `group-homework` | the type alone | `team` |

**Excluded — no notification rows, no notification classes, no dispatch:** `exam` (retired from the
catalogue) and `group-assignment`. The dispatchers must *skip* them rather than fall back to a generic
name.

**Why subjects 2 and 4 are separate rows even though both are `child-training`:** the platform already
presents them as two things — `CompetitionTrainingResource` and `MarathonCompetitionTrainingResource`
both query `type = 'child-training' AND parent IS NOT NULL` — and their audiences differ (the training
inside a *competition* is followed by competition participants, the one inside a *marathon-competition*
by marathon stakeholders). One row for both would make the message wrong for one of them.

#### 3.0.2 The action matrix — 8 subjects × 7 actions = **56 rows**

| Action | Source today | Note |
|---|---|---|
| `created`, `updated`, `deleted` | `Models/Assessment.php::dispatchAssessmentEvent()` | the type-set dispatch; `updated` is currently dead (§2.3) |
| `starts.soon`, `ends.soon` | `SendAssessmentUpcomingNotifications` | hourly window |
| `completed`, `results.available` | same command (`ends_at` in the last hour); `results.available` only when `show_result` | `competition.results.available` is also dispatched by `RankingService` and `CloseExpiredEvents` |

Optional actions, each a decision (§7): **`attempt.submitted` / `attempt.timed_out`** for the three types
that have attempts (`self-training`, `group-exam`, `group-homework`) — today these exist only as the
generic `assessment.attempt.*`, dispatched by `MentalMathTimer`, and must become typed or be dropped;
**`group-homework.submitted`** — the row exists with no dispatcher (§2.2).

#### 3.0.3 The dispatchers that must change (this is code, not data)

| File | Change |
|---|---|
| `app/Models/Assessment.php` | `dispatchAssessmentEvent()`: (a) **stop dispatching the generic `assessment.{action}`**; (b) resolve the subject from the type **and, for `child-training`, from the parent's type**; (c) dispatch **nothing** for `exam` / `group-assignment` / any type outside the eight |
| `app/Console/Commands/SendAssessmentUpcomingNotifications.php` | same subject resolution in `dispatchBoth()`; drop the generic dispatch; restrict the query to the eight types |
| `app/Console/Commands/CloseExpiredEvents.php`, `Services/RankingService.php` | already dispatch the specific `competition.*` names — keep; verify no generic path remains |
| `app/Filament/Pages/MentalMathTimer.php` | `assessment.attempt.{submitted,timed_out}` → `"{$attempt->assessment->subject}.attempt.…"` (needs the same subject resolver) — or delete the dispatch (§7-Q5) |
| `app/Services/Assessment/PaperResultService.php` | keep `competition.result.paper_entered` (specific already) and give it a row |
| the group submission path | wire `group-homework.submitted` or remove the row (§7-Q6) |

The subject resolver is **one function** — `Assessment::notificationSubject(): ?string` — used by all
five call sites, so the rule cannot drift. It returns `null` for a type that must not notify.

#### 3.0.4 The 56 rows' baseline: what exists, what is new

| Subject | Rows today | Missing | Action |
|---|---|---|---|
| `marathon-competition` | 3 (`created`, `updated` inactive, `deleted`) | 4 | add `starts.soon`, `ends.soon`, `completed`, `results.available`; enable `updated` + add its class |
| `competition` | 5 | 2 | add `starts.soon`, `ends.soon`; enable `updated` + class |
| `training` | 5 | 2 | add `completed`, `results.available`; enable `updated` + class |
| `self-training` | 5 | 2 | same |
| `group-exam` | 5 | 2 | add `updated`, `deleted` (classes exist? verify — `GroupExam\Updated/Deleted` do **not** exist → 2 new stubs) |
| `group-homework` | 3 | 4 | add `updated`, `deleted`, `completed`, `results.available` (`Completed`/`Results\Available`/`Updated`/`Deleted` stubs missing) |
| `competition-training` | 0 (was `child-training.*`) | 7 | 5 rows **renamed** from `child-training.*` + 2 new (`completed`, `results.available`) |
| `marathon-competition-training` | 0 (was `child-training.*`) | 7 | same |

**Totals:** **29 rows disabled + deleted** (13 generic `assessment.*`, 12 `exam.*`, 4 `group-assignment.*`),
**5 rows renamed into 10**, **4 + 16 = 20 rows added** → **56 rows** for 8 subjects.

**Classes:** map both training subjects onto the existing `ChildTraining\*` stubs with two
`CLASS_OVERRIDES` entries (no new files for `created`/`deleted`/`starts.soon`/`ends.soon`), add the one
missing `Updated` stub, add the 6 missing stubs (`GroupExam\{Updated,Deleted}`, `GroupHomework\{Updated,Deleted,Completed,Results\Available}`),
and **delete 29 stubs** (`Assessment\*` 12, `Exam\*` 13, `GroupAssignment\*` 4 — both of the audit's
orphans are `Exam\Attempt\*` and go with them).

#### 3.0.5 Recipients are a function of `scope` (E3, applied to the eight)

**Revision 4 replaces this table with the matrix's §2.6 — the event's audience is read from the
participation data.** A scope no longer implies "the participants"; an event notifies **the people the
platform already knows are attached to it**, in addition to whoever the scope puts in charge:

| Who | Resolver | Where it comes from |
|---|---|---|
| the scope's authority (decider / oversight) | `scope-authority` | `config/participation.php` per scope |
| the **eligible programs' admins** | `event-eligible-admins` | `event_eligibilities.eligible_program_id` → the program's admins |
| the **eligible teachers** (and the eligible programs' teachers) | `event-eligible-teachers` | `event_eligibilities.eligible_teacher_id` + `eligible_program_id` |
| the **teachers taking part** | `event-participating-teachers` | `event_participations` where `status ∈ {pending, approved}` |
| the **approved students** | `event-students` | `student_enrollments` where `status = approved` |
| a `child-training`'s audience | `parent-participants` | the **parent** competition's **enrolment role set** — its eligible teachers, its participating teachers and its approved (joined) students |
| `training` — **no enrolment exists** | `scope-participants` | the audience the scope implies; a training has **no** enrolment/participation/eligibility leg (matrix §2.6.3) |
| `self-training` (scope `user`) | `student` | the solver |
| `group-*` (scope `team`) | `team-members` + `team-teacher` | the team |

Applied to every §5 / §14 lifecycle action (`created`, `updated`, `deleted`, `starts.soon`, `ends.soon`,
`completed`, `results.available`, `status.changed`, `locked`, `unlocked`) — the matrix's **§2.6** is
normative and holds the per-scope block and the two consequences. Eligibility lists exist **only for
system-scoped events**, so `event-eligible-*` appears on those rows alone; a program or teacher event's
eligibility is implicit in its `program_id` / `teacher_id`, which is what `scope-authority` and
`program-teachers` already return. **`training` (§5.3) is the exception:** enrolment is a marathon /
competition concept only (matrix §2.6.3), so a training's rows carry `scope-participants` and never the
participation keys. The **per-person** workflow events (`{e}.enrollment.*`, `{e}.participation.*`,
`{e}.eligibility.*`) are deliberately **outside** the rule — they keep the one person they are about, or
every student would be told about another student's rejection.

Two rules on top: the **actor** (`acting-user` / `creator`) is never the only recipient of an event that
needs a decision, and **one audience per group** (see §3.2.4).

#### 3.0.6 The authoritative target name list (the fixture the gate checks)

`{subject}.{action}` for `subject ∈ {marathon-competition, marathon-competition-training, competition,
competition-training, training, self-training, group-exam, group-homework}` × `action ∈ {created,
updated, deleted, starts.soon, ends.soon, completed, results.available}` — **56 names**, plus the optional
attempt/submission names of §3.0.2 once decided, plus `competition.result.paper_entered`.

### 3.1 Workstream A — the category taxonomy (19 → 19, regrouped; no snake_case, every event fits)

A category is a **UI/filter and reporting** grouping (the notification class's namespace is a code
concern and does not have to match). Today 19 categories mix three axes — business domain (`course`),
feature tier (`plan`), storage (`system`) — and one is snake_case while its sibling is not
(`program_level` vs `program`).

| Category | Covers | Changed from today |
|---|---|---|
| `user` | registration, approval, suspension, profile, password, verification, role, program assignment | unchanged (18 rows) |
| `program` | program lifecycle **+ program levels** | **absorbs `program_level`** (3 rows) |
| `plan` | the three plan tiers' CRUD (`program-plan.*`, `student-plan.*`, `teacher-plan.*`) | loses the 3 dead `plan.*` rows (§2.2) |
| `subscription` | lifecycle, payments, trials, grace, feature limits | unchanged (25 rows) |
| `assessment` | **the eight subjects of §3.0 only** — 56 rows | **−34** (`exam.*`, generic `assessment.*`, `group-assignment.*`), **+** the two training families |
| `attendance` | marked / missed | unchanged |
| `classroom` | scheduled / created / updated / cancelled | unchanged |
| `certificate` | created / issued | unchanged |
| `content` | **file, video** (only — the matrix keeps `course` and `lesson` as their own categories) | unchanged |
| `team` | team + members + path steps | unchanged |
| `marathon` | marathon lifecycle only | **loses** the participation families |
| `competition` | competition lifecycle only (+ `assigned`, `locked`, `unlocked`) | **loses** the same |
| **`participation`** | **NEW** — `{marathon,competition}.{enrollment.*, participation.*, payment.*, seat.*, seats_increase.*, eligibility.*}` | **splits out of `marathon`/`competition`** (~40 rows + the 10 new ones from §2.1): one workflow, one switch |
| `contact` | form submitted / reply sent | unchanged |
| `message` | `message.sent` | unchanged (1 row, inactive) |
| **`data`** | **NEW** — `data.exported`, `data.imported`, `data.import.failed` | moved out of `system` |
| `system` | backup, maintenance, queue health, storage usage | unchanged minus `data.*` |
| `announcement` | created / updated / deleted | unchanged |

**Deliverables for A**

1. **A data migration** (not only a seeder — a live install keeps its rows), keyed by `event_name`,
   idempotent, deleting nothing: category moves (above), the `child-training.* → {competition,
   marathon-competition}-training.*` **renames** (§3.0.4), and the 29 rows of §3.0.3 set `is_active = false`
   with a recorded reason.
2. **Category metadata** in the catalogue (§3.3) — `label` (en/ar) per category — so the admin screen
   groups by it instead of printing the raw key.
3. **Lang keys** `lang/{en,ar}/settings.php` → `notification_settings.categories.*` for the 19, and the
   `recipient_type_labels` reviewed for the resolvers that change (§3.2).
4. **`NotificationSettingResource`**: category as a tab/grouped filter and a labelled badge; the list
   driven by the metadata, not by a hard-coded array.
5. **Test**: every row's category is in the metadata; every assessment row's subject is one of the eight;
   no row exists for `exam.*`, `group-assignment.*` or `assessment.*`.

### 3.2 Workstream B — recipients, per event (E3)

Today 301 groups use **22 of 34** resolvers and there is no stated policy — so "relevant to each event"
starts as a written rule, then is applied row by row.

#### 3.2.1 The policy

| Role in the event | Who | Resolver |
|---|---|---|
| **Subject** — the person the event is ABOUT | the student / teacher / subscriber / participant | `student`, `teacher`, `subscriber`, `participant(s)` |
| **Owner** — accountable for the record | creator / teacher / event owner | `creator`, `assessment-owner`, `marathon-owner`, `course-owner`, `lesson-owner` |
| **Decider** — must act | program authorities, approver, join-request owner | `program-admins`, `approver`, `join-request-owner`, `{marathon,competition}-authorities` |
| **Informed** — program-level awareness | program admins/teachers/students | `program-*`, `portal-*` |
| **Oversight** — platform | super admins/managers | `super-admin(s)`, `super-manager`, `portal-manager` |
| **Actor** — whoever pressed the button | the user performing the action | `acting-user` — **only** for audit/confirmation events, never the sole recipient of a decision |

#### 3.2.2 Adopt or retire the 12 unused resolvers

Registered but named by no group: `portal-admin`, `portal-manager`, `portal-teacher`,
`portal-teacher-assistant`, `portal-teachers`, `portal-student`, `course-owner`, `lesson-owner`,
`join-request-owner`, `approver`, `enroller`, `custom`.

- **Adopt where the policy names them:** the three event-audience keys of §3.0.5 (`event-eligible-admins`,
  `event-eligible-teachers`, `event-participating-teachers`) for every §5 / §14 lifecycle row;
  `course-owner` / `lesson-owner` for `course.*` / `lesson.*`
  (today they notify the dynamic `teacher`, which is right only when the teacher owns them);
  `portal-manager` for plan/oversight rows; `join-request-owner` + `approver` for the
  approval events that today name `super-admin` by role; `enroller` for the `*.enrollment.manual` rows.
- **Retire the rest:** a resolver nobody may pick is a dropdown entry that resolves to nothing
  (decision §7-Q3).

#### 3.2.3 New resolvers, only where an event resolves nobody relevant

- `seat-requester` — the teacher who opened a seats-increase request (for the 8 new
  `{type}.seats_increase_*` rows).
- Otherwise reuse. `paper-owner` is **not** needed — the matrix's §5.2 row already names `student` + the
  scope authority + `acting-user`, and a resolver that reads only `$context['creator']` cannot serve it
  (no dispatcher passes that key). **Do not invent a resolver without a row that needs it.**

**The subscription audience is a three-tier policy (rev 1.9) — matrix §19 is normative.** Every
subscription row starts from `subscriber` (the holder: a person, or that program's **Program Admins and
Program Managers** when a program holds it) and adds **at most one** platform group, chosen by what the
event is for:

| Tier | Audience | Rule | Rows |
|---|---|---|---|
| **1 — Subject** | `subscriber` | the holder is told about **their own** subscription | 13 |
| **2 — Subject + Decider** | `subscriber` + `super-admin` | someone must **act** — `request.submitted`, `approved`, `removed`, `upgrade/downgrade.requested`, `payment.submitted` | 6 |
| **3 — Subject + Oversight** | `subscriber` + `super-manager` (and `program-admins` where the subscription is program-scoped) | **money moved or access ended** — `default/initial.assigned`, `expiring.soon`/`expiring.tomorrow`, `expired`, `feature.limit.reached`, `payment.failed`, `trial.converted` | 8 |

The keys are role-aware — **`super-admin` = Decider**, **`super-manager` = Oversight**, the split matrix
§2.2 defines — not the combined `super-admins` alias these rows previously mixed in. **This corrects the
sketch this section previously carried** that "`subscription.trial.converted` is served by `subscriber` +
`program-admins`": a conversion **moves money**, so it is a **tier-3** row (`subscriber` +
`super-manager`). See matrix §19 for the per-row tiers and §26 (rev 2.8) for the change.

**The event audience adds three more (revision 4).** `event-eligible-admins`, `event-eligible-teachers`
and `event-participating-teachers` (§3.0.5 above) read the eligibility and participation tables, and join
`event-students` and `parent-participants` to make an event's whole audience nameable. They are part of
the matrix's **19 PROPOSED keys** (matrix §2.4 / §2.5 / §2.6 / §2.7), adopted with **P3**.

**The level dimension adds two more (revision 7).** `level-students` and `level-owner` (matrix **§2.7**)
narrow the **student** audience of the two marathon-competition subjects to the level the student joined
the parent marathon at. The reason is data, not taste: a marathon holds **one `marathon-competition` per
level** (`assessments.level_classification`), a student joins the marathon **at one level**
(`student_enrollments.level_classification_id`, `2026_07_28_000001`), and the UI then shows that student
**only their level's competitions** (`MarathonResource::getCompetitionPath()`); staff get a level select
instead (`CompetitionsRelationManager::getStudentLevelId()`), a child training **inherits** its parent's
level (`ChildAssessments:133`), and deleting a level **cascades into its assessments** (FK
`onDelete('cascade')`). The event **name does not change** — it stays `{subject}.{scope}.{action}` and the
level is a **context fact** read from `assessments.level_classification`, per the user's decision. Applied
to **§5.1 (`marathon-competition`) and §5.4 (`marathon-competition-training`) only**: `event-students` →
`level-students` + `level-owner` on the first, `parent-participants` → the same pair on the second. The
teacher/admin audiences are **not** level-narrowed — the seat tables carry no level
(`seat_allocations` is keyed by `event_participation_id`) — and the rows must never *require* a level:
with `level_classification` NULL, `level-students` falls back to the event's approved enrolments, exactly
as `getCompetitionPath()` applies no filter when the student has no joined level. Extending it to the
standalone competition family is matrix **Q19**; the loss of `parent-participants`' teacher half on §5.4 is
**Q20**.

**And one already-registered key is adopted for the enrolment flow (revision 6).** `student-teacher`
resolves `$student->teacher` — the **eligible teacher** of an enrolment, whose seat pool the enrolment is
charged to (`StudentEnrollmentService::resolveSeatAllocation()`) — and is named by
`{e}.enrollment.{submitted,approved,removed,manual}` so a student's joining request reaches **both** the
event's owner and the student's teacher (matrix §16.1 / Q18). The audience is the one the (unwired)
`config/participation.php` `recipients` block already describes (`enrollment.submitted → teacher`).

**The matrix now holds the resolved list.** `NOTIFICATION_MATRIX.md` **§2.4 + §2.5 + §2.6 + §2.7** (rev 2.1 / 2.2 / 2.4 / 2.5 / 2.7)
enumerates **19 PROPOSED keys**: §2.4's 8 name an audience by `scope` (`scope-authority`,
`scope-participants`, `program-members`, `teacher-students`, `assessment-students`,
`parent-participants`, `certificate-holder`, `record-owner`); §2.5's 6 cover the **participation life
cycle** (`event-participants`, `event-students`, `eligible-teacher`, `eligible-student`,
`eligible-program`, `enrollment-student`); §2.6's 3 read the event's own eligibility / participation
tables (`event-eligible-admins`, `event-eligible-teachers`, `event-participating-teachers`); §2.7's 2
narrow the two marathon-competition subjects to the event's **level** (`level-students`, `level-owner`). §2.4.1 also requires repairs in **six** already-registered keys:
`team-teacher` / `team-members` read `team` where `classroom.*` sends `team_id`; `teacher` reads a `User`
where several dispatchers send `teacher_id` and never reads the `competition` event key;
`assessment-owner` returns nobody for `scope = team`; `subscriber` is fed the wrong model for certificates;
and — the biggest one — **`participants` resolves nobody at all**, because it reads the deprecated
join-request models while the live architecture writes `event_participations` / `student_enrollments`.
Adopt-or-skip is the matrix's **Q11** / **Q13**, to ship with **P3 (Recipients)** so rows and code land
together. Note this **supersedes** the `seat-requester` bullet above — matrix §25-Q6 reuses `participant`
(the seat-increase dispatch already passes it), so no such key is proposed.

#### 3.2.4 Two structural rules to respect while editing rows

1. **One audience per group.** `RecipientResolutionStage` fixes a user's channels from the **first** group
   that contributes them, so two groups naming the same audience with different channels silently give one
   of the two. The 6 rows listed in §1 must be checked: if the difference is intentional (mail to the
   student, in-app to authorities) it must be a *different* audience per group — otherwise it is a trap.
2. **A dynamic resolver with a missing context key returns nobody.** When a subject's resolver is added to
   a row, the dispatcher must pass the model (not the id) — the §3.0.3 table lists the dispatchers whose
   context must gain the parent assessment for the two training subjects.

#### 3.2.5 Review order (category by category, highest risk first)

`system` / `content` (super-admin fan-out — keep for backup/maintenance/storage, drop for
`file.uploaded`) → `subscription` (`subscriber` is right on every row; the 9 `super-admin` + 9
`super-manager` groups are now split by the matrix's **§19** three tiers — Decider vs Oversight vs routine)
→ `user` → **`assessment`** (the eight
subjects of §3.0 — the largest single edit) → `participation` (new).

### 3.3 Workstream C — one consolidated seeding file (E4)

**PROPOSED shape** — data separated from mechanics:

```
database/seeders/notifications/Catalogue.php          ← the ONE data file, written from
                                                        NOTIFICATION_EVENTS_MATRIX.md (319 entries)
database/seeders/notifications/Categories.php         ← the 19 categories + labels (§3.1)
database/seeders/NotificationCatalogueSeeder.php      ← idempotent upsert + report
app/Console/Commands/SyncNotificationCatalogue.php    ← notifications:sync-catalogue [--dry-run] [--force]
```

**The data file has a readable source of truth: `NOTIFICATION_EVENTS_MATRIX.md`.** It carries the same
rows as the matrix in *category → event → recipient* plain language — no statuses, no notes, no code — so
the seeding data can be reviewed by someone who does not read PHP before it becomes `Catalogue.php`. The
work order is: agree the rows **there** → write `Catalogue.php` + `Categories.php` from them → run
`notifications:sync-catalogue --dry-run`. The matrix stays the decision log behind it (statuses, the
rules, the code mapping, the open questions), and the per-category counts in matrix §24.4 are the check
that the two have not drifted. For a reader who should not have to read event names at all,
**`NOTIFICATION_EVENTS_MATRIX_V2.md`** states the same 327 events as *who actually receives this*, in
plain words, with no role tags and no resolver keys (refreshed 2026-10-09 — `PROJECT_DOCUMENTATION.md`
§23.119).

Each event entry (one shape for all, so a reviewer can diff two rows):

```php
'exam.created' => [   // (dropped under §3.0 — shown for shape only)
    'label'    => ['en' => '…', 'ar' => '…'],
    'category' => 'assessment',
    'active'   => true,          // the E1/E2 switch, explicit per row
    'groups'   => [
        [ 'recipient' => 'teacher', 'value' => null, 'channels' => ['database'],
          'dedup' => 1440, 'actions' => [...],
          'messages' => ['en' => ['database' => '…', 'mail_subject' => null, 'mail_body' => null, 'whatsapp' => null],
                         'ar' => [...]] ],
    ],
],
```

**Semantics (this is the part that fixes T3):**

| Situation | Behaviour |
|---|---|
| name not in `notification_settings` | **insert** (`is_default = true`) |
| row exists, `is_default = true` | **update** label/category/groups/active to the file's values |
| row exists, `is_default = false` (admin created it) | **never touched**, reported as *skipped* |
| row exists, not in the file | **reported as unknown**, never deleted; `--force` disables it |
| name dispatched by the code but absent from the file | reported as **missing** |

`--dry-run` prints the whole plan (insert/update/skip/unknown/missing). **No `delete()` — ever.** The
seeder becomes safe to run alone, in any order, on any install, which retires T3.

**Replacing the five seeders:** `DatabaseSeeder` stops calling them; each keeps a `@deprecated` header and
delegates to the catalogue seeder, so an ops runbook that still says
`db:seed --class=NotificationSettingSeeder` stops being destructive instead of failing.

### 3.4 Workstream D — the engine/UI hardening that makes it "enterprise" (E5, E6)

Ordered by blocking-ness. Each item names the trap it closes.

| # | Work | Closes |
|---|---|---|
| **D1** | **Fix the settings editor.** Remove `placeholders` (and `channels`) from `NotificationSetting::$fillable`/`casts`, or add the columns. Nothing reads `placeholders` (grep proves it). Then add a **test that mounts the modal and saves** — its absence is why this shipped broken. | **T1 (BLOCKER)** |
| D2 | `notifications:sync-catalogue --dry-run` (above) + a settings-screen save test. | T3, E4 |
| D3 | Rewrite `notifications:validate` → **`notifications:doctor`**: derive the resolver/event counts from the providers and the DB (no magic numbers), **never dispatch outside `--send-sample`**, and fail (exit 1) on: a dispatched name with no row, a row with no class, an unregistered recipient, a channel with no template, a template with an unknown placeholder, an assessment row outside the eight subjects. | T9, E6 |
| D4 | Make the **hard-coded pipeline** honest: read `config('notification-engine.pipeline')` (with `registerStages()` as the default) or delete the config array and say so. | T2 |
| D5 | Fix **quiet hours** (`QuietHoursStage` writes `delay_seconds`; `QueueDecisionStage` reads `delaySeconds`). | T6 |
| D6 | Fix **retry fan-out** (`RetryStage` schedules per **failed recipient**, not when the batch count is non-zero) and schedule `notifications:retry-failed`. | T7 |
| D7 | Fix `queue_connection` (the literal `default` is not a connection, so the queued second pass always throws). | T8 |
| D8 | **Preferences UI** (`notification_preferences`) and **program overrides UI** (`program_notification_overrides`), with the cache invalidation the resolvers require. | T15 |
| D9 | **Delivery observability**: a Filament page for `notification_history` / `failed_notifications`, plus retention for `notifications` / `notification_history` / `failed_notifications`. | T16, §13 |
| D10 | Digest support (`digest_frequency`) or remove the columns; `{scope}` → a real placeholder or removed from the 2 templates. | T12, T16 |
| D11 | The `notifications` table index for the bell's filter/ordering. | T18 |

---

## 4. Phases, in dependency order

| Phase | Scope | Why this order | Done when |
|---|---|---|---|
| **P0 — Unblock** | D1, D2 (dry-run only) | the editor is the only way an operator can maintain 200+ rows; the seeder is a footgun until the consolidated path exists | the settings modal saves, and a test proves it |
| **P1 — Assessment scope (E1, E2)** | **§3.0**: the subject resolver + the 5 dispatcher changes + the 29 rows disabled + the 5 renames + the 20 added + the 7 class additions / 29 deletions | the largest single correctness win, and it is a **code** change that must land before the catalogue is written, or the file would encode the old names | dispatching an `exam` or `group-assignment` event produces **no** notification attempt; all 8 subjects deliver |
| **P2 — Catalogue truth (E4)** | the catalogue file + seeder + `notifications:sync-catalogue` + Workstream A (categories) for the **rest** of the domains | the assessment rows are already right from P1; this makes them maintainable | `notifications:doctor` reports 0 missing / 0 unknown; category migration applied |
| **P3 — Recipients (E3)** | Workstream B: policy, adopt/retire the 12 resolvers, `seat-requester`, category-by-category review, per-event tests | needs the file from P2 as its medium | every row satisfies the policy; the per-event suite is green |
| **P4 — Enterprise behaviour** | **D5–D7** (small, real bugs), then **D8, D9** (the two UIs + observability), then D10, D11 | D5–D7 are engine bugs, not features; the UIs are the largest remaining chunk | a user can opt out; a program can silence an event; a failed send is visible and retryable |
| **P5 — Gate & document** | D3's strict mode in the test suite; docs (`NOTIFICATION_SYSTEM_WORKFLOW.md` §§7, 8, 16, 17; `PROJECT_DOCUMENTATION.md` §23; this file → **DONE**) | documentation last, from finished behaviour | the gate fails if P1–P4 regress |

**Estimated shape** (for sequencing, not commitment): P0 small; **P1 medium** (5 dispatchers + 56 rows +
~35 class files); P2 large-but-mechanical; P3 medium (judgement per row + tests); P4 large; P5 small.

---

## 5. Risks and how the plan handles them

| Risk | Mitigation |
|---|---|
| **The renamed training subjects orphan existing rows** (`child-training.*` still dispatched by a stale deployment). | P1 renames in one deploy: the migration renames the rows **and** the code switches the dispatcher in the same change; a temporary `CLASS_OVERRIDES` alias for the old names is **not** kept (a silent alias would hide the drift) — instead the gate reports any dispatch of a non-subject name. |
| **The catalogue file becomes a second source of truth that drifts from the code.** | The gate (D3) compares the file with `notification_settings` **and** with the dispatched-name fixture (which now includes the 56 subject names as data). |
| **Re-seeding overwrites curated admin wording.** | Upsert touches only `is_default` rows; admin-created rows are skipped and reported. Edits *to default rows* are still overwritten — §7-Q2. |
| **`--force` disables a row an install depends on.** | Unknown rows are **reported**, disabled only under `--force`, reversible, and never deleted. |
| **Dropping `exam.*` removes a notification a deployment still relies on.** | The type is retired from the catalogue and priced by nothing (`AssessmentResource` comment); `exam.*` rows are disabled (not deleted) in the migration, so the change is reversible with one flag. |
| **Recipient changes flood or silence a real workflow.** | One phase, one category at a time, each with a recipient test; the matrix review is recorded per category. |

---

## 6. Verification — what is added

| Test | Proves |
|---|---|
| `AssessmentNotificationSubjectTest` | the subject resolver: `exam` and `group-assignment` return **null**; `child-training` returns the two training subjects by parent; the other five return their type; every dispatch site uses it |
| `NotificationSettingsCatalogueTest` | every row's category is in the metadata; every recipient type is registered; every channel has its template; no unknown placeholder; **no `assessment.*` / `exam.*` / `group-assignment.*` row exists** |
| `NotificationSettingsEditorTest` | the list + modal **save** (the test whose absence hid T1); a non-default row is deletable |
| `NotificationEventCoverageTest` | the **dispatched-name fixture** (including the 56 subject names, §3.0.6) has an active row and an existing class for every name — the E1 gate |
| `NotificationCatalogueSeederTest` | idempotency; a non-default row untouched; an unknown row reported; nothing deleted |
| per-event `NotificationsRecipientsTest` (data provider) | for one fixture per event: the expected users receive it on the expected channels, and nobody else does |
| `NotificationEnginePipelineTest` (existing) | extended for every stage the plan touches (D4–D7) |

Plus `php artisan notifications:doctor --strict` in CI.

---

## 7. Open decisions

| # | Decision | Recommendation |
|---|---|---|
| **Q1** | *(answered by revision 2)* the `{type}.updated` family | enable it for the four subjects that keep a class-less `updated` (`marathon-competition`, `training`, `self-training`, the two training families) and add the stub; `exam.updated` disappears with its type |
| **Q2** | May a re-seed overwrite an admin's edit to a default row? | yes, but visibly: `--force` for the destructive path, and the command prints what it would overwrite (alternative: an `is_customized` pin) |
| **Q3** | The 12 unused resolvers: adopt or retire? | adopt `course-owner`, `lesson-owner`, `portal-manager`, `approver`, `join-request-owner`, `enroller`; retire `portal-admin`, `portal-teacher`, `portal-teacher-assistant`, `portal-teachers`, `portal-student`; keep `custom` for the Send Custom Notification page |
| **Q4** | The `participation` category split — accept? | yes: the only axis on which ~50 rows of one workflow become independently switchable |
| **Q5** | Attempts (`attempt.submitted` / `attempt.timed_out`): type them for `self-training`, `group-exam`, `group-homework`, or drop them? | **type them** (+6 rows): the solver's result today notifies nobody except through the generic `assessment.attempt.*` that this revision removes |
| **Q6** | `group-homework.submitted`: wire the submission step or drop the row? | **wire it** — a team homework submission is a workflow someone must act on; `group-assignment.submitted` drops with its type |
| **Q7** | `data.*` + `subscription.invoice.generated`: disable, or build the dispatchers? | disable now (dead weight in every admin's list); revisit when an export/import flow ships |

---

## 8. Documentation obligations (AGENTS.md §3, §10)

Landed with each phase, not at the end:

1. **`NOTIFICATION_SYSTEM_WORKFLOW.md`** — §6 (the assessment family: 8 subjects, `exam`/`group-assignment`
   excluded), §7.2/§7.4 (figures, the one seeder), §8 (the resolver list and the unused ones), §16
   (**T3** rewritten: no longer dangerous; **T11 corrected: 37**, not 1; **T19** never-dispatched rows;
   **T20** orphan classes — the two orphans and ~30 stubs are deleted in P1, so the row changes to
   RESOLVED), §17 (the new tests).
2. **`PROJECT_DOCUMENTATION.md`** — §23 (the audit: §23.18's inventory regenerated from the new catalogue,
   §23.19's trigger map, §23.30's required lists) plus the pointer already added to §23's header.
3. **`NOTIFICATION_SYSTEM_IMPLEMENTATION_PLAN.md`** — the **executable** plan under this one: its **69 gaps
   (G-01…G-69)**, 14-point definition of done, 12 workstreams / **71** steps (each with a check) and six
   phases (P0–P6) are the per-step working list. This file stays the *why, and in what order*; that one is
   the *how*, step by step. Tick a gap there as each phase here lands, so the two never describe different
   states.
4. **This file** — each phase flips its own status; the file is **archived** when P5 is green.

---

## 9. What this plan deliberately does not do

- **It does not notify for `exam` or `group-assignment`.** The types stay usable in the product; they
  simply have no notification rows (reversible per deployment).
- **It does not add a queue-based fan-out redesign.** The engine is synchronous by design and the batch cap
  is 500; making it truly async is a separate plan (D7 only makes the existing path honest).
- **It does not rename events outside the assessment family.** For those, the name is the join key and
  200+ rows depend on it.
- **It does not touch the 283 Filament toasts.** They are UI feedback, not messaging (workflow doc §2).
- **It does not invent resolvers, categories or languages without a row/event that needs them.**

---

## Change log for this document

| Version | Date | Change |
|---|---|---|
| **1.9** | 2026-09-30 | **The subscription recipient policy is reconciled with the matrix — the `trial.converted` conflict is resolved.** This file's §3.2.3 said a converted trial "is served by `subscriber` + `program-admins`"; the matrix's §19 carried `super-admin` + `super-manager`. Neither was wrong about *who exists*, but they disagreed, so the audience is now stated in one place: **matrix §19 (rev 2.8) is normative** and holds a **three-tier policy** — every row starts from `subscriber` (the holder) and adds at most one platform group: a **`super-admin`** where someone must **act** (tier 2), a **`super-manager`** where **money moved or access ended** (tier 3), nothing extra on the routine rows (tier 1). §3.2.3 now carries the same table and points at the matrix; the `trial.converted` conversion is **tier 3** (`subscriber` + `super-manager`) because it moves money. §3.2.5's review note ("9 `super-admin` + 9 `super-manager` must be split …") is marked done. Also corrected in §3.2.3 while editing it: `paper-owner` is not needed because a resolver reading only `$context['creator']` cannot serve `competition.result.paper_entered` — the matrix's §5.2 row names `student` + the scope authority + `acting-user`. **No resolver is added or removed by this revision**, and `NOTIFICATION_EVENTS_MATRIX.md` / `NOTIFIERS_EXPLAINATION.md` were regenerated. |
| **1.8** | 2026-09-29 | **Revision 7 — the level dimension (user-directed).** A student joins a **marathon** at one **level classification** (`student_enrollments.level_classification_id`, `2026_07_28_000001`), a marathon holds **one `marathon-competition` per level** (`assessments.level_classification`), and the UI then shows that student **only their level's competitions** (`MarathonResource::getCompetitionPath()`; staff get a level select, `CompetitionsRelationManager::getStudentLevelId()`); a child training **inherits** its parent's level (`ChildAssessments:133`) and deleting a level **cascades into its assessments** (FK `onDelete('cascade')`). New normative **matrix §2.7** adds two PROPOSED keys — `level-students` (the approved enrolments whose `level_classification_id` is the event's own level, read from the **parent marathon** for a marathon-competition) and `level-owner` (`level_classifications.user_id` when the level is **teacher**-scoped; nobody otherwise) — and applies them to **§5.1 / §5.4 only**. The event **name is unchanged** (still `{subject}.{scope}.{action}`): the level is a **dispatch context fact**, per the user's decision. The teacher/admin audiences are not level-narrowed (the seat tables carry no level) and a row never *requires* a level — NULL level ⇒ `level-students` behaves as before. Resolver vocabulary 51 → **53 keys** (34 registered + **19** PROPOSED); catalogue unchanged at **319 events**. Matrix Q19 (extend to the competition family?) and Q20 (the parent-teacher half lost on §5.4) added; `NOTIFIERS_EXPLAINATION.md` regenerated (797 recipient lines, 458 `⚠`). |
| **1.7** | 2026-09-29 | **Revision 6 — enrolment is a marathon/competition concept, and the enrolment role set is the participant audience of the four competition-family subjects.** §3.0.5 gains the rule and the source evidence behind it (`config/participation.php` configures only `marathon`/`competition`; `StudentEnrollment` is "an event (marathon or competition)"; the morph map holds only those two; the three relation managers bail on `Assessment.type !== 'competition'`; the training resources register none). Consequences: the matrix's **§5.3 `training` loses the participation-derived audience** (`scope-authority` + `scope-participants`), **`parent-participants` is redefined** as the parent's enrolment role set, and a student's **joining request now reaches the event's owner *and* the student's teacher** (`student-teacher`, matrix §16.1 / Q18 — matching the unwired `config/participation.php` `recipients` block). Also corrects the stale claim that `student-teacher` has no admin label (it does: `lang/en/settings.php:157`). Resolver vocabulary 48 → **51 keys**. |
| **1.6** | 2026-09-29 | **Revision 5 — the audience of an event is the participation data (user-directed).** §3.0.5 no longer derives recipients from `scope` alone: an event notifies, besides its authority, **the eligible programs' admins, the eligible teachers, the teachers taking part and the approved students** — read from `event_eligibilities`, `event_participations` and `student_enrollments` at dispatch time. Three new resolvers (§3.2.3) join `event-students` / `parent-participants`; the matrix's **§2.6** is normative, **49 §5 rows and 12 §14 rows were rewritten** to the block, the two `*-training` subjects use `parent-participants`, and the per-person §16 workflow events stay single-subject. **17 PROPOSED resolver keys** in total (was 14). |
| **1.5** | 2026-09-29 | **Revision 4 — Workstream C gets a readable source of truth.** NEW `NOTIFICATION_EVENTS_MATRIX.md` (the plain-language twin of the matrix: 19 categories, 319 entries, 513 recipient rows, a 48-key resolver glossary) is now what `Catalogue.php` + `Categories.php` are written from; §3.3 states the order and matrix §24.4 the count check. Category count corrected **17 → 19** (the index had omitted `course` and `lesson`) and the taxonomy target restated as **19 → 19, regrouped** rather than 19 → 18, because the matrix keeps `course`/`lesson` out of `content`. |
| **1.4** | 2026-09-29 | **Points at the matrix's §2.5 (rev 2.2) as well — 14 PROPOSED keys, not 8.** §2.5 adds the participation-life-cycle vocabulary (enrollment / eligibility / join request) and records that **`participants` resolves nobody** (deprecated join-request models; the live tables are `event_participations` / `student_enrollments`) — so Workstream B's resolver work grows from "at most 2–3 new" to the matrix's 14, with `ParticipantsResolver` a **rewrite**, and §16.5's eligibility rows gain a real subject. Adopt-or-skip is the matrix's Q11 / Q13, shipped with **P3**. |
| **1.3** | 2026-09-29 | **Points at the matrix's new §2.4 (rev 2.1).** Workstream B's §3.2.3 no longer sketches "at most 2–3 new resolvers": `NOTIFICATION_MATRIX.md` §2.4 holds the resolved set — **8 PROPOSED scope-aware keys** plus repairs to **five** registered ones — and the `seat-requester` idea is dropped (matrix Q6 reuses `participant`). Adopt-or-skip is the matrix's Q11, shipped with **P3**. |
| **1.2** | 2026-09-29 | **Revision 3 — the scope is folded into the event name.** On the user's direction, `NOTIFICATION_MATRIX.md` (rev 2) now names every event on a scope-carrying model `{base}.{scope}.{action}`, and this plan defers to it: `assessments` (per subject → **138** assessment rows), `marathons` (**21**), `announcements` (**9**), `certificates` (**6**); **17 categories, 312 events**. Corrections the matrix forced: the **`competition` category is gone** — every `competition.*` event is the assessment type `competition`, so the subject also owns `locked`/`unlocked`/`assigned`/`result.paper_entered` (3 scopes × 11 actions = 33); **`marathon.approved`/`rejected` are never dispatched** (drop, not enable); `LevelClassification` and `RankingTitle` carry a `scope` but dispatch nothing; `program_levels` has no scope column, so `program.level.*` stays unscoped. New defects recorded: the two scheduler commands dispatch `competition.*` for `marathon-competition` records, and `announcement.*` resolves nobody. |
| **1.1** | 2026-09-29 | **Revision 2 — the assessment families are scoped to eight named subjects (§3.0, normative).** There is no generic `assessment.*` family and no `exam.*` / `group-assignment.*`. Added: the eight-subject table with the `child-training` → `{competition,marathon-competition}-training` split (derived from the parent's type, matching the two Filament resources that both query `type = 'child-training'`); the 8 × 7 = **56-row** action matrix; the **five dispatchers that must change** (including a single `Assessment::notificationSubject()` resolver, the removal of the `assessment.{action}` fallback, and typed attempts in `MentalMathTimer`); the counted delta (**29 rows disabled, 5 renamed into 10, 20 added**); the scope → recipient matrix; the class additions/deletions (**29 stubs deleted** — `Assessment\*` 12, `Exam\*` 13, `GroupAssignment\*` 4 — and **7 added**: `ChildTraining\Updated` plus `GroupExam\{Updated,Deleted}` and `GroupHomework\{Updated,Deleted,Completed,Results\Available}`; two `CLASS_OVERRIDES` map both training subjects onto the existing `ChildTraining\*` stubs). §2.2 grew from 7 to **9 never-dispatched rows** (`group-{homework,assignment}.submitted` have no dispatcher). Q1 answered; Q5 and Q6 added. Phases re-cut: **P1 is now the assessment scope** and is a code change. |
| 1.0 | 2026-09-29 | The plan as first written: six acceptance criteria, the measured inventory, the four gaps (37 dispatched-but-unseeded, 7 seeded-but-never-dispatched, 2 orphan classes, 12 unused resolvers), the 19 → 18 category taxonomy, the recipient policy, the consolidated catalogue seeder, 11 hardening items, five phases, risks and tests. |
