contract

type Contract struct {
	// Expectations are checked independently. Order does not affect the result but is preserved, because a
	// file somebody wrote should read back the way they wrote it.
	Expectations []Expectation `yaml:"expectations" json:"expectations"`

	// MinMessages is how many messages must be seen before any expectation is judged.
	//
	// Without this a contract fires on the first message of the morning, when one absent field is 100% of the
	// evidence. Defaults to 100, which is enough for a 99% threshold to mean something.
	MinMessages int `yaml:"min_messages,omitempty" json:"minMessages,omitempty"`

	// DerivedFrom records the profile this came from, when it was promoted rather than hand-written.
	DerivedFrom string `yaml:"derived_from,omitempty" json:"derivedFrom,omitempty"`
}

type Expectation struct {
	// Path is the field or segment, in the same notation filters and transformations use, so an expectation
	// can be pasted into a filter and vice versa.
	Path string `yaml:"path" json:"path"`

	// Rule is what is expected.
	Rule Rule `yaml:"rule" json:"rule"`

	// MinRate is the proportion of messages that must satisfy the rule, between 0 and 1.
	//
	// Defaults to 0.99 rather than 1.0, deliberately. An expectation of "always" is almost never what
	// somebody means: real feeds contain test messages and manual entries, and a contract that fires on one
	// of them in ten thousand is a contract that gets switched off.
	MinRate float64 `yaml:"min_rate,omitempty" json:"minRate,omitempty"`

	// Values is the permitted set for OneOf.
	Values []string `yaml:"values,omitempty" json:"values,omitempty"`

	// Limit is the maximum for MaxRepeats.
	Limit int `yaml:"limit,omitempty" json:"limit,omitempty"`

	// Why records who decided this and when.
	//
	// This is the domain-tax field. Most of what makes an interface hard to maintain is that nobody knows
	// why a decision was made, and the person who knew has left. An expectation without a reason becomes an
	// expectation nobody dares change and nobody dares delete, which is how a contract turns into
	// superstition.
	Why string `yaml:"why,omitempty" json:"why,omitempty"`

	// Relaxed records that this expectation was deliberately loosened, and why.
	//
	// Separate from simply editing MinRate, because an assertion silently weakened is worse than one that
	// was never written: it still looks like a guarantee. Recording the relaxation keeps the history visible
	// in the file that carries it.
	Relaxed string `yaml:"relaxed,omitempty" json:"relaxed,omitempty"`
}

type PromoteOptions struct {
	// AlwaysThreshold is the fill rate above which a field is treated as always populated. Defaults to 0.995.
	AlwaysThreshold float64

	// MinRate is the tolerance written into generated Populated expectations. Defaults to 0.99.
	//
	// Lower than what was observed on purpose. An expectation generated at exactly the observed rate fires on
	// the first message that is slightly worse, which is the same day it was created.
	MinRate float64

	// MaxCodeSetSize is the largest value set that will be promoted. Defaults to 12.
	//
	// Small on purpose. A field with thirty distinct values might be a code set or might be free text that
	// happens to repeat, and getting that wrong asserts patient data.
	MaxCodeSetSize int

	// MaxCodeLength is the longest single value that will be treated as a code. Defaults to 12.
	MaxCodeLength int

	// RepeatHeadroom multiplies the observed maximum repeat count. Defaults to 2.
	RepeatHeadroom int

	// Source names where the profile came from, for the DerivedFrom field.
	Source string
}

type Result struct {
	// Messages is how many were examined.
	Messages int `json:"messages"`

	// Judged is false when there were too few messages to conclude anything. Distinguished from "no
	// violations", because they mean opposite things and look identical in a summary.
	Judged bool `json:"judged"`

	// Note explains a result that cannot be trusted.
	Note string `json:"note,omitempty"`

	// Violations are ordered worst first, by how far from the threshold they fell.
	Violations []Violation `json:"violations"`

	// Checked is how many expectations were evaluated, so a passing result says what it proved rather than
	// only that nothing was wrong.
	Checked int `json:"checked"`

	// Unjudged names expectations that could not be evaluated at all, each with the reason.
	//
	// Separate from Violations because they are not findings about the feed, they are findings about the
	// contract - and separate from Checked because counting them there is the lie this exists to correct. An
	// expectation nothing could be judged against was previously counted as checked and produced no violation,
	// so it read as a passing check and had never run once.
	Unjudged []string `json:"unjudged,omitempty"`
}

type Rule string

type Violation struct {
	Expectation Expectation `json:"expectation"`

	// Actual is the observed rate, or the observed repeat count for MaxRepeats.
	Actual float64 `json:"actual"`

	// Messages is how many messages the observation rests on. Reported because a rate from 120 messages and
	// the same rate from 120,000 justify very different responses.
	Messages int `json:"messages"`

	// Unexpected lists values seen that the contract does not permit, for OneOf. Codes rather than free text,
	// so this does not become a way to read patient data - a rule with a permitted value list is by
	// definition about a code set.
	Unexpected []string `json:"unexpected,omitempty"`

	// Says is the sentence to show somebody. Built here rather than at the point of display so every caller -
	// the CLI, the API, an alert webhook - says the same thing.
	Says string `json:"says"`
}