registry

Documentation

Overview

Package registry loads the embedded Jev question-set registry and applies the act/gather/fallback decision policy to answers.

Thresholds come only from the registry: nothing in this package accepts a caller-supplied act or escalate threshold.

Index

• Constants
• Variables
• func AppendDecision(stateDir string, dec Decision) error
• func DecisionsPath(stateDir string) string
• type Decider
  • func (d *Decider) Decide(id string, answers map[string]jev.Answer) (Decision, error)
  • func (d *Decider) DecideWith(id string, answers map[string]jev.Answer, ...) (Decision, error)
  • func (d *Decider) DecideWithConfidence(id string, answers map[string]jev.Answer, ...) (Decision, error)
• type Decision
• type Policy
  • func (p Policy) Classify(confidence float64) string
• type Question
• type Registry
  • func Load() (*Registry, error)
  • func Parse(raw []byte) (*Registry, error)
  • func (r *Registry) IDs() []string
  • func (r *Registry) Set(id string) (*Set, bool)
  • func (r *Registry) Threshold(id, which string) (float64, error)
• type Set
  • func (s *Set) JevQuestions(callTime map[string]map[string]json.RawMessage) (map[string]jev.Question, error)

Constants

const (
	Act      = "act"
	Gather   = "gather"
	Fallback = "fallback"
)

Decisions.

const (
	ReasonOptionNotOffered = "option-not-offered"
	ReasonShadow           = "shadow"
)

Reasons attached to a decision.

Variables

var ErrNoDecision = errors.New("registry: no decision possible")

ErrNoDecision reports answers that cannot be decided: the set declares no usable primary question, the primary answer is missing, or its confidence is not a finite number.

var ErrUnknownSet = errors.New("registry: unknown question set")

ErrUnknownSet reports a question set id that is not registered.

Functions

func AppendDecision

func AppendDecision(stateDir string, dec Decision) error

AppendDecision writes dec as one line of <stateDir>/jevkit/decisions.jsonl.

func DecisionsPath

func DecisionsPath(stateDir string) string

DecisionsPath is <stateDir>/jevkit/decisions.jsonl.

Types

type Decider

type Decider struct {
	Registry *Registry
	// StateDir holds jevkit/decisions.jsonl. Empty disables logging.
	StateDir string
	// Getenv reads JEVKIT_SHADOW; nil means os.Getenv.
	Getenv func(string) string
	// Now stamps records; nil means time.Now.
	Now func() time.Time
}

Decider applies a registry's policy and logs each decision.

func (*Decider) Decide

func (d *Decider) Decide(id string, answers map[string]jev.Answer) (Decision, error)

Decide decides answers (question id to answer) against the set id.

The primary question's answer supplies the confidence: choice and score answers carry one, a noul answer's value is its confidence. A choice that is not among a non-empty criteria set is a fallback. With JEVKIT_SHADOW=1 the would-have decision is logged and the returned decision is fallback.

func (*Decider) DecideWith

func (d *Decider) DecideWith(id string, answers map[string]jev.Answer, callTime map[string]map[string]json.RawMessage) (Decision, error)

DecideWith validates primary choices against declared and call-time options.

func (*Decider) DecideWithConfidence

func (d *Decider) DecideWithConfidence(id string, answers map[string]jev.Answer, callTime map[string]map[string]json.RawMessage, confidence float64) (Decision, error)

DecideWithConfidence applies the registered thresholds to a conservative confidence derived from the primary answer's probability distribution. The original answer, including its distribution, is kept in the decision log.

type Decision

type Decision struct {
	Timestamp          string                 `json:"timestamp"`
	Decision           string                 `json:"decision"`
	Chosen             *string                `json:"chosen"`
	Confidence         float64                `json:"confidence"`
	QuestionSetID      string                 `json:"questionSetId"`
	QuestionSetVersion int                    `json:"questionSetVersion"`
	Surface            string                 `json:"surface"`
	Reason             string                 `json:"reason"`
	Shadow             bool                   `json:"shadow,omitempty"`
	FallbackUsed       bool                   `json:"fallbackUsed"`
	Answers            map[string]interface{} `json:"answers,omitempty"`
	RegistryVersion    string                 `json:"registryVersion"`
	CommandFamily      string                 `json:"commandFamily,omitempty"`
	PolicyRuleID       string                 `json:"policyRuleId,omitempty"`
	Runtime            string                 `json:"runtime,omitempty"`
	ReviewID           string                 `json:"reviewId,omitempty"`
	BytesBefore        int                    `json:"bytesBefore,omitempty"`
	BytesAfter         int                    `json:"bytesAfter,omitempty"`
	LinesBefore        int                    `json:"linesBefore,omitempty"`
	LinesAfter         int                    `json:"linesAfter,omitempty"`
}

Decision is the policy outcome for one set of answers and one decisions.jsonl line.

In shadow mode the value returned to the caller has Decision "fallback", while the logged record keeps the would-have decision.

type Policy

type Policy struct {
	PrimaryQuestion   string  `json:"primaryQuestion"`
	ActThreshold      float64 `json:"actThreshold"`
	EscalateThreshold float64 `json:"escalateThreshold"`
	Fallback          string  `json:"fallback"`
	// GatherHint, when set, tells a caller what evidence to add before
	// asking again after a gather decision.
	GatherHint string `json:"gatherHint,omitempty"`
}

Policy holds a set's decision thresholds.

func (Policy) Classify

func (p Policy) Classify(confidence float64) string

Classify applies the registered thresholds to a confidence value: >= act is act, >= escalate is gather, anything lower is fallback.

type Question

type Question struct {
	Type         string          `json:"type"`
	Instructions string          `json:"instructions"`
	Criteria     json.RawMessage `json:"criteria,omitempty"`
	CriteriaMode string          `json:"criteriaMode,omitempty"`
}

Question is one registered question definition.

type Registry

type Registry struct {
	RegistryVersion string          `json:"registryVersion"`
	QuestionSets    map[string]*Set `json:"questionSets"`
}

Registry is the parsed question-set registry.

func Load

func Load() (*Registry, error)

Load returns the embedded registry, validated once on first use.

func Parse

func Parse(raw []byte) (*Registry, error)

Parse validates raw against the embedded schema and the per-type shape rules the schema cannot express, then returns the parsed registry.

func (*Registry) IDs

func (r *Registry) IDs() []string

IDs lists the registered set ids in sorted order.

func (*Registry) Set

func (r *Registry) Set(id string) (*Set, bool)

Set returns the set registered under id.

func (*Registry) Threshold

func (r *Registry) Threshold(id, which string) (float64, error)

Threshold returns a set's "act" or "escalate" threshold.

type Set

type Set struct {
	ID          string              `json:"id"`
	Version     int                 `json:"version"`
	Surface     string              `json:"surface"`
	Description string              `json:"description"`
	Questions   map[string]Question `json:"questions"`
	Policy      Policy              `json:"policy"`
	Calibration string              `json:"calibration,omitempty"`
}

Set is one registered question set.

func (*Set) JevQuestions

func (s *Set) JevQuestions(callTime map[string]map[string]json.RawMessage) (map[string]jev.Question, error)

JevQuestions turns registry rubrics into wire questions. Dynamic options are accepted only for questions that explicitly declare call-time criteria.