package store import ( "context" "crypto/sha256" "database/sql" _ "embed" "encoding/hex" "encoding/json" "errors" "fmt" "sync" "speech-learning-api/internal/domain" ) //go:embed coursebank/sequences.json var sequenceData []byte //go:embed coursebank/sequence_manifest.json var sequenceManifest []byte const sequenceSchema = ` CREATE TABLE IF NOT EXISTS course_v2_sequence_progress ( user_id TEXT NOT NULL REFERENCES users(id),language TEXT NOT NULL,version TEXT NOT NULL, module_id TEXT NOT NULL,revision TEXT NOT NULL,cursor INT NOT NULL DEFAULT 0 CHECK(cursor>=0), active_task_id TEXT REFERENCES course_v2_tasks(id),presented_at TIMESTAMPTZ, skipped_steps INT NOT NULL DEFAULT 0 CHECK(skipped_steps>=0), reviewed BOOLEAN NOT NULL DEFAULT false, PRIMARY KEY(user_id,language,version,module_id,revision)); ALTER TABLE course_v2_sequence_progress ADD COLUMN IF NOT EXISTS reviewed BOOLEAN NOT NULL DEFAULT false; ` type sequencePack struct { Revision string `json:"revision"` Review string `json:"editorial_review_sha256"` Sequences []domain.LearningSequence `json:"sequences"` } var sequencesOnce sync.Once var sequencesPack sequencePack var sequencesError error func bundledSequences() (sequencePack, error) { sequencesOnce.Do(func() { var manifest struct { SHA string `json:"sha256"` } if sequencesError = json.Unmarshal(sequenceManifest, &manifest); sequencesError != nil { return } sum := sha256.Sum256(sequenceData) if hex.EncodeToString(sum[:]) != manifest.SHA { sequencesError = errors.New("sequence checksum mismatch") return } if sequencesError = json.Unmarshal(sequenceData, &sequencesPack); sequencesError != nil { return } base, err := BundledBank() if err != nil { sequencesError = err return } sequencesError = validateSequences(sequencesPack, base) }) return sequencesPack, sequencesError } func validateSequences(pack sequencePack, base []domain.BankEntry) error { if pack.Revision == "" || len(pack.Review) != 64 || len(pack.Sequences) == 0 { return errors.New("missing sequence review") } entries := map[string]domain.BankEntry{} for _, entry := range base { entries[entry.ID] = entry } seen := map[string]bool{} phases := []string{"listen", "vocabulary", "read", "repeat", "grammar", "write", "compose", "speak"} kinds := []string{"choice", "choice", "choice", "repeat_sentence", "choice", "short_text", "free_text", "free_speech"} skills := []string{"listening", "vocabulary", "reading", "speaking", "grammar", "writing", "writing", "speaking"} for _, seq := range pack.Sequences { if seq.ID == "" || seen[seq.ID] || seq.Titles["de-DE"] == "" || seq.Titles["ru-RU"] == "" { return fmt.Errorf("invalid sequence: %s", seq.ID) } seen[seq.ID] = true phase := -1 for _, step := range seq.Steps { entry, ok := entries[step.BankEntryID] next := phase if next < 0 || step.Phase != phases[next] { next++ } if next >= len(phases) || step.Phase != phases[next] || !ok || entry.Task.ModuleID != seq.ModuleID || entry.Task.Kind != kinds[next] || entry.Task.Skill != skills[next] { return fmt.Errorf("invalid sequence step: %s/%s", seq.ID, step.BankEntryID) } phase = next } if phase != len(phases)-1 { return fmt.Errorf("incomplete sequence: %s", seq.ID) } last := seq.Steps[len(seq.Steps)-1] previous := seq.Steps[len(seq.Steps)-2] if entries[last.BankEntryID].Task.AnswerKey.ReferenceAnswer != entries[previous.BankEntryID].Task.AnswerKey.ReferenceAnswer { return fmt.Errorf("unrelated final writing/speech: %s", seq.ID) } } return nil } type sequencePosition struct { Sequence domain.LearningSequence Step domain.LearningSequenceStep StepIndex int TopicIndex int Topics int } func sequencePositions(pack sequencePack, module string) []sequencePosition { out := []sequencePosition{} topics := 0 for _, seq := range pack.Sequences { if seq.ModuleID == module { topics++ } } topic := 0 for _, seq := range pack.Sequences { if seq.ModuleID != module { continue } for n, step := range seq.Steps { out = append(out, sequencePosition{seq, step, n, topic, topics}) } topic++ } return out } func recommendationAt(pack sequencePack, positions []sequencePosition, cursor, skipped int, task, native string) *domain.SequenceRecommendation { r := &domain.SequenceRecommendation{Revision: pack.Revision, Complete: cursor >= len(positions), SkippedSteps: skipped} if r.Complete { return r } pos := positions[cursor] r.SequenceID = pos.Sequence.ID r.Title = pos.Sequence.Titles[native] r.Phase = pos.Step.Phase r.Step = pos.StepIndex + 1 r.Steps = len(pos.Sequence.Steps) r.Topic = pos.TopicIndex + 1 r.Topics = pos.Topics r.TaskID = task return r } // This cursor records participation/explicit skipping, never success. It is // independent of native language, variant and grades. Exams never use it. func (s *AdaptiveStore) SequenceRecommendation(ctx context.Context, user, language, module, native string) (*domain.SequenceRecommendation, error) { if language != "en-US" { return nil, nil } pack, err := bundledSequences() if err != nil { return nil, err } positions := sequencePositions(pack, module) if len(positions) == 0 { return nil, nil } var cursor, skipped int var reviewed bool var task string err = s.db.QueryRowContext(ctx, `SELECT cursor,skipped_steps,COALESCE(active_task_id,''),reviewed FROM course_v2_sequence_progress WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5`, user, language, domain.CourseVersion, module, pack.Revision).Scan(&cursor, &skipped, &task, &reviewed) if err != nil && !errors.Is(err, sql.ErrNoRows) { return nil, err } r := recommendationAt(pack, positions, cursor, skipped, task, native) r.Review = reviewed if task != "" && !r.Complete { answered, err := sequenceAnswered(ctx, s.db, domain.CourseJob{UserID: user, Language: language, ModuleID: module}, pack.Revision) if err != nil { return nil, err } r.NeedsAnswer = !answered } return r, nil } type sequenceSelection struct { Reset bool Reviewed bool Cursor int Skipped int Recommendation *domain.SequenceRecommendation } func selectSequence(ctx context.Context, tx *sql.Tx, j domain.CourseJob, candidates []bankCandidate) (*sequenceSelection, int, error) { if j.Language != "en-US" || j.Skill != "" || j.Kind != "next" { return nil, 0, nil } pack, err := bundledSequences() if err != nil { return nil, 0, err } positions := sequencePositions(pack, j.ModuleID) if len(positions) == 0 { if j.SubjectID != "" { return nil, 0, ErrCourseConflict } return nil, 0, nil } _, err = tx.ExecContext(ctx, `INSERT INTO course_v2_sequence_progress(user_id,language,version,module_id,revision) VALUES($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision) if err != nil { return nil, 0, err } var cursor, skipped int var reviewed bool reset := false var active string err = tx.QueryRowContext(ctx, `SELECT cursor,skipped_steps,COALESCE(active_task_id,''),reviewed FROM course_v2_sequence_progress WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5 FOR UPDATE`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision).Scan(&cursor, &skipped, &active, &reviewed) if err != nil { return nil, 0, err } if j.SubjectID != "" && (j.SubjectID != active || cursor >= len(positions)) { return nil, 0, ErrCourseConflict } if cursor < len(positions) && active != "" { answered, err := sequenceAnswered(ctx, tx, j, pack.Revision) if err != nil { return nil, 0, err } if answered && !reviewed && j.SubjectID == "" { // One optional review after an actually graded mistake. No pass mark // gates the path; a second answer or explicit skip continues it. var weak bool err = tx.QueryRowContext(ctx, `SELECT COALESCE((SELECT a.status='graded' AND (a.evaluation->>'score')::float8<80 FROM course_v2_attempts a JOIN course_v2_sequence_progress p ON p.active_task_id=a.task_id WHERE p.user_id=$1 AND p.language=$2 AND p.version=$3 AND p.module_id=$4 AND p.revision=$5 AND a.user_id=$1 AND NOT a.demo AND a.exam_id IS NULL AND a.created_at>=p.presented_at ORDER BY a.created_at DESC,a.id DESC LIMIT 1),false)`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, pack.Revision).Scan(&weak) if err != nil { return nil, 0, err } if weak { reviewed = true reset = true answered = false } } if answered || j.SubjectID != "" { cursor++ reviewed = false reset = true if !answered { skipped++ } active = "" } } r := recommendationAt(pack, positions, cursor, skipped, active, j.InstructionLanguage) r.Review = reviewed selection := &sequenceSelection{Cursor: cursor, Skipped: skipped, Recommendation: r, Reviewed: reviewed, Reset: reset} if r.Complete { return selection, 0, nil } for n, candidate := range candidates { if candidate.bankEntryID == positions[cursor].Step.BankEntryID { return selection, n, nil } } return nil, 0, ErrCourseVariantUnavailable } func saveSequenceSelection(ctx context.Context, tx *sql.Tx, j domain.CourseJob, selection *sequenceSelection, taskID string) error { if selection == nil { return nil } r := selection.Recommendation if r.Complete { taskID = "" } r.TaskID = taskID r.NeedsAnswer = taskID != "" _, err := tx.ExecContext(ctx, `UPDATE course_v2_sequence_progress SET cursor=$6,skipped_steps=$7,presented_at=CASE WHEN $9 OR active_task_id IS DISTINCT FROM NULLIF($8,'') THEN now() ELSE presented_at END,active_task_id=NULLIF($8,''),reviewed=$10 WHERE user_id=$1 AND language=$2 AND version=$3 AND module_id=$4 AND revision=$5`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, r.Revision, selection.Cursor, selection.Skipped, taskID, selection.Reset, selection.Reviewed) return err } func sequenceAnswered(ctx context.Context, db interface { QueryRowContext(context.Context, string, ...any) *sql.Row }, j domain.CourseJob, revision string) (bool, error) { var answered bool err := db.QueryRowContext(ctx, `SELECT EXISTS(SELECT 1 FROM course_v2_attempts a JOIN course_v2_sequence_progress p ON p.active_task_id=a.task_id WHERE p.user_id=$1 AND p.language=$2 AND p.version=$3 AND p.module_id=$4 AND p.revision=$5 AND a.user_id=$1 AND a.exam_id IS NULL AND NOT a.demo AND a.status IN ('graded','ungraded','pending') AND a.created_at>=p.presented_at)`, j.UserID, j.Language, domain.CourseVersion, j.ModuleID, revision).Scan(&answered) return answered, err }