core

type AggregatedPolicy struct {
	PolicyID           string       `json:"policy_id"`
	Controls           []ControlRef `json:"controls"`
	Status             PolicyStatus `json:"status"`
	Severity           Severity     `json:"severity"`
	Category           string       `json:"category,omitempty"`
	ResourcesEvaluated int          `json:"resources_evaluated"`
	ResourcesFailed    int          `json:"resources_failed"`
	Message            string       `json:"message"`
	RuleVersion        string       `json:"rule_version,omitempty"`

	// ConfiguredCadence is the cadence string in effect at this run
	// (e.g., "daily", "every:6h"). Non-identifying.
	ConfiguredCadence string `json:"configured_cadence,omitempty"`

	// LastEvaluatedAt is the start time of the most recent run that
	// actually evaluated this policy. For freshly-evaluated rows it
	// equals StartedAt; for carry-forward rows it points to the
	// earlier run. Non-identifying. Pointer so a zero value is omitted
	// from the wire rather than serialized as "0001-01-01T00:00:00Z"
	// (encoding/json's omitempty does not omit a zero time.Time struct).
	LastEvaluatedAt *time.Time `json:"last_evaluated_at,omitempty"`

	// NextDueAt is the wall-clock time after which the policy is due
	// to be re-evaluated. Nil when the policy is always due (cadence
	// "continuous" / "every:0s") or when the most recent terminal
	// status was not pass (on_fail_retry → due on next run). Pointer
	// for the same omit-zero reason as LastEvaluatedAt.
	NextDueAt *time.Time `json:"next_due_at,omitempty"`

	// IsCarriedForward is true when this row references a prior
	// evaluation rather than a fresh one in this run.
	IsCarriedForward bool `json:"is_carried_forward,omitempty"`

	// PolicyContentHash is the SHA-256 hash of the policy spec +
	// referenced evidence-type schemas at this run. The cloud uses
	// it to detect a bundle bump that may invalidate prior
	// evaluations.
	PolicyContentHash string `json:"policy_content_hash,omitempty"`
}

type AppliedException struct {
	PolicyID        string `json:"policy_id"`
	State           string `json:"state"`
	Reason          string `json:"reason,omitempty"`
	ApprovedBy      string `json:"approved_by,omitempty"`
	ApprovedAt      string `json:"approved_at,omitempty"`
	ExpiresAt       string `json:"expires_at,omitempty"`
	ResourceID      string `json:"resource_id,omitempty"`
	ResourcePattern string `json:"resource_pattern,omitempty"`
}

type CIEnvironment struct {
	Provider    string `json:"provider"`
	Workflow    string `json:"workflow,omitempty"`
	RunURL      string `json:"run_url,omitempty"`
	WorkerImage string `json:"worker_image,omitempty"`
}

type CarryForwardRef struct {
	LastEvaluatedAt  time.Time
	LastEvaluatedRun string
	LastEnvelopeRef  string
	LastKnownStatus  PolicyStatus
	SkipReason       string
}

type CloudClient interface {
	Submit(ctx context.Context, payload SubmissionPayload) error
}

type Control struct {
	ID               string
	Name             string
	Description      string
	Category         string
	BaselineSeverity Severity
}

type ControlRef struct {
	Framework        string              `json:"framework,omitempty"`
	FrameworkVersion string              `json:"framework_version,omitempty"`
	ControlID        string              `json:"control_id"`
	Relationship     ControlRelationship `json:"relationship,omitempty"`
}

type ControlRelationship string

type Envelope struct {
	FormatVersion string            `json:"format_version"`
	ProducedAt    time.Time         `json:"produced_at"`
	Records       []EvidenceRecord  `json:"records"`
	Signature     EnvelopeSignature `json:"signature"`
}

type EnvelopeSignature struct {
	Algorithm string `json:"algorithm"`
	PublicKey []byte `json:"public_key"`
	Value     []byte `json:"value"`
}

type EvidenceMode string

type EvidenceRecord struct {
	Type        string          `json:"type"`
	ID          string          `json:"id"`
	IdentityKey string          `json:"identity_key,omitempty"`
	Payload     json.RawMessage `json:"payload"`
	SourceID    string          `json:"source_id"`
	CollectedAt time.Time       `json:"collected_at"`
	// Scope records which account/region/project this observation was
	// collected from. Sovereignty buyers are multi-account/multi-region
	// by regulatory necessity (data residency), so scope is a
	// first-class dimension of evidence identity — two records with the
	// same ID but different Scope are distinct observations. Optional
	// and pointer-typed so records that don't set it serialize
	// byte-identically to pre-scope envelopes (no signature churn);
	// source plugins populate it incrementally as they gain
	// scope-awareness. Scope stays vault-side — it never crosses the
	// aggregation boundary into the Cloud SubmissionPayload.
	Scope *RecordScope `json:"scope,omitempty"`
}

type EvidenceType struct {
	ID      string          `json:"id"`
	Version int             `json:"version"`
	Schema  json.RawMessage `json:"schema"`
}

type Framework interface {
	ID() string
	Version() string
	Controls() []Control
	Policies() []PolicyRef
}

type FrameworkRunSummary struct {
	SchemaVersion string         `json:"schema_version"`
	RunID         string         `json:"run_id"`
	Framework     string         `json:"framework"`
	PeriodID      string         `json:"period_id"`
	CompletedAt   time.Time      `json:"completed_at"`
	Policies      []PolicyResult `json:"policies"`
}

type Manifest struct {
	SchemaVersion     string             `json:"schema_version"`
	RunID             string             `json:"run_id"`
	Framework         string             `json:"framework,omitempty"`
	PeriodID          string             `json:"period_id,omitempty"`
	StartedAt         time.Time          `json:"started_at"`
	CompletedAt       time.Time          `json:"completed_at"`
	FileHashes        map[string]string  `json:"file_hashes"`
	ExceptionsApplied []AppliedException `json:"exceptions_applied,omitempty"`
	Signature         ManifestSignature  `json:"signature"`
}

type ManifestSignature struct {
	Algorithm string `json:"algorithm"`
	PublicKey []byte `json:"public_key"`
	Value     []byte `json:"value"`
}

type ParameterSpec struct {
	Type        string
	Default     any
	Min         any
	Max         any
	Enum        []any
	Pattern     string
	Description string
}

type PassWhenClause struct {
	// Slot names the slot whose records are evaluated.
	Slot string
	// Quantifier determines the aggregation semantics.
	Quantifier PassWhenQuantifier
	// Condition is the per-record test applied to records that pass the Filter.
	Condition *PassWhenCondition
	// Filter is an optional pre-condition. Records not satisfying the Filter
	// are excluded from the quantifier evaluation entirely (neither pass nor
	// fail). Nil means all records are evaluated.
	Filter *PassWhenCondition
	// ViolationMsg is a template for per-record violation messages.
	// Supports {{.field.path}} substitution against the record context.
	ViolationMsg string
	// IdentityKey is an optional field path used to deduplicate violations.
	// When set, only the first violation per unique value of this field is
	// emitted. Defaults to "id".
	IdentityKey string
	// MinPercentage is the minimum percentage (0–100) of records that must
	// satisfy the Condition. Only meaningful when Quantifier == QuantifierCount.
	MinPercentage *float64
}

type PassWhenCondition struct {
	// Op is the comparison operator: eq, neq, lt, lte, gt, gte, in,
	// not_in, is_set, all_of, any_of.
	Op string
	// Field is the dot-path to the field to compare, e.g. "payload.mfa_enabled"
	// or "id". Ignored for all_of / any_of. Field is always a record path;
	// "$params.<name>" is resolved only on the Value (RHS) side, not here —
	// a "$params.*" Field would be looked up as a record path and fail.
	Field string
	// Value is the RHS of the comparison for leaf operators. May be a scalar
	// (bool, int, float64, string) or a []interface{} for in / not_in.
	// A string value of the form "$params.<name>" is resolved to the parameter
	// value at evaluation time.
	Value any
	// Conditions is the sub-condition list for all_of / any_of operators.
	Conditions []*PassWhenCondition
}

type PassWhenQuantifier string

type PassWhenSpec struct {
	Clauses []PassWhenClause
}

type PeriodAggregate struct {
	EvaluationsInPeriod          int           `json:"evaluations_in_period"`
	PassCount                    int           `json:"pass_count"`
	FailCount                    int           `json:"fail_count"`
	LongestFailureStreak         time.Duration `json:"longest_failure_streak,omitempty"`
	FirstEvaluationAt            time.Time     `json:"first_evaluation_at,omitempty"`
	LastEvaluationAt             time.Time     `json:"last_evaluation_at,omitempty"`
	LongestGapBetweenEvaluations time.Duration `json:"longest_gap_between_evaluations,omitempty"`
}

type Policy struct {
	ID          string
	Controls    []ControlRef
	Description string
	Remediation string
	Severity    Severity
	Category    string
	Cadence     string
	OnPush      bool
	Slots       map[string]Slot
	Parameters  map[string]ParameterSpec
	RuleRef     string
	Tags        []string

	// EvidenceMode is the explicit first-class field that determines the
	// evaluator path: automated (Path B/C) or manual (Path A). Required.
	EvidenceMode EvidenceMode
	// PassWhen is the declarative condition DSL for automated policies.
	// Non-nil when evidence_mode: automated and no rule: escape-hatch.
	// Exactly one of PassWhen / RuleRef must be set for automated policies.
	PassWhen *PassWhenSpec
	// CatalogEntry is the evidence_catalog_id for manual policies. It
	// identifies which entry in the manual evidence catalog resolves to the
	// expected PDF path. Required when EvidenceMode == EvidenceModeManual.
	CatalogEntry string
}

type PolicyRef struct {
	PolicyID string
}

type PolicyResult struct {
	PolicyID           string
	Controls           []ControlRef
	Status             PolicyStatus
	Severity           Severity
	Category           string
	EffectiveParams    map[string]any
	Violations         []Violation
	ResourcesEvaluated int
	ResourcesFailed    int
	EvidenceEnvelopes  []string
	RuleVersion        string
	Diag               map[string]any

	// ConfiguredCadence is the cadence string in effect at this run
	// (e.g., "daily" or "every:6h"). Captured on every result so the
	// framework summary and the audit ledger can show the cadence
	// without recomputing it. Same value as in PolicyState.
	ConfiguredCadence string

	// PolicyContentHash is the SHA-256 of the canonicalized policy
	// spec plus referenced evidence-type schemas at this run.
	// Auditors comparing two runs can detect a policy/schema update
	// by comparing this field.
	PolicyContentHash string

	// NextDueAt is the wall-clock time after which the policy is due
	// to be re-evaluated under its configured cadence. Zero for
	// "continuous" / "every:0s" cadences (always due) and for
	// policies whose most recent terminal status was not pass (in
	// which case the on_fail_retry rule applies on the next run).
	NextDueAt time.Time

	// CarryForward is non-nil iff Status is StatusCarriedForward. It
	// references the prior evaluation that this run inherits from.
	// The reference is hash-tied to the original signed envelope so
	// an auditor can verify it offline without trusting the CLI.
	CarryForward *CarryForwardRef

	// PeriodAggregate, when non-nil, summarizes every evaluation of
	// this policy across the current audit period. Populated by
	// `sigcomply audit-ledger`, not by the single-run path — a
	// single run cannot know its period history without scanning
	// the vault. See PeriodAggregate's doc for the rationale.
	PeriodAggregate *PeriodAggregate
}

type PolicyState struct {
	SchemaVersion string `json:"schema_version"`

	PolicyID  string `json:"policy_id"`
	Framework string `json:"framework"`

	// LastRunAt is the run-start timestamp of the most recent run that
	// evaluated this policy (pass, fail, error, or skipped-with-fresh-
	// data). Carried-forward runs do NOT update LastRunAt — by
	// definition they did not evaluate.
	LastRunAt time.Time `json:"last_run_at"`

	// LastPassAt is the run-start timestamp of the most recent run that
	// evaluated this policy and produced StatusPass. Cadence gating
	// uses this field, not LastRunAt — so a failed policy is "due"
	// again on the next run regardless of nominal cadence (the
	// on_fail_retry rule).
	LastPassAt time.Time `json:"last_pass_at,omitempty"`

	// LastFailAt is the run-start timestamp of the most recent run that
	// evaluated this policy and produced StatusFail.
	LastFailAt time.Time `json:"last_fail_at,omitempty"`

	// LastRunStatus is the terminal status of the most recent
	// evaluation. One of: pass, fail, error, skip, na, waived. Empty
	// when this is a freshly-allocated state with no run history.
	LastRunStatus PolicyStatus `json:"last_run_status,omitempty"`

	// LastPeriodID is the period_id that the most recent evaluation
	// belongs to. Carry-forward results reference this period via the
	// envelope under LastEnvelopeRef.
	LastPeriodID string `json:"last_period_id,omitempty"`

	// LastRunID is the run_id of the most recent evaluation. The
	// concurrent-write rule uses it as a tiebreaker when two runs
	// share LastRunAt to the second.
	LastRunID string `json:"last_run_id,omitempty"`

	// LastPolicyHash is the SHA-256 of the canonicalized policy spec
	// at the time of the most recent evaluation. A bundle update that
	// changes the policy text invalidates this hash, marking the
	// policy due on the next run regardless of cadence. The actual
	// hash for the current run is computed at plan time via
	// PolicyContentHash.
	LastPolicyHash string `json:"last_policy_hash,omitempty"`

	// LastEnvelopeRef is the run-relative path of the signed evidence
	// envelope produced by the most recent evaluation. Carry-forward
	// results emit a reference to this path so an auditor can
	// hash-verify the original envelope independently.
	LastEnvelopeRef string `json:"last_envelope_ref,omitempty"`

	// NextDueAt is the wall-clock time after which the policy is
	// considered due again under its configured cadence. Pre-computed
	// at end of each run so the next planner pass is a single field
	// read per policy. For "continuous" / "every: 0s" cadences this
	// is the zero time (always due).
	NextDueAt time.Time `json:"next_due_at,omitempty"`

	// ConfiguredCadence is the cadence string in effect at the most
	// recent evaluation ("daily", "every: 6h", etc.). Captured so a
	// subsequent run can detect a configuration change and re-
	// evaluate even when the time-since-last-pass would suggest
	// otherwise. Currently informational; the planner gates on
	// LastPolicyHash for content changes.
	ConfiguredCadence string `json:"configured_cadence,omitempty"`
}

type PolicyStatus string

type RecordScope struct {
	Account string `json:"account,omitempty"`
	Region  string `json:"region,omitempty"`
	Project string `json:"project,omitempty"`
}

type Repository struct {
	Provider string `json:"provider"`
	NameSlug string `json:"name_slug"`
	URL      string `json:"url,omitempty"`
}

type Rule interface {
	ID() string
	Evaluate(ctx context.Context, in RuleInput) (RuleResult, error)
}

type RuleInput struct {
	PolicyID string
	Slots    map[string][]EvidenceRecord
	Params   map[string]any
	Now      time.Time
}

type RuleResult struct {
	Status     PolicyStatus
	Violations []Violation
	Diag       map[string]any
}

type RunSummary struct {
	PoliciesTotal          int     `json:"policies_total"`
	PoliciesPassed         int     `json:"policies_passed"`
	PoliciesFailed         int     `json:"policies_failed"`
	PoliciesSkipped        int     `json:"policies_skipped"`
	PoliciesError          int     `json:"policies_error"`
	PoliciesNA             int     `json:"policies_na"`
	PoliciesWaived         int     `json:"policies_waived"`
	PoliciesCarriedForward int     `json:"policies_carried_forward"`
	ComplianceScore        float64 `json:"compliance_score"`
}

type Severity string

type Slot struct {
	Accepts     []string
	Cardinality SlotCardinality
	Required    bool
	Description string
}

type SlotCardinality string

type SlotRequest struct {
	PolicyID      string
	AcceptedTypes []string
	SlotName      string
	Params        map[string]any
}

type SourcePlugin interface {
	ID() string
	Emits() []string
	Init(ctx context.Context, cfg map[string]any) error
	Collect(ctx context.Context, req SlotRequest) ([]EvidenceRecord, error)
}

type SubmissionPayload struct {
	Schema string `json:"schema"`

	RunID     string `json:"run_id"`
	Framework string `json:"framework"`
	PeriodID  string `json:"period_id"`

	CommitSHA  string    `json:"commit_sha"`
	CommitTime time.Time `json:"commit_time"`
	Branch     string    `json:"branch"`

	Repository  Repository    `json:"repository"`
	Environment CIEnvironment `json:"environment"`

	CLIVersion  string    `json:"cli_version"`
	StartedAt   time.Time `json:"started_at"`
	CompletedAt time.Time `json:"completed_at"`

	Summary  RunSummary         `json:"summary"`
	Policies []AggregatedPolicy `json:"policies"`
}

type Vault interface {
	Init(ctx context.Context) error
	PutEnvelope(ctx context.Context, path string, e *Envelope) error
	PutJSON(ctx context.Context, path string, body any) error
	PutBinary(ctx context.Context, path string, body []byte, meta map[string]string) error
	GetBinary(ctx context.Context, path string) ([]byte, error)
	List(ctx context.Context, prefix string) ([]string, error)
}

type Violation struct {
	ResourceID string
	Reason     string
	Details    map[string]any
}