grounding

type APILibraryChecker struct {
	// contains filtered or unexported fields
}

type APILibraryCheckerConfig struct {
	// Enabled determines if API/library checking is active.
	Enabled bool

	// CheckLibraryExists validates that claimed libraries appear in imports.
	// E.g., "uses gorm" but gorm is not in any import statements.
	CheckLibraryExists bool

	// CheckLibraryConfusion detects similar library mixups.
	// E.g., claims "gorm" but evidence shows "sqlx" is imported.
	CheckLibraryConfusion bool

	// CheckAPIUsageInEvidence validates that claimed API patterns exist.
	// E.g., "gorm.Open()" but this call pattern doesn't appear in code.
	CheckAPIUsageInEvidence bool

	// MaxClaimsToCheck limits how many library claims to check per response.
	// Prevents excessive checking on large responses.
	MaxClaimsToCheck int

	// MinLibraryNameLength filters out short names that may be false positives.
	// Library names shorter than this are ignored.
	MinLibraryNameLength int
}

type AbsoluteClaim struct {
	// Sentence is the full sentence containing the absolute language.
	Sentence string

	// ClaimType categorizes the absolute (absolute, negative_absolute, universal, exhaustive).
	ClaimType string

	// Keywords are the extracted topic keywords from the claim.
	Keywords []string

	// Position is the character offset in the response.
	Position int

	// MatchedPattern is the pattern that matched.
	MatchedPattern string
}

type AnchoredSynthesisBuilder interface {
	// BuildAnchoredSynthesisPrompt creates a synthesis prompt grounded in evidence.
	//
	// Inputs:
	//   ctx - Context for cancellation and metrics.
	//   assembledCtx - The context with tool results and code context.
	//   userQuestion - The user's original question.
	//   projectLang - The detected project language (e.g., "go", "python").
	//
	// Outputs:
	//   string - The anchored synthesis prompt.
	BuildAnchoredSynthesisPrompt(ctx context.Context, assembledCtx *agent.AssembledContext, userQuestion string, projectLang string) string

	// ScoreEvidence scores all tool results for relevance and recency.
	//
	// Inputs:
	//   toolResults - The tool results to score.
	//   userQuestion - The user's question for relevance scoring.
	//
	// Outputs:
	//   []ScoredEvidence - Scored evidence sorted by total score (descending).
	ScoreEvidence(toolResults []agent.ToolResult, userQuestion string) []ScoredEvidence

	// SelectTopEvidence selects the best evidence within token budget.
	//
	// Inputs:
	//   scored - Scored evidence (already sorted).
	//   maxTokens - Maximum token budget.
	//
	// Outputs:
	//   []ScoredEvidence - Selected evidence within budget.
	SelectTopEvidence(scored []ScoredEvidence, maxTokens int) []ScoredEvidence
}

type AnchoredSynthesisConfig struct {
	// Enabled determines if anchored synthesis is active.
	Enabled bool

	// MaxEvidenceTokens is the maximum token budget for evidence in prompt.
	MaxEvidenceTokens int

	// MaxResultLength is the maximum length per individual result.
	MaxResultLength int

	// MinResultsToInclude ensures at least this many results are included.
	MinResultsToInclude int

	// RecencyWeight scales the recency score contribution (0.0-1.0).
	RecencyWeight float64

	// RelevanceWeight scales the relevance score contribution (0.0-1.0).
	RelevanceWeight float64

	// IncludeNegativeExamples adds "DO NOT" instructions to the prompt.
	IncludeNegativeExamples bool

	// EnforceLanguage adds language-specific guidance to the prompt.
	EnforceLanguage bool
}

type AttributeChecker struct {
	// contains filtered or unexported fields
}

type AttributeCheckerConfig struct {
	// Enabled determines if attribute hallucination checking is active.
	Enabled bool

	// MaxClaimsToCheck limits how many attribute claims to check per response.
	// Prevents excessive checking on large responses.
	MaxClaimsToCheck int

	// IgnorePartialClaims if true, only validates exact count claims.
	// If false, also validates claims like "has fields X and Y".
	IgnorePartialClaims bool

	// MinSymbolLength filters out short symbol names that may be false positives.
	MinSymbolLength int
}

type AttributeClaim struct {
	Kind       AttributeClaimKind
	SymbolName string
	Value      string   // The claimed value (e.g., "3" for count, "error" for type)
	Values     []string // For list-based claims (e.g., field names)
	RawText    string   // Original text containing the claim
	Position   int      // Position in response
}

type AttributeClaimKind int

type BehavioralChecker struct {
	// contains filtered or unexported fields
}

type BehavioralCheckerConfig struct {
	// Enabled determines if behavioral hallucination checking is active.
	Enabled bool

	// CheckErrorHandling enables checking claims about error handling.
	// E.g., "logs errors", "returns error to caller", "handles failures gracefully".
	CheckErrorHandling bool

	// CheckValidation enables checking claims about input validation.
	// E.g., "validates input", "sanitizes data", "checks parameters".
	CheckValidation bool

	// CheckSecurity enables checking claims about security behavior.
	// E.g., "encrypts data", "authenticates users", "authorizes access".
	// NOTE: Security claims use RequireCounterEvidence to avoid false positives.
	CheckSecurity bool

	// RequireCounterEvidence if true, only flags claims with explicit counter-evidence.
	// If false, also flags claims with no supporting evidence (more false positives).
	// Default: true (conservative, fewer false positives).
	RequireCounterEvidence bool

	// MaxClaimsToCheck limits how many behavioral claims to check per response.
	// Prevents excessive checking on large responses.
	MaxClaimsToCheck int
}

type BehavioralClaim struct {
	// Subject is the function/component the claim is about.
	Subject string

	// Behavior is the claimed behavior.
	Behavior string

	// Category is the type of behavioral claim.
	Category BehavioralClaimCategory

	// Position is the character offset in the response.
	Position int

	// Raw is the original matched text.
	Raw string
}

type BehavioralClaimCategory int

type ChainOfVerification struct {
	// contains filtered or unexported fields
}

type ChainOfVerificationConfig struct {
	// Enabled determines if chain-of-verification is active.
	Enabled bool

	// VerifyThreshold is the minimum confidence to keep a claim.
	// Values: "HIGH", "MEDIUM", "LOW"
	VerifyThreshold string

	// MaxClaimsToVerify limits how many claims to verify per response.
	MaxClaimsToVerify int
}

type CheckInput struct {
	// Response is the LLM response text.
	Response string

	// UserQuestion is the original user question being answered.
	// Used by SemanticDriftChecker to verify response addresses the question.
	UserQuestion string

	// ProjectRoot is the absolute path to the project root.
	ProjectRoot string

	// ProjectLang is the primary language of the project (e.g., "go", "python").
	ProjectLang string

	// KnownFiles maps file paths that exist in the project to true.
	KnownFiles map[string]bool

	// KnownSymbols maps symbol names that exist in the graph to true.
	KnownSymbols map[string]bool

	// KnownPackages maps package paths that exist in the project to true.
	// Derived from graph file paths (e.g., "pkg/calcs", "cmd/orchestrator").
	// Used by PhantomPackageChecker to validate package path references.
	KnownPackages map[string]bool

	// CodeContext is the code that was shown to the LLM.
	CodeContext []agent.CodeEntry

	// ToolResults are the tool outputs the LLM saw.
	ToolResults []ToolResult

	// EvidenceIndex is the pre-built evidence index (optional).
	EvidenceIndex *EvidenceIndex
}

type Checker interface {
	// Name returns the checker name for logging and metrics.
	Name() string

	// Check runs the grounding check.
	//
	// Inputs:
	//   ctx - Context for cancellation.
	//   input - The input data for checking.
	//
	// Outputs:
	//   []Violation - Any violations found.
	Check(ctx context.Context, input *CheckInput) []Violation
}

type CircuitBreakerStateValue int

type Citation struct {
	// Raw is the original text (e.g., "[main.go:45]").
	Raw string

	// FilePath is the extracted file path.
	FilePath string

	// StartLine is the starting line number.
	StartLine int

	// EndLine is the ending line number (same as StartLine for single line).
	EndLine int

	// Position is the character position in the response.
	Position int
}

type CitationChecker struct {
	// contains filtered or unexported fields
}

type CitationCheckerConfig struct {
	// RequireCitations requires citations for claims.
	RequireCitations bool

	// ValidateFileExists checks that cited files exist.
	ValidateFileExists bool

	// ValidateInContext checks that cited files were in context.
	ValidateInContext bool

	// ValidateLineRange checks that line numbers are valid.
	ValidateLineRange bool
}

type Claim struct {
	// Type is the kind of claim.
	Type ClaimType

	// Value is the claimed value (file path, symbol name, etc.).
	Value string

	// RawText is the original text that contained this claim.
	RawText string

	// Position is where in the response this claim was found.
	Position int
}

type ClaimType int

type ClaimVerification struct {
	// ClaimID is the ID of the claim being verified.
	ClaimID int `json:"claim_id"`

	// Verified is true if the LLM could verify the claim.
	Verified bool `json:"verified"`

	// Confidence is HIGH, MEDIUM, LOW, or CANNOT_VERIFY.
	Confidence string `json:"confidence"`

	// Citation is the file:line reference (if verified).
	Citation string `json:"citation,omitempty"`

	// Reason explains why the claim couldn't be verified.
	Reason string `json:"reason,omitempty"`
}

type CodeBlock struct {
	// Content is the code content without the fences.
	Content string

	// Language is the language specifier (e.g., "go", "python"), may be empty.
	Language string

	// Position is the character offset in the response where this block starts.
	Position int

	// EndPosition is the character offset where this block ends.
	EndPosition int

	// ContextBefore is the text immediately before the code block.
	ContextBefore string

	// IsInline indicates if this is inline code (single backticks) vs fenced.
	IsInline bool
}

type CodeBlockMatch struct {
	// Block is the original code block.
	Block CodeBlock

	// Classification is how the code was classified.
	Classification CodeClassification

	// Similarity is the best similarity score found (0.0-1.0).
	Similarity float64

	// MatchedFile is the file path where the best match was found.
	MatchedFile string

	// SkipReason explains why the block was skipped (if Classification == Skipped).
	SkipReason string
}

type CodeClassification int

type CodeSnippetChecker struct {
	// contains filtered or unexported fields
}

type CodeSnippetCheckerConfig struct {
	// Enabled determines if code snippet checking is active.
	Enabled bool

	// VerbatimThreshold is the minimum similarity for VERBATIM classification.
	// Code above this threshold is considered an exact or near-exact match.
	// Default 0.9 (90% similar = verbatim).
	VerbatimThreshold float64

	// ModifiedThreshold is the minimum similarity for MODIFIED classification.
	// Code between ModifiedThreshold and VerbatimThreshold is similar but differs.
	// Code below this threshold is classified as FABRICATED.
	// Default 0.5 (50-90% = modified, <50% = fabricated).
	ModifiedThreshold float64

	// MinSnippetLength is the minimum code length to validate.
	// Shorter snippets are skipped (too easy to match by chance).
	// Default 20 characters.
	MinSnippetLength int

	// MaxSnippetLength is the maximum code length to validate.
	// Longer snippets are truncated for performance.
	// Default 5000 characters.
	MaxSnippetLength int

	// MaxCodeBlocksToCheck limits how many code blocks to validate per response.
	// Prevents excessive checking on responses with many code blocks.
	// Default 10.
	MaxCodeBlocksToCheck int

	// NormalizationLevel specifies how to normalize code before comparison.
	// Default NormWhitespace (preserve comments).
	NormalizationLevel NormalizationLevel

	// SuggestionContextLines is how many lines before a code block to check
	// for suggestion phrases (e.g., "you could", "for example").
	// Default 5 lines.
	SuggestionContextLines int

	// CheckInlineCode enables checking inline code (single backticks).
	// Default false - inline code is often too short to validate reliably.
	CheckInlineCode bool
}

type ConfidenceChecker struct {
	// contains filtered or unexported fields
}

type ConfidenceCheckerConfig struct {
	// Enabled determines if confidence fabrication checking is active.
	Enabled bool

	// AbsentEvidenceSeverity is the severity for claims with no supporting evidence.
	// Default SeverityCritical - making absolute claims with no search is very problematic.
	AbsentEvidenceSeverity Severity

	// PartialEvidenceSeverity is the severity for claims with partial/truncated evidence.
	// Default SeverityHigh - absolute claims with limited search should be flagged.
	PartialEvidenceSeverity Severity

	// AllowHedgedAbsolutes skips claims that have hedging language nearby.
	// E.g., "it appears that all..." - the hedge negates the absolute.
	// Default true.
	AllowHedgedAbsolutes bool

	// SkipTautologies skips claims that are definitionally true.
	// E.g., "all .go files have .go extension" - always true.
	// Default true.
	SkipTautologies bool

	// SkipCodeBlocks skips absolute language inside code blocks/quotes.
	// Avoids flagging quoted documentation or code comments.
	// Default true.
	SkipCodeBlocks bool

	// MaxClaimsToCheck limits how many absolute claims to check per response.
	// Prevents excessive checking on responses with many absolute words.
	MaxClaimsToCheck int
}

type Config struct {
	// Enabled determines if grounding checks are enabled.
	Enabled bool

	// RejectOnCritical rejects responses with critical violations.
	RejectOnCritical bool

	// AddFootnoteOnWarning adds warning footnotes to responses.
	AddFootnoteOnWarning bool

	// MaxViolationsBeforeReject triggers rejection at this threshold.
	MaxViolationsBeforeReject int

	// MinConfidence is the minimum confidence to be considered grounded.
	MinConfidence float64

	// MaxResponseScanLength limits how much of the response to scan.
	MaxResponseScanLength int

	// Timeout is the maximum time for grounding checks.
	Timeout time.Duration

	// ShortCircuitOnCritical stops checking after first critical violation.
	ShortCircuitOnCritical bool

	// MaxHallucinationRetries is the circuit breaker limit.
	MaxHallucinationRetries int

	// LanguageCheckerConfig configures the language consistency checker.
	LanguageCheckerConfig *LanguageCheckerConfig

	// CitationCheckerConfig configures the citation checker.
	CitationCheckerConfig *CitationCheckerConfig

	// GroundingCheckerConfig configures the grounding (claim validation) checker.
	GroundingCheckerConfig *GroundingCheckerConfig

	// TMSVerifierConfig configures the TMS-based claim verifier.
	TMSVerifierConfig *TMSVerifierConfig

	// StructuredOutputConfig configures the structured output validator.
	StructuredOutputConfig *StructuredOutputConfig

	// ChainOfVerificationConfig configures the chain-of-verification verifier.
	ChainOfVerificationConfig *ChainOfVerificationConfig

	// MultiSampleConfig configures the multi-sample consistency verifier.
	MultiSampleConfig *MultiSampleConfig

	// StructuralClaimCheckerConfig configures the structural claim checker.
	StructuralClaimCheckerConfig *StructuralClaimCheckerConfig

	// PhantomCheckerConfig configures the phantom file checker.
	PhantomCheckerConfig *PhantomCheckerConfig

	// PostSynthesisConfig configures post-synthesis verification.
	PostSynthesisConfig *PostSynthesisConfig

	// AnchoredSynthesisConfig configures tool-anchored synthesis prompts.
	AnchoredSynthesisConfig *AnchoredSynthesisConfig

	// PhantomSymbolCheckerConfig configures the phantom symbol checker.
	PhantomSymbolCheckerConfig *PhantomSymbolCheckerConfig

	// SemanticDriftCheckerConfig configures the semantic drift checker.
	SemanticDriftCheckerConfig *SemanticDriftCheckerConfig

	// AttributeCheckerConfig configures the attribute hallucination checker.
	AttributeCheckerConfig *AttributeCheckerConfig

	// LineNumberCheckerConfig configures the line number fabrication checker.
	LineNumberCheckerConfig *LineNumberCheckerConfig

	// RelationshipCheckerConfig configures the relationship hallucination checker.
	RelationshipCheckerConfig *RelationshipCheckerConfig

	// BehavioralCheckerConfig configures the behavioral hallucination checker.
	BehavioralCheckerConfig *BehavioralCheckerConfig

	// QuantitativeCheckerConfig configures the quantitative hallucination checker.
	QuantitativeCheckerConfig *QuantitativeCheckerConfig

	// CodeSnippetCheckerConfig configures the fabricated code snippet checker.
	CodeSnippetCheckerConfig *CodeSnippetCheckerConfig

	// APILibraryCheckerConfig configures the API/library hallucination checker.
	APILibraryCheckerConfig *APILibraryCheckerConfig

	// TemporalCheckerConfig configures the temporal hallucination checker.
	TemporalCheckerConfig *TemporalCheckerConfig

	// CrossContextCheckerConfig configures the cross-context confusion checker.
	CrossContextCheckerConfig *CrossContextCheckerConfig

	// ConfidenceCheckerConfig configures the confidence fabrication checker.
	ConfidenceCheckerConfig *ConfidenceCheckerConfig

	// PhantomPackageCheckerConfig configures the phantom package checker.
	PhantomPackageCheckerConfig *PhantomPackageCheckerConfig
}

type ConsensusResult struct {
	// ConsistentClaims are claims that appeared in threshold+ samples.
	ConsistentClaims []NormalizedClaim

	// InconsistentClaims are claims that appeared in fewer samples.
	InconsistentClaims []NormalizedClaim

	// TotalSamples is the number of samples analyzed.
	TotalSamples int

	// ConsensusRate is the percentage of claims that are consistent.
	ConsensusRate float64
}

type CrossContextChecker struct {
	// contains filtered or unexported fields
}

type CrossContextCheckerConfig struct {
	// Enabled determines if cross-context confusion checking is active.
	Enabled bool

	// CheckAttributeConfusion enables checking for attributes applied to wrong location.
	// E.g., field from pkg/server/Config attributed to pkg/client/Config.
	CheckAttributeConfusion bool

	// CheckLocationClaims enables checking explicit location claims.
	// E.g., "ProcessData in utils" validated against actual location.
	CheckLocationClaims bool

	// FlagAmbiguousReferences flags references to multi-location symbols without disambiguation.
	// E.g., "Config has..." when Config exists in multiple packages.
	FlagAmbiguousReferences bool

	// AmbiguityThreshold is the minimum number of locations before flagging ambiguity.
	// When a symbol exists in fewer than this many locations, no ambiguity warning.
	// Default 2 - flag when 2+ locations exist.
	AmbiguityThreshold int

	// MaxClaimsToCheck limits how many location claims to check per response.
	// Prevents excessive checking on large responses.
	MaxClaimsToCheck int
}

type DefaultAnchoredSynthesisBuilder struct {
	// contains filtered or unexported fields
}

type DefaultGrounder struct {
	// contains filtered or unexported fields
}

type EvidenceIndex struct {
	// Files that were shown (normalized paths).
	Files map[string]bool

	// FileBasenames maps base filenames for convenience.
	FileBasenames map[string]bool

	// Symbols (function/type names) that appeared in context.
	Symbols map[string]bool

	// SymbolDetails maps symbol names to detailed information.
	// Key: symbol name, Value: list of SymbolInfo for all locations.
	// This provides richer information than Symbols map for validation.
	SymbolDetails map[string][]SymbolInfo

	// Frameworks/libraries mentioned in shown code.
	Frameworks map[string]bool

	// Languages of shown code.
	Languages map[string]bool

	// FileContents maps file paths to their content.
	FileContents map[string]string

	// FileLines maps file paths to their total line count.
	// Populated during evidence building by counting newlines in content.
	// Used by LineNumberChecker to validate cited line numbers.
	FileLines map[string]int

	// Imports maps file paths to their imported package paths.
	// Key: normalized file path, Value: list of import paths.
	// Used by RelationshipChecker to validate import claims.
	Imports map[string][]ImportInfo

	// CallsWithin tracks function calls within shown code.
	// Key: "FunctionName" or "pkg.FunctionName", Value: list of called functions.
	// Only populated for functions defined in evidence.
	// Used by RelationshipChecker to validate call relationship claims.
	CallsWithin map[string][]string

	// RawContent is concatenated content for substring matching.
	RawContent string
}

type EvidenceStrength int

type ExtractedClaim struct {
	// ID is a unique identifier for this claim.
	ID int

	// Statement is the text of the claim.
	Statement string

	// File is the file referenced (if any).
	File string

	// Line is the line number referenced (if any).
	Line int

	// RawText is the original text containing this claim.
	RawText string
}

type FileManifest struct {
	// contains filtered or unexported fields
}

type Grounder interface {
	// Validate checks if a response is grounded in project reality.
	//
	// Inputs:
	//   ctx - Context for cancellation.
	//   response - The LLM response content.
	//   assembledCtx - The context that was given to the LLM.
	//
	// Outputs:
	//   *Result - The validation result.
	//   error - Non-nil only if validation itself fails.
	Validate(ctx context.Context, response string, assembledCtx *agent.AssembledContext) (*Result, error)

	// ShouldReject determines if the result warrants rejection.
	//
	// Inputs:
	//   result - The validation result.
	//
	// Outputs:
	//   bool - True if the response should be rejected.
	ShouldReject(result *Result) bool

	// GenerateFootnote creates a warning footnote for questionable responses.
	//
	// Inputs:
	//   result - The validation result.
	//
	// Outputs:
	//   string - A footnote to append to the response, or empty if not needed.
	GenerateFootnote(result *Result) string
}

type GroundingChecker struct {
	// contains filtered or unexported fields
}

type GroundingCheckerConfig struct {
	// CheckFiles enables file reference validation.
	CheckFiles bool

	// CheckSymbols enables symbol reference validation.
	CheckSymbols bool

	// CheckFrameworks enables framework reference validation.
	CheckFrameworks bool

	// SymbolSeverity is the severity for ungrounded symbols.
	// Defaults to warning since symbol names can be generic.
	SymbolSeverity Severity

	// FileSeverity is the severity for ungrounded file references.
	// Defaults to critical since files should definitely exist.
	FileSeverity Severity

	// FrameworkSeverity is the severity for ungrounded framework mentions.
	// Defaults to critical since this strongly indicates hallucination.
	FrameworkSeverity Severity
}

type ImportInfo struct {
	// Path is the import path (e.g., "github.com/pkg/errors").
	Path string

	// Alias is the local name if aliased, or the package name from path.
	// For `import foo "pkg/bar"`, Alias is "foo".
	// For `import "pkg/bar"`, Alias is "bar".
	Alias string
}

type LanguageChecker struct {
	// contains filtered or unexported fields
}

type LanguageCheckerConfig struct {
	// WeightThreshold is the accumulated weight needed to trigger a violation.
	WeightThreshold float64

	// EnablePython enables Python pattern detection.
	EnablePython bool

	// EnableJavaScript enables JavaScript/TypeScript pattern detection.
	EnableJavaScript bool

	// EnableGo enables Go pattern detection.
	EnableGo bool
}

type LanguageMarker struct {
	// Pattern is the regex to match.
	Pattern *regexp.Regexp

	// Description is a human-readable description.
	Description string

	// Weight is how strongly this indicates the language (0.0-1.0).
	Weight float64
}

type LibraryClaim struct {
	// Type is the kind of library claim.
	Type LibraryClaimType

	// Library is the claimed library name (e.g., "gorm", "gin", "sqlx").
	Library string

	// Method is the claimed method/function (for API calls, e.g., "Open", "Get").
	Method string

	// Position is the character offset in the response.
	Position int

	// Raw is the original matched text.
	Raw string
}

type LibraryClaimType int

type LineCitation struct {
	// Raw is the original matched text.
	Raw string

	// FilePath is the file path (may be basename only).
	FilePath string

	// StartLine is the cited starting line (1-indexed).
	StartLine int

	// EndLine is the cited ending line (same as StartLine for single-line citations).
	EndLine int

	// Position is the character offset in the response where this was found.
	Position int

	// SymbolName is the associated symbol name, if any.
	SymbolName string
}

type LineNumberChecker struct {
	// contains filtered or unexported fields
}

type LineNumberCheckerConfig struct {
	// Enabled determines if line number checking is active.
	Enabled bool

	// LineTolerance is the base tolerance for single line citations.
	// A citation is considered valid if within ±LineTolerance of actual line.
	LineTolerance int

	// RangeTolerance is the base tolerance for range citations.
	// Range start/end are each allowed ±RangeTolerance variance.
	RangeTolerance int

	// StrictMode requires exact line matches when true (tolerance = 0).
	StrictMode bool

	// ScaleTolerance adjusts tolerance based on file size.
	// Large files (>500 lines) get 2x tolerance.
	// Small files (<100 lines) get 0.5x tolerance.
	ScaleTolerance bool

	// MaxCitationsToCheck limits how many citations to check per response.
	// Prevents excessive checking on responses with many citations.
	MaxCitationsToCheck int
}

type LocationClaim struct {
	// Symbol is the symbol name being referenced.
	Symbol string

	// Location is the claimed location (package, file, or partial path).
	Location string

	// Attribute is the claimed attribute (field, parameter, etc.).
	// Empty if no specific attribute is claimed.
	Attribute string

	// Position is the character offset in the response.
	Position int

	// Raw is the matched text.
	Raw string
}

type MultiSampleConfig struct {
	// Enabled determines if multi-sample verification is active.
	Enabled bool

	// NumSamples is the number of samples to generate (default: 3).
	NumSamples int

	// Temperature is the sampling temperature (default: 0.7).
	Temperature float64

	// ConsensusThreshold is the minimum samples for consensus (default: 2).
	ConsensusThreshold int
}

type MultiSampleVerifier struct {
	// contains filtered or unexported fields
}

type NormalizationLevel int

type NormalizedClaim struct {
	// Original is the original claim text.
	Original string

	// Normalized is the normalized form for comparison.
	Normalized string

	// Type is the claim type (file, symbol, framework).
	Type ClaimType

	// Value is the extracted value.
	Value string

	// SampleIndices tracks which samples contained this claim.
	SampleIndices []int
}

type PhantomCheckerConfig struct {
	// Enabled determines if phantom file checking is active.
	Enabled bool

	// Extensions are the file extensions to check (e.g., ".go", ".py").
	// Empty means check all common code extensions.
	Extensions []string

	// MaxRefsToCheck limits how many file references to check per response.
	// Prevents excessive checking on large responses.
	MaxRefsToCheck int
}

type PhantomFileChecker struct {
	// contains filtered or unexported fields
}

type PhantomPackageChecker struct {
	// contains filtered or unexported fields
}

type PhantomPackageCheckerConfig struct {
	// Enabled determines if phantom package checking is active.
	Enabled bool

	// MaxPackagesToCheck limits how many package references to check.
	// Prevents excessive checking on large responses.
	MaxPackagesToCheck int

	// MinPackageLength filters out short paths (e.g., "pkg" alone).
	// Package paths shorter than this are ignored.
	MinPackageLength int

	// CheckGoPackages enables checking Go-style pkg/cmd/internal paths.
	CheckGoPackages bool

	// CheckPythonPackages enables checking Python-style dot.paths.
	CheckPythonPackages bool
}

type PhantomSymbolChecker struct {
	// contains filtered or unexported fields
}

type PhantomSymbolCheckerConfig struct {
	// Enabled determines if phantom symbol checking is active.
	Enabled bool

	// RequireFileAssociation requires symbol to be associated with a specific file.
	// If true, only validates symbols that have file context.
	// If false, validates against all known symbols globally.
	RequireFileAssociation bool

	// MinSymbolLength filters out short symbols that may be false positives.
	// Symbols shorter than this are ignored.
	MinSymbolLength int

	// MaxSymbolsToCheck limits how many symbol references to check per response.
	// Prevents excessive checking on large responses.
	MaxSymbolsToCheck int

	// IgnoredSymbols contains common type names to ignore (e.g., "Context", "Error").
	// These are too common to validate reliably.
	IgnoredSymbols []string
}

type PostSynthesisConfig struct {
	// Enabled determines if post-synthesis verification runs.
	Enabled bool

	// MaxRetries is the maximum number of synthesis retries before feedback loop.
	MaxRetries int

	// RelevantCheckers specifies which checkers to run post-synthesis.
	// Empty means use default relevant checkers.
	RelevantCheckers []string
}

type PostSynthesisResult struct {
	// Passed is true if verification passed without critical violations.
	Passed bool

	// Violations found during post-synthesis checking.
	Violations []Violation

	// RetryCount is how many retries were attempted.
	RetryCount int

	// StrictnessLevel indicates the strictness at which verification ran.
	StrictnessLevel StrictnessLevel

	// NeedsFeedbackLoop is true if retries exhausted and should explore more.
	NeedsFeedbackLoop bool

	// FeedbackQuestions are questions to explore if feedback loop triggered.
	FeedbackQuestions []string

	// CheckDuration is how long verification took.
	CheckDuration time.Duration

	// CheckersRun is the number of checkers that ran.
	CheckersRun int
}

type PostSynthesisVerifier interface {
	// VerifyPostSynthesis checks a synthesized response for hallucinations.
	//
	// Inputs:
	//   ctx - Context for cancellation.
	//   response - The synthesized response text.
	//   assembledCtx - The context that was given to the LLM.
	//   retryCount - Current retry attempt (0 = first attempt).
	//
	// Outputs:
	//   *PostSynthesisResult - The verification result.
	//   error - Non-nil only if verification itself fails.
	VerifyPostSynthesis(ctx context.Context, response string, assembledCtx *agent.AssembledContext, retryCount int) (*PostSynthesisResult, error)

	// GenerateStricterPrompt creates a prompt with increased strictness.
	//
	// Inputs:
	//   basePrompt - The original synthesis prompt.
	//   violations - The violations from the previous attempt.
	//   level - The strictness level to apply.
	//
	// Outputs:
	//   string - The enhanced prompt with strictness guidance.
	GenerateStricterPrompt(basePrompt string, violations []Violation, level StrictnessLevel) string
}

type QuantitativeChecker struct {
	// contains filtered or unexported fields
}

type QuantitativeCheckerConfig struct {
	// Enabled determines if quantitative hallucination checking is active.
	Enabled bool

	// CheckFileCounts enables checking claims about file counts.
	// E.g., "15 test files", "3 Go files".
	CheckFileCounts bool

	// CheckLineCounts enables checking claims about line counts.
	// E.g., "main.go is 200 lines", "function has 50 lines".
	CheckLineCounts bool

	// CheckSymbolCounts enables checking claims about symbol counts.
	// E.g., "5 functions in package", "3 methods on type".
	CheckSymbolCounts bool

	// ExactTolerance is the tolerance for exact claims (not using "about").
	// Default 0 means exact claims must match exactly.
	// Value of 1 allows off-by-one errors.
	ExactTolerance int

	// ApproximateUnderPct is tolerance for undercounting with approximate claims.
	// "About 200" for 140 actual = 30% under, allowed by default.
	// Default 0.3 (30% under is acceptable).
	ApproximateUnderPct float64

	// ApproximateOverPct is tolerance for overcounting with approximate claims.
	// "About 200" for 230 actual = 15% over, triggers violation by default.
	// Default 0.15 (15% over triggers violation).
	// Asymmetric because overcounting is worse than undercounting.
	ApproximateOverPct float64

	// MaxClaimsToCheck limits how many quantitative claims to check per response.
	// Prevents excessive checking on large responses.
	MaxClaimsToCheck int
}

type QuantitativeClaim struct {
	// Type is the kind of quantitative claim.
	Type QuantitativeClaimType

	// Number is the claimed numeric value.
	Number int

	// Subject is what's being counted (e.g., "test files", "lines", "functions").
	Subject string

	// Context provides additional context (e.g., file name for line counts).
	Context string

	// IsApproximate indicates if the claim used "about", "around", etc.
	IsApproximate bool

	// Position is the character offset in the response.
	Position int

	// Raw is the original matched text.
	Raw string
}

type QuantitativeClaimType int

type QuestionType int

type RelationshipChecker struct {
	// contains filtered or unexported fields
}

type RelationshipCheckerConfig struct {
	// Enabled determines if relationship checking is active.
	Enabled bool

	// ValidateImports enables import relationship checking.
	// Validates claims like "X imports Y" against actual imports.
	ValidateImports bool

	// ValidateCalls enables function call relationship checking.
	// Validates claims like "A calls B" against call graph.
	ValidateCalls bool

	// ValidateImplements enables interface implementation checking.
	// Validates claims like "T implements I" against type methods.
	// NOTE: Currently disabled by default - requires type resolution.
	ValidateImplements bool

	// MaxRelationshipsToCheck limits how many relationship claims to check.
	// Prevents excessive checking on responses with many claims.
	MaxRelationshipsToCheck int
}

type RelationshipClaim struct {
	// Subject is the entity making the relationship (caller, importer).
	Subject string

	// Object is the entity being related to (callee, imported package).
	Object string

	// Kind is the type of relationship.
	Kind RelationshipKind

	// Position is the character offset in the response.
	Position int

	// Raw is the original matched text.
	Raw string
}

type RelationshipKind int

type Result struct {
	// Grounded is true if the response is sufficiently grounded.
	Grounded bool `json:"grounded"`

	// Confidence is a score from 0.0 to 1.0 indicating grounding confidence.
	Confidence float64 `json:"confidence"`

	// Violations contains all violations found during checking.
	Violations []Violation `json:"violations,omitempty"`

	// CriticalCount is the number of critical violations.
	CriticalCount int `json:"critical_count"`

	// WarningCount is the number of warnings.
	WarningCount int `json:"warning_count"`

	// ChecksRun is the number of grounding checks that were executed.
	ChecksRun int `json:"checks_run"`

	// CheckDuration is how long the grounding check took.
	CheckDuration time.Duration `json:"check_duration"`

	// CitationsFound is the number of citations found in the response.
	CitationsFound int `json:"citations_found"`

	// CitationsValid is the number of valid citations.
	CitationsValid int `json:"citations_valid"`
}

type SampleResponse struct {
	// Index is the sample number (0-based).
	Index int

	// Content is the response text.
	Content string

	// Claims are the extracted claims from this sample.
	Claims []NormalizedClaim
}

type ScoredEvidence struct {
	// Index is the original position in the ToolResults slice.
	Index int

	// InvocationID links to the original tool invocation.
	InvocationID string

	// Output is the tool result content.
	Output string

	// RecencyScore ranges from 0.0 (oldest) to 0.5 (most recent).
	RecencyScore float64

	// RelevanceScore ranges from 0.0 (not relevant) to 0.5 (highly relevant).
	RelevanceScore float64

	// TotalScore is RecencyScore + RelevanceScore.
	TotalScore float64

	// EstimatedTokens is the approximate token count for this result.
	EstimatedTokens int
}

type SemanticDriftChecker struct {
	// contains filtered or unexported fields
}

type SemanticDriftCheckerConfig struct {
	// Enabled determines if semantic drift checking is active.
	Enabled bool

	// CriticalThreshold is the drift score above which violations are critical.
	// Default 0.7 - response completely off-topic.
	CriticalThreshold float64

	// HighThreshold is the drift score above which violations are high severity.
	// Default 0.5 - significant drift from the question.
	HighThreshold float64

	// WarningThreshold is the drift score above which warnings are generated.
	// Default 0.3 - partial drift detected.
	WarningThreshold float64

	// KeywordWeight is the weight for keyword overlap scoring.
	// Default 0.4 - how much keywords from question appear in response.
	KeywordWeight float64

	// TopicWeight is the weight for topic coherence scoring.
	// Default 0.4 - whether response discusses the right topic.
	TopicWeight float64

	// TypeWeight is the weight for question type matching.
	// Default 0.2 - whether response format matches question type.
	TypeWeight float64

	// MinKeywords is the minimum keywords needed to perform drift check.
	// Questions with fewer keywords are skipped (too ambiguous).
	MinKeywords int

	// MinResponseLength is the minimum response length to check.
	// Very short responses are skipped (can't meaningfully assess).
	MinResponseLength int

	// ListTypeMismatchPenalty is the penalty for non-list response to LIST question.
	// Default 0.7 - significant mismatch as list questions expect enumeration.
	ListTypeMismatchPenalty float64

	// WhereTypeMismatchPenalty is the penalty for non-location response to WHERE question.
	// Default 0.5 - moderate mismatch as WHERE questions expect file/path references.
	WhereTypeMismatchPenalty float64

	// HowTypeMismatchPenalty is the penalty for non-process response to HOW question.
	// Default 0.3 - slight mismatch as HOW questions expect process descriptions.
	HowTypeMismatchPenalty float64
}

type Severity string

type StrictnessLevel int

type StructuralClaimChecker struct {
	// contains filtered or unexported fields
}

type StructuralClaimCheckerConfig struct {
	// Enabled determines if structural claim checking is active.
	Enabled bool

	// RequireToolEvidence requires tool output (ls/find/tree) for structural claims.
	RequireToolEvidence bool

	// MaxPathsToExtract limits the number of paths extracted from tree structures.
	MaxPathsToExtract int
}

type StructuredClaim struct {
	// Statement is the factual claim being made.
	Statement string `json:"statement"`

	// File is the file that supports this claim.
	File string `json:"file"`

	// LineStart is the starting line number.
	LineStart int `json:"line_start"`

	// LineEnd is the ending line number.
	LineEnd int `json:"line_end"`

	// EvidenceQuote is the exact text from the file.
	EvidenceQuote string `json:"evidence_quote"`

	// Confidence is how certain the LLM is (0.0-1.0).
	Confidence float64 `json:"confidence"`
}

type StructuredOutputChecker struct {
	// contains filtered or unexported fields
}

type StructuredOutputConfig struct {
	// Enabled determines if structured output validation is active.
	Enabled bool

	// RequireJSON requires the response to be valid JSON.
	RequireJSON bool

	// RequireEvidenceQuotes requires claims to have evidence quotes.
	RequireEvidenceQuotes bool

	// MinConfidence is the minimum confidence to accept a claim.
	MinConfidence float64

	// ValidateEvidenceExists checks that evidence quotes exist in file content.
	ValidateEvidenceExists bool
}

type StructuredResponse struct {
	// Summary is a brief answer to the user's question.
	Summary string `json:"summary"`

	// Claims are the factual claims made in the response.
	Claims []StructuredClaim `json:"claims"`

	// FilesExamined lists the files the LLM saw in context.
	FilesExamined []string `json:"files_examined"`

	// ToolsUsed lists the tools the LLM used.
	ToolsUsed []string `json:"tools_used"`

	// Uncertainty describes what the LLM is not sure about.
	Uncertainty string `json:"uncertainty,omitempty"`
}

type SymbolInfo struct {
	// Name is the symbol name (function, type, variable, constant name).
	Name string

	// Kind is the symbol kind: "function", "type", "variable", "constant", "method".
	Kind string

	// File is the file path where the symbol is defined.
	File string

	// Line is the line number where the symbol is defined.
	Line int

	// ReturnTypes lists the return types for functions/methods (in order).
	// For "func Parse() (*Result, error)", this is ["*Result", "error"].
	// Empty for non-functions.
	ReturnTypes []string

	// Parameters lists the parameter types for functions/methods (in order).
	// For "func Parse(ctx context.Context, data []byte)", this is ["context.Context", "[]byte"].
	// Empty for non-functions.
	Parameters []string

	// Fields lists the field names for structs.
	// For "type Config struct { Name string; Value int }", this is ["Name", "Value"].
	// Empty for non-structs.
	Fields []string

	// Methods lists the method names for interfaces.
	// For "type Reader interface { Read() }", this is ["Read"].
	// Empty for non-interfaces.
	Methods []string

	// Receiver is the receiver type for methods (e.g., "*Config" for pointer receiver).
	// Empty for functions and non-method types.
	Receiver string
}

type TMSVerificationResult struct {
	// SupportedClaims are claims with evidence support (status IN).
	SupportedClaims []VerifiedClaim

	// UnsupportedClaims are claims without evidence support (status OUT).
	UnsupportedClaims []VerifiedClaim

	// Contradictions are logical contradictions detected by TMS.
	Contradictions []string

	// PropagationIterations is how many TMS iterations were run.
	PropagationIterations int

	// TotalClaims is the total number of claims verified.
	TotalClaims int
}

type TMSVerifier struct {
	// contains filtered or unexported fields
}

type TMSVerifierConfig struct {
	// Enabled determines if TMS verification is enabled.
	Enabled bool

	// MaxIterations limits TMS propagation iterations.
	MaxIterations int
}

type TemporalChecker struct {
	// contains filtered or unexported fields
}

type TemporalCheckerConfig struct {
	// Enabled determines if temporal hallucination checking is active.
	Enabled bool

	// StrictMode flags all temporal claims as warnings instead of info.
	// When false (default), temporal claims use SeverityInfo.
	// When true, temporal claims use SeverityWarning.
	StrictMode bool

	// CheckRecencyClaims enables checking "recently", "just", "new" claims.
	CheckRecencyClaims bool

	// CheckHistoricalClaims enables checking "was", "used to", "originally" claims.
	CheckHistoricalClaims bool

	// CheckVersionClaims enables checking "v1.0", "version 2", "since" claims.
	CheckVersionClaims bool

	// CheckReasonClaims enables checking "because", "due to", "in order to" claims.
	// These claims about WHY code was changed are always unverifiable.
	CheckReasonClaims bool

	// MaxClaimsToCheck limits how many temporal claims to check per response.
	// Prevents excessive checking on responses with many temporal references.
	MaxClaimsToCheck int

	// SkipCodeBlocks if true, ignores temporal words inside code blocks.
	// Default true - avoids flagging "new" in "new(Something)" etc.
	SkipCodeBlocks bool
}

type TemporalClaim struct {
	// Category is the type of temporal claim.
	Category TemporalClaimCategory

	// Position is the character offset in the response.
	Position int

	// Raw is the matched text.
	Raw string
}

type TemporalClaimCategory int

type ToolResult struct {
	// InvocationID links back to the invocation.
	InvocationID string

	// Output is the tool's output text.
	Output string
}

type ValidationStats struct {
	ChecksRun       int
	ViolationsFound int
	CriticalCount   int
	WarningCount    int
	Grounded        bool
	Confidence      float64
	Duration        time.Duration
}

type VerificationRequest struct {
	// Claims are the claims extracted from the response.
	Claims []ExtractedClaim

	// OriginalResponse is the LLM response being verified.
	OriginalResponse string

	// Evidence is the evidence index from context.
	Evidence *EvidenceIndex
}

type VerificationResponse struct {
	// Verifications contains the result for each claim.
	Verifications []ClaimVerification `json:"verifications"`
}

type VerificationResult struct {
	// AllVerified is true if all claims were verified.
	AllVerified bool

	// VerifiedClaims are claims that passed verification.
	VerifiedClaims []VerifiedClaimResult

	// UnverifiedClaims are claims that failed verification.
	UnverifiedClaims []VerifiedClaimResult

	// RawResponse is the raw verification response for debugging.
	RawResponse string
}

type VerifiedClaim struct {
	// Index is the claim's position in the original list.
	Index int

	// Claim is the original claim.
	Claim Claim

	// Supported indicates if the claim is supported by evidence.
	Supported bool

	// Reason explains why the claim is or isn't supported.
	Reason string

	// MissingEvidence lists evidence that would be needed to support this claim.
	MissingEvidence []string
}

type VerifiedClaimResult struct {
	// ClaimID is the ID of the claim.
	ClaimID int

	// Statement is the claim text.
	Statement string

	// Verified is true if verified.
	Verified bool

	// Confidence is the confidence level.
	Confidence string

	// Citation is the supporting citation.
	Citation string

	// Reason explains lack of verification.
	Reason string
}

type Violation struct {
	// Type is the kind of violation.
	Type ViolationType `json:"type"`

	// Severity indicates how serious the violation is.
	Severity Severity `json:"severity"`

	// Code is a machine-readable issue code.
	Code string `json:"code"`

	// Message is a human-readable description.
	Message string `json:"message"`

	// Evidence is what triggered this violation.
	Evidence string `json:"evidence,omitempty"`

	// Expected is what should exist instead.
	Expected string `json:"expected,omitempty"`

	// Location is where in the response this occurred.
	Location string `json:"location,omitempty"`

	// Suggestion provides guidance on how to fix the violation.
	Suggestion string `json:"suggestion,omitempty"`

	// Phase indicates when this violation was detected ("pre_synthesis" or "post_synthesis").
	Phase string `json:"phase,omitempty"`

	// RetryCount indicates which retry attempt detected this violation.
	RetryCount int `json:"retry_count,omitempty"`

	// LocationOffset is the character position in the response (for sorting).
	LocationOffset int `json:"location_offset,omitempty"`
}

type ViolationPriority int

type ViolationType string