SDD-007 — Global Learner Orchestration & Model Growth Control

Nguyên tắc: Store everything, model only what matters, load only what is relevant, optimize globally.

Infinite History → Compact Current Model → Small Relevant Context → Globally Optimized Decision

Invariants: Raw History ≠ Learner Model · Learner Model ≠ Runtime Context · School Recommendation ≠ Final Recommendation · School Workload ≠ Learner Capacity · Canonical Skill ≠ School-specific duplicate.

2. High-Level

Schools (Turtle…Ray) → Evidence Layer → {Evidence Store + Context Event Registry (SDD-002 §5b), Event Store} → Learner Engine → Canonical Learner Model → {Context Engine (SDD-002 §3), Goal Engine (SDD-002 §16), Workload/Constraint} → Global Learner Orchestrator → school Assessment/Learning/Recommendation Engines (chỉ tạo candidates) → Final Action Plan. (SRC-032: "Goals Engine" trong sơ đồ cũ nay được spec chính thức = Goal Engine SDD-002 §16.)

3–4. Data Separation & Model Growth (REQ-INT-10)

• Evidence Store: immutable observations {evidence_id, learner_id, skill_id, source, value, reliability, school_id, occurred_at}.
• Event Store: những gì đã xảy ra (audit, analytics, rebuild state) — không dùng trực tiếp làm AI context.
• Learner Model: chỉ computed state (skill_states, capability_states, stable_preferences, learning_patterns, active_goals_summary, model_metadata); 20.000 câu trả lời → Evidence Store; model chỉ giữ Linear Equations: mastery 0.78, confidence 0.91.
• Hard constraints: no raw events, no full conversation history, no complete assessment history, no duplicated school skill state, no expired context. Historical → summaries có provenance ("responds well to worked examples; difficulty with multi-step algebra") truy ngược được evidence gốc.

5. Shared Canonical Skill Graph (REQ-SCH-02)

Skill canonical (vd ALG.LINEAR_EQUATION.SOLVE) — một mastery state duy nhất; school thêm context: Turtle expected difficulty 2, Shark 5, SAT exam_application. Cấm turtle_linear_equation / shark_linear_equation / sat_linear_equation (fix fragmentation RISK-003, RISK-019).

6–7. Context Projection & Context Builder (REQ-INT-07)

Context tạo theo task: Goal + Relevant Skills + Recent Evidence + Workload + Constraints + Relevant History. Mỗi Engine khai báo Context Contract (max_skills, recent_evidence_days, include_active_goal, include_parent_model…). Context Builder Service là gateway bắt buộc trước khi AI chạm learner data: Retrieve → Filter → Rank relevance → Summarize → Enforce token budget → Return. Cấm LLM query learner DB tùy ý (QG-010).

6b. Planning Engine → Learning Plan Model (REQ-INT-20, REQ-LRN-18, REQ-PAR-15 — SRC-107)

SRC-384 (2026-08-19). Chuỗi model này sinh ra thứ gì trên MÀN HÌNH, và learner gặp nó theo trình tự nào, nay ghi ở SDD-021: hàng chờ 1 việc lớn + 2 việc nhỏ ở đầu Dashboard, và các lần đo.

Learning Plan Model = chiến lược học hiện tại cho một khoảng thời gian: "với trạng thái, mục tiêu và giới hạn hiện tại thì nên phân bổ việc học thế nào trong vài ngày/tuần/tháng tới?". Đây là living plan, không phải danh sách bài cố định; Recommendation Engine dùng nó để chọn Next Best Action cho hôm nay.

Đầu vào (Planning Engine đọc, không tự tính lại): Learner Model (mạnh/yếu theo node → gom theo mạch), Retention Model (summary.at_risk), Goal Model (learner_goal_entries active + deadline), Learner Context Model + Context Events (§5b), Constraints (quỹ thời gian/ngày), Readiness Model (còn cách target bao xa).

Đầu ra (content_json của version): priorities · phases · allocation · maintenance · retention · milestones · replanning_triggers · inputs · changes.

Quy tắc plan-v1	Nội dung
Quỹ thời gian	lời khai time_budget > available_minutes_per_week / 7 > mặc định 45′ (nói rõ là giả định)
Ốm / stress	cắt đôi thời gian, sàn 15′, đổi ưu tiên sang "học ngắn, đủ đều"
Ôn (retention)	25% buổi học, tối đa 15′, chỉ khi at_risk > 0
Vá chỗ yếu	50–60% phần còn lại khi có node gap/shaky, gom theo mạch chứ không liệt kê node
Giai đoạn	có chỗ yếu → "Xây lại nền" (2 tuần → nửa horizon) rồi "Luyện thi"/"Đi tiếp phần mới"
Chế độ	dùng lại mode blend 80/20 của SDD-011 §6 — không viết logic phân bổ thứ hai

Lưu & lịch sử: dùng chung learner_model_versions với model_kind='learning_plan' (migration 0027) — dedupe theo content hash nên chạy lại mà plan không đổi thì không đẻ version rác. Planning Engine là step cuối của WF-04: chạy trước 5 engine kia thì plan dựa trên dữ liệu cũ.

Vì sao plan đổi — mỗi version mang changes = {from_version, changes[], why[], triggered_by}: diff các trường learner thật sự nhìn thấy (thời gian/ngày, giai đoạn, phân bổ buổi học, thứ tự ưu tiên, chế độ), còn why sinh từ so sánh chính các đầu vào (inputs): lời khai mới/hết hạn (trích nguyên văn + ai khai), số bài chưa vững, số phần sắp quên, hạn mục tiêu, số ngày còn lại. Không có phần này thì learner chỉ thấy plan "tự nhiên khác đi" và mất niềm tin.

Ai khai được (SRC-107): cả Nemo lẫn bố mẹ — POST /v1/learners/{id}/context-events với 8 loại (time_budget, illness, exam_soon, busy, stress, motivation, focus_subject, other). Khai cùng loại thì bản mới supersede bản cũ (temporal, không cộng dồn mâu thuẫn); khai xong chạy luôn WF-15 "Declaration → Model Update" nên plan đổi ngay. UI: /plan ở learn, #/child/{id}/plan ở Marlins — cùng một model, chỉ khác chỗ đứng nhìn.

8. Global Workload Model (REQ-INT-08) — [Phase 2: tách Constraint, chờ Q-096]

{available_time, committed_time, deadlines, active_programs, cognitive_load, recent_load, fatigue, capacity} — dùng chung mọi school. Mỗi recommendation khai estimated_minutes, cognitive_load, deadline, frequency, priority. Demand 17h/capacity 10h → phải resolve, không đưa cả ba.

Định hướng SRC-032 (✍️ mặc định, chờ Q-096): SPLIT — Constraint Model (Phase 2, REQ-INT-19 ⏳) own normative limits (giới hạn giờ/ngày, quy định gia đình như "không học sau 22:00, chủ nhật nghỉ", health restrictions, academic constraints "giữ Toán học kỳ ≥ 8.0"); Workload thu hẹp còn descriptive demand (committed_time, cognitive_load, recent_load). Check TotalAllocatedTime ≤ Capacity chuyển sang Constraint Engine; plan bất khả thi → flag PLAN INFEASIBLE (yêu cầu tối ưu: ưu tiên high-value, giảm coverage, delay goal thấp) thay vì sinh lịch phi thực tế. Fatigue/ốm = Context Event ILLNESS (SDD-002 §5b) mà cả hai consume.

9. Global Learner Orchestrator (REQ-INT-09, REQ-LRN-06)

School engines sinh CandidateRecommendation[];

GlobalPriority = GoalValue × Urgency × ExpectedImpact × DependencyImportance × Confidence
              ÷ (TimeCost × CognitiveCost)
constraint: TotalAllocatedTime ≤ LearnerCapacity
→ GlobalLearningPlan  (vd: Fix Fractions 3h · SAT Mock 2h · IELTS Reading 3h · Shark Geometry defer)

Ánh xạ SRC-032 (✍️ mặc định, chờ Q-097): Orchestrator = lớp umbrella chứa 3 decision engines — GlobalPriority formula thuộc Recommendation Engine, capacity check thuộc Constraint Engine (§8), sinh/điều chỉnh plan thuộc Planning Engine. Learning Plan Model (REQ-INT-20 ✔ — hiện thực ở §6b): living strategy versioned {priorities, phases, allocation, maintenance, retention, milestones, replanning_triggers}; GlobalLearningPlan = allocation view hiện hành của model này; replanning triggers = goal replanning, semester transition, EXAM_RESCHEDULED, ILLNESS (workflows §15). Mode blend 80/20 (SDD-011 §6) = default heuristic thuộc Planning Engine — không viết allocation logic thứ hai; precedence: Constraint/health context > mode blend > default deep.

10. Conflict Resolution

Conflict Detector: Time (quá capacity) · Goal (tranh thời gian) · Pedagogical (A bảo tiến, B bảo còn prerequisite gap) · Duplicate work (merge activity) · Deadline (SAT 7 ngày > goal 6 tháng).

Inter-model precedence (SRC-032 §26, ✍️ mặc định chờ Q-099): Constraint/health context override plan/goal urgency (ốm → không ép lịch intensive, nhưng không dừng hẳn — đổi intervention: difficulty ↓, worked examples ↑, session ↓); source confidence cao thắng thấp; event mới supersede event cũ; goal parent-declared ≠ learner-declared → escalate cho parent quyết, hệ không tự quyết. Mục tiêu: tối ưu toàn trajectory, không tối ưu một metric cục bộ (không "Geometry yếu → nhồi 30' Geometry" khi stress HIGH + 30' còn lại).

12. Recency & Decay (REQ-INT-12)

effective_confidence = stored_confidence × recency_factor; context TTL: tired_today ~ hours, exam_next_week ~ days, active_course ~ months — TTL heuristics = default effective window per event type của Context Event Registry (SDD-002 §5b); lifecycle rời rạc ACTIVE/RESOLVED/EXPIRED nằm trong registry schema (decay liên tục chỉ áp cho confidence). "Struggled with fractions Grade 6" không được chi phối Grade 10 khi evidence mới đã supersede.

13. Incremental Recalculation

Evidence mới → chỉ recompute skill đó + dependent nodes + aggregates + affected recommendations (dependency graph). Heavy recompute qua Queue/Workflow.

14–15. Storage & Caching

D1: learner_skill_state, goals + goal_dependencies (nâng cấp learner_goals — SDD-002 §16), learner_context_events (SDD-002 §5b), recommendation_log (diff — SDD-002 §15), enrollments, workload_commitments, model_versions, context_metadata, recommendations. Migration & sequencing: dual-write learner_goals/learner_exam_targets → goals và sửa onboardingState đọc goals kind='exam_school' TRƯỚC khi cắt bảng cũ (tránh deploy lệch pha); semester_exam_schedule + learner_context_models thành projection (chấp nhận mất lịch sử context cũ — chỉ còn updated_at cuối). R2: snapshots, archived reports, bulky AI outputs. Queues: EvidenceRecorded, ModelUpdateRequested, RecommendationInvalidated, WorkloadChanged, ContextEventRecorded, GoalChanged, ConstraintChanged. Workflows: full recalculation, semester transition, goal replanning, cross-school schedule. Cache (KV): CurrentLearnerSummary/Plan/Workload/ActiveGoals — invalidate bằng domain events; cache không phải source of truth.

16. Versioning

Model: {model_version, algorithm_version, generated_at, evidence_cutoff}; recommendation lưu {learner_model_version, context_version, algorithm_version} → giải thích được "vì sao ngày 12/08 khuyên vậy".

17. Failure Isolation

Orchestrator lỗi → learner tiếp tục activity, portal sống, model không mất, recommendation trì hoãn. Một school lỗi → school khác không block. Context generation lỗi → fallback deterministic compact context. Orchestrator không là hard dependency của page load.

Trace

REQ-INT-07 → §6-7 · REQ-INT-08 → §8 · REQ-INT-09 → §9-10 · REQ-INT-10 → §3-4, §13 · REQ-INT-12 → §12 · REQ-SCH-02 → §5 · REQ-LRN-06 → §5, §9 · REQ-INT-20 / REQ-LRN-18 / REQ-PAR-15 → §6b.