checkcache

type Cache interface {
	// Lookup returns, for each key it has a pass or fail for, the check and its run, by
	// Key.ID(). A key with no result is absent. When several runs hold the key (two
	// writers), the latest wins. Only checks with a fingerprint are findable.
	Lookup(keys []Key) (map[string]Found, error)
	// Put stores runs. Writing a key that already has a result adds to it, never rewrites
	// it; a reader resolves duplicates as Lookup says.
	Put(runs []Run) error
	// Runs returns every run stored, each once (a run put again replaces the earlier copy),
	// newest first: the history a reader that lists (not looks up) works over. A run with no
	// findable check is a run too.
	Runs() ([]Run, error)
}

type Check struct {
	Subject string `json:"subject"`
	Kind    string `json:"kind"`
	Status  string `json:"status"`
	// Fingerprint is the cache key part; only a guard's verdict carries one (its steps inside
	// it do not), and what has none is not findable.
	Fingerprint string         `json:"fingerprint,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Items       []Item         `json:"items,omitempty"`
}

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

type Found struct {
	Run   Run
	Check Check
}

type GcStats struct {
	Records    int // latest result per key kept
	Duplicates int // superseded results dropped
	SegsBefore int
	SegsAfter  int
	Retrained  bool
}

type Item struct {
	Key      string         `json:"key,omitempty"`
	Passed   bool           `json:"passed"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Key struct {
	// Rule is the rule's qualified name (<plugin>/file-guard/<name>).
	Rule string `json:"rule"`
	// Kind names the check inside the rule: check[1]:judge:./rubric.md.j2.
	Kind string `json:"kind"`
	// Subject is the unit judged. Today the one subject of a rule's checks is "changeset".
	Subject string `json:"subject"`
	// Fingerprint is what the verdict is about: the subject's files (path and content) and the
	// fingerprint the rule's `subjects:` script gave the subject (changeset.GuardFingerprint).
	// Not in it: a commit SHA, a citation, the model, the judge's template, `prepare`'s output.
	Fingerprint string `json:"fingerprint"`
}

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

type Options struct {
	// Dir is any directory inside the repository whose object store holds the ref.
	Dir string
	// Remote is a remote name or URL the ref is synced with. Empty = local only.
	Remote string
	// Ref is the local ref that mirrors the branch. Default refs/sloprail/checks.
	// CI points it at a ref it fetched (refs/remotes/origin/sloprail/checks).
	Ref string
	// Branch is the remote ref. Default refs/heads/sloprail/checks.
	Branch string
	// NoAutoGc stops a Put from compacting the branch when it grows (see maybeGc). For tests
	// that count segments or commits.
	NoAutoGc bool
}

type Run struct {
	ID      string `json:"id"`
	RunAt   string `json:"run_at"` // fixed-width UTC, so stamps compare as strings
	BatchID string `json:"batch,omitempty"`
	// Rule is the rule's qualified name; RuleHash its definition's hash when the run was made.
	// The hash is recorded for the trace only: a verdict's key never holds it, so a rule's
	// logic changing does not void what was judged before.
	Rule     string `json:"rule"`
	RuleHash string `json:"ruleHash"`
	BaseRef  string `json:"base_ref"`
	HeadRef  string `json:"head_ref"`
	// BaseTree and HeadTree are the tree ids of BaseRef and HeadRef when the run was made
	// (absent on a run recorded before they existed): equal trees are an equal net change,
	// so a range over the same two trees can read this run's verdict (Store.CachedByTrees).
	BaseTree string `json:"base_tree,omitempty"`
	HeadTree string `json:"head_tree,omitempty"`
	// ExitCode and Error record an ENGINE failure (git, a range that could not be read):
	// such a run passes nothing.
	ExitCode int            `json:"exit_code,omitempty"`
	Error    string         `json:"error,omitempty"`
	Complete bool           `json:"complete"` // every check it was going to run is stored
	Metadata map[string]any `json:"metadata,omitempty"`
	// Provenance: who ran it. Never part of a key.
	RepoID    string  `json:"repo_id,omitempty"`
	Branch    string  `json:"branch,omitempty"`
	SessionID string  `json:"session_id,omitempty"`
	AgentID   string  `json:"agent_id,omitempty"`
	Checks    []Check `json:"checks"`
}

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