Phase 4a: fetch and parse the authoritative Compass learning tasks

The Learning Tasks grid is capped at 20 rows and, on the parent page, mixes
both children, so it cannot answer "what is overdue". The parent home page
reported 6 overdue tasks for Harry while the stored grid held 1.

Fetch the per-child task list (read-only) from
POST /Services/LearningTasks.svc/GetAllLearningTasksByUserId, parse it into
task rows, and refuse to store it when the overdue count disagrees with the
home page summary (FR-12).

- fetcher: store learning-tasks-all.json + meta (userId, status, task count)
- parse: new learning-tasks-all page, JSON parser, home-page reconciliation
- store: drop superseded grid-derived task rows before the upsert
- docs: docs/phase-4a-overdue-tasks.md; close the Phase 3 known gap

Verified with live runs: Harry 70 tasks / 6 overdue, Finn 42 tasks / 2 overdue,
both equal to the home page; a tampered home page stops the parse.

Note: the fetcher and store.go files also carry the per-child session work
that was already uncommitted in this shared workspace (AUD-108).

Co-Authored-By: Paperclip <noreply@paperclip.ing>

internal/parse/parse.go

@@ -19,10 +19,11 @@ const (
 // Recognised page slugs, matching the <slug>.html files stored by the Phase 2
 // fetchers under var/raw/<child>/<runId>/.
 const (
-	PageHome          = "home"
-	PageChildProfile  = "child-profile"
-	PageLearningTasks = "learning-tasks"
-	PageCalendar      = "calendar"
+	PageHome             = "home"
+	PageChildProfile     = "child-profile"
+	PageLearningTasks    = "learning-tasks"
+	PageLearningTasksAll = "learning-tasks-all"
+	PageCalendar         = "calendar"
 )
 
 // Item is one message, learning task or calendar event read from Compass.
@@ -43,11 +44,14 @@ type Item struct {
 }
 
 // Page is one stored raw page: its slug, the URL it was fetched from, and the
-// HTML bytes.
+// bytes. HTML pages carry HTML; the JSON service page carries JSON and the
+// child's Compass userId (from the fetcher's meta file).
 type Page struct {
-	Slug string
-	URL  string
-	HTML []byte
+	Slug   string
+	URL    string
+	HTML   []byte
+	JSON   []byte
+	UserID string
 }
 
 // Parse turns the stored pages for one child into structured items. It fails,
@@ -64,11 +68,38 @@ func Parse(child string, pages []Page, loc *time.Location) ([]Item, error) {
 		loc = time.UTC
 	}
 
+	ordered := pagesOf(pages)
+
+	// When the authoritative per-child task list is stored, it supersedes the
+	// legacy HTML grid: the grid is capped and, on the parent page, mixes
+	// children. Parse the JSON list and ignore the grid pages for tasks so the
+	// same task is never stored twice.
+	hasAuthoritativeTasks := false
+	for _, p := range ordered {
+		if p.Slug == PageLearningTasksAll {
+			hasAuthoritativeTasks = true
+		}
+	}
+
 	var items []Item
 	recognised := 0
-	for _, p := range pagesOf(pages) {
+	var tasks *parsedTasks
+	for i := range ordered {
+		p := ordered[i]
 		switch p.Slug {
+		case PageLearningTasksAll:
+			got, err := parseLearningTasksAll(child, p, loc)
+			if err != nil {
+				return nil, err
+			}
+			tasks = &got
+			items = append(items, got.items...)
+			recognised++
 		case PageLearningTasks:
+			if hasAuthoritativeTasks {
+				recognised++
+				continue
+			}
 			got, err := parseLearningTasks(child, p, loc)
 			if err != nil {
 				return nil, err
@@ -77,7 +108,11 @@ func Parse(child string, pages []Page, loc *time.Location) ([]Item, error) {
 			recognised++
 		case PageChildProfile:
 			// The React profile page has no server-rendered grid; when it does
-			// carry the legacy grid, use it.
+			// carry the legacy grid, use it. The JSON list supersedes it.
+			if hasAuthoritativeTasks {
+				recognised++
+				continue
+			}
 			got, found, err := extractLearningTasks(child, p, loc)
 			if err != nil {
 				return nil, err
@@ -107,6 +142,23 @@ func Parse(child string, pages []Page, loc *time.Location) ([]Item, error) {
 		return nil, fmt.Errorf("parse: no recognised Compass page in %d stored page(s)", len(pages))
 	}
 
+	// FR-12: the stored task list must agree with the summary on the home page.
+	// A partial or stale list must never be shown as "nothing overdue", so a
+	// disagreement stops the parse instead of writing a quiet wrong answer.
+	if tasks != nil {
+		home := findPage(ordered, PageHome)
+		if home == nil {
+			return nil, fmt.Errorf("parse: %s: %s is present but the home page is missing; cannot verify the overdue count (FR-12)", child, PageLearningTasksAll)
+		}
+		want, found := homeOverdueCount(home.HTML, tasks.userID)
+		if !found {
+			return nil, fmt.Errorf("parse: %s: home page has no record of Compass user %s; cannot verify the overdue count (FR-12)", child, tasks.userID)
+		}
+		if want != tasks.overdue {
+			return nil, fmt.Errorf("parse: %s: home page reports %d overdue learning task(s) but the stored learning-task list has %d; refusing to store a partial list (FR-12)", child, want, tasks.overdue)
+		}
+	}
+
 	// A task row is the same task wherever it appears (learning tasks and child
 	// profile pages both carry the grid). Keep the first, drop the repeats.
 	seen := map[string]bool{}
@@ -132,6 +184,16 @@ func Parse(child string, pages []Page, loc *time.Location) ([]Item, error) {
 	return out, nil
 }
 
+// findPage returns the stored page with this slug, or nil.
+func findPage(pages []Page, slug string) *Page {
+	for i := range pages {
+		if pages[i].Slug == slug {
+			return &pages[i]
+		}
+	}
+	return nil
+}
+
 // pagesOf returns the pages with duplicates removed, keeping the last copy of a
 // slug (the fetcher overwrites a slug file on a re-fetch, so the last is
 // authoritative).