surface

type CategoricalConsequence struct {
	// Level is the categorical value (e.g., "high", "critical", "organization").
	// Must be a member of ConsequenceType.RatingScale or ScopeScale.
	Level string `json:"level"`

	// Ordinal is the zero-based position in the scale (optional, for ordering).
	// Example: ["low", "medium", "high"] → "medium" has Ordinal = 1
	// Validators can populate this automatically from the scale.
	Ordinal *int `json:"ordinal,omitempty"`
}

type Consequence struct {
	// TypeID references a ConsequenceType.ID in the surface definition.
	// Determines which Value variant is valid.
	TypeID string `json:"type_id"`

	// Value holds the consequence magnitude in a type-appropriate format.
	// The structure depends on the ConsequenceType.MeasureType:
	//   - Financial: NumericValue (monetary amount)
	//   - Temporal: NumericValue (duration in specified units)
	//   - RiskRating: CategoricalValue (rating level)
	//   - ImpactScope: CategoricalValue (scope level)
	//   - Custom: NumericValue or CategoricalValue (domain-specific)
	Value ConsequenceValue `json:"value"`
}

type ConsequenceType struct {
	ID          string      `json:"id"`
	Name        string      `json:"name"`
	Description string      `json:"description"`
	MeasureType MeasureType `json:"measure_type"`

	// Financial consequences
	Currency string `json:"currency,omitempty"` // ISO 4217 code (USD, EUR, GBP, etc.)

	// Temporal consequences (stored as hours for JSON-friendliness)
	DurationUnit DurationUnit `json:"duration_unit,omitempty"` // hours, days, months, years

	// Risk rating consequences
	RatingScale []string `json:"rating_scale,omitempty"` // e.g., [low, medium, high, critical]

	// Impact scope consequences
	ScopeScale []string `json:"scope_scale,omitempty"` // e.g., [individual, team, organization, public]

	// Validation bounds
	MinValue *float64 `json:"min_value,omitempty"`
	MaxValue *float64 `json:"max_value,omitempty"`
}

type ConsequenceValue struct {
	// Numeric holds quantitative consequences (financial, temporal).
	// Must be non-nil for MeasureTypeFinancial and MeasureTypeTemporal.
	Numeric *NumericConsequence `json:"numeric,omitempty"`

	// Categorical holds qualitative consequences (risk rating, impact scope).
	// Must be non-nil for MeasureTypeRiskRating and MeasureTypeImpactScope.
	Categorical *CategoricalConsequence `json:"categorical,omitempty"`
}

type ContextField struct {
	Name        string          `json:"name"`
	Type        FieldType       `json:"type"`
	Required    bool            `json:"required"`
	Description string          `json:"description"`
	Validation  *ValidationRule `json:"validation,omitempty"`

	// Example demonstrates a valid value for this field.
	// Validators MUST verify Example conforms to Type and Validation.
	// Invalid examples MUST be rejected to prevent documentation decay.
	Example any `json:"example,omitempty"`
}

type ContextSchema struct {
	Fields []ContextField `json:"fields"`
}

type DecisionSurface struct {

	// ID is the logical surface identifier, stable across versions.
	// Format: kebab-case, e.g. "lending-secured-origination"
	ID string `json:"id"`

	// Version is the numeric version of this surface definition.
	// Versions are immutable once active. Composite key: (ID, Version)
	Version int `json:"version"`

	// RequiredContext defines the structured context schema for decisions.
	// Orchestrator validates request context against this schema.
	// IMMUTABLE after activation.
	RequiredContext ContextSchema `json:"required_context"`

	// ConsequenceTypes declares what kinds of impact decisions on this surface produce.
	// Authority profiles set thresholds within these types.
	// IMMUTABLE after activation.
	ConsequenceTypes []ConsequenceType `json:"consequence_types"`

	// MinimumConfidence is a surface-level confidence floor.
	// MUST be in range [0.0, 1.0]. Authority profiles cannot set confidence
	// thresholds below this value.
	// IMMUTABLE after activation.
	MinimumConfidence float64 `json:"minimum_confidence"`

	// PolicyPackage is the Rego package path or policy bundle identifier.
	// If empty, no policy evaluation is performed for this surface.
	// IMMUTABLE after activation.
	PolicyPackage string `json:"policy_package,omitempty"`

	// PolicyVersion pins the policy bundle version for this surface version.
	// IMMUTABLE after activation.
	PolicyVersion string `json:"policy_version,omitempty"`

	// FailureMode controls behavior when policy evaluation fails.
	// MUTABLE: operational policy can change.
	FailureMode FailureMode `json:"failure_mode"`

	// Name is the human-readable surface name.
	// MUTABLE: clarifications and typo fixes allowed.
	Name string `json:"name"`

	// Description explains what decisions this surface governs.
	// MUTABLE: documentation improvements allowed.
	Description string `json:"description"`

	// Domain is the high-level business area (financial_services, healthcare, etc.)
	// IMMUTABLE after activation.
	Domain string `json:"domain"`

	// Category is the functional area within the domain (lending, payments, prescriptions)
	// IMMUTABLE after activation.
	Category string `json:"category,omitempty"`

	// Taxonomy is a hierarchical path for discovery and grouping.
	// Example: ["financial", "lending", "secured", "origination"]
	// IMMUTABLE after activation.
	Taxonomy []string `json:"taxonomy,omitempty"`

	// Tags are free-form labels for ad-hoc categorization.
	// MUTABLE: tags can be added/removed post-activation.
	Tags []string `json:"tags,omitempty"`

	// DecisionType classifies the strategic level (strategic/tactical/operational)
	// IMMUTABLE after activation.
	DecisionType DecisionType `json:"decision_type"`

	// ReversibilityClass captures undo-ability (reversible/conditionally_reversible/irreversible)
	// IMMUTABLE after activation.
	ReversibilityClass ReversibilityClass `json:"reversibility_class"`

	// MandatoryEvidence lists documentation requirements for decisions.
	// IMMUTABLE after activation.
	MandatoryEvidence []EvidenceRequirement `json:"mandatory_evidence,omitempty"`

	// AuditRetentionHours specifies how long governance envelopes must be retained.
	// Stored as integer hours for JSON-friendliness (8760 = 1 year, 87600 = 10 years).
	//
	// VALIDATION:
	//   - Zero (0) means use system default retention
	//   - Positive values must be >= 24 (minimum 1 day)
	//   - Negative values are INVALID
	//
	// MUTABLE: compliance requirements can change.
	AuditRetentionHours int `json:"audit_retention_hours,omitempty"`

	// SubjectRequired mandates that every decision must identify a subject.
	// Enables subject-based audit trails and compliance reporting.
	// IMMUTABLE after activation.
	SubjectRequired bool `json:"subject_required"`

	// ComplianceFrameworks lists applicable regulatory/compliance requirements.
	// Examples: ["SOX", "GDPR", "HIPAA", "PCI-DSS"]
	// MUTABLE: frameworks can be added as requirements evolve.
	ComplianceFrameworks []string `json:"compliance_frameworks,omitempty"`

	// Status is the current lifecycle state (draft/review/active/deprecated/retired)
	// MUTABLE: surfaces progress through lifecycle.
	Status SurfaceStatus `json:"status"`

	// EffectiveFrom is when this surface version becomes available for use.
	// IMMUTABLE after activation.
	EffectiveFrom time.Time `json:"effective_from"`

	// EffectiveUntil is when this version is retired (nil means no expiration).
	// MUTABLE: can be set to schedule deprecation/retirement.
	EffectiveUntil *time.Time `json:"effective_until,omitempty"`

	// DeprecationReason explains why this surface was deprecated (if applicable).
	// MUTABLE: set when deprecating.
	DeprecationReason string `json:"deprecation_reason,omitempty"`

	// SuccessorSurfaceID points to the replacement surface (if deprecated/retired).
	// MUTABLE: set when deprecating to guide migration.
	SuccessorSurfaceID string `json:"successor_surface_id,omitempty"`

	// SuccessorVersion points to the replacement surface version.
	// MUTABLE: set when deprecating to guide migration.
	SuccessorVersion int `json:"successor_version,omitempty"`

	// BusinessOwner is accountable for governance decisions on this surface.
	// MUTABLE: ownership can transfer.
	BusinessOwner string `json:"business_owner"`

	// TechnicalOwner maintains the surface definition and integration.
	// MUTABLE: ownership can transfer.
	TechnicalOwner string `json:"technical_owner"`

	// Stakeholders are additional parties interested in this surface.
	// MUTABLE: stakeholders can change.
	Stakeholders []string `json:"stakeholders,omitempty"`

	// DocumentationURL links to detailed surface documentation.
	// MUTABLE: documentation can be updated.
	DocumentationURL string `json:"documentation_url,omitempty"`

	// ExternalReferences links to related systems, policies, or frameworks.
	// Example: {"jira": "GOVERN-1234", "confluence": "https://..."}
	// MUTABLE: references can be updated.
	ExternalReferences map[string]string `json:"external_references,omitempty"`

	// CreatedAt is when this surface version was created.
	// IMMUTABLE: set once on creation.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when this surface version was last modified.
	// MUTABLE: automatically updated on every Update call.
	UpdatedAt time.Time `json:"updated_at"`

	// CreatedBy identifies who created this surface version.
	// IMMUTABLE: set once on creation.
	CreatedBy string `json:"created_by,omitempty"`

	// ApprovedBy identifies who approved this surface for activation.
	// MUTABLE: set when transitioning to Status == Active.
	ApprovedBy string `json:"approved_by,omitempty"`

	// ApprovedAt is when this surface was approved for activation.
	// MUTABLE: set when transitioning to Status == Active.
	ApprovedAt *time.Time `json:"approved_at,omitempty"`
}

type DecisionType string

type DefaultSurfaceValidator struct{}

type DurationUnit string

type EvidenceRequirement struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"` // mandatory vs recommended
	Format      string `json:"format"`   // structured_data, document_reference, attestation
}

type FailureMode string

type FieldType string

type MeasureType string

type NumericConsequence struct {
	// Amount is the numeric magnitude.
	Amount float64 `json:"amount"`

	// Unit overrides the default unit from ConsequenceType (optional).
	// Example: ConsequenceType specifies "USD" but this consequence is "EUR"
	Unit string `json:"unit,omitempty"`
}

type ReversibilityClass string

type SearchCriteria struct {
	Domain   string          `json:"domain,omitempty"`
	Category string          `json:"category,omitempty"`
	Tags     []string        `json:"tags,omitempty"`     // ANY match
	Taxonomy []string        `json:"taxonomy,omitempty"` // Prefix match
	Status   []SurfaceStatus `json:"status,omitempty"`   // ANY match (OR)
}

type SurfaceRepository interface {
	// Create persists a new surface version. Returns error if (ID, Version) exists.
	Create(ctx context.Context, s *DecisionSurface) error

	// Update modifies mutable fields on an existing surface version.
	// See FIELD MUTABILITY contract in DecisionSurface struct documentation.
	//
	// Implementations MUST:
	//   - Reject updates to IMMUTABLE fields after Status == Active
	//   - Automatically set UpdatedAt to current timestamp
	//   - Preserve CreatedAt, CreatedBy (never change)
	//
	// Returns error if attempting to mutate immutable fields.
	Update(ctx context.Context, s *DecisionSurface) error

	// FindLatestByID returns the latest version (highest version number) for
	// the logical surface ID, regardless of status.
	FindLatestByID(ctx context.Context, id string) (*DecisionSurface, error)

	// FindByIDVersion returns a specific surface version.
	FindByIDVersion(ctx context.Context, id string, version int) (*DecisionSurface, error)

	// FindActiveAt resolves the active surface version at a given timestamp.
	// Returns the active version where EffectiveFrom <= at < EffectiveUntil.
	// Returns error if multiple active versions exist (invariant violation).
	FindActiveAt(ctx context.Context, id string, at time.Time) (*DecisionSurface, error)

	// ListVersions returns all versions of a surface, ordered by version descending.
	ListVersions(ctx context.Context, id string) ([]*DecisionSurface, error)

	// ListAll returns the latest version of each logical surface, regardless of status.
	// "Latest" is determined by MAX(version) grouped by ID.
	// Implementations MUST ensure consistent version ordering.
	ListAll(ctx context.Context) ([]*DecisionSurface, error)

	// ListByStatus returns surfaces (latest version only) with the given status.
	// "Latest" is determined by MAX(version) grouped by ID.
	// Implementations MUST ensure consistent version ordering.
	ListByStatus(ctx context.Context, status SurfaceStatus) ([]*DecisionSurface, error)

	// ListByDomain returns surfaces (latest version only) in the given domain.
	// "Latest" is determined by MAX(version) grouped by ID.
	// Implementations MUST ensure consistent version ordering.
	ListByDomain(ctx context.Context, domain string) ([]*DecisionSurface, error)

	// Search finds surfaces (latest version only) matching criteria.
	// "Latest" is determined by MAX(version) grouped by ID.
	// Implementations MUST ensure consistent version ordering.
	Search(ctx context.Context, criteria SearchCriteria) ([]*DecisionSurface, error)
}

type SurfaceRepositoryValidator interface {
	// ValidateActiveOverlap checks that activating this surface version would
	// not create overlapping active windows with other versions.
	//
	// INVARIANT: At most one active version per surface ID at any instant.
	//
	// Implementation:
	//   1. Query all versions of surface.ID with Status == Active
	//   2. For each active version V:
	//        - Check if [s.EffectiveFrom, s.EffectiveUntil) overlaps [V.EffectiveFrom, V.EffectiveUntil)
	//   3. Return error if any overlap detected
	//
	// Returns error if overlap would occur.
	ValidateActiveOverlap(ctx context.Context, s *DecisionSurface) error
}

type SurfaceStatus string

type SurfaceValidator interface {
	// ValidateSurface checks structural validity and business rules.
	//
	// STRUCTURAL CHECKS:
	//   - Non-empty required fields (ID, Name, Domain, BusinessOwner, etc.)
	//   - MinimumConfidence in range [0.0, 1.0]
	//   - AuditRetentionHours: zero or >= 24 (negative is invalid)
	//   - Compatible ValidationRule for each ContextField type
	//   - Example conforms to ContextField Type and Validation
	//   - ConsequenceType bounds: MinValue <= MaxValue
	//
	// DOES NOT CHECK:
	//   - Active version overlap (requires repository access)
	//   - Lifecycle transition validity (separate method)
	ValidateSurface(ctx context.Context, s *DecisionSurface) error

	// ValidateContext verifies that a context map conforms to the surface's schema.
	// Checks:
	//   - All required fields are present
	//   - Field types match schema
	//   - Values satisfy validation rules
	ValidateContext(ctx context.Context, s *DecisionSurface, context map[string]any) error

	// ValidateConsequence checks that a consequence conforms to surface types.
	//
	// VALIDATION RULES:
	//   1. TypeID must reference a valid ConsequenceType.ID in the surface
	//   2. Exactly one of Value.Numeric or Value.Categorical must be set
	//   3. Value variant must match ConsequenceType.MeasureType:
	//        - Financial/Temporal → Numeric required
	//        - RiskRating/ImpactScope → Categorical required
	//        - Custom → either allowed (surface defines which)
	//   4. For Numeric:
	//        - Amount must be within [MinValue, MaxValue] if bounds set
	//        - Unit, if provided, should be compatible with Currency/DurationUnit
	//   5. For Categorical:
	//        - Level must be member of RatingScale or ScopeScale
	//        - Ordinal, if provided, must match Level's position in scale
	//
	// Returns error if consequence does not conform to surface declaration.
	ValidateConsequence(ctx context.Context, s *DecisionSurface, consequence Consequence) error

	// ValidateTransition checks if a lifecycle status change is allowed.
	// Allowed transitions:
	//   draft → review → active → deprecated → retired
	//   draft → retired (cancel without activation)
	//   review → draft (return for revision)
	ValidateTransition(ctx context.Context, from, to SurfaceStatus) error
}

type ValidationRule struct {
	// String validation
	Pattern   string   `json:"pattern,omitempty"`    // regex pattern
	MinLength *int     `json:"min_length,omitempty"` // minimum string length
	MaxLength *int     `json:"max_length,omitempty"` // maximum string length
	Enum      []string `json:"enum,omitempty"`       // allowed values (exact match)

	// Number validation
	Minimum          *float64 `json:"minimum,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty"`
	ExclusiveMinimum bool     `json:"exclusive_minimum,omitempty"` // true: value > min; false: value >= min
	ExclusiveMaximum bool     `json:"exclusive_maximum,omitempty"` // true: value < max; false: value <= max

	// Array validation
	MinItems *int `json:"min_items,omitempty"`
	MaxItems *int `json:"max_items,omitempty"`
}