state

type AIReview struct {
	Summary  string `json:"summary"`            // rendered final review text (legacy: free-form markdown)
	Findings string `json:"findings,omitempty"` // per-batch raw findings (PR-level only)

	// Structured review output — populated by Phase 5+ review flows.
	// When present, the TUI renders this instead of the legacy Summary field.
	Structured *ReviewOutput `json:"structured,omitempty"`

	// DiffSnapshot records the DiffHash of each file at the time the review
	// was generated. Used to detect staleness when diffs change after a review.
	DiffSnapshot map[string]string `json:"diff_snapshot,omitempty"`

	// SecurityDigest is the AOI pre-scan summary injected into review prompts.
	// Persisted so the TUI can display it even after the review is cached.
	SecurityDigest string `json:"security_digest,omitempty"`

	// DeepFindings from AOI-driven review calls (structured findings with severity, category, etc.)
	DeepFindings []DeepFinding `json:"deep_findings,omitempty"`
}

type Boundary struct {
	// Kind matches RuntimeEntryPoint.Kind. One of: "http", "queue",
	// "scheduled", "cli", "rpc", "webhook", "other".
	Kind string `json:"kind"`

	// File is the path holding the boundary declaration (e.g. the
	// route file, queue subscription, scheduled job).
	File string `json:"file"`

	// Lines is the optional line range hint within File. Best-effort
	// from the LLM's read of the file header.
	Lines string `json:"lines,omitempty"`

	// Symbol is the boundary's identifier (route name, handler
	// function, subscription topic) when one is identifiable. Used
	// to anchor the synthesized AOIs to specific code.
	Symbol string `json:"symbol,omitempty"`

	// Description is a one-line free-form explanation: "POST
	// /admin/users — admin creation handler", "SNS subscription to
	// payment-events topic", "scheduled daily reconciliation".
	Description string `json:"description"`
}

type Category string

type CorruptStateError struct {
	Path  string
	Cause error
}

type DeepDismissal struct {
	AOIID               string `json:"aoi_id"`
	File                string `json:"file,omitempty"`
	Evidence            string `json:"evidence,omitempty"`
	Rationale           string `json:"rationale"`
	ConfidenceScore     int    `json:"confidence_score,omitempty"`
	ConfidenceReasoning string `json:"confidence_reasoning,omitempty"`
}

type DeepFinding struct {
	FindingID   string   `json:"finding_id,omitempty"` // assigned before recheck (e.g. "F-001")
	AOIID       string   `json:"aoi_id"`
	File        string   `json:"file"`
	Lines       string   `json:"lines"`
	Severity    string   `json:"severity"` // "critical", "high", "medium", "low", "nit"
	Category    Category `json:"category"`
	Subcategory string   `json:"subcategory,omitempty"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Evidence    string   `json:"evidence,omitempty"` // what was verified and found (tool-backed)
	// EvidenceSnippet is 1-3 verbatim lines from File at Lines that
	// prove the finding. Phase 3's prompt requires it, and the
	// in-loop verifier matches this against the file before the
	// finding is accepted — anchoring every claim to text that
	// actually exists at the cited location. Findings whose snippet
	// doesn't match get one refinement round trip and, if still
	// unmatched, are dropped.
	EvidenceSnippet string         `json:"evidence_snippet,omitempty"`
	Trigger         FindingTrigger `json:"trigger"`
	Suggestion      string         `json:"suggestion,omitempty"`

	// ConfidenceScore (0-100) is the model's certainty that the
	// finding is real, independent of severity. Downstream validators
	// (commits 4 + 5 in the audit-quality plan) subtract from this
	// score when required evidence is missing without touching
	// severity. 0 means unknown (legacy data).
	ConfidenceScore int `json:"confidence_score,omitempty"`

	// ConfidenceReasoning is a short justification. Validators append
	// concrete tags (e.g., "missing-trace", "defenses-not-checked")
	// so the reviewer can see why the score moved.
	ConfidenceReasoning string `json:"confidence_reasoning,omitempty"`

	// Trace is the end-to-end path the reviewer walked from the
	// suspect line to the next system boundary. The Phase 3 prompt
	// asks for at least three hops for findings at severity
	// critical/high so a snippet-in-isolation flag can't survive at
	// severe severity without the reviewer showing their work.
	// Findings at lower severity (medium/low/nit) don't require a
	// trace.
	Trace []TraceHop `json:"trace,omitempty"`

	// DefensesChecked lists the canonical defense layers the
	// reviewer inspected before flagging this finding. Each entry
	// is a short tag from a fixed vocabulary the Phase 3 prompts
	// enumerate (boundary-authz, handler-guard, conditional-write,
	// idempotency-key, schema-validation, framework-escape,
	// result-discipline, native-limit) or a free-form
	// `other:<tag>` for cases outside the list.
	//
	// For findings whose category is in the "required" set
	// (authorization, concurrency, input-validation, external-io),
	// an empty list triggers a confidence penalty in
	// ApplyConfidencePenalties — the reviewer didn't show which
	// defenses they ruled out, so we can't trust the finding as
	// fully as one that does. Other categories leave this
	// optional.
	DefensesChecked []string `json:"defenses_checked,omitempty"`

	// SiblingDeviation is carried over from the AOI when the
	// finding came from a Phase 2.5 outlier — the AOI scanner
	// noticed N siblings all follow a pattern and this one doesn't.
	// Set when the AOI's SiblingDeviation was non-nil and the
	// reviewer confirmed the deviation as a real finding (rather
	// than dismissing it as intentional). Carried so the audit
	// report can render "9 of 11 admin POSTs call guardAdmin —
	// this one doesn't" under the finding.
	SiblingDeviation *SiblingDeviation `json:"sibling_deviation,omitempty"`

	// AffectedSites lists the specific call sites a Systemic /
	// consolidated finding covers. Required (3+ distinct files) for
	// any finding whose Title starts with "Systemic:" — see
	// ApplySystemicGate. Optional and typically empty for per-file
	// findings; the consolidator populates this when merging
	// findings across files so the audit report can render each
	// site explicitly rather than burying them in description text.
	AffectedSites []SiteRef `json:"affected_sites,omitempty"`

	// Systemic is set by the recheck parser when a finding came out
	// of the `consolidated` bucket — i.e. it represents a cross-file
	// pattern merged from multiple per-file findings, not an
	// individual issue. The two-pass recheck pipeline uses this to
	// route systemic findings around the per-file dismiss pass
	// (their context is the multi-file aggregation, not any single
	// file). Was previously inferred via an `isSystemic` heuristic
	// (File=="multiple" / Title prefix); the flag is authoritative
	// because the producer sets it explicitly.
	Systemic bool `json:"systemic,omitempty"`
}

type DeepReviewResult struct {
	// Type is "individual" or "grouped".
	Type string `json:"type"`

	// CacheKey is the hash used to look up this result.
	CacheKey string `json:"cache_key"`

	// Category and Subcategory identify the concern area.
	Category    Category `json:"category"`
	Subcategory string   `json:"subcategory,omitempty"`

	// RawOutput is the LLM's JSON response (unparsed for flexibility).
	RawOutput json.RawMessage `json:"raw_output"`

	// Findings extracted from the LLM output.
	Findings []DeepFinding `json:"findings,omitempty"`

	// Dismissals extracted from the LLM output.
	Dismissals []DeepDismissal `json:"dismissals,omitempty"`

	// CrossCutting observation (grouped reviews only).
	CrossCutting string `json:"cross_cutting,omitempty"`
}

type DismissedRecord struct {
	FindingID string      `json:"finding_id"`
	Finding   DeepFinding `json:"finding"`
	Rationale string      `json:"rationale"`
}

type FileCoverage struct {
	File               string `json:"file"`
	AOIsScanned        int    `json:"aois_scanned"`
	Findings           int    `json:"findings"`
	Dismissals         int    `json:"dismissals"`
	Failed             int    `json:"failed,omitempty"`
	AvgDismissConf     int    `json:"avg_dismiss_confidence,omitempty"`
	MaxFindingSeverity string `json:"max_finding_severity,omitempty"`
}

type FileState struct {
	Status        ReviewStatus    `json:"status"`
	DiffHash      string          `json:"diff_hash"`
	Chat          []Message       `json:"chat,omitempty"`
	Purpose       string          `json:"purpose,omitempty"`        // AI-generated description of what the file does
	BatchFindings string          `json:"batch_findings,omitempty"` // cached findings from PR-level batch review
	AOIResults    json.RawMessage `json:"aoi_results,omitempty"`    // cached AOI scan result (AOIScanResult JSON)
	// AOIPromptHash is sha256 of the AOI scanner prompt at the time
	// AOIResults was written. The audit pipeline includes this in the
	// cache-hit check so prompt changes (e.g. commit 7's TODO/FIXME
	// + unit-type rules) auto-invalidate stale entries rather than
	// silently serving results produced by the previous prompt.
	AOIPromptHash   string `json:"aoi_prompt_hash,omitempty"`
	AOIContextLines int    `json:"aoi_context_lines,omitempty"` // context lines used when AOI was generated
	FileType        string `json:"file_type,omitempty"`         // cached file classification (e.g. "handler", "test")
}

type FindingRevalidation struct {
	Verdict    string `json:"verdict"` // "true-positive", "false-positive", "fixed", "uncertain"
	Reasoning  string `json:"reasoning"`
	Confidence string `json:"confidence"` // "high", "medium", "low"
}

type FindingTrigger struct {
	Repro      string `json:"repro,omitempty"`
	Observable string `json:"observable,omitempty"`
}

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type ReviewCoverage struct {
	Files         []FileCoverage `json:"files"`
	FilesInScope  int            `json:"files_in_scope"`
	FilesWithAOIs int            `json:"files_with_aois"`
	FilesReviewed int            `json:"files_reviewed"`
	// OrphanFiles are in-scope files that produced zero AOIs. The
	// most actionable signal in the coverage view: differentiates
	// "AOI scanner skipped this" from "AOIs all came back clean".
	OrphanFiles []string `json:"orphan_files,omitempty"`
	// SkippedFiles are in-scope files that the pipeline did not send
	// to any review call. Populated when the user opts into
	// --review-mode=aoi-only and one or more files had no AOIs.
	// Different from OrphanFiles (which means "AOIs not generated
	// for this file"): SkippedFiles is the user-chosen consequence
	// of the review-mode flag, not a quirk of the scanner.
	SkippedFiles []string `json:"skipped_files,omitempty"`
}

type ReviewFinding struct {
	Severity string `json:"severity"` // "critical", "high", "medium", "low", "nit"

	// Confidence is the legacy string band ("high"|"medium"|"low") kept
	// for backward compatibility with cached state and older prompts.
	// New code should read ConfidenceScore; render via ConfidenceBand().
	Confidence string `json:"confidence,omitempty"`

	// ConfidenceScore is the 0-100 certainty that the finding is real,
	// independent of its severity. Severity = "how bad if real";
	// ConfidenceScore = "how sure I am it's real". 0 means unknown
	// (e.g., a finding loaded from legacy state that only had the
	// string band).
	ConfidenceScore int `json:"confidence_score,omitempty"`

	// ConfidenceReasoning is a short one-line justification for the
	// score. Concrete signals like "missing-trace" or
	// "defenses-not-checked" are appended by downstream validators
	// (see commits 4 + 5 in the audit-quality plan).
	ConfidenceReasoning string `json:"confidence_reasoning,omitempty"`

	Category   Category `json:"category"`
	File       string   `json:"file"`
	Line       int      `json:"line"`
	Title      string   `json:"title"`
	Detail     string   `json:"detail"`
	Suggestion string   `json:"suggestion,omitempty"`
	CWE        string   `json:"cwe,omitempty"`      // e.g. "CWE-89" — populated for security findings
	Resolved   bool     `json:"resolved,omitempty"` // user-toggled or auto-resolved by task completion

	// SourceIDs lists the deep-finding IDs (e.g. "F-001", "F-007") this
	// synthesis finding derives from. One synthesis finding can cite
	// multiple deep findings when synthesis consolidates a systemic
	// pattern across files. Consumers should dereference these against
	// the top-level `deep_findings` list for evidence / trigger / per-
	// site file:line ranges — synthesis findings keep only a single
	// representative file/line and a short narrative.
	//
	// Empty/omitted when synthesis ran without deep findings as input
	// (single-pass review path).
	SourceIDs []string `json:"source_ids,omitempty"`

	// Revalidation — populated by the security revalidation pass (Phase 4).
	Revalidation *FindingRevalidation `json:"revalidation,omitempty"`
}

type ReviewMeta struct {
	// CompletedAt is the wall-clock time the run finished.
	CompletedAt time.Time `json:"completed_at"`

	// Verdict is the structured-review verdict (or a synthesised
	// "approve"/"comment" when synthesis was skipped).
	// Empty for failure runs (use Error to disambiguate).
	Verdict string `json:"verdict,omitempty"`

	// Summary is a one-line description for the Review tab when no
	// per-finding renderer is available (e.g. clean PR).
	Summary string `json:"summary,omitempty"`

	// FindingsCount is the number of findings that survived recheck
	// (i.e. the length of DeepFindings or Review.Structured.Findings
	// at end of run). Zero is a valid value — clean PR.
	FindingsCount int `json:"findings_count"`

	// DismissedCount is the number of findings recheck removed. Useful
	// when the user wants to confirm "the model did look at things and
	// decide they were fine."
	DismissedCount int `json:"dismissed_count"`

	// Error captures a failure message when the run aborted partway
	// through (e.g. ">20% of AOI calls failed", upstream HTTP error,
	// JSON parse error). Empty on successful runs. Persisted so the
	// user can see what failed on reopen rather than losing the
	// context after the TUI exits.
	Error string `json:"error,omitempty"`

	// MinSeverity records the --min-severity threshold the run was
	// filtered at (one of "critical", "high", "medium", "low", "nit").
	// Empty when no filter was applied. The TUI uses this to render a
	// "partial run" badge so the user knows findings below the
	// threshold were dropped before recheck and can re-run without
	// the filter to see the full set.
	MinSeverity string `json:"min_severity,omitempty"`
}

type ReviewOutput struct {
	Summary            string          `json:"summary"`
	Verdict            string          `json:"verdict"` // "approve", "request_changes", "comment"
	Findings           []ReviewFinding `json:"findings"`
	MissingTests       []string        `json:"missing_tests"`
	QuestionsForAuthor []string        `json:"questions_for_author"`

	// Coverage is the per-file breakdown of what was reviewed and
	// what wasn't — stamped deterministically by the pipeline after
	// synthesis runs, not authored by the LLM. Nil when the pipeline
	// chose not to compute it (e.g. no AOI report available).
	Coverage *ReviewCoverage `json:"coverage,omitempty"`
}

type ReviewSnapshot struct {
	PRNumber      int           `json:"pr_number,omitempty"`
	PRTitle       string        `json:"pr_title,omitempty"`
	FilesReviewed int           `json:"files_reviewed,omitempty"`
	Review        *ReviewOutput `json:"review,omitempty"`
	DeepFindings  []DeepFinding `json:"deep_findings,omitempty"`
}

type ReviewStatus string

type RuntimeEntryPoint struct {
	// Kind classifies the surface: "http", "queue", "scheduled",
	// "cli", "rpc", "webhook", "other".
	Kind string `json:"kind"`

	// File is an optional path to a representative example of this
	// entry-point kind (e.g. "internal/api/handlers/routes.go").
	// Populated when one identifiable file exemplifies the kind;
	// omitted when the surface is spread across many files with no
	// single anchor. Used by Phase 3 prompts as a concrete reference
	// when classifying boundaries.
	File string `json:"file,omitempty"`

	// Symbol is an optional function/route/handler name within File
	// (e.g. "registerAdminRoutes"). Pairs with File. Omitted when
	// File is empty or when no specific symbol stands out.
	Symbol string `json:"symbol,omitempty"`

	// RetryModel describes who retries on failure and what triggers
	// retry (e.g., "API Gateway does not retry — caller's job",
	// "SNS retries with exponential backoff per record").
	RetryModel string `json:"retry_model,omitempty"`

	// BatchModel describes batching: single-record vs. batched, and
	// whether one bad record fails the batch.
	BatchModel string `json:"batch_model,omitempty"`

	// ValidationAt is one of "boundary", "handler", "both", "none".
	// Where in the call chain inputs get validated.
	ValidationAt string `json:"validation_at,omitempty"`
}

type RuntimeModel struct {
	// AuthModel describes who guards what — gateway authorizers,
	// middleware, in-handler checks. 1-2 sentences.
	AuthModel string `json:"auth_model,omitempty"`

	// ValidationSites lists where user/network input gets validated
	// before reaching business logic. Short strings, one per layer
	// or location.
	ValidationSites []string `json:"validation_sites,omitempty"`

	// EntryPoints enumerates the externally-reachable surfaces. Each
	// entry classifies its kind, retry model, batching model, and
	// where validation happens. Empty list means "no entry points
	// identified" (could be a library/CLI-only repo).
	EntryPoints []RuntimeEntryPoint `json:"entry_points,omitempty"`

	// ResultDiscipline describes how errors propagate — Result types,
	// exception handling, error wrapping, sentinel values. One line.
	ResultDiscipline string `json:"result_discipline,omitempty"`

	// Invariants lists the load-bearing assumptions the codebase
	// relies on but doesn't necessarily enforce in every call site
	// (e.g., "all IDs are UUID v4", "amounts are stored in minor
	// units", "the inbox table is append-only"). Short statements.
	Invariants []string `json:"invariants,omitempty"`
}

type SiblingDeviation struct {
	Pattern    string   `json:"pattern"`
	SiblingIDs []string `json:"sibling_ids,omitempty"`
}

type SiteRef struct {
	File   string `json:"file"`
	Lines  string `json:"lines,omitempty"`
	Symbol string `json:"symbol,omitempty"` // calling function/handler when identifiable
}

type State struct {
	PRNumber           string                `json:"pr_number"`
	GlobalChat         []Message             `json:"global_chat,omitempty"`
	Review             *AIReview             `json:"review,omitempty"` // PR-level AI review
	Files              map[string]*FileState `json:"files"`
	ProjectContext     string                `json:"project_context,omitempty"`      // cached project briefing
	ProjectContextHash string                `json:"project_context_hash,omitempty"` // hash of inputs used to generate it
	PRBrief            string                `json:"pr_brief,omitempty"`             // cached PR-specific briefing (comments, prior reviews, CI)
	PRBriefHash        string                `json:"pr_brief_hash,omitempty"`        // hash of inputs used to generate the PR brief

	// RuntimeModel is the structured codebase shape produced by Phase
	// 0.5 — auth model, validation sites, entry points, result
	// discipline, invariants. Injected into every Phase 3 prompt so
	// the reviewer can ground findings in "what this codebase looks
	// like at runtime". RuntimeModelHash carries the hash of inputs
	// used to produce it.
	RuntimeModel     *RuntimeModel `json:"runtime_model,omitempty"`
	RuntimeModelHash string        `json:"runtime_model_hash,omitempty"`

	// BoundaryInventory is the Phase 1.5 list of externally-reachable
	// surfaces (HTTP routes, queue consumers, schedulers, storage
	// triggers, CAS-shaped DB writes). Each entry seeds 1-3 defense-
	// coverage AOIs synthesized before Phase 3 so every boundary is
	// guaranteed to be reviewed for the standard defense questions
	// (schema validation, error handling, authorization, per-record
	// isolation, result discipline).
	BoundaryInventory     []Boundary `json:"boundary_inventory,omitempty"`
	BoundaryInventoryHash string     `json:"boundary_inventory_hash,omitempty"`

	// SiblingClusterOutliers caches the outlier AOIs synthesized by
	// Phase 2.5 sibling clustering. Stored as opaque JSON because the
	// outliers are typed []security.AreaOfInterest and state must not
	// import security (security already imports state for
	// SiblingDeviation). On cache hit the audit package unmarshals
	// into its own typed slice. Hash covers the candidate AOI set
	// + the cluster prompt; either rolls the cache.
	SiblingClusterOutliers json.RawMessage `json:"sibling_cluster_outliers,omitempty"`
	SiblingClusterHash     string          `json:"sibling_cluster_hash,omitempty"`

	// DeepReviews caches Phase 3 deep review results. Keyed by a hash of the
	// review inputs (file content + AOI content + focus categories for individual;
	// all AOI content + focus categories for grouped).
	DeepReviews map[string]*DeepReviewResult `json:"deep_reviews,omitempty"`

	// RecheckCache caches Phase 3b recheck output by hash of the input
	// findings + project context + mode. The value is a serialized
	// []DeepFinding (the cleaned, deduplicated set).
	RecheckCache map[string]json.RawMessage `json:"recheck_cache,omitempty"`

	// SynthesisCache caches Phase 4 synthesis output by hash of the input
	// findings + cross-cutting + project context. The value is a serialized
	// SynthesisResult (audit-package type, opaque to this package).
	SynthesisCache map[string]json.RawMessage `json:"synthesis_cache,omitempty"`

	// DeepFindings is the top-level persisted list of Phase 1 + Phase 1c
	// findings, independent of the synthesized Review object. Populated
	// incrementally as each batch completes so a crash, cancellation, or
	// failed-synthesis still leaves the user with their findings on
	// reopen. The Review tab reads this when state.Review is nil — which
	// is the default in TUI mode where synthesis is skipped.
	DeepFindings []DeepFinding `json:"deep_findings,omitempty"`

	// RecheckDismissals records every finding the Phase 3b recheck pass
	// removed, along with the LLM's rationale. Persisted so the audit
	// report can show users WHY a finding disappeared, and so prompt
	// tuning can be measured (compare dismissal counts and rationales
	// across runs). Replaces the previous "DismissedCount only" output,
	// which routed rationales to log.Printf and lost them.
	RecheckDismissals []DismissedRecord `json:"recheck_dismissals,omitempty"`

	// LastReview records that a review run completed against this PR,
	// regardless of whether it produced any findings. Without this,
	// "review ran and found nothing" is indistinguishable from "no
	// review has ever been attempted" — both leave Review/DeepFindings
	// empty and force the TUI to fall back to "no review yet" prompts.
	//
	// Set by the pipeline at the end of a successful run (or partial
	// run that produced any artifacts). Cleared by ClearForFreshReview
	// when the user forces a re-review.
	LastReview *ReviewMeta `json:"last_review,omitempty"`
	// contains filtered or unexported fields
}

type TraceHop struct {
	Role     string `json:"role"`               // "suspect" | "caller" | "boundary" | free-form
	File     string `json:"file,omitempty"`     // path of the hop's file
	Lines    string `json:"lines,omitempty"`    // line range within the file
	Evidence string `json:"evidence,omitempty"` // 1-line summary of what was confirmed at this hop
}