tutor-service/internal/workflows/contracts.go

package workflows

type EvidenceKind string

const (
	EvidenceAnswer  EvidenceKind = "answer"
	EvidenceGrading EvidenceKind = "grading"
	EvidenceSource  EvidenceKind = "source"
	EvidenceSession EvidenceKind = "session"
	EvidenceAsset   EvidenceKind = "asset"
)

type EvidenceRef struct {
	Kind       EvidenceKind `json:"kind"`
	ID         string       `json:"id"`
	Quote      string       `json:"quote,omitempty"`
	Confidence float64      `json:"confidence"`
}

type ConceptRef struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Track string `json:"track"`
}

type ReadinessState string

const (
	ReadinessUnknown        ReadinessState = "unknown"
	ReadinessFragile        ReadinessState = "fragile"
	ReadinessImproving      ReadinessState = "improving"
	ReadinessInterviewReady ReadinessState = "interview_ready"
	ReadinessStrongSignal   ReadinessState = "strong_signal"
)

type DiagnosticResult struct {
	UserID                  string           `json:"user_id"`
	Track                   string           `json:"track"`
	TargetRole              string           `json:"target_role"`
	Stack                   []string         `json:"stack"`
	InitialReadiness        ReadinessState   `json:"initial_readiness"`
	ConceptFindings         []ConceptFinding `json:"concept_findings"`
	RecommendedNextConcepts []ConceptRef     `json:"recommended_next_concepts"`
}

type ConceptFinding struct {
	Concept   ConceptRef     `json:"concept"`
	Readiness ReadinessState `json:"readiness"`
	Reason    string         `json:"reason"`
	Evidence  []EvidenceRef  `json:"evidence"`
}

type GradedAnswer struct {
	AnswerID                string                   `json:"answer_id"`
	QuestionID              string                   `json:"question_id"`
	Concepts                []ConceptRef             `json:"concepts"`
	Scores                  AnswerScores             `json:"scores"`
	Overall                 AnswerOverall            `json:"overall"`
	Strengths               []string                 `json:"strengths"`
	Gaps                    []string                 `json:"gaps"`
	Evidence                []EvidenceRef            `json:"evidence"`
	MisconceptionCandidates []MisconceptionCandidate `json:"misconception_candidates"`
	FollowUp                FollowUpRecommendation   `json:"follow_up"`
}

type AnswerScores struct {
	Correctness        int `json:"correctness"`
	Depth              int `json:"depth"`
	Communication      int `json:"communication"`
	ProductionJudgment int `json:"production_judgment"`
}

type AnswerOverall string

const (
	AnswerMiss    AnswerOverall = "miss"
	AnswerPartial AnswerOverall = "partial"
	AnswerSolid   AnswerOverall = "solid"
	AnswerStrong  AnswerOverall = "strong"
)

type MisconceptionCandidate struct {
	Label       string        `json:"label"`
	Description string        `json:"description"`
	Evidence    []EvidenceRef `json:"evidence"`
	Confidence  float64       `json:"confidence"`
}

type FollowUpRecommendation struct {
	Needed   bool            `json:"needed"`
	Question string          `json:"question,omitempty"`
	Purpose  FollowUpPurpose `json:"purpose,omitempty"`
}

type FollowUpPurpose string

const (
	FollowUpClarify      FollowUpPurpose = "clarify"
	FollowUpRepair       FollowUpPurpose = "repair"
	FollowUpStretch      FollowUpPurpose = "stretch"
	FollowUpPressureTest FollowUpPurpose = "pressure_test"
)

type MemoryUpdateCandidate struct {
	UserID         string         `json:"user_id"`
	SourceAnswerID string         `json:"source_answer_id"`
	Updates        []MemoryUpdate `json:"updates"`
}

type MemoryUpdate struct {
	Kind          MemoryUpdateKind `json:"kind"`
	Concept       ConceptRef       `json:"concept"`
	ProposedState ReadinessState   `json:"proposed_state"`
	Summary       string           `json:"summary"`
	Evidence      []EvidenceRef    `json:"evidence"`
	Confidence    float64          `json:"confidence"`
	Durability    Durability       `json:"durability"`
}

type MemoryUpdateKind string

const (
	MemoryConceptMastery MemoryUpdateKind = "concept_mastery"
	MemoryMisconception  MemoryUpdateKind = "misconception"
	MemoryIntervention   MemoryUpdateKind = "intervention"
	MemoryReviewSchedule MemoryUpdateKind = "review_schedule"
)

type Durability string

const (
	DurabilityTentative Durability = "tentative"
	DurabilityConfirmed Durability = "confirmed"
)

type NextChallenge struct {
	UserID           string           `json:"user_id"`
	Track            string           `json:"track"`
	Concept          ConceptRef       `json:"concept"`
	LadderLevel      LadderLevel      `json:"ladder_level"`
	Question         string           `json:"question"`
	Rationale        string           `json:"rationale"`
	DifficultyAction DifficultyAction `json:"difficulty_action"`
	Evidence         []EvidenceRef    `json:"evidence"`
}

type LadderLevel string

const (
	LadderDefine            LadderLevel = "define"
	LadderTradeoffs         LadderLevel = "tradeoffs"
	LadderDebug             LadderLevel = "debug"
	LadderDesignConstraints LadderLevel = "design_constraints"
	LadderInterviewPressure LadderLevel = "interview_pressure"
)

type DifficultyAction string

const (
	DifficultyLower   DifficultyAction = "lower"
	DifficultyHold    DifficultyAction = "hold"
	DifficultyRaise   DifficultyAction = "raise"
	DifficultyRecover DifficultyAction = "recover"
)

type ReadinessUpdate struct {
	UserID         string                  `json:"user_id"`
	Track          string                  `json:"track"`
	ConceptUpdates []ConceptReadinessDelta `json:"concept_updates"`
	Unlocks        []Unlock                `json:"unlocks"`
}

type ConceptReadinessDelta struct {
	Concept  ConceptRef     `json:"concept"`
	Previous ReadinessState `json:"previous"`
	Next     ReadinessState `json:"next"`
	Reason   string         `json:"reason"`
	Evidence []EvidenceRef  `json:"evidence"`
}

type Unlock struct {
	Kind   UnlockKind `json:"kind"`
	Label  string     `json:"label"`
	Reason string     `json:"reason"`
}

type UnlockKind string

const (
	UnlockBossQuestion   UnlockKind = "boss_question"
	UnlockReviewCard     UnlockKind = "review_card"
	UnlockPortfolioEntry UnlockKind = "portfolio_entry"
)