claims

type Claim struct {
	// ID is the unique identifier for this claim.
	ID string `json:"id"`

	// Text is the exact claim text from the document.
	Text string `json:"text"`

	// Location identifies where the claim appears.
	Location Location `json:"location"`

	// Category categorizes the type of claim.
	Category ClaimCategory `json:"category"`

	// Validation describes how the claim is validated.
	Validation *Validation `json:"validation,omitempty"`

	// Statistical holds structured numeric detail for statistical claims
	// (Category == ClaimStatistical) — the value and unit behind Text, kept
	// separate so the number itself is queryable rather than only existing
	// inside a formatted string. Nil for non-statistical claims.
	Statistical *StatisticalDetail `json:"statistical,omitempty"`

	// Verdict is the validation result.
	Verdict Verdict `json:"verdict"`

	// Rationale explains the verdict.
	Rationale string `json:"rationale,omitempty"`

	// RelatedClaimIDs are IDs of related claims.
	RelatedClaimIDs []string `json:"relatedClaimIds,omitempty"`
}

type ClaimCategory string

type ClaimsCounts struct {
	Total       int `json:"total"`
	Verified    int `json:"verified"`
	Unverified  int `json:"unverified"`
	NeedsReview int `json:"needsReview"`
	Rejected    int `json:"rejected"`
}

type ClaimsCriteria struct {
	// RequireAllVerified requires all claims to be verified.
	RequireAllVerified bool `json:"requireAllVerified"`

	// AllowSubjectiveWithDisclaimer permits subjective claims if acknowledged.
	AllowSubjectiveWithDisclaimer bool `json:"allowSubjectiveWithDisclaimer"`

	// AllowNeedsReview permits claims that need review (conditional pass).
	AllowNeedsReview bool `json:"allowNeedsReview"`

	// MinReliabilityTier is the minimum acceptable reliability for external sources.
	MinReliabilityTier ReliabilityTier `json:"minReliabilityTier"`

	// RequireReproducible requires internal validations to be reproducible.
	RequireReproducible bool `json:"requireReproducible"`

	// RequiredCategories are claim categories that must have at least one verified claim.
	RequiredCategories []ClaimCategory `json:"requiredCategories,omitempty"`

	// MinCorroboratingSources is the minimum number of independent sources
	// required for a verified claim to be treated as sufficiently
	// corroborated, counting the claim's own source plus each entry in its
	// RelatedClaimIDs. 0 or 1 disables the requirement — a single source is
	// always sufficient. See IsSufficientlyCorroborated.
	MinCorroboratingSources int `json:"minCorroboratingSources,omitempty"`

	// CorroborationCategories restricts MinCorroboratingSources to specific
	// claim categories (e.g. only ClaimStatistical). An empty slice applies
	// the requirement to every category.
	CorroborationCategories []ClaimCategory `json:"corroborationCategories,omitempty"`

	// MaxClaimAge is how old a verified statistical claim's
	// StatisticalDetail.AsOfDate may be, relative to now, before it is
	// treated as stale (presented as current when it no longer is). Zero or
	// negative disables the requirement — no claim is ever too old. A claim
	// with no Statistical detail, or one whose AsOfDate is unset, is never
	// flagged: age is unknown, not stale. See IsFresh.
	MaxClaimAge time.Duration `json:"maxClaimAge,omitempty"`
}

type ClaimsDecision struct {
	// Status is the decision outcome.
	Status ClaimsDecisionStatus `json:"status"`

	// Passed indicates if the claims validation passed.
	Passed bool `json:"passed"`

	// Rationale explains the decision.
	Rationale string `json:"rationale"`

	// Counts summarizes claims by verdict.
	Counts ClaimsCounts `json:"counts"`
}

type ClaimsDecisionStatus string

type ClaimsMetadata struct {
	// Document is the filename or path being validated.
	Document string `json:"document"`

	// DocumentID is the document identifier.
	DocumentID string `json:"documentId,omitempty"`

	// DocumentTitle is the document title.
	DocumentTitle string `json:"documentTitle,omitempty"`

	// DocumentVersion is the document version.
	DocumentVersion string `json:"documentVersion,omitempty"`

	// GeneratedAt is when the report was created.
	GeneratedAt time.Time `json:"generatedAt"`

	// GeneratedBy identifies what created this report.
	GeneratedBy string `json:"generatedBy,omitempty"`

	// ValidatedBy identifies who validated the claims.
	ValidatedBy string `json:"validatedBy,omitempty"`
}

type ClaimsReport struct {
	// Schema is the JSON Schema URL.
	Schema string `json:"$schema,omitempty"`

	// Metadata contains report identification.
	Metadata ClaimsMetadata `json:"metadata"`

	// Claims are the extracted and validated claims.
	Claims []Claim `json:"claims"`

	// Summary provides aggregated statistics.
	Summary ClaimsSummary `json:"summary"`

	// Criteria defines the pass requirements.
	Criteria ClaimsCriteria `json:"criteria"`

	// Decision is the validation outcome.
	Decision ClaimsDecision `json:"decision"`
}

type ClaimsSummary struct {
	// Counts by verdict.
	Counts ClaimsCounts `json:"counts"`

	// ByCategory counts claims by category.
	ByCategory map[ClaimCategory]int `json:"byCategory,omitempty"`

	// BySourceType counts claims by validation source type.
	BySourceType map[SourceType]int `json:"bySourceType,omitempty"`

	// ByReliability counts external claims by reliability tier.
	ByReliability map[ReliabilityTier]int `json:"byReliability,omitempty"`

	// UnverifiedClaims lists IDs of unverified claims.
	UnverifiedClaims []string `json:"unverifiedClaims,omitempty"`

	// NeedsReviewClaims lists IDs of claims needing review.
	NeedsReviewClaims []string `json:"needsReviewClaims,omitempty"`

	// RejectedClaims lists IDs of rejected claims.
	RejectedClaims []string `json:"rejectedClaims,omitempty"`
}

type DerivedValidation struct {
	// SourceClaimIDs are the IDs of claims this is derived from.
	SourceClaimIDs []string `json:"sourceClaimIds"`

	// DerivationMethod describes how the claim was derived.
	DerivationMethod string `json:"derivationMethod"`

	// Formula is the calculation formula if applicable.
	Formula string `json:"formula,omitempty"`

	// Reasoning explains the derivation logic.
	Reasoning string `json:"reasoning,omitempty"`
}

type ExternalSourceType string

type ExternalValidation struct {
	// URL is the source URL.
	URL string `json:"url"`

	// SourceType categorizes the source.
	SourceType ExternalSourceType `json:"sourceType"`

	// Role distinguishes how directly this source speaks for the claim
	// (primary / secondary-relay / secondary-analysis / self-reported),
	// independent of SourceType's general authority category. Optional and
	// empty by default so existing claims are unaffected: an empty Role is
	// not flagged by RequiresCorroboration — only an explicitly-set
	// secondary-analysis or self-reported role is.
	Role SourceRole `json:"sourceRole,omitempty"`

	// Reliability indicates the trustworthiness of the source.
	Reliability ReliabilityTier `json:"reliability"`

	// AccessedAt is when the URL was accessed. Nil when unknown — a pointer
	// so omitempty actually omits it, rather than serializing the
	// time.Time zero value ("0001-01-01T00:00:00Z").
	AccessedAt *time.Time `json:"accessedAt,omitempty"`

	// Archived indicates if the URL is archived (e.g., Wayback Machine).
	Archived bool `json:"archived,omitempty"`

	// ArchiveURL is the archive URL if different from primary URL.
	ArchiveURL string `json:"archiveUrl,omitempty"`

	// QuotedText is the exact text from the source supporting the claim.
	QuotedText string `json:"quotedText,omitempty"`

	// VerifiedMatch indicates the claim text matches the source.
	VerifiedMatch bool `json:"verifiedMatch,omitempty"`
}

type InternalValidation struct {
	// Method describes how validation was performed.
	Method InternalValidationMethod `json:"method"`

	// EvidencePath is the path to code, logs, or artifacts.
	EvidencePath string `json:"evidencePath,omitempty"`

	// EvidenceHash is a hash of the evidence file for integrity.
	EvidenceHash string `json:"evidenceHash,omitempty"`

	// Reproducible indicates whether the validation can be reproduced.
	Reproducible bool `json:"reproducible"`

	// ReproductionSteps describes how to reproduce the validation.
	ReproductionSteps string `json:"reproductionSteps,omitempty"`

	// ValidatedBy identifies who performed the validation.
	ValidatedBy string `json:"validatedBy,omitempty"`

	// ValidatedAt is when validation was performed. Nil when unknown — a
	// pointer so omitempty actually omits it, rather than serializing the
	// time.Time zero value ("0001-01-01T00:00:00Z").
	ValidatedAt *time.Time `json:"validatedAt,omitempty"`

	// Environment describes the validation environment.
	Environment *ValidationEnvironment `json:"environment,omitempty"`

	// Output is the observed output that validates the claim.
	Output string `json:"output,omitempty"`
}

type InternalValidationMethod string

type LintFinding struct {
	ClaimID  string       `json:"claimId,omitempty"`
	Rule     string       `json:"rule"`
	Severity LintSeverity `json:"severity"`
	Message  string       `json:"message"`
}

type LintSeverity string

type Location struct {
	// Section is the section heading or identifier.
	Section string `json:"section,omitempty"`

	// Line is the line number (1-indexed).
	Line int `json:"line,omitempty"`

	// StartOffset is the character offset from start of document.
	StartOffset int `json:"startOffset,omitempty"`

	// EndOffset is the ending character offset.
	EndOffset int `json:"endOffset,omitempty"`
}

type Precision string

type ReliabilityTier string

type SourceRole string

type SourceType string

type StatisticalDetail struct {
	// Value is the numeric value of the claim.
	Value float64 `json:"value"`

	// Unit is the unit of measurement (e.g. "%", "USD", "users"). Empty for
	// dimensionless counts.
	Unit string `json:"unit,omitempty"`

	// Precision indicates how exact the value is.
	Precision Precision `json:"precision,omitempty"`

	// AsOfDate is when the underlying fact was true, if known and different
	// from when the source was accessed.
	AsOfDate *time.Time `json:"asOfDate,omitempty"`
}

type SubjectiveRecommendation string

type SubjectiveValidation struct {
	// Acknowledged indicates if this is labeled as an estimate in the document.
	Acknowledged bool `json:"acknowledged"`

	// Methodology describes any methodology used for the estimate.
	Methodology string `json:"methodology,omitempty"`

	// Recommendation suggests what to do with this claim.
	Recommendation SubjectiveRecommendation `json:"recommendation"`

	// Rationale explains why this is acceptable or not.
	Rationale string `json:"rationale,omitempty"`
}

type Validation struct {
	// Type indicates the validation approach.
	Type SourceType `json:"type"`

	// External contains details for externally-sourced claims.
	External *ExternalValidation `json:"external,omitempty"`

	// Internal contains details for internally-validated claims.
	Internal *InternalValidation `json:"internal,omitempty"`

	// Derived contains details for claims derived from other claims.
	Derived *DerivedValidation `json:"derived,omitempty"`

	// Subjective contains details for subjective estimates.
	Subjective *SubjectiveValidation `json:"subjective,omitempty"`
}

type ValidationEnvironment struct {
	// Product is the product being tested.
	Product string `json:"product,omitempty"`

	// Version is the version tested.
	Version string `json:"version,omitempty"`

	// Configuration describes the configuration used.
	Configuration string `json:"configuration,omitempty"`

	// Platform is the platform (os, arch).
	Platform string `json:"platform,omitempty"`
}

type Verdict string