finding

type Comment struct {
	ID           shared.ID
	EngagementID shared.ID
	FindingID    shared.ID
	Author       string
	Body         string
	CreatedAt    time.Time
}

type DASTInput struct {
	JudgmentID  string          // confirmed judgment ID; legacy CapSAST runtime projections use this as the dedup anchor
	CWE         string          // the weakness, e.g. "CWE-89"
	Location    string          // where: URL path or deterministic check location
	Rule        string          // the check or taint rule that fired
	Source      string          // stable check source token for native CapDAST findings
	Fingerprint string          // stable check fingerprint for native CapDAST findings
	Severity    shared.Severity // optional; defaults to Unknown (re-triaged via the normal finding workflow)
}

type DataFlowTrace struct {
	Language         string           `json:"language"`
	Source           SourceLocation   `json:"source"`
	Sink             SourceLocation   `json:"sink"`
	Steps            []SourceLocation `json:"steps"`
	CoverageComplete bool             `json:"coverage_complete"`
	GraphTruncated   bool             `json:"graph_truncated"`
}

type ExploitationInput struct {
	Title       string
	Description string
	Severity    shared.Severity
	CVSSVector  string
	CWE         string
	AssetID     shared.ID
}

type Finding struct {
	ID           shared.ID
	EngagementID shared.ID
	Title        string
	Description  string
	Severity     shared.Severity
	CVSSVector   string
	CWE          string
	Status       Status

	// Kind discriminates how the finding was produced (sca|recon|exploitation|
	// manual); it drives promotion gating. Empty is treated as KindSCA for
	// backward compatibility with legacy rows.
	Kind Kind

	// RuleKey is the stable catalog rule identifier emitted by the producer.
	RuleKey string

	// SourceLocation is the structured source position emitted by first-party
	// analyzers. Legacy DedupKey locations remain supported during migration.
	SourceLocation *SourceLocation

	// DataFlow is a bounded source-to-sink position trace for confirmed semantic taint findings.
	DataFlow *DataFlowTrace

	// Workflow: the human assignee, and an optimistic-concurrency version that
	// Kanban/status/assignee edits check to prevent lost updates.
	Assignee string
	Version  int

	// Risk priority (CISA KEV -> EPSS x CVSS), copied from the source vuln so
	// findings can be ordered by real risk. KEV findings rank above all.
	KEV bool
	// PublicExploit is true when a public exploit is known to exist for this finding's vulnerability
	// (an exploitation-risk signal from the advisory corpus, D1.3). Surfaced for triage; it does not itself
	// change ranking (KEV, actual exploitation, stays the top signal). Omitted from JSON when false.
	PublicExploit bool `json:",omitempty"`
	// EPSSPercentile is the EPSS score's rank among all scored CVEs (0..1), copied from the source vuln as
	// a triage aid alongside RiskScore. Omitted from JSON when unset (0) so a scan path with no EPSS
	// enrichment (e.g. an offline CLI scan without the corpus percentile) does not emit a misleading 0.
	EPSSPercentile float64 `json:",omitempty"`
	// RiskScore is the computed risk priority; omitted from JSON when unset (0) so a scan path that does
	// not populate it — e.g. the CLI, which has no KEV/EPSS enrichment — does not emit a misleading 0.00.
	RiskScore float64 `json:",omitempty"`

	// Detection provenance: the sources that detected the underlying
	// vulnerability and the multi-source confidence. Empty for non-SCA findings.
	Sources    []string
	Confidence string

	// Continuous vulnerability-intelligence provenance. Empty for legacy and
	// non-SCA findings; these fields are machine-owned projection metadata.
	AdvisoryID           string
	OccurrenceID         shared.ID
	ComponentFingerprint string
	FixedVersion         string
	// DirectBumps is the minimal set of DIRECT (top-level) dependencies to upgrade to remove this
	// transitive vulnerability from the resolved graph (EPIC #860 D3.8, the "upgrade path"). It is sorted
	// and deduplicated. A directly-declared vulnerable dependency lists itself. It is empty for a
	// first-party/non-SCA finding, when no dependency graph was resolved, or when the component is reachable
	// only through a dependency cycle (no clean set of direct introducers). Omitted from JSON when empty.
	DirectBumps []string `json:",omitempty"`
	// DetectionState is the continuous-intelligence projection's lifecycle state; empty on a one-shot
	// scan (e.g. the CLI) that has no stored occurrence history. Omitted from JSON when empty so a
	// consumer does not build logic on a field that is a constant blank on those paths.
	DetectionState   string `json:",omitempty"`
	RiskAssessmentID shared.ID
	EvaluatedAt      *time.Time

	// Class separates actionable third-party findings from historical
	// advisories matched against the project's own unversioned modules.
	Class string

	// Finding-quality signals: the component scope, metadata-only
	// reachability, action impact, and unified Synapse risk priority (1..5).
	Scope        string
	Reachability string
	Impact       string
	Priority     int

	// ClassReachability is the coarse JVM class-reachability verdict for the component:
	// "reachable" | "unreferenced" | "" (unknown). Advisory only – deprioritizes an unreferenced
	// component's finding, never suppresses it; lets a report/export SEPARATE used from unreferenced deps.
	ClassReachability string `json:",omitempty"`

	// DedupKey makes a finding idempotent across re-scans (e.g. advisory+component+version
	// for SCA vulns, or license:<id>); used as the upsert conflict key.
	DedupKey string

	// EvidenceScore gates promotion: candidates below the threshold are not
	// auto-promoted (deterministic evidence gating: AI-proposed findings are never
	// auto-promoted). Omitted from JSON when unset (0), so a scan path that does not score evidence
	// (e.g. the CLI) does not emit a meaningless 0.
	EvidenceScore int `json:",omitempty"`

	// ProposedBy is the actor that proposed an exploitation/AI finding (e.g. "agent:<sid>").
	// It exists so the adversarial verifier that later raises the score CANNOT be the same
	// actor that proposed it (a finding cannot confirm itself). Empty for
	// SCA/recon/manual findings.
	ProposedBy string

	Audit shared.Audit
}

type HypothesisInput struct {
	Title          string
	Description    string
	ConstituentIDs []string        // the finding ids this chain links (>= 2; a chain links multiple findings)
	Severity       shared.Severity // optional; defaults to Unknown (a human triages the chain's severity)
	AssetID        shared.ID
}

type Kind string

type ManualInput struct {
	Title       string
	Description string
	Severity    shared.Severity
	CVSSVector  string
	CWE         string
}

type Retest struct {
	ID           shared.ID     `json:"id"`
	EngagementID shared.ID     `json:"engagementId"`
	FindingID    shared.ID     `json:"findingId"`
	Outcome      RetestOutcome `json:"outcome"`
	Note         string        `json:"note,omitempty"`
	Tester       string        `json:"tester"`
	At           time.Time     `json:"at"`
}

type RetestOutcome string

type SASTInput struct {
	JudgmentID string          // the confirmed CapSAST judgment (dedup anchor – re-confirming updates in place)
	CWE        string          // the weakness, e.g. "CWE-89"
	Location   string          // where: "path[:line]" or the importPath.Symbol of the sink-using function
	Rule       string          // the taint rule that fired, e.g. "taint-sqli"
	Severity   shared.Severity // optional; defaults to Unknown (re-triaged via the normal finding workflow)
	DataFlow   *DataFlowTrace  // optional bounded source-to-sink witness from the confirmed judgment
}

type SourceLocation struct {
	File        string `json:"file"`
	StartLine   int    `json:"start_line"`
	EndLine     int    `json:"end_line"`
	StartColumn *int   `json:"start_column,omitempty"`
	EndColumn   *int   `json:"end_column,omitempty"`
}

type Status string

type ThreatInput struct {
	JudgmentID string          // the confirmed threat judgment (dedup anchor – re-confirming updates in place)
	Category   string          // STRIDE category token (e.g. "spoofing", "info_disclosure")
	Element    string          // the threatened model element id (a component or data flow)
	Asset      string          // optional Asset.ID at risk ("" when none)
	Severity   shared.Severity // optional; defaults to Unknown (re-triaged via the normal finding workflow)
}

type Verdict = verdict.Verdict