predicate

type ArtifactType string

type CodeScan struct {
	// subject-binding fields, not part of the predicate body
	Type        ArtifactType `json:"-"`
	SubjectName string       `json:"-"`
	SubjectPath string       `json:"-"`
	Digest      string       `json:"-"`

	Tools         []CodeScanTool       `json:"tools"`
	Summary       CodeScanSummary      `json:"summary"`
	Configuration []ResourceDescriptor `json:"configuration"`
	Invocation    CodeScanInvocation   `json:"invocation"`
	// FindingsIncluded is true when results[] is authoritative (every fail-kind
	// finding is present). A policy may recompute over results[] only when
	// findingsIncluded is true AND truncated is false; otherwise it must fall
	// back to the summary counts.
	FindingsIncluded bool `json:"findingsIncluded"`
	// Truncated is true when results[] omits findings (excluded by default, or
	// capped by --max-findings).
	Truncated bool `json:"truncated"`
	// ResultCount is the total number of fail-kind findings discovered, equal to
	// summary.byLevel.total + summary.suppressed, regardless of how many findings
	// are emitted in results[].
	ResultCount int `json:"resultCount"`

	Results        []CodeScanFinding `json:"results,omitempty"`
	ScanContext    *CodeScanContext  `json:"scanContext,omitempty"`
	ScanStartedOn  string            `json:"scanStartedOn,omitempty"`
	ScanFinishedOn string            `json:"scanFinishedOn,omitempty"`
}

type CodeScanContext struct {
	CommitSHA string `json:"commitSha,omitempty"`
	Ref       string `json:"ref,omitempty"`
	URL       string `json:"url,omitempty"`
}

type CodeScanFinding struct {
	RuleID                string            `json:"ruleId"`
	Tool                  string            `json:"tool,omitempty"`
	Level                 string            `json:"level"`
	Kind                  string            `json:"kind"`
	SecuritySeverity      string            `json:"securitySeverity,omitempty"`
	SecuritySeverityLevel string            `json:"securitySeverityLevel,omitempty"`
	Message               string            `json:"message,omitempty"`
	Location              *CodeScanLocation `json:"location,omitempty"`
	BaselineState         string            `json:"baselineState,omitempty"`
	Suppressed            bool              `json:"suppressed"`
	SuppressionKind       string            `json:"suppressionKind,omitempty"`
	PartialFingerprints   map[string]string `json:"partialFingerprints,omitempty"`
}

type CodeScanInvocation struct {
	ExecutionSuccessful bool `json:"executionSuccessful"`
}

type CodeScanLevelCounts struct {
	Error   int `json:"error"`
	Warning int `json:"warning"`
	Note    int `json:"note"`
	None    int `json:"none"`
	Total   int `json:"total"`
}

type CodeScanLocation struct {
	URI       string `json:"uri,omitempty"`
	StartLine int    `json:"startLine,omitempty"`
	EndLine   int    `json:"endLine,omitempty"`
}

type CodeScanOptions struct {
	Type            ArtifactType
	SubjectName     string
	SubjectPath     string
	Digest          string
	ResultsPath     string
	IncludeFindings bool
	MaxFindings     int
	ConfigURI       string
	CommitSHA       string
	Ref             string
	URL             string
}

type CodeScanSeverityCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
	None     int `json:"none"`
	Total    int `json:"total"`
}

type CodeScanSummary struct {
	ByLevel            CodeScanLevelCounts    `json:"byLevel"`
	BySecuritySeverity CodeScanSeverityCounts `json:"bySecuritySeverity"`
	Suppressed         int                    `json:"suppressed"`
	New                int                    `json:"new,omitempty"`
}

type CodeScanTool struct {
	Name           string `json:"name"`
	Version        string `json:"version,omitempty"`
	InformationURI string `json:"informationUri,omitempty"`
}

type Config struct {
	PolicyRepo  PolicyRepo
	SchemasPath string
}

type Context struct {
	Repository        string `json:"repository"`
	RepositoryOwner   string `json:"repository_owner"`
	RepositoryID      string `json:"repository_id"`
	ServerURL         string `json:"server_url"`
	RepositoryOwnerID string `json:"repository_owner_id"`
	WorkflowRef       string `json:"workflow_ref"`
	RefName           string `json:"ref_name"`
	EventName         string `json:"event_name"`
	SHA               string `json:"sha"`
	RunNumber         string `json:"run_number"`
	RunID             string `json:"run_id"`
	Actor             string `json:"actor"`

	Event struct {
		WorkflowRun struct {
			CreatedAt string `json:"created_at"`
		} `json:"workflow_run"`
		HeadCommit struct {
			Timestamp string `json:"timestamp"`
		} `json:"head_commit"`
	} `json:"event"`

	Inputs    map[string]any `json:"inputs"`
	JobStatus string         `json:"job_status"`
	Runner    *Runner        `json:"runner"`

	Organization struct {
		Name string `json:"name"`
	} `json:"organization"`
}

type DependencyScan struct {
	Type        ArtifactType `json:"-"`
	SubjectName string       `json:"-"`
	SubjectPath string       `json:"-"`
	Digest      string       `json:"-"`
	Scanner     struct {
		Name    string `json:"name"`
		URI     string `json:"uri"`
		Version string `json:"version"`
		DB      struct {
			URI        string `json:"uri"`
			Version    string `json:"version,omitempty"`
			LastUpdate string `json:"lastUpdate,omitempty"`
		} `json:"db"`
		Result []ScanResult `json:"result"`
	} `json:"scanner"`
	Metadata struct {
		ScanStartedOn  string `json:"scanStartedOn"`
		ScanFinishedOn string `json:"scanFinishedOn"`
	} `json:"metadata,omitempty"`
}

type DependencyScanOptions struct {
	Type        ArtifactType
	SubjectName string
	SubjectPath string
	Digest      string
	ResultsPath string
	StartedAt   time.Time
	FinishedAt  time.Time
}

type GrypeResult struct {
	Descriptor struct {
		Version   string `json:"version"`
		Timestamp string `json:"timestamp"`
		DB        struct {
			Status *struct {
				Built         string `json:"built"`
				SchemaVersion string `json:"schemaVersion"`
				From          string `json:"from,omitempty"`
			} `json:"status,omitempty"`
		} `json:"db"`
	} `json:"descriptor"`
	Matches []struct {
		Vulnerability struct {
			ID       string `json:"id"`
			Severity string `json:"severity"`
			CVSS     []struct {
				Metrics struct {
					BaseScore float64 `json:"baseScore"`
				} `json:"metrics"`
			} `json:"cvss"`
		} `json:"vulnerability"`
	} `json:"matches"`
}

type Metadata struct {
	Artifact struct {
		Version  string `json:"version"`
		Created  string `json:"created"`
		Type     string `json:"type"`
		Registry string `json:"registry,omitempty"`
		FullName string `json:"fullName,omitempty"`
		Digest   string `json:"digest,omitempty"`
		Path     string `json:"path,omitempty"`
	} `json:"artifact"`
	RepositoryData struct {
		Repository      string `json:"repository"`
		RepositoryID    string `json:"repositoryId"`
		GitHubServerURL string `json:"githubServerURL"`
	} `json:"repositoryData"`
	OwnerData struct {
		Owner   string `json:"owner"`
		OwnerID string `json:"ownerId"`
	} `json:"ownerData"`
	RunnerData struct {
		OS          string `json:"os"`
		Arch        string `json:"arch"`
		Environment string `json:"environment"`
	} `json:"runnerData"`
	WorkflowData struct {
		WorkflowRefPath string         `json:"workflowRefPath"`
		Inputs          map[string]any `json:"inputs,omitempty"`
		Branch          string         `json:"branch"`
		Event           string         `json:"event"`
	} `json:"workflowData"`
	JobData struct {
		RunNumber   string `json:"runNumber"`
		RunID       string `json:"runId"`
		Status      string `json:"status"`
		TriggeredBy string `json:"triggeredBy"`
		StartedAt   string `json:"startedAt"`
		CompletedAt string `json:"completedAt"`
	} `json:"jobData"`
	CommitData struct {
		SHA       string `json:"sha"`
		Timestamp string `json:"timestamp"`
	} `json:"commitData"`
	Organization struct {
		Name string `json:"name"`
	} `json:"organization"`
	Compliance struct {
		PolicyRef  string   `json:"policyRef"`
		ControlIds []string `json:"controlIds"`
	} `json:"compliance"`
	Security struct {
		Permissions map[string]string `json:"permissions"`
	} `json:"security"`
}

type Options struct {
	// artifact fields
	Version     string
	Created     time.Time
	Type        ArtifactType
	Registry    string
	FullName    string
	SubjectPath string
	Digest      string

	// repo fields
	Repository      string
	RepositoryID    string
	GitHubServerURL string

	// owner fields
	Owner   string
	OwnerID string

	// runner fields
	OS          string
	Arch        string
	Environment string

	// workflow fields
	WorkflowRefPath string
	Inputs          map[string]any
	Branch          string
	Event           string

	// job fields
	RunNumber   string
	RunID       string
	Status      string
	TriggeredBy string
	StartedAt   time.Time
	CompletedAt time.Time

	// commit fields
	SHA       string
	Timestamp time.Time

	// org fields
	OrgName string

	// compliance fields
	PolicyRef  string
	ControlIds []string

	// permissions fields
	Permissions map[string]string
}

type PolicyRepo struct {
	Owner string
	Name  string
	Ref   string
}

type ResourceDescriptor struct {
	Name             string            `json:"name,omitempty"`
	URI              string            `json:"uri,omitempty"`
	Digest           map[string]string `json:"digest,omitempty"`
	Content          string            `json:"content,omitempty"`
	DownloadLocation string            `json:"downloadLocation,omitempty"`
	MediaType        string            `json:"mediaType,omitempty"`
	Annotations      map[string]any    `json:"annotations,omitempty"`
}

type ReviewService interface {
	// ListPullRequestsWithCommit returns pull requests associated with a commit
	// SHA. Documented quirk (go-github v88): if the SHA is not present in the
	// repository's default branch, the result includes ONLY open pull requests —
	// so a release-branch/tag build can return zero merged PRs even though the
	// change was reviewed. NewSourceReview treats that as incompleteness, not a
	// definitive direct push.
	ListPullRequestsWithCommit(ctx context.Context, owner, repo, sha string, opts *gh.ListOptions) ([]*gh.PullRequest, *gh.Response, error)
	// ListReviews lists all reviews on a pull request (paginated).
	ListReviews(ctx context.Context, owner, repo string, number int, opts *gh.ListOptions) ([]*gh.PullRequestReview, *gh.Response, error)
	// GetBranchProtection returns classic branch protection. Needs admin /
	// Administration:read; a 404 means no protection (not an error condition).
	GetBranchProtection(ctx context.Context, owner, repo, branch string) (*gh.Protection, *gh.Response, error)
	// ListRulesForBranch returns the repository rules (rulesets) active for a
	// branch. Readable without admin — the no-admin path to the required-review
	// threshold.
	ListRulesForBranch(ctx context.Context, owner, repo, branch string, opts *gh.ListOptions) (*gh.BranchRules, *gh.Response, error)
	// GetRuleset returns a repository ruleset (incl. org/enterprise parents when
	// includesParents). Needs Administration:read; a 403/404 is best-effort — the
	// producer omits bypass actors rather than failing the attestation.
	GetRuleset(ctx context.Context, owner, repo string, rulesetID int64, includesParents bool) (*gh.RepositoryRuleset, *gh.Response, error)

	// GetRulesetHistory returns the VERSION HISTORY of a ruleset, newest first,
	// for the SLSA Source-L3 continuity walk. go-github v88 binds NEITHER ruleset
	// history endpoint, so this is issued via the raw client. It tries the
	// repo-scoped endpoint first; if that 404s (the id belongs to an ORG/parent
	// ruleset that is only visible through includesParents on the repo), it falls
	// back to the org-scoped endpoint. A 403/404 on BOTH surfaces as an error so
	// continuity fails CLOSED (unreadable history is NEVER read as "no changes").
	// Paginates via the Link header (resp.NextPage).
	GetRulesetHistory(ctx context.Context, owner, repo string, rulesetID int64, opts *gh.ListOptions) ([]*RulesetVersion, *gh.Response, error)
	// GetRulesetVersion returns the full ruleset STATE at one historical version
	// (enforcement, conditions, rules, bypass actors). Like GetRulesetHistory it
	// is issued via the raw client with a repo→org fallback, and any 403/404
	// surfaces as an error so the continuity walk fails closed.
	GetRulesetVersion(ctx context.Context, owner, repo string, rulesetID, versionID int64) (*RulesetVersionState, *gh.Response, error)

	// ListCommits maps a continuity start TIME to a start COMMIT producer-side (the
	// verifier never calls GitHub). Called with SHA=branch + Since=start; the oldest
	// returned commit at-or-after the start time is the approximate start revision
	// R0. Paginated truncation (>cap pages) is treated as unresolvable -> fail closed.
	ListCommits(ctx context.Context, owner, repo string, opts *gh.CommitsListOptions) ([]*gh.RepositoryCommit, *gh.Response, error)
	// GetRepository returns the repository (for its default branch), so the
	// continuity walk can decide whether a ruleset version that targets only
	// "~DEFAULT_BRANCH" actually covers the artifact's protected branch. Unreadable
	// -> the default branch is unknown -> a "~DEFAULT_BRANCH"-only version fails
	// closed.
	GetRepository(ctx context.Context, owner, repo string) (*gh.Repository, *gh.Response, error)
}

type RulesetActor struct {
	ID   int64
	Type string
}

type RulesetVersion struct {
	VersionID int64
	Actor     RulesetActor
	UpdatedAt time.Time
}

type RulesetVersionState struct {
	Enforcement  string
	Conditions   *gh.RepositoryRulesetConditions
	Rules        *gh.RepositoryRulesetRules
	BypassActors []*gh.BypassActor
}

type Runner struct {
	OS          string `json:"os"`
	Arch        string `json:"arch"`
	Environment string `json:"environment"`
}

type ScanResult struct {
	ID       string     `json:"id"`
	Severity []Severity `json:"severity"`
}

type Severity struct {
	Method string `json:"method"`
	Score  string `json:"score"`
}

type SourceReview struct {
	// subject-binding fields, not part of the predicate body
	Type        ArtifactType `json:"-"`
	SubjectName string       `json:"-"`
	SubjectPath string       `json:"-"`
	Digest      string       `json:"-"`

	SourceRepository string          `json:"sourceRepository"`
	SourceRevision   string          `json:"sourceRevision"`
	Ref              string          `json:"ref,omitempty"`
	PullRequest      *SourceReviewPR `json:"pullRequest,omitempty"`

	Summary SourceReviewSummary `json:"summary"`

	// ApproversIncluded is true when approvers[] is authoritative (every
	// qualifying reviewer is present). The gate may recompute over approvers[]
	// only when this is true; otherwise it must use the summary counts and fail
	// closed if a per-reviewer filter it cannot satisfy is requested.
	ApproversIncluded bool                   `json:"approversIncluded"`
	Approvers         []SourceReviewApprover `json:"approvers,omitempty"`

	BranchProtection *SourceReviewBranchProtection `json:"branchProtection,omitempty"`

	// TechnicalControls records the enforced SLSA-L3 branch-protection controls
	// (force-push blocked, linear history, deletion blocked, required signatures,
	// required status checks, bypass actors). Best-effort, evidence only.
	TechnicalControls *SourceReviewTechnicalControls `json:"technicalControls,omitempty"`

	// ContinuityStartRevision is set ONLY when ContinuityEvidence proves an
	// unbroken enforcement window from this revision through the attested revision
	// (SLSA L3 continuity); it is empty otherwise. The verifier MUST NOT infer L3
	// continuity from this value alone — it gates on TechnicalControls.
	// ContinuityComplete AND a non-empty value together (absence or an
	// incomplete-proof value is undetermined, not satisfied).
	ContinuityStartRevision string `json:"continuityStartRevision,omitempty"`

	// ContinuityEvidence records how the continuity window was established (or why
	// it could not be). Audit evidence only — the gate keys on ContinuityComplete +
	// ContinuityStartRevision. Omitted when continuity was not even attempted.
	ContinuityEvidence *SourceReviewContinuityEvidence `json:"continuityEvidence,omitempty"`

	// ReviewDecision is reserved for an optional best-effort GraphQL enrichment
	// (pullRequest.reviewDecision). It is INFORMATIONAL ONLY and never a basis for
	// PASS. The producer adds no GraphQL client, so it is always empty here.
	ReviewDecision string `json:"reviewDecision,omitempty"`

	Configuration []ResourceDescriptor `json:"configuration"`

	// ReviewToolingComplete is false when the review evidence could not be fully
	// gathered (PRs/reviews unfetchable, or no merged PR resolved — which covers
	// both a genuine direct push and the ListPullRequestsWithCommit default-branch
	// quirk). Mirrors code-scan's invocation.executionSuccessful: the gate fails
	// this closed by default.
	ReviewToolingComplete bool `json:"reviewToolingComplete"`
}

type SourceReviewApprover struct {
	Login       string `json:"login"`
	Association string `json:"association,omitempty"`
	SubmittedAt string `json:"submittedAt,omitempty"`
	CommitID    string `json:"commitId,omitempty"`
	Stale       bool   `json:"stale"`
	IsBot       bool   `json:"isBot"`
}

type SourceReviewBranchProtection struct {
	RequireReviews               bool `json:"requireReviews"`
	RequiredApprovingReviewCount int  `json:"requiredApprovingReviewCount"`
	DismissStaleReviews          bool `json:"dismissStaleReviews"`
	RequireCodeownerReview       bool `json:"requireCodeownerReview"`
	// RequireLastPushApproval records GitHub's "last push must be approved by
	// someone other than the pusher" control. The producer enforces the
	// on-head-commit half via staleness (an approval not on the PR head does not
	// count); the "approver != last pusher" nuance requires push authorship not
	// fetched here, so it is recorded as evidence and left for a future version.
	RequireLastPushApproval bool `json:"requireLastPushApproval"`
}

type SourceReviewContinuityEvidence struct {
	// Method is "ruleset-history" when continuity was proven by walking ruleset
	// version history, or "none" when it could not be established (the fail-closed
	// default). Any other meaning is reserved.
	Method string `json:"method"`
	// RulesetIDs are the distinct backing ruleset ids whose histories were walked.
	RulesetIDs []int64 `json:"rulesetIds,omitempty"`
	// VersionsWalked is the total number of historical ruleset versions inspected.
	VersionsWalked int `json:"versionsWalked"`
	// EarliestHistoryAt is the UpdatedAt of the oldest retained version observed
	// across the walked rulesets (RFC3339, UTC). Used to detect retention capping.
	EarliestHistoryAt string `json:"earliestHistoryAt,omitempty"`
	// WindowStartAt is the latest per-ruleset clean-run start across all legs
	// (RFC3339, UTC) — continuity holds only since ALL legs were simultaneously
	// enforced. Empty when continuity was not established.
	WindowStartAt string `json:"windowStartAt,omitempty"`
	// WeakenedAt is the UpdatedAt (RFC3339, UTC) of the version that broke
	// continuity (disabled/weakened/excluded/wide-bypass). Empty ("") on a clean
	// window.
	WeakenedAt string `json:"weakenedAt,omitempty"`
	// HistoryComplete is true only when every walked ruleset's history was read in
	// full (no 403/404, no pagination/truncation). False forces ContinuityComplete
	// false (unknown history is not "no changes").
	HistoryComplete bool `json:"historyComplete"`
	// RetentionCapped is true when the earliest retained version is NEWER than the
	// computed window start — the start cannot be corroborated by retained history,
	// so continuity fails closed.
	RetentionCapped bool `json:"retentionCapped"`
}

type SourceReviewOptions struct {
	Type             ArtifactType
	SubjectName      string
	SubjectPath      string
	Digest           string
	Owner            string
	Repo             string
	CommitSHA        string // the canonical source revision (merge/squash commit on the target branch)
	Ref              string // target branch ref of the artifact build
	PRNumber         int    // optional disambiguation hint; 0 = auto-discover from the commit
	IncludeApprovers bool   // default on; embeds the per-approver list
	ConfigURI        string
}

type SourceReviewPR struct {
	Number         int    `json:"number"`
	URL            string `json:"url,omitempty"`
	Author         string `json:"author,omitempty"`
	MergedAt       string `json:"mergedAt,omitempty"`
	MergeCommitSha string `json:"mergeCommitSha,omitempty"`
}

type SourceReviewSummary struct {
	Approvals            int  `json:"approvals"`
	DistinctApprovers    int  `json:"distinctApprovers"`
	ChangesRequested     int  `json:"changesRequested"`
	RequiredApprovals    int  `json:"requiredApprovals"`
	RequirementMet       bool `json:"requirementMet"`
	SelfApprovalExcluded bool `json:"selfApprovalExcluded"`
	// CodeownerReviewMet is tri-state: a nil pointer (JSON null) means "not
	// authoritatively determinable" — REST-only cannot reliably evaluate
	// CODEOWNERS, so the producer always leaves it null. The gate treats null as
	// undetermined and fails closed when codeowner review is required.
	CodeownerReviewMet *bool `json:"codeownerReviewMet"`
}

type SourceReviewTechnicalControls struct {
	ForcePushBlocked      bool     `json:"forcePushBlocked"`
	RequiredLinearHistory bool     `json:"requiredLinearHistory"`
	DeletionBlocked       bool     `json:"deletionBlocked"`
	RequiredSignatures    bool     `json:"requiredSignatures"`
	RequiredStatusChecks  []string `json:"requiredStatusChecks,omitempty"`
	// BypassActors is the factual list of ruleset bypass actors, formatted
	// "<ActorType>:<ActorID>:<BypassMode>" (e.g. "Integration:801323:always"),
	// de-duped and sorted. The verifier judges narrow-vs-open. Read alongside
	// BypassActorsComplete: an empty list is only meaningful when complete.
	BypassActors []string `json:"bypassActors,omitempty"`
	// BypassActorsComplete is true only when the bypass-actor list is
	// AUTHORITATIVE: rule discovery was not truncated AND every backing ruleset's
	// bypass actors were readable (Administration:read granted). When false, an
	// empty BypassActors means "unknown", NOT "none" — the verifier MUST fail
	// closed rather than read the absence as no-bypass.
	BypassActorsComplete bool `json:"bypassActorsComplete"`
	// ContinuityComplete is true ONLY when the ruleset version-history walk proved
	// the L3-relevant controls were never disabled/weakened from a start revision
	// through the attested revision (an unbroken enforcement window). It is the
	// continuity sibling of BypassActorsComplete: when false (the default, and the
	// outcome of any unreadable/ambiguous history), the verifier MUST treat
	// continuity as UNDETERMINED and keep the source level dormant — an empty or
	// even populated ContinuityStartRevision is meaningless without it.
	ContinuityComplete bool `json:"continuityComplete"`
}

type TestResult struct {
	Type        ArtifactType `json:"-"`
	SubjectName string       `json:"-"`
	SubjectPath string       `json:"-"`
	Digest      string       `json:"-"`

	// Result is one of PASSED, WARNED, or FAILED.
	Result string `json:"result"`
	// Configuration references the configuration used for the test run. Required
	// by the spec; may be an empty list when no configuration is referenced.
	Configuration []ResourceDescriptor `json:"configuration"`
	// URL optionally links to the test run (e.g. logs).
	URL string `json:"url,omitempty"`
	// PassedTests, WarnedTests, FailedTests hold test identifiers by outcome.
	// Skipped tests map to warnedTests. Never null (empty arrays preferred).
	PassedTests []string `json:"passedTests"`
	WarnedTests []string `json:"warnedTests"`
	FailedTests []string `json:"failedTests"`
}

type TestResultOptions struct {
	Type        ArtifactType
	SubjectName string
	SubjectPath string
	Digest      string
	ResultsPath string
	URL         string
	ConfigURI   string
}