package store import ( "context" "crypto/sha256" "database/sql" "embed" "encoding/hex" "encoding/json" "errors" "fmt" "strings" "speech-learning-api/internal/domain" ) //go:embed coursebank/variants/*.json var variantFiles embed.FS var ErrCourseVariantUnavailable = errors.New("no reviewed exercises are available for this explanation language") const variantSchema = ` CREATE TABLE IF NOT EXISTS course_v2_bank_variants ( id TEXT PRIMARY KEY,base_entry_id TEXT NOT NULL REFERENCES course_v2_bank(id), canonical_task_id TEXT NOT NULL,instruction_language TEXT NOT NULL,revision TEXT NOT NULL, data JSONB NOT NULL,checksum TEXT NOT NULL,active BOOLEAN NOT NULL DEFAULT true); CREATE UNIQUE INDEX IF NOT EXISTS course_v2_variant_active_presentation ON course_v2_bank_variants(base_entry_id,instruction_language) WHERE active; CREATE INDEX IF NOT EXISTS course_v2_variant_lookup ON course_v2_bank_variants(instruction_language,base_entry_id) WHERE active; ALTER TABLE course_v2_tasks ADD COLUMN IF NOT EXISTS variant_id TEXT REFERENCES course_v2_bank_variants(id); CREATE INDEX IF NOT EXISTS course_v2_task_canonical ON course_v2_tasks(owner_id,language,version,(COALESCE(NULLIF(data->>'canonical_task_id',''),bank_entry_id))) WHERE exam_id IS NULL; -- Separate frozen presentations are allowed; their evidence identity is shared -- only when the editorial review classifies them as equivalent translations. DROP INDEX IF EXISTS course_v2_bank_assignment; CREATE UNIQUE INDEX IF NOT EXISTS course_v2_bank_variant_assignment ON course_v2_tasks(owner_id,bank_entry_id,COALESCE(variant_id,'')) WHERE exam_id IS NULL AND bank_entry_id IS NOT NULL; ` func BundledVariants(base []domain.BankEntry) ([]domain.BankVariant, error) { manifestData, err := variantFiles.ReadFile("coursebank/variants/manifest.json") if err != nil { return nil, err } var manifest struct { Total int `json:"total"` Files map[string]string `json:"files"` } if err = json.Unmarshal(manifestData, &manifest); err != nil { return nil, err } variants := []domain.BankVariant{} for name, digest := range manifest.Files { if strings.ContainsAny(name, "/\\") || name == "manifest.json" { return nil, errors.New("invalid variant manifest path") } data, err := variantFiles.ReadFile("coursebank/variants/" + name) if err != nil { return nil, err } sum := sha256.Sum256(data) if hex.EncodeToString(sum[:]) != digest { return nil, fmt.Errorf("variant checksum mismatch: %s", name) } var batch []domain.BankVariant dec := json.NewDecoder(strings.NewReader(string(data))) dec.DisallowUnknownFields() if err = dec.Decode(&batch); err != nil { return nil, err } variants = append(variants, batch...) } if len(variants) != manifest.Total || manifest.Total == 0 { return nil, errors.New("invalid variant count") } return variants, ValidateVariants(base, variants) } func ValidateVariants(base []domain.BankEntry, variants []domain.BankVariant) error { entries := map[string]domain.BankEntry{} for _, entry := range base { entries[entry.ID] = entry } seen := map[string]bool{} presentations := map[string]bool{} moduleLabels := map[string]string{} for _, v := range variants { original, ok := entries[v.BaseEntryID] t := v.Task b := original.Task if !ok || v.ID == "" || seen[v.ID] || !v.Reviewed || v.Revision == "" || v.InstructionLanguage == "" || t.ID != "" || t.Source != "" || t.ExamID != "" || t.EvidenceTaskID != "" || t.VariantID != v.ID || t.ContentRevision != v.Revision || t.CanonicalTaskID != v.CanonicalTaskID || t.InstructionLanguage != v.InstructionLanguage || t.SchemaVersion != b.SchemaVersion || t.ModuleID != b.ModuleID || t.TargetLanguage != b.TargetLanguage || t.CourseVersion != b.CourseVersion || t.CEFRLevel != b.CEFRLevel || t.Skill != b.Skill || t.Kind != b.Kind || t.AnswerKey == nil || t.Instruction == "" || len([]rune(t.Prompt)) > 2000 || strings.Contains(t.Prompt, "<") { return fmt.Errorf("invalid task variant: %s", v.ID) } if _, exists := entries[v.ID]; exists { return fmt.Errorf("variant identity collides with a base entry: %s", v.ID) } if v.ModuleTitle == "" || v.ModuleDescription == "" { return fmt.Errorf("variant module labels missing: %s", v.ID) } labelKey := t.ModuleID + ":" + v.InstructionLanguage labelValue := v.ModuleTitle + "\n" + v.ModuleDescription if previous, exists := moduleLabels[labelKey]; exists && previous != labelValue { return fmt.Errorf("inconsistent module labels: %s", v.ID) } moduleLabels[labelKey] = labelValue seen[v.ID] = true presentation := v.BaseEntryID + ":" + v.InstructionLanguage if presentations[presentation] { return fmt.Errorf("duplicate active locale presentation: %s", v.ID) } presentations[presentation] = true referenceLanguage := t.TargetLanguage if t.Skill == "vocabulary" { referenceLanguage = t.InstructionLanguage } if t.AnswerKey.ReferenceAnswerLanguage != referenceLanguage { return fmt.Errorf("invalid reference language: %s", v.ID) } if (v.Equivalence != "translation" && v.Equivalence != "adaptation") || (v.Equivalence == "translation" && v.CanonicalTaskID != v.BaseEntryID) || (v.Equivalence == "adaptation" && v.CanonicalTaskID != v.ID) { return fmt.Errorf("invalid variant identity: %s", v.ID) } prompt := t.Instruction if t.Stimulus != nil { stimulus := t.Stimulus if stimulus.Text == "" || stimulus.Language == "" || (stimulus.Role == "target" && stimulus.Language != t.TargetLanguage) || !bankMember(stimulus.Role, []string{"target", "source", "context"}) || (stimulus.Role == "source" && stimulus.Language == t.TargetLanguage) || t.Skill == "listening" { return fmt.Errorf("invalid public stimulus: %s", v.ID) } prompt += " " + stimulus.Text } if t.Prompt != prompt || t.AudioText != b.AudioText || t.Passage != b.Passage || t.ReferenceText != b.ReferenceText || len(t.Options) != len(b.Options) || t.AnswerKey.CorrectOptionID != b.AnswerKey.CorrectOptionID || t.AnswerKey.Explanation == "" || len(t.AnswerKey.Rubric) == 0 || t.AnswerKey.ReferenceAnswerLanguage == "" { return fmt.Errorf("variant changes protected task content: %s", v.ID) } labels := map[string]bool{} for i, option := range t.Options { label := strings.ToLower(strings.TrimSpace(option.Label)) expectedRole := "target" expectedLanguage := t.TargetLanguage if t.Skill == "vocabulary" { expectedRole = "meaning" expectedLanguage = t.InstructionLanguage } if option.Role != expectedRole || option.Language != expectedLanguage { return fmt.Errorf("invalid option language role: %s", v.ID) } if expectedRole == "meaning" && v.Equivalence == "translation" && t.InstructionLanguage == t.TargetLanguage { return fmt.Errorf("same-language meanings need a reviewed adaptation: %s", v.ID) } if option.ID != b.Options[i].ID || option.Language == "" || label == "" || labels[label] || (v.Equivalence == "translation" && option.Role == "target" && option.Label != b.Options[i].Label) { return fmt.Errorf("invalid variant options: %s", v.ID) } labels[label] = true if option.ID == t.AnswerKey.CorrectOptionID && option.Label != t.AnswerKey.ReferenceAnswer { return fmt.Errorf("variant reference/key mismatch: %s", v.ID) } } if v.Equivalence == "translation" && t.Skill != "vocabulary" && t.AnswerKey.ReferenceAnswer != b.AnswerKey.ReferenceAnswer { return fmt.Errorf("translation changes reference: %s", v.ID) } } return nil } func (s *AdaptiveStore) installVariants(ctx context.Context, base []domain.BankEntry) error { variants, err := BundledVariants(base) if err != nil { return err } if _, err = s.db.ExecContext(ctx, variantSchema); err != nil { return err } tx, err := s.db.BeginTx(ctx, nil) if err != nil { return err } defer tx.Rollback() if _, err = tx.ExecContext(ctx, `UPDATE course_v2_bank_variants v SET active=false FROM course_v2_bank b WHERE v.base_entry_id=b.id AND b.language='en-US' AND b.version=$1`, domain.CourseVersion); err != nil { return err } for _, v := range variants { data, err := json.Marshal(v) if err != nil { return err } sum := sha256.Sum256(data) checksum := hex.EncodeToString(sum[:]) var old string err = tx.QueryRowContext(ctx, `SELECT checksum FROM course_v2_bank_variants WHERE id=$1`, v.ID).Scan(&old) if err == nil && old != checksum { return fmt.Errorf("variant revision is immutable: %s", v.ID) } if err != nil && !errors.Is(err, sql.ErrNoRows) { return err } if _, err = tx.ExecContext(ctx, `INSERT INTO course_v2_bank_variants(id,base_entry_id,canonical_task_id,instruction_language,revision,data,checksum) VALUES($1,$2,$3,$4,$5,$6,$7) ON CONFLICT(id) DO UPDATE SET active=true`, v.ID, v.BaseEntryID, v.CanonicalTaskID, v.InstructionLanguage, v.Revision, data, checksum); err != nil { return err } } return tx.Commit() } // availableBank joins a locale presentation to its original curriculum entry. // Existing German entries are left byte-for-byte intact in the bank. const availableBank = `WITH available AS ( SELECT b.id AS base_id,''::text AS variant_id,b.id AS canonical_id,b.data AS entry,b.module_id,b.skill FROM course_v2_bank b WHERE b.active AND b.language=$2 AND b.version=$3 AND $4='de-DE' UNION ALL SELECT b.id,v.id,v.canonical_task_id,jsonb_build_object('id',v.id,'revision',v.revision,'learning_goal_id',b.goal,'difficulty',b.difficulty,'reviewed',true,'task',v.data->'task'),b.module_id,b.skill FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id WHERE v.active AND b.active AND b.language=$2 AND b.version=$3 AND v.instruction_language=$4 )` func (s *AdaptiveStore) InstructionLanguages(ctx context.Context, language string) ([]string, error) { rows, err := s.db.QueryContext(ctx, `SELECT 'de-DE' WHERE EXISTS(SELECT 1 FROM course_v2_bank WHERE active AND language=$1 AND version=$2) UNION SELECT DISTINCT v.instruction_language FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id WHERE v.active AND b.active AND b.language=$1 AND b.version=$2 ORDER BY 1`, language, domain.CourseVersion) if err != nil { return nil, err } defer rows.Close() out := []string{} for rows.Next() { var value string if err = rows.Scan(&value); err != nil { return nil, err } out = append(out, value) } return out, rows.Err() } func (s *AdaptiveStore) SetInstructionLanguage(ctx context.Context, user, language, instruction string) error { options, err := s.InstructionLanguages(ctx, language) if err != nil { return err } if !bankMember(instruction, options) { return ErrCourseVariantUnavailable } _, err = s.db.ExecContext(ctx, `UPDATE users SET instruction_language=$2 WHERE id=$1`, user, instruction) return err } // A request replay may resume its frozen German exam after the learner has // chosen another explanation language. Availability applies to new sessions. func (s *AdaptiveStore) HasExamRequest(ctx context.Context, user, language, request string) (bool, error) { var exists bool err := s.db.QueryRowContext(ctx, `SELECT EXISTS(SELECT 1 FROM course_v2_exams WHERE user_id=$1 AND language=$2 AND version=$3 AND request_id=$4)`, user, language, domain.CourseVersion, request).Scan(&exists) return exists, err } // Module labels are derived display content, never a rewrite of stored course // packs, task snapshots or learning-goal identifiers. func (s *AdaptiveStore) localizeModuleLabels(ctx context.Context, language, instruction string, modules []domain.AdaptiveModule) error { if instruction == "" || instruction == "de-DE" { return nil } rows, err := s.db.QueryContext(ctx, `SELECT DISTINCT b.module_id,v.data->>'module_title',v.data->>'module_description' FROM course_v2_bank_variants v JOIN course_v2_bank b ON b.id=v.base_entry_id WHERE v.active AND b.active AND b.language=$1 AND b.version=$2 AND v.instruction_language=$3`, language, domain.CourseVersion, instruction) if err != nil { return err } defer rows.Close() for rows.Next() { var id, title, description string if err = rows.Scan(&id, &title, &description); err != nil { return err } for i := range modules { if modules[i].ID == id { modules[i].Title = title modules[i].Description = description } } } return rows.Err() }