gatefailure.go

// Package ir holds the canonical GateFailure IR lifted from cyberready_cli_mvp_v3_29.
// Do not redesign these JSON field names — agents and Coreward bridge expect them.
package ir

// ConcurrencyControl carries OCC (optimistic concurrency) fields for Git Notes chaining.
type ConcurrencyControl struct {
	ExpectedParentCommitSHA string `json:"expected_parent_commit_sha"`
	StateVersionToken       string `json:"state_version_token"`
}

// StatechartContext describes where in the compliance state machine the failure occurred.
type StatechartContext struct {
	ActiveParentStatePath   []string `json:"active_parent_state_path"`
	FailedOrthogonalRegions []string `json:"failed_orthogonal_regions"`
}

// AgentIdentity identifies the agent/mandate that triggered validation (optional).
// Source is self-declared (env) or bridge (Coreward sock present). Reason is the
// fail-open sock probe (not_installed / unavailable) and is never a gate.
// Not part of attest state_hash / ComputeStateHash field order.
type AgentIdentity struct {
	AgentID         string `json:"agent_id"`
	ModelHash       string `json:"model_hash"`
	ActiveMandateID string `json:"active_mandate_id"`
	Source          string `json:"source,omitempty"`
	Reason          string `json:"reason,omitempty"`
}

// ASTCoordinates pin a failure to a file/symbol when available.
type ASTCoordinates struct {
	TargetFile    string `json:"target_file"`
	NodePath      string `json:"node_path"`
	TargetSymbol  string `json:"target_symbol"`
	FallbackLines string `json:"fallback_lines"`
}

// Remediation tells an agent or human how to reach the expected state.
type Remediation struct {
	ActionRequired string `json:"action_required"`
	ExpectedState  string `json:"expected_state"`
}

// Failure is a single gate violation.
type Failure struct {
	GateID               string         `json:"gate_id"`
	Severity             string         `json:"severity"`
	Type                 string         `json:"type"`
	SanitizedDescription string         `json:"sanitized_description"`
	ASTCoordinates       ASTCoordinates `json:"ast_coordinates"`
	Remediation          Remediation    `json:"remediation"`
}

// SchemaVersion is the GateFailure JSON IR version for agents (stable contract).
const SchemaVersion = "1"

// Machine outcome values (MUST-52). Consumers must not infer outcome from score.
const (
	OutcomePass       = "pass"
	OutcomeFindings   = "findings"
	OutcomeIncomplete = "incomplete"
	OutcomeError      = "error"
)

// GateFailurePayload is the dual-rep IR: JSON for machines, Markdown for agents.
type GateFailurePayload struct {
	EvaluationDigest   string             `json:"evaluation_digest,omitempty"`
	ComparisonKey      string             `json:"comparison_key,omitempty"`
	AsOf               string             `json:"as_of,omitempty"`
	SchemaVersion      string             `json:"schema_version"`
	Timestamp          string             `json:"timestamp"`
	ConcurrencyControl ConcurrencyControl `json:"concurrency_control"`
	StatechartContext  StatechartContext  `json:"statechart_context"`
	AgentIdentity      AgentIdentity      `json:"agent_identity"`
	Failures           []Failure          `json:"failures"`
	PackID             string             `json:"pack_id,omitempty"`
	ReadinessScore     int                `json:"readiness_score,omitempty"`
	// Outcome is pass | findings | incomplete | error (MUST-52). Present when set.
	Outcome string `json:"outcome,omitempty"`
	// SkippedRules counts rules not evaluated (e.g. --diff). Non-zero ⇒ incomplete (MUST-23).
	SkippedRules int `json:"skipped_rules,omitempty"`
	// FailedRules / EvaluatedRules are public tallies (not a percent grade). Additive.
	FailedRules    int `json:"failed_rules,omitempty"`
	EvaluatedRules int `json:"evaluated_rules,omitempty"`
	// ConformityClaim is always "none" on tip emissions (historical digests omit it).
	ConformityClaim string `json:"conformity_claim,omitempty"`
}

// PackageManifest is used for deterministic package.json dependency parsing.
type PackageManifest struct {
	Dependencies    map[string]string `json:"dependencies"`
	DevDependencies map[string]string `json:"devDependencies"`
}

// UniqueFailedGates counts failed gate identities, independently of finding rows.
func UniqueFailedGates(failures []Failure) int {
	ids := make(map[string]struct{}, len(failures))
	for _, f := range failures {
		ids[f.GateID] = struct{}{}
	}
	return len(ids)
}