findings

type ConsentRecord struct {
	AcceptedBy string `json:"accepted_by"`
	AcceptedAt string `json:"accepted_at"`
	Reason     string `json:"reason"`
}

type Dimension string

type Finding struct {
	ID          string    `json:"id"`
	Dimension   Dimension `json:"dimension"`
	Severity    Severity  `json:"severity"`
	File        string    `json:"file,omitempty"`
	Line        int       `json:"line,omitempty"`
	Title       string    `json:"title"`
	Description string    `json:"description"`
	Suggestion  string    `json:"suggestion"`
	// Reasoning explains why the finding was flagged. Only set for findings the
	// agent reasoned from mapped surface; it records the agent's rationale so it
	// survives beyond the conversation (PRD section 11).
	Reasoning string `json:"reasoning,omitempty"`
	// Confidence is 1.0 for deterministic (regex/AST) findings and < 1.0 for
	// findings the agent reasoned from surface.
	Confidence float64 `json:"confidence"`
	// Probabilistic is true when the finding comes from the agent's reasoning
	// over mapped surface rather than a deterministic match.
	Probabilistic bool `json:"probabilistic"`
	// RequiresConsent is true for critical security findings, which cannot be
	// silenced with a plain ignore — they need an explicit ConsentRecord.
	RequiresConsent bool `json:"requires_consent"`
	// Baselined is true when the finding is pre-existing debt recorded in a
	// baseline snapshot; baselined findings never trigger the deploy block.
	Baselined bool `json:"baselined,omitempty"`
	// Suppressed, when non-nil, holds the consent under which a finding was
	// accepted and silenced.
	Suppressed *ConsentRecord `json:"suppressed,omitempty"`
	// Fingerprint is the content identity used by the baseline (see Fingerprint).
	// It is a one-way hash, safe to commit. Empty until stamped at the scan boundary.
	Fingerprint string `json:"fingerprint,omitempty"`
}

type SensorResult struct {
	Sensor     string        `json:"sensor"`
	Score      int           `json:"score"`
	Findings   []Finding     `json:"findings"`
	Surface    []SurfaceItem `json:"surface,omitempty"`
	DurationMs int64         `json:"duration_ms"`
	Error      string        `json:"error,omitempty"`
}

type Severity string

type SurfaceItem struct {
	// ID is a stable anchor derived from (file, line, category) — see
	// core/surface.StableID. The agent returns it in a verdict, and codefit
	// recomputes it to validate the verdict statelessly.
	ID string `json:"id"`
	// Category is the surface class: "idor" | "authz" | "overfetch" | ...
	Category string `json:"category"`
	File     string `json:"file"`
	Line     int    `json:"line"`
	// Snippet is the relevant source fragment for the agent to read.
	Snippet string `json:"snippet"`
	// StructuralSignals are verifiable syntactic FACTS about the item ("reads
	// params.id", "no call to a known authz helper was detected in the body"),
	// never judgments ("is vulnerable", "missing authorization"). They are what
	// the agent reasons over.
	StructuralSignals []string `json:"structural_signals"`
	// StructuralFacts is the queryable form of the same facts: boolean detections
	// a consumer can filter/sort by without parsing prose (e.g. authz →
	// "known_authz_detected", idor → "local_access_detected"). They are FACTS
	// ("a known pattern was/wasn't detected"), never judgments and never severity:
	// known_authz_detected=false means "no known authz pattern was seen", NOT "this
	// is unauthorized". Ordering by a fact is allowed; concluding from it is the
	// agent's.
	StructuralFacts map[string]bool `json:"structural_facts"`
	// IndirectCall names the external function a handler delegates to when the
	// resource access is NOT local to the body (e.g. an Express controller calling
	// a service that owns the Prisma query). It is paired with the structural fact
	// indirect_access=true. codefit does NOT follow the call across files — it
	// names the callee so the agent can reason about where the access happens
	// (cross-file option C). Empty when the access is local.
	IndirectCall string `json:"indirect_call,omitempty"`
	// ReasonToReview is the QUESTION the agent must answer about this item, never
	// a conclusion.
	ReasonToReview string `json:"reason_to_review"`
	// Fingerprint is the content identity used by the baseline (see Fingerprint).
	// Empty until stamped at the scan boundary.
	Fingerprint string `json:"fingerprint,omitempty"`
}