control

type AnalysisResult struct {
	// Project information
	ProjectPath   string `json:"projectPath"`
	ProjectID     int    `json:"projectId"`
	DefaultBranch string `json:"defaultBranch"`
	// AnalyzeBranch is the branch the analysis actually ran against
	// (--branch or the project's default). May differ from DefaultBranch.
	AnalyzeBranch string `json:"analyzeBranch,omitempty"`
	// HeadCommitSha is the head SHA of the analyzed branch, when known.
	// Used to build stable remote source links so that, even if the
	// branch moves later, links in the artifact still point at the
	// exact code that produced the finding. Empty when the SHA could
	// not be resolved (e.g. local-only runs without a fetched HEAD).
	HeadCommitSha string `json:"headCommitSha,omitempty"`

	// ArtifactCommitSHA and ArtifactRef are the resolved analyzed commit and
	// its branch/tag, computed once at output time and read by every artifact
	// writer so the JSON report, PBOM, SARIF and OCSF all report the same
	// commit the same way (#443). ArtifactCommitSHA is the resolved SHA, never
	// the literal "HEAD" placeholder (empty when nothing real resolved). They
	// are json:"-" because each writer places them in its own schema slot
	// (the report's headCommitSha, SARIF's versionControlProvenance, ...),
	// never as raw fields on the marshaled result.
	ArtifactCommitSHA string `json:"-"`
	ArtifactRef       string `json:"-"`
	// ArtifactRepoURI is the analyzed project's web URL, carried so SARIF's
	// versionControlProvenance can name the repository the commit belongs to
	// (repositoryUri is required there). Empty when it cannot be derived.
	ArtifactRepoURI string `json:"-"`

	// AnalyzedCIConfig is the CI configuration this run actually evaluated:
	// for GitLab the resolved merged pipeline, for GitHub each scanned
	// workflow file (#443). It carries a json tag so it appears in the JSON
	// report, and only there: no other artifact marshals the result whole.
	AnalyzedCIConfig *AnalyzedCIConfig `json:"analyzedCiConfig,omitempty"`

	// CI configuration status
	CiValid        bool     `json:"ciValid"`
	CiMissing      bool     `json:"ciMissing"`
	CiErrors       []string `json:"ciErrors,omitempty"` // Specific CI config errors from GitLab
	CIConfigSource string   `json:"ciConfigSource"`     // "local" or "remote"

	// Pipeline origin data
	PipelineOriginMetrics *PipelineOriginMetricsSummary `json:"pipelineOriginMetrics,omitempty"`

	// Pipeline image data
	PipelineImageMetrics *PipelineImageMetricsSummary `json:"pipelineImageMetrics,omitempty"`

	// Findings from the Rego/OPA rule engine. Single source of truth
	// for compliance results since all legacy Go controls were retired.
	Findings []opaengine.Finding `json:"findings,omitempty"`

	// Raw collected data (not included in JSON output, used for PBOM generation
	// and for the per-control aggregated stats block printed under each
	// control header in the terminal output).
	PipelineImageData  *gitlab.GitlabPipelineImageData      `json:"-"`
	PipelineOriginData *gitlab.GitlabPipelineOriginData     `json:"-"`
	ProtectionData     *gitlab.GitlabProtectionAnalysisData `json:"-"`
	// VariablesData records the settings-variable collection for the
	// cicdVariablesMustBe* controls. Set only after the collection ran;
	// nil (never ran) or Known=false (401/403) makes those controls
	// report not-evaluable rather than a false pass (see StatusFor).
	VariablesData *gitlab.GitlabVariablesAnalysisData `json:"-"`

	// SecurityPolicyData is the security-policy linkage collection, retained
	// for the same reason ProtectionData and VariablesData are: the
	// per-policy evaluation recomputes this control's tier caveat against
	// the POLICY's configuration, and the two booleans below cannot answer
	// "is a policy project linked" on their own (row 62).
	SecurityPolicyData *gitlab.SecurityPolicyData `json:"-"`

	// SecurityPolicyEvaluable is true when the security policy project linkage
	// was read authoritatively (a successful GraphQL read). False when it could
	// not be read (auth error, or the field is unavailable on the instance), so
	// StatusFor reports projectMustHaveSecurityPolicySource (ISSUE-601) as
	// not-evaluable rather than a false pass.
	SecurityPolicyEvaluable bool `json:"-"`

	// SecurityPolicyTierCaveat is set when the security-policy control ran, the
	// linkage was read, and NO policy project is linked — the tier-ambiguous
	// case (Ultimate-only feature; a non-Ultimate project cannot link one, an
	// Ultimate project may have left it unset). Renderers surface a conditional
	// caveat next to ISSUE-601.
	SecurityPolicyTierCaveat bool `json:"-"`

	// GitHubStats holds per-control denominators computed from the
	// GitHub IR after a GitHub analysis. Used by the GitHub renderer
	// to produce per-control stats blocks ("Total Images: 19,
	// Pinned By Digest: 1, …") and per-control compliance
	// percentages, matching the GitLab output structure. Nil on the
	// GitLab path.
	GitHubStats *GitHubAnalysisStats `json:"-"`

	// Pipeline is the normalized IR this run evaluated (GitLab path). It is
	// retained so a per-policy evaluation can re-run the rules over the same
	// collected data under different parameters: the platform serves each
	// policy its OWN control config, and a policy's verdict must come from
	// its own config rather than from whichever one happened to run first.
	// Nil on the GitHub path, which has GitHubPipeline below.
	Pipeline *ir.NormalizedPipeline `json:"-"`

	// Situation carries the per-job situation facts (trigger facts,
	// privilege, impact, feeds) derived from the pipeline, for the later contextual
	// score to read. Not user-visible: it never serializes and nothing
	// downstream of the report changes because of it.
	Situation *Situation `json:"-"`

	// Paths is set by ComputeScoreForProfile under scoring-v4: the attack
	// paths assembled from Findings and Situation, kept on the result for
	// the outputs that read them. Unset under scoring-v3. Not user-visible
	// on this type: it never serializes, the same way Situation above does
	// not.
	Paths []AttackPath `json:"-"`

	// GitHubPipeline is the normalized IR produced by the GitHub
	// collector, retained on the result so legacy JSON / PBOM /
	// CycloneDX builders can read images, action references, and
	// per-branch protection details without re-running the gitlab.
	// Nil on the GitLab path.
	GitHubPipeline *ir.NormalizedPipeline `json:"-"`

	// Warnings holds non-fatal "could not verify" messages from the run,
	// e.g. a known-CVE check skipped because an action's pinned commit
	// could not be resolved to a version (tag list blocked by an org IP
	// allow list, rate limit, or network). Surfaced in the terminal,
	// JSON, SARIF and GLSAST output, and gated by --fail-warnings (exit
	// 3) so a degraded check is visible instead of silently passing.
	Warnings []string `json:"warnings,omitempty"`

	// UnexpandedActions lists the action references the nested resolution
	// could not expand (GitHub only, spec 2026-10-16 section 7): budget,
	// fetch, expression or api_disabled.
	UnexpandedActions []ir.UnexpandedAction `json:"unexpandedActions,omitempty"`

	// ApprovalRulesTierCaveat is set when an MR approval-rule control ran but
	// the GitLab approvals API returned zero rules — the ambiguous case where
	// the project is either on GitLab Free (feature unavailable, API returns an
	// empty list) or on Premium/Ultimate with no rules configured. The API
	// gives no tier signal to tell them apart, so renderers surface a
	// Premium/Ultimate caveat next to ISSUE-502/504 rather than presenting the
	// result as authoritative.
	ApprovalRulesTierCaveat bool `json:"-"`

	// MRApprovalSettingsTierCaveat is set when the MR approval-settings control
	// ran and the project has no approval protection in effect — the GitLab-Free
	// signature (the feature does not exist there and the API 200-defaults every
	// protection off, which the operator cannot change). The settings API gives
	// no other tier signal, so renderers surface a Premium/Ultimate caveat next
	// to ISSUE-503 advising the operator to disable the control if they are on
	// Free. Any single protection being active proves a paid tier and clears it.
	MRApprovalSettingsTierCaveat bool `json:"-"`

	// MRSettingsPremiumCaveatFields lists the Premium/Ultimate MR-setting
	// expectations (mergePipelinesEnabled, mergeTrainsEnabled) that read as OFF
	// while the config expects them ON. These features require a paid tier, and
	// the project payload gives no tier signal, so an OFF read is ambiguous: a
	// Free project that cannot enable them, or a paid project that left them off
	// (a real misconfiguration). Non-empty => renderers surface a CONDITIONAL
	// caveat next to ISSUE-506 (disable the expectation if on Free; enable the
	// feature if on a paid tier) rather than asserting the tier either way.
	MRSettingsPremiumCaveatFields []string `json:"-"`

	// DataCollectionDegraded is set when a collection or enrichment step
	// failed mid-run, so the analysis ran on incomplete data: a GitLab
	// merged-CI fetch that timed out (empty pipeline), or a GitHub run
	// where some workflow files or the branch-protection fetch could not
	// be retrieved. When true the renderer withholds the letter-score
	// banner and marks the un-collected controls "not evaluated" instead
	// of presenting missing data as 100% compliant (#220). Distinct from
	// CiMissing, which is the legitimate "this project has no CI config"
	// state and is not degraded.
	DataCollectionDegraded bool `json:"dataCollectionDegraded,omitempty"`
	// NestedActionsBudgetExceeded is set when the nested actions resolution
	// stopped at its container budget (monorepo spec 2026-10-16 R3): the
	// closure is incomplete, which a platform push names among its missing
	// fields (actions_closure). Never serialised, the degraded reason says it.
	NestedActionsBudgetExceeded bool `json:"-"`

	// DegradedReasons lists the human-readable collection/enrichment
	// failures behind DataCollectionDegraded (e.g. "3 workflow file(s)
	// could not be fetched", "branch protection could not be fetched").
	// Surfaced as a caveat in the terminal. Empty when not degraded.
	DegradedReasons []string `json:"degradedReasons,omitempty"`

	// NotEvaluable maps a control name to the machine-readable reason its
	// verdict could not be established this run, for controls whose data
	// lane supplied nothing while the rest of the run evaluated normally.
	//
	// It exists because DegradedReasons above is all-or-nothing: any entry
	// turns EVERY control into an error. A lane split — where one source is
	// unavailable and the others are fine — has to say so per control, or
	// the unavailable lane either hides (a silent pass over data nobody
	// collected) or wrongly discredits every other control's verdict.
	//
	// A control listed here reports not_evaluable instead of passing. Real
	// findings still win: a control that DID fire is failed, because a
	// violation found on partial data is still a violation.
	NotEvaluable map[string]string `json:"notEvaluable,omitempty"`

	// CollectedLanes records which GATED data collections this run actually
	// performed, keyed by the lane names in collection_scope.go. A gate that
	// did not fire leaves its lane absent, and the per-policy path then
	// marks the controls reading that lane not_evaluable with
	// lane_not_collected rather than letting an empty result read as a pass
	// (platform decision row 62). True as soon as the collection ran, from
	// the platform's snapshot or from the git host: what matters here is
	// whether the data was sought at all, not whether it arrived.
	CollectedLanes map[string]bool `json:"-"`
}

type AnalyzedCIConfig struct {
	// Path is the GitLab CI config path that was analyzed (the project's
	// ci_config_path, default ".gitlab-ci.yml"). Empty on the GitHub path.
	Path string `json:"path,omitempty"`
	// Content is the GitLab configuration that findings were evaluated
	// against. Merged reports whether it is the include-merged pipeline
	// (true) rather than a single raw file.
	Content string `json:"content,omitempty"`
	Merged  bool   `json:"merged,omitempty"`
	// Workflows are the GitHub workflow files that were scanned, each with
	// its repo-relative path and content. Empty on the GitLab path.
	Workflows []AnalyzedWorkflowFile `json:"workflows,omitempty"`
}

type AnalyzedWorkflowFile struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type AttackPath struct {
	ID         string    `json:"id"`
	Tier       PathTier  `json:"tier"`
	BaseTier   PathTier  `json:"baseTier"`
	State      PathState `json:"state"`
	EntryKind  EntryKind `json:"entryKind"`
	Entry      EntryFact `json:"entry"`
	AnchorHash string    `json:"anchorHash"` // the first of AnchorHashes
	AnchorCode ErrorCode `json:"anchorCode"` // the first known-bad code of AnchorCodes, else the first entry-role one
	// AnchorHashes is every anchoring finding (identity.PlatformHash),
	// sorted: findings sharing the path's entry kind and entry subject are
	// one attack, whichever job they enter, so they anchor one path
	// together, and a finding of subjectFindingCodes on that subject and
	// an entry job joins them. AnchorCodes is their codes, sorted and
	// deduplicated.
	AnchorHashes []string    `json:"anchorHashes"`
	AnchorCodes  []ErrorCode `json:"anchorCodes"`
	Jobs         []string    `json:"jobs"` // the entry jobs, strongest branch first, then the jobs they feed
	Reach        Reach       `json:"reach"`
	ReachKind    string      `json:"reachKind"`  // the first of ReachKinds: "impact:<kind>" | "secrets" | "token" | "execution" | "none"
	ReachKinds   []string    `json:"reachKinds"` // every reach kind of Reach, strongest first
	Modifiers    []string    `json:"modifiers"`  // "private_exposure", "unresolvable", "gate:<code>", "push_entry_cap", "dependency_cap", "source_cap", "insider_cap", "maintainer_cap", "pinned_head_cap", "advisory_cap", "cache_writer_cap"
	GateHashes   []string    `json:"gateHashes"` // findings that amplified this path
	Exposure     string      `json:"exposure"`
	// Branches is one per entry job, in Jobs order: the walk from that job,
	// what it reaches, and the tier, state and modifiers it gives on its
	// own. The path takes its tier, modifiers and reach from the first.
	Branches []PathBranch `json:"branches"`

	// Sentence, FindingIDs and Loss are the report fields spec section 4
	// lists, filled by ScoreV4WithExplanations once the path is priced
	// (AssemblePaths leaves them empty): the path's plain-language
	// sentence; the anchor's hash, then the gates', then the consumed
	// privilege findings'; and the price of the path's tier, what the
	// path costs before the nested cap (pathLosses carries what it keeps).
	Sentence   string   `json:"sentence"`
	FindingIDs []string `json:"findingIds"`
	Loss       float64  `json:"loss"`

	// Claims is every claim this path rests on, each with the state the
	// facts behind it settle to (proven, assumed or unknown), computed
	// once at assembly end (claimsFor, control/pathclaims.go), in a fixed
	// order: the entry, the reach's own secrets, each walked edge, the
	// token, the environment, the cache writers, the download guard, and
	// the reach's impacts.
	Claims []Claim `json:"claims"`
	// contains filtered or unexported fields
}

type BestFix struct {
	AnchorHash string    `json:"anchorHash"`
	Code       ErrorCode `json:"code"`
	Job        string    `json:"job,omitempty"`
	Subject    string    `json:"subject,omitempty"`
	// PathID is the attack path the fix removes, empty when the fix is a
	// finding on no path.
	PathID       string  `json:"pathId,omitempty"`
	PointsGained float64 `json:"pointsGained"`
	// NewPoints is the final points once the fix is made.
	NewPoints float64 `json:"newPoints"`
	NewLetter string  `json:"newLetter"`
	Sentence  string  `json:"sentence"`
	// Reason says why PointsGained differs from the price of what the fix
	// removes ("+13 pts: the path's 15, less 2 for a finding that then
	// stands alone"), empty when it does not or when no reason can be read
	// off the two scores. The reports print it; the JSON does not carry it.
	Reason string `json:"-"`
	// Stays is set when no fix moves the final points: the best fix is
	// then the one that recovers the most before the caps, PointsGained is
	// 0, and Stays says why the score does not move yet ("The score stays
	// at 31 until fewer High paths remain."). The reports print it after
	// the fix; the JSON carries it in Sentence.
	Stays string `json:"-"`
	// contains filtered or unexported fields
}

type CacheFact struct {
	// Key is what a save and a restore must share to reach each other (a
	// caching action's discriminators included: a dependency path, a
	// buildx scope, a rust-cache job id); Family is the name to print, the
	// key without them.
	Key    string `json:"key"`
	Family string `json:"family"`
	Mode   string `json:"mode"` // "restore", "save" or "both"
	Prefix bool   `json:"prefix"`
	Uses   string `json:"uses"`
	Line   int    `json:"line"`
	// Parts is the discriminators of the real key a caching action builds
	// itself (setup-node, setup-python, setup-go, setup-uv, rust-cache)
	// that this program resolved to a concrete value, by name: "os",
	// "arch", "version", "manager". A name absent here is a part
	// cacheKeyTemplate (control/cachekeys.go) cannot resolve either, so it
	// stays an open placeholder, matching whatever the other side carries,
	// never a literal guess (Parts is additive, nil for every caller that
	// predates it).
	Parts map[string]string `json:"parts,omitempty"`
}

type CallerFact struct {
	Job              string   `json:"job"`
	TokenWrite       []string `json:"tokenWrite"`
	TokenWriteSource string   `json:"tokenWriteSource"`
	Secrets          []string `json:"secrets"`
	AllSecrets       bool     `json:"allSecrets"`
	Triggers         []string `json:"triggers"`
}

type CatalogControl struct {
	ID             string   `json:"id"`
	Name           string   `json:"name"`
	DisplayName    string   `json:"displayName"`
	Category       string   `json:"category"`
	Providers      []string `json:"providers"`
	Description    string   `json:"description"`
	RequiresConfig bool     `json:"requiresConfig"`
	// RequiresTier is the GitLab plan this control needs (premium or
	// ultimate), absent when every plan can satisfy it. A control whose
	// gate is one field only carries nothing here: the tier rides on the
	// field inside ConfigSchema (ask 56 of the 2026-09-22 issues-page
	// review).
	RequiresTier string                             `json:"requiresTier,omitempty"`
	ConfigSchema *configuration.ControlConfigSchema `json:"configSchema,omitempty"`
	IssueCodes   []string                           `json:"issueCodes"`
	// IssueCodeRoles maps each of IssueCodes to its role (entry, privilege,
	// gate, hygiene), the input the contextual score weighs a finding by. A
	// sibling map so the IssueCodes array keeps its shape for consumers.
	IssueCodeRoles map[string]string `json:"issueCodeRoles"`
	// IssueCodeEntryKinds maps each entry-role code in IssueCodes to the
	// situation fact it anchors to (pr_target, untrusted_expression,
	// mutable_dependency, poisoned_cache). Codes with another role are
	// absent: a sibling map, same shape rule as IssueCodeRoles.
	IssueCodeEntryKinds map[string]string `json:"issueCodeEntryKinds"`
}

type CatalogDocument struct {
	CatalogVersion int                `json:"catalogVersion"`
	CLIVersion     string             `json:"cliVersion"`
	Controls       []CatalogControl   `json:"controls"`
	IssueTypes     []CatalogIssueType `json:"issueTypes"`
}

type CatalogIssueType struct {
	Code        string `json:"code"`
	Severity    string `json:"severity"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Remediation string `json:"remediation"`
	DocURL      string `json:"docUrl"`
	ControlName string `json:"controlName"`
}

type Claim struct {
	Kind    string     `json:"kind"`
	Subject string     `json:"subject"`
	State   ClaimState `json:"state"`
	Source  string     `json:"source,omitempty"`
}

type ClaimState string

type CodeLoss struct {
	Code         ErrorCode     `json:"code"`
	Severity     IssueSeverity `json:"severity"`
	Count        int           `json:"count"`
	Weight       float64       `json:"weight"`
	Cap          float64       `json:"cap,omitempty"` // omitted when infinite (critical)
	UncappedLoss float64       `json:"uncappedLoss"`
	CappedLoss   float64       `json:"cappedLoss"`
}

type CodeRole string

type ControlEntry struct {
	DisplayName string
	ControlName string
	Skipped     bool
	// SkipReason is the human-friendly explanation rendered next to
	// the "(skipped)" header and in the Status: SKIPPED (…) line. Left
	// empty for the default "disabled in configuration" case; callers
	// that flip Skipped for a different reason (e.g. a required data
	// source was unavailable) set this so the operator sees why.
	SkipReason string
	Compliance float64
}

type EntryFact struct {
	Kind     EntryKind `json:"kind"`
	State    FactState `json:"state"`
	Evidence string    `json:"evidence"`
	Subject  string    `json:"subject"`
	File     string    `json:"file,omitempty"`
	Line     int       `json:"line,omitempty"`
	// CacheScopes is the scope the run that executes this entry saves its
	// cache under (entry_cache_scope): "pull_request" for a fork pull
	// request (its run never leaves the pull request's merge ref), the
	// job's own CacheScopes for every other entry this program builds
	// structurally (fork_pr, unprotected_push): the fact does not narrow
	// what a push or a dependency entry already tells the job's triggers.
	// Empty for an entry read off a finding rather than a situation fact
	// (control/paths.go computes the equivalent scope itself, off the
	// entry's own kind, for those).
	CacheScopes []string `json:"cacheScopes,omitempty"`
	// Actor is who can make the entry's job run (ir.GateClass): "outsider"
	// on a fork pull request entry and on a privileged entry no gate
	// holds, the class of the entry job's gate otherwise
	// (control/actor.go). "unknown" is the true value when the gate could
	// not be decided: the path then takes the outsider's mechanics, in the
	// unverified state, one tier down. Gate is that gate's reason ("label
	// x", "author x" for the pull request's author, "actor x", "environment
	// x requires reviewers", "merged"), and PinnedSha whether what the
	// entry runs is the head commit that was approved (a checkout only).
	// All three empty on an entry no outsider reaches through a trigger (a
	// dependency, a push, a cache).
	Actor     string `json:"actor,omitempty"`
	Gate      string `json:"gate,omitempty"`
	PinnedSha bool   `json:"pinnedSha,omitempty"`
	// Via is the chain a nested entry finding was reached through,
	// outermost first (monorepo spec 2026-10-16 section 6); empty on a
	// direct entry.
	Via []string `json:"via,omitempty"`
}

type EntryKind string

type ErrorCode string

type ErrorCodeInfo struct {
	// Code is the unique issue code (e.g., ISSUE-102).
	Code ErrorCode `json:"code"`
	// Severity reflects potential impact (see documentation); used for Plumber Score.
	Severity IssueSeverity `json:"severity"`
	// Title is a short human-readable title used by SARIF / GLSAST / JSON
	// renderers when no provider-specific override is set. Acts as the
	// default; the catalog DisplayName covers the terminal renderer's
	// per-provider naming separately.
	Title string `json:"title"`
	// Description explains what the issue is. Same fallback semantics as
	// Title: rendered as-is when no provider override is set.
	Description string `json:"description"`
	// Remediation provides guidance on how to fix the issue.
	Remediation string `json:"remediation"`
	// NestedRemediation replaces Remediation on a finding whose reference a
	// composite action or a called workflow pulled in (its data carries via,
	// spec 2026-10-16 section 6): the user cannot edit the container, so the
	// fix is on the outermost action. Empty when the remediation applies
	// either way.
	NestedRemediation string `json:"nestedRemediation,omitempty"`
	// DocURL is a direct link to the documentation for this issue.
	DocURL string `json:"docUrl"`
	// ControlName is the .plumber.yaml control key this code belongs to.
	ControlName string `json:"controlName"`
	// Role decides how a finding of this code enters the score (spec: contextual
	// score). EntryKind is set for RoleEntry only and names the situation fact
	// the finding anchors to.
	Role      CodeRole  `json:"role"`
	EntryKind EntryKind `json:"entryKind,omitempty"`

	// TitleByProvider lets cross-provider controls render different titles
	// in SARIF / JSON / GLSAST depending on which provider produced the
	// finding (mirrors the per-provider DisplayName already supported by
	// the catalog). Keyed by "gitlab" / "github". An empty map (the common
	// case) means TitleFor() falls back to Title for every provider.
	TitleByProvider map[string]string `json:"titleByProvider,omitempty"`
	// DescriptionByProvider works the same way for the longer description.
	DescriptionByProvider map[string]string `json:"descriptionByProvider,omitempty"`
}

type FactState string

type GitHubAnalysisStats struct {
	// Actions pinning (ISSUE-701).
	ActionRefsTotal    int
	ActionRefsUnpinned int
	ActionRefsExempt   int
	// ActionRefsImmutableRelease lists the tag refs ISSUE-701 accepted
	// because the tag is backed by an immutable GitHub release (#421):
	// not unpinned, and listed so the report says why a ref that looks
	// unpinned passed.
	ActionRefsImmutableRelease []PinnedRef
	// WorkflowLockfilePath is the scanned branch's workflow lockfile
	// (".github/workflows/actions.lock"), empty when it has none.
	WorkflowLockfilePath string
	// ActionRefsWorkflowLockfile lists the step refs ISSUE-701 accepted
	// because that lockfile locks them (#542). Reusable-workflow calls and
	// the steps of another repository's reusable workflow never appear:
	// lockfiles do not cover reusable workflows.
	ActionRefsWorkflowLockfile []PinnedRef
	// ActionRefsNested counts the entries a composite action or a called
	// workflow pulled in (monorepo spec 2026-10-16 section 8), trusted
	// owners included: they are part of the closure the rules read.
	ActionRefsNested int

	// Actions supply-chain (ISSUE-702, ISSUE-703, ISSUE-402). Counted
	// across every `uses:` entry that has API metadata, regardless of
	// the pin-by-SHA trusted-owner exemption — the rules themselves do
	// not exempt. In practice trusted-owner refs have nil metadata
	// (enrichment skips them) and won't add to either count.
	ActionRefsArchived   int
	ActionRefsVulnerable int
	ActionRefsAmbiguous  int
	// ActionRefsAbsentUpstream (ISSUE-707) counts SHA-pinned refs the
	// upstream repo confirmed do not exist. Guarded on isShaPinned so it
	// stays aligned with the impostor-commit rego, which only fires on a
	// 40-char SHA.
	ActionRefsAbsentUpstream int

	// Container images (ISSUE-102 / ISSUE-103).
	ImagesTotal          int
	ImagesPinnedByDigest int
	ImagesUsingForbidden int
	// ImagesExemptUnpinned counts the exemptImages matches without a
	// digest: not pinned, yet not "Not Pinned By Digest" either, since
	// ISSUE-103 does not judge them.
	ImagesExemptUnpinned int
	// ImagesExempted lists the references of the exempt images whose tag
	// is forbidden, the ones the exemption let through ISSUE-102.
	ImagesExempted []string

	// Docker-in-Docker (ISSUE-412 / ISSUE-413).
	JobsTotal              int
	JobsWithDinD           int
	JobsWithInsecureDaemon int

	// Excessive permissions (ISSUE-803). Counts jobs whose effective
	// `permissions:` is the literal `write-all` shortcut (workflow-
	// level grants are propagated per-job by the collector, so the
	// per-job count is the right denominator either way).
	JobsWithWriteAll int

	// Debug trace (ISSUE-203, GitHub side). VariableBindingsTotal is
	// the env-var denominator displayed by the stats block; mirrors
	// the GitLab side's "Variables Checked". DebugTraceFound counts
	// (job, var) pairs where the variable name matches a configured
	// forbidden entry case-insensitively and the value is truthy.
	VariableBindingsTotal int
	DebugTraceFound       int

	// Reusable workflow secrets (ISSUE-302).
	ReusableCalls               int
	ReusableCallsSecretsInherit int

	// Security jobs (ISSUE-410).
	SecurityJobsTotal    int
	SecurityJobsWeakened int

	// Workflow content scanned for template injection (ISSUE-207).
	ScriptLinesTotal int

	// Unverified script execution (ISSUE-411).
	UnverifiedScriptsFound int

	// CacheWriteExempted lists the exempted jobs (exemptWorkflows,
	// exemptJobs) that ISSUE-705 would have flagged: granted cache write on
	// an untrusted trigger, accepted as a risk (ISSUE-705).
	CacheWriteExempted []string

	// Workflows + properties (ISSUE-802, ISSUE-801).
	WorkflowsTotal                int
	WorkflowsWithDangerousTrigger int
	WorkflowsMissingPermissions   int

	// WorkflowFilesInvalid (ISSUE-423) counts the GitHub workflow files
	// this scan fetched but could not parse as a workflow. These files
	// are not among WorkflowsTotal (never parsed into a job).
	WorkflowFilesInvalid int

	// Branch protection (ISSUE-501 / ISSUE-505).
	BranchesTotal     int
	BranchesProtected int
	BranchesMatched   int // matched a configured namePattern
	// BranchesProtectionDetailsUnknown counts in-scope branches whose
	// protection-detail fetch did not yield authoritative data
	// (typically: GitHub /branches/{name}/protection 403/404 because
	// the token lacks Administration:Read). The branch_non_compliant
	// rule (ISSUE-505) abstains on such branches; this counter exists
	// so the renderer can surface a "we couldn't fully evaluate this"
	// caveat instead of a misleading 100% compliant.
	BranchesProtectionDetailsUnknown int
}

type ImpactFact struct {
	Kind     string    `json:"kind"` // publishes | deploys | writes_repo | signs_or_releases
	State    FactState `json:"state"`
	Evidence string    `json:"evidence"`
	// Source is "token" when the impact is what the job token's write scope
	// lets any code in the job do, empty when a step of the job does it.
	Source string `json:"source,omitempty"`
	// Via names the job of a reusable workflow whose step does it, when the
	// job holding the impact is the one calling that workflow; empty for
	// the job's own steps and token.
	Via string `json:"via,omitempty"`
}

type IncludeFact struct {
	Subject string   `json:"subject"`
	File    string   `json:"file,omitempty"`
	Line    int      `json:"line,omitempty"`
	Jobs    []string `json:"jobs"`
}

type IssueSeverity string

type JobSituation struct {
	// ForkPR is the job's fork pull request trigger fact (at most one per
	// job, a union when same-named jobs merge): GitHub "on: pull_request"
	// without a same-repository guard, GitLab "rules: merge_request_event".
	// No control reports it; the platform reach rules read it.
	ForkPR []EntryFact `json:"forkPR"`
	// PrivilegedTriggers is the job's events that run in the base
	// repository's context with its secrets and write token
	// (pull_request_target, workflow_run, issue_comment and the like),
	// sorted. A fork run of a job carrying one keeps its privilege; the
	// platform reach rules read it.
	PrivilegedTriggers []string `json:"privilegedTriggers"`
	// RefTriggers is the job's events that run it on a branch or a tag of
	// the repository itself (push, schedule, release, workflow_dispatch),
	// sorted: such a run saves its cache in that ref's scope, never only in
	// a pull request's.
	RefTriggers []string `json:"refTriggers"`
	// Push is the job's push to the default branch fact, present while the
	// branch is not known to be protected; its state is unknown when the
	// trigger filter or the protection cannot be decided. A
	// branch-protection finding on that branch starts its path here.
	Push      []EntryFact  `json:"push"`
	Privilege Privilege    `json:"privilege"`
	Impact    []ImpactFact `json:"impact"`
	Feeds     []string     `json:"feeds"`
	// FeedsVia is, per job of Feeds, the kinds of edge that link the two,
	// sorted: FeedArtifact, FeedArtifactAltered, FeedArtifactExecuted,
	// FeedCache, FeedOutput, FeedOutputCompared, FeedOutputExecuted. On
	// GitHub, needs output reads and artifact downloads never carry the
	// bare FeedArtifact or FeedOutput any more (see the two typed kinds
	// of each); GitLab keeps both, needs: alone being how an artifact
	// download there waits for its upload too.
	FeedsVia map[string][]string `json:"feedsVia"`
	// Caches is every cache the job restores, saves or both, with the step
	// declaring it, sorted.
	Caches []CacheFact `json:"caches"`
	// CacheScopes is the refs GitHub files what the job's runs save to the
	// cache under, sorted: "default" (the default branch: a push to it, a
	// schedule, a dispatch, and the other events that run there when the
	// job's cache-mode grants them write), "tag", "pull_request",
	// "merge_group", "branch" (a push to other branches only), or "any"
	// when the job carries no trigger (GitLab). Empty when its runs save
	// nothing (cache-mode read or none, or only low-trust events). Only a
	// "default" (or "any") save reaches a run of another ref.
	CacheScopes []string `json:"cacheScopes"`
	// RestoresCache is set when the job declares a cache it restores and
	// its cache-mode leaves restoring on (not write-only or none): a job a
	// poisoned cache reaches.
	RestoresCache bool `json:"restoresCache"`
	// SaveScopesByEvent is, per event the job runs on (its gated
	// triggers), the scopes a run of that event saves the cache under,
	// empty when GitHub keeps that run read-only: CacheScopes split by
	// event, so an entry that holds only in some runs (an untrusted
	// expression whose context only some events carry) saves only where
	// those runs do. Empty when the job carries no trigger (GitLab).
	SaveScopesByEvent map[string][]string `json:"saveScopesByEvent,omitempty"`
	// Uploads is true when some job carrying the name produces an
	// artifact (ir.ArtifactRef Mode "produce": an actions/upload-artifact
	// or actions/upload-pages-artifact step on GitHub, an artifacts:
	// block on GitLab). With a cache save (CacheFact Mode "save" or
	// "both") it is what lets code on the runner poison something a
	// later run reads: without either, the runner is thrown away.
	Uploads bool `json:"uploads"`
	// Callers is, on a job of a reusable workflow of the repository, every
	// call that runs it, sorted. The job's own Privilege already reads
	// through them (its token the union of theirs when it declares none,
	// its secrets those a call passes); a path entering the job names, per
	// caller, what that call gives.
	Callers []CallerFact `json:"callers"`
	// OwnImage is true when the job runs in a container and every image it
	// resolves to (through its matrix, or the image each caller of a
	// reusable workflow passes) is under the repository owner's namespace of
	// the GitHub container registry (ghcr.io/<owner>/...): an image of the
	// repository's organization, not an outside one.
	OwnImage bool `json:"ownImage"`
	// Dead is true when every job carrying the name has a constant false
	// if: (ir.Job.Dead) or a non-empty Inert reason: it never runs, so no
	// path enters it, and it is no feed edge either way.
	Dead bool `json:"dead"`
	// Inert is why this job can never run (ir.Job.Inert, MarkInert): its
	// workflow is disabled, its runner label is retired, it has no
	// trigger, it is a reusable workflow nobody calls, or it is pinned
	// to another repository. Empty for a job that can run; a job sharing
	// its name with a non-inert job still reads one of the group's own
	// non-empty reasons here (never cleared by a sibling that can run),
	// so the terminal report still names the cause.
	Inert string `json:"inert"`
	// Gate is who can make the job run on its privileged triggers
	// (ir.Job.Gate, ir.ClassifyGates), the weakest among the jobs sharing
	// its name; nil when none carries a privileged trigger, and on GitLab.
	Gate *ir.Gate `json:"gate,omitempty"`
}

type OtherFindingsLoss struct {
	Count        int            `json:"count"`
	Counts       SeverityCounts `json:"counts"`
	UncappedLoss float64        `json:"uncappedLoss"`
	Cap          float64        `json:"cap"`
	CappedLoss   float64        `json:"cappedLoss"`
	CapApplied   bool           `json:"capApplied"`
}

type PathBlock struct {
	Tier         PathTier
	Unverified   bool
	Loss         float64
	Entry        string // "image docker.io/alpine:latest"
	EntrySubject string // the part of Entry read off the workflow: "docker.io/alpine:latest"
	// Branches is one per entry job of the path, in the path's job order.
	Branches []PathBlockBranch
	// EntryUnverified and ReachUnverified say what could not be checked:
	// about the entry, or about what it reaches. Empty when there is
	// nothing to say.
	EntryUnverified string
	RunsIn          string // "job est_file" | "jobs build, deploy": the entry jobs
	ReachesShort    string
	ReachUnverified string
	So              string
	// Cap says, on a path a cap lowered (the push entry cap, the
	// dependency cap), why it stops at its tier (Medium or High); empty
	// otherwise. It is how the score was computed, not what the path is,
	// so a graph prints it as a Note only when ShowCap is set, which the
	// renderers set under --score-point.
	Cap     string
	ShowCap bool
	// Environment is what the block says about the environment the path's
	// entry job runs in: its name, then that it requires a review, when it
	// does. A protection, never an impact.
	Environment []string
	Fix         string
	Findings    []PathBlockFinding
	// ClaimsNote is what Plumber assumed and what it could not read, named
	// by the subjects of the path's own assumed and unknown claims
	// (claimsNote): "" when every claim
	// (claimsFor) is proven. Notes() folds it onto the cap note, after a
	// period, when ShowCap prints one; otherwise it opens a Note line of
	// its own.
	ClaimsNote string
}

type PathBlockBranch struct {
	Job    string
	Fed    []string
	FedVia [][]string
	Reach  string
	Marker string // "(on pull_request_target)", "(unverified)", both, or empty
}

type PathBlockFinding struct {
	Code     ErrorCode
	Title    string
	Location string
	Count    int
}

type PathBranch struct {
	Job       string    `json:"job"`
	Jobs      []string  `json:"jobs"`
	Reach     Reach     `json:"reach"`
	Tier      PathTier  `json:"tier"`
	State     PathState `json:"state"`
	Modifiers []string  `json:"modifiers"`
	// FeedsVia is, per job of Jobs the entry job feeds, the kinds of edge
	// that link them (JobSituation.FeedsVia); absent when it feeds none.
	FeedsVia map[string][]string `json:"feedsVia,omitempty"`
	// contains filtered or unexported fields
}

type PathLoss struct {
	Tier       PathTier `json:"tier"`
	Count      int      `json:"count"`
	Weight     float64  `json:"weight"`
	Cap        float64  `json:"cap,omitempty"` // omitted when infinite (critical)
	CappedLoss float64  `json:"cappedLoss"`
	PathIDs    []string `json:"pathIds"`
}

type PathRow struct {
	Entry   string // "docker.io/alpine:latest (mutable image tag)"
	Jobs    string // "build" | "build, deploy"
	Reaches string // "7 secrets; token: write"
}

type PathState string

type PathTier string

type PinnedRef struct {
	Job       string
	Uses      string
	Line      int
	PinnedVia string
}

type PipelineImageMetricsSummary struct {
	Total uint `json:"total"`
}

type PipelineOriginMetricsSummary struct {
	JobTotal            uint `json:"jobTotal"`
	JobHardcoded        uint `json:"jobHardcoded"`
	OriginTotal         uint `json:"originTotal"`
	OriginComponent     uint `json:"originComponent"`
	OriginLocal         uint `json:"originLocal"`
	OriginProject       uint `json:"originProject"`
	OriginRemote        uint `json:"originRemote"`
	OriginTemplate      uint `json:"originTemplate"`
	OriginGitLabCatalog uint `json:"originGitLabCatalog"`
	OriginOutdated      uint `json:"originOutdated"`
}

type PlatformPolicyLine struct {
	Name        string
	Enforcement string
	Letter      string
	FinalPoints int
	Blocking    bool
}

type PlatformPostSummary struct {
	GlobalLetter string
	GlobalPoints int
	HasGlobal    bool
	Policies     []PlatformPolicyLine
}

type PlumberScoreResult struct {
	ProfileID string `json:"profileId"`

	Counts SeverityCounts `json:"counts"`

	// RawPoints is 100 minus summed capped per-code losses (before Critical malus).
	RawPoints float64 `json:"rawPoints"`
	// RawPointsUnclamped is RawPoints before the floor at zero. RawPoints is
	// what the gate and the badge are defined on, so it stays clamped; this
	// carries the true signed deficit for consumers that store history and
	// want to distinguish "barely failing" from "catastrophic".
	RawPointsUnclamped float64 `json:"rawPointsUnclamped"`
	// FinalPoints applies Critical category malus (max points in E band when any Critical exists).
	FinalPoints float64 `json:"finalPoints"`
	// Score is the letter A–E from final points (what people mean by "how did we score?").
	Score string `json:"score"`

	CriticalMalusApplied bool    `json:"criticalMalusApplied"`
	CriticalMalusMax     float64 `json:"criticalMalusMax,omitempty"` // max points when malus applies (30)

	// Losses is a per-severity rollup of capped per-code losses.
	Losses []SeverityLoss `json:"losses"`
	// CodeLosses is the per-code breakdown that drives the score in scoring-v3;
	// under scoring-v4 it lists the other findings per code, each code's
	// CappedLoss its share of the capped bucket.
	CodeLosses []CodeLoss `json:"codeLosses"`

	// Paths is the assembled attack-path set scoring-v4 priced.
	Paths []AttackPath `json:"paths,omitempty"`
	// PathLosses is the attack-path bucket, one entry per tier present.
	PathLosses []PathLoss `json:"pathLosses,omitempty"`
	// OtherFindings is the other-findings bucket, nil when every live
	// finding is consumed by a path.
	OtherFindings *OtherFindingsLoss `json:"otherFindings,omitempty"`
	// FloorApplied and FloorPoints are kept for the consumers that read
	// them and are never set: the contextual score has no floor, its nested
	// caps keep a run with no Critical item at 31 or more, with no High at
	// 51 or more, with no Medium at 71 or more.
	FloorApplied bool    `json:"floorApplied,omitempty"`
	FloorPoints  float64 `json:"floorPoints,omitempty"`
	// CriticalPaths is how many assembled paths are Tier Critical; > 0 is
	// what drives scoring-v4's own Critical malus (CriticalMalusApplied),
	// a gate alone never does.
	CriticalPaths int `json:"criticalPaths,omitempty"`
	// PathCounts is how many assembled paths each tier holds, keyed
	// critical/high/medium/low, non-zero tiers only (spec section 4: the
	// PBOM carries it); nil when no path assembled.
	PathCounts map[string]int `json:"pathCounts,omitempty"`
	// Situation is the situation facts as text (SituationText): visibility,
	// the default branch, the jobs. Empty under scoring-v3.
	Situation string `json:"situation,omitempty"`
	// BestFix is the single highest-value fix ScoreV4WithExplanations found
	// among the run's non-dismissed findings, nil when none gains points.
	BestFix *BestFix `json:"bestFix,omitempty"`
}

type Privilege struct {
	Secrets        []string  `json:"secrets"`
	SecretsState   FactState `json:"secretsState"`
	SecretsInherit bool      `json:"secretsInherit"`
	// AllSecrets is true when the job holds every secret of the repository,
	// proven by the way it reads them (secrets: inherit, or the whole
	// secrets context), whatever their names.
	AllSecrets       bool     `json:"allSecrets"`
	ProtectedSecrets []string `json:"protectedSecrets"`
	TokenWrite       []string `json:"tokenWrite"`
	TokenWriteSource string   `json:"tokenWriteSource"` // declared | log | effect | unknown | none
	// TokenWriteState is how settled TokenWriteSource is: "proven" for
	// declared, log and effect (a real declaration, a run's own log, or
	// a bot-authored write all settle it), "unknown" for unknown and
	// none (nothing settled it either way).
	TokenWriteState      FactState `json:"tokenWriteState"`
	PersistedCredentials FactState `json:"persistedCredentials"`
	// Environment is the job's deployment environment, a protection the job
	// runs behind and never an impact by itself. Reviewers is "proven" once
	// the provider's environments were read authoritatively, "unknown"
	// while they were not collected (GitLab) or the collection failed
	// (GitHub 401/403/404/network). RequiredReviewers and Rules are only
	// meaningful when Reviewers is "proven": RequiredReviewers is whether
	// the matching environment requires an approval before the job runs;
	// Rules names which protection rules that environment carries
	// (required_reviewers, wait_timer, branch_policy).
	Environment struct {
		Name              string    `json:"name"`
		Protected         string    `json:"protected"` // "true" | "false" | "unknown"
		Reviewers         FactState `json:"reviewers"` // "proven" | "unknown"
		RequiredReviewers bool      `json:"requiredReviewers"`
		Rules             []string  `json:"rules"`
	} `json:"environment"`
}

type Reach struct {
	Secrets []string `json:"secrets"` // names reachable by the attacker, after platform rules
	// AllSecrets is true when a walked job holds every secret of the
	// repository (Privilege.AllSecrets), after platform rules.
	AllSecrets bool         `json:"allSecrets"`
	TokenWrite []string     `json:"tokenWrite"` // write scopes reachable by the attacker, after platform rules
	Impacts    []ImpactFact `json:"impacts"`    // impact facts of the walked jobs, concatenated
	// Executes is true for every path: a push runs the job's own steps, and
	// a job with no script of its own (a bare `uses:` push trigger, for
	// instance) still runs whatever that uses target executes. The field
	// stays (the outputs read it, and a future entry kind may need to turn
	// it off) but under the current entry kinds it is always true.
	Executes bool `json:"executes"`
	// contains filtered or unexported fields
}

type ScoreInputV4 struct {
	Findings []opaengine.Finding
	Paths    []AttackPath
	// ProjectPath is the analysed repository's "owner/repo", which the
	// best fix re-assembles the paths for (AssemblePaths); empty when
	// unknown.
	ProjectPath string
	// DefaultBranch is the pipeline's default branch, which a finding on
	// no path is priced against (IndividualSeverity); empty when unknown.
	DefaultBranch string
}

type SeverityCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

type SeverityLoss struct {
	Severity   IssueSeverity `json:"severity"`
	Count      int           `json:"count"`
	CappedLoss float64       `json:"cappedLoss"`
}

type Situation struct {
	Exposure string                  `json:"exposure"` // ir.Visibility*
	Jobs     map[string]JobSituation `json:"jobs"`
	// DefaultBranch is the pipeline's default branch (input.pipeline.defaultBranch
	// on the Rego side), empty when the provider never gave it. A gate whose
	// own branch matches this one amplifies every path, not only paths
	// through jobs it shares (spec section 2, rule 7).
	DefaultBranch string `json:"defaultBranch"`
	// Provider is the pipeline's provider, "github" or "gitlab".
	Provider string `json:"provider"`
	// Includes is every pipeline include with a source.
	Includes []IncludeFact `json:"includes"`
}

type SituationFact struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type StatLine struct {
	Label string
	Value string
}