report

type AttestationContent struct {
	// Framework is the lens (a framework_refs key), or "" for all.
	Framework string `json:"framework"`
	// HostsTotal is the active in-scope host count; HostsAttested is how
	// many of those have a completed scan to attest from.
	HostsTotal    int `json:"hosts_total"`
	HostsAttested int `json:"hosts_attested"`
	// Attested lists, per attested host, the scan the attestation is over.
	Attested []AttestedHost `json:"attested"`
	// Rollup is the headline compliance aggregate, FROZEN into the signed
	// snapshot at generation time (computed once from the frozen scans'
	// immutable scan_results, framework-lensed). Because it is part of the
	// content it is signed + tamper-evident, and the in-app view, the PDF
	// cover, and the signature all read the same numbers (P1: one snapshot,
	// identical across every face). It is bounded (aggregates + a small
	// top-N), never the per-(host, rule) rows.
	Rollup AttestationRollup `json:"rollup"`
}

type AttestationRollup struct {
	// LegacyCompliancePct is DECODE ONLY. It is the pooled whole-percent
	// number artifacts carried before 2026-09-03: passing over every rule
	// outcome in the attested set, so a host with 700 rules outvoted one with
	// 50, and a whole percent could never equal the one-decimal fleet score.
	//
	// No constructor sets it. It exists so a legacy artifact still decodes
	// and still renders the number it was signed with. omitempty is what
	// keeps it out of every artifact generated from now on.
	LegacyCompliancePct *int `json:"compliance_pct,omitempty"`

	// ScorePct is the equal-host mean of the attested hosts' scores, to one
	// decimal, null when no attested host produced a verdict.
	//
	// Null and 0.0 are different facts. Zero means every evaluated rule
	// failed; null means nothing was evaluated, and collapsing the second
	// into the first is bugs/OW-023 and OW-024.
	ScorePct *float64 `json:"score_pct"`
	// TotalChecks is every (host, rule) outcome counted; the rest are the
	// per-status splits.
	TotalChecks int `json:"total_checks"`
	Passing     int `json:"passing"`
	Failing     int `json:"failing"`
	Skipped     int `json:"skipped"`
	Errored     int `json:"errored"`
	// TopFailing lists the rules failing on the most hosts (capped).
	TopFailing []TopFailingRule `json:"top_failing"`

	// Provenance is the frozen envelope. Nil on a legacy artifact, which is
	// exactly how a legacy artifact is identified: a missing artifact_class
	// is the legacy shape and nothing backfills one.
	Provenance *ScoreProvenance `json:"provenance,omitempty"`
}

type AttestedHost struct {
	HostID    uuid.UUID `json:"host_id"`
	ScanID    uuid.UUID `json:"scan_id"`
	ScannedAt time.Time `json:"scanned_at"`
}

type CorpusEntry struct {
	// Version is null for a curated corpus, which has a digest and no version.
	Version            *string `json:"corpus_version"`
	Digest             string  `json:"corpus_digest"`
	ContributorsScored int     `json:"contributors_scored"`
}

type Coverage struct {
	HostsTotal       int `json:"hosts_total"`
	HostsFresh       int `json:"hosts_fresh"`
	HostsStale       int `json:"hosts_stale"`
	HostsUnreachable int `json:"hosts_unreachable"`
}

type EngineEntry struct {
	EngineVersion      string `json:"engine_version"`
	ContributorsScored int    `json:"contributors_scored"`
}

type ErrAmbiguousScore struct{ Kind string }

type ErrInvalidProvenance struct{ Reason string }

type ExceptionContent struct {
	Summary    ExceptionSummary `json:"summary"`
	Exceptions []ExceptionRow   `json:"exceptions"`

	// Provenance is the read-model envelope. It carries no score and no
	// contributor count, because this artifact aggregates no scan set.
	Provenance *ReadModelProvenance `json:"provenance,omitempty"`
}

type ExceptionRow struct {
	HostName    string     `json:"host_name"`
	RuleID      string     `json:"rule_id"`
	Status      string     `json:"status"`
	Reason      string     `json:"reason"`
	RequestedBy string     `json:"requested_by"`
	RequestedAt time.Time  `json:"requested_at"`
	ReviewedBy  string     `json:"reviewed_by"`
	ReviewedAt  *time.Time `json:"reviewed_at"`
	ExpiresAt   *time.Time `json:"expires_at"`
	Active      bool       `json:"active"`
}

type ExceptionSummary struct {
	Total        int `json:"total"`
	Active       int `json:"active"`
	Requested    int `json:"requested"`
	Approved     int `json:"approved"`
	Rejected     int `json:"rejected"`
	Revoked      int `json:"revoked"`
	Expired      int `json:"expired"`
	ExpiringSoon int `json:"expiring_soon"`
}

type ExecutiveContent struct {
	// LegacyCompliancePct is DECODE ONLY, the pooled whole-percent number
	// artifacts carried before 2026-09-03. See AttestationRollup for why it
	// is kept and why no constructor sets it.
	LegacyCompliancePct *int `json:"compliance_pct,omitempty"`

	// ScorePct is the equal-host mean of the in-scope hosts' scores, to one
	// decimal, null when no host produced a verdict.
	ScorePct *float64 `json:"score_pct"`
	// HostCount is the number of active (non-deleted) hosts.
	HostCount int `json:"host_count"`
	// PassingRules / FailingRules are host_rule_state rows by status.
	PassingRules int `json:"passing_rules"`
	FailingRules int `json:"failing_rules"`
	// CriticalIssues is the count of failing rows with critical severity.
	CriticalIssues int `json:"critical_issues"`
	// TopFailingRules lists the rules failing on the most hosts.
	TopFailingRules []TopFailingRule `json:"top_failing_rules"`
	// Coverage describes how much of the in-scope fleet the numbers
	// actually reflect (fresh vs stale/never-scanned, and unreachable).
	Coverage Coverage `json:"coverage"`

	// Provenance is the frozen envelope; nil on a legacy artifact.
	Provenance *ScoreProvenance `json:"provenance,omitempty"`
}

type FrameworkCount struct {
	Framework string `json:"framework"`
	RuleCount int    `json:"rule_count"`
}

type GenerateRequest struct {
	// Kind selects the report kind; "" defaults to executive. attestation
	// produces the Framework Attestation (CSV/OSCAL bulk faces).
	Kind Kind
	// GroupID scopes the report to one group's member hosts.
	GroupID *uuid.UUID
	// Framework scopes the report to one framework lens.
	Framework string
	// PeriodDays is the look-back window for time-windowed kinds
	// (remediation): the report covers requests in the last PeriodDays. 0
	// defaults to defaultPeriodDays; ignored by point-in-time kinds.
	PeriodDays int
}

type GroupScoper interface {
	ScopeGroup(ctx context.Context, groupID uuid.UUID) (name string, hostIDs []uuid.UUID, err error)

	// ScopeGroupIn resolves the same thing inside a caller-supplied
	// transaction, so a signed artifact's scope and its content come from one
	// snapshot. Resolving membership on the pool first let a host join or
	// leave in between, and nothing in the artifact would say so.
	ScopeGroupIn(ctx context.Context, q db.Queryer, groupID uuid.UUID) (name string, hostIDs []uuid.UUID, err error)
}

type Kind string

type ReadModelProvenance struct {
	ArtifactClass        string `json:"artifact_class"`
	CorpusIdentityStatus string `json:"corpus_identity_status"`

	// Kept as explicit nulls to honor decision 06's always-present rule.
	// Omitting them would narrow that decision and would need a superseding
	// record.
	CorpusVersion *string `json:"corpus_version"`
	CorpusDigest  *string `json:"corpus_digest"`
}

type RemediationActRow struct {
	HostName    string     `json:"host_name"`
	RuleID      string     `json:"rule_id"`
	Status      string     `json:"status"`
	Mechanism   string     `json:"mechanism"`
	RequestedBy string     `json:"requested_by"`
	RequestedAt time.Time  `json:"requested_at"`
	ReviewedBy  string     `json:"reviewed_by"`
	ReviewedAt  *time.Time `json:"reviewed_at"`
}

type RemediationContent struct {
	// PeriodFrom/PeriodTo bound the window (by requested_at). PeriodTo is
	// the generation instant; PeriodFrom is PeriodTo minus the period.
	PeriodFrom time.Time           `json:"period_from"`
	PeriodTo   time.Time           `json:"period_to"`
	Summary    RemediationSummary  `json:"summary"`
	Activities []RemediationActRow `json:"activities"`

	// Provenance is the read-model envelope; see ExceptionContent.
	Provenance *ReadModelProvenance `json:"provenance,omitempty"`
}

type RemediationSummary struct {
	Total      int `json:"total"`
	Executed   int `json:"executed"`
	RolledBack int `json:"rolled_back"`
	Failed     int `json:"failed"`
	Rejected   int `json:"rejected"`
	Pending    int `json:"pending"`
}

type RenderPayload struct {
	SnapshotID uuid.UUID `json:"snapshot_id"`
}

type RenderProcessor struct {
	// contains filtered or unexported fields
}

type Report struct {
	ID          uuid.UUID
	Title       string
	Kind        Kind
	ScopeLabel  string
	Scope       Scope
	DataAsOf    time.Time
	GeneratedBy string
	Format      string
	Content     json.RawMessage
	// ContentSHA256 is the snapshot's content address: the hex SHA-256 of
	// the canonical (marshaled) Content. Identical content yields an
	// identical hash; it is the stable identity the signature signs over.
	ContentSHA256 string
	// Signature is the Ed25519 signature over the content address (nil
	// when the snapshot was generated without a signer). SigningKeyID is
	// the fingerprint of the key that produced it.
	Signature    []byte
	SigningKeyID string
	CreatedAt    time.Time
}

type Scope struct {
	// GroupID, when set, scopes the report to that group's member hosts.
	GroupID *uuid.UUID `json:"group_id,omitempty"`
	// GroupName is the group's display name at generation time, frozen
	// onto the report so the label survives a later group rename/delete.
	GroupName string `json:"group_name,omitempty"`
	// Framework, when non-empty, scopes the report to rules whose
	// framework_refs contain this key (same lens as the fleet rollup).
	Framework string `json:"framework,omitempty"`
}

type ScoreProvenance struct {
	ArtifactClass string `json:"artifact_class"`

	FormulaVersion    *int    `json:"formula_version"`
	AggregationMethod *string `json:"aggregation_method"`
	Lens              *string `json:"lens"`

	EngineIdentityStatus       string        `json:"engine_identity_status"`
	Engines                    []EngineEntry `json:"engines"`
	HostsWithoutEngineIdentity *int          `json:"hosts_without_engine_identity"`
	EngineVersion              *string       `json:"engine_version"`

	CorpusIdentityStatus       string        `json:"corpus_identity_status"`
	Corpora                    []CorpusEntry `json:"corpora"`
	HostsWithoutCorpusIdentity *int          `json:"hosts_without_corpus_identity"`
	CorpusVersion              *string       `json:"corpus_version"`
	CorpusDigest               *string       `json:"corpus_digest"`

	// Participation counts. A mean over 2 of 200 hosts and a mean over 200 of
	// 200 are different claims that a percentage alone cannot tell apart, and
	// on a signed artifact the reader cannot go and look.
	HostsTotal        int `json:"hosts_total"`
	HostsScored       int `json:"hosts_scored"`
	HostsWithoutScore int `json:"hosts_without_score"`
}

type Service struct {
	// contains filtered or unexported fields
}

type Signer struct {
	// contains filtered or unexported fields
}

type TopFailingRule struct {
	RuleID           string `json:"rule_id"`
	FailingHostCount int    `json:"failing_host_count"`
}