okf

type AdvisoryOptions struct {
	// Options is the type vocabulary with descriptions; empty skips
	// type_mismatch.
	Options []TypeOption
	// Threshold is the okf_type threshold (0 → DefaultTypeThreshold).
	Threshold float64
	// Decider computes missing answers; nil reads receipts only.
	Decider Decider
	// Topic is the bundle's topic reference for Decide (Root = bundle).
	// Concepts matching Topic.Exclude (decisions.exclude) get no advisory
	// finding: they are never judged.
	Topic decisions.TopicRef
	// Extras are the topic's extra okf_type banks, asked with type_mismatch
	// (answers only recorded in receipts).
	Extras []*questions.Bank
}

type CheckOptions struct {
	Types  []string
	Strict bool
	// Advisory enables the advisory findings type_mismatch and
	// description_unsupported (never errors); nil skips them.
	Advisory *AdvisoryOptions
}

type ConceptResult struct {
	WrittenPath     string   `json:"writtenPath"`
	Type            string   `json:"type"`
	LinksRewritten  int      `json:"linksRewritten"`
	UnresolvedLinks []string `json:"unresolvedLinks"`
	Warnings        []string `json:"warnings,omitempty"`
	// TypeSuggestion is the decision model's type suggestion, when asked.
	TypeSuggestion *TypeSuggestion `json:"typeSuggestion,omitempty"`
	// TypeWarning is set when --type disagrees with a confident suggestion.
	TypeWarning string `json:"typeWarning,omitempty"`
}

type Decider interface {
	Decide(ctx context.Context, r decisions.Request) (decisions.Result, error)
}

type EngineTypeSuggester struct {
	Decider Decider
	Topic   decisions.TopicRef
	Options []TypeOption
	// Extras are the topic's extra okf_type question banks (spec §4.3):
	// their questions ride along in the same request and their answers are
	// only recorded in receipts.
	Extras []*questions.Bank
}

type PromoteInput struct {
	SourceDocPath string
	VaultPath     string
	TargetTopic   models.TopicInfo
	Type          string
	Description   string
	Types         []string
	Clock         func() time.Time
	// Suggester asks the decision model for the type (spec §11). Without
	// Type, its suggestion is used when P(argmax) ≥ TypeThreshold; with
	// Type, a disagreement at that probability becomes TypeWarning. nil
	// means no decision model: Type is then required.
	Suggester TypeSuggester
	// TypeThreshold is the okf_type threshold (0 → DefaultTypeThreshold).
	TypeThreshold float64
}

type TypeDocument struct {
	Subject string
	Title   string
	Body    string
}

type TypeOption struct {
	Name        string
	Description string
}

type TypeScore struct {
	Type        string  `json:"type"`
	Probability float64 `json:"probability"`
}

type TypeSuggester interface {
	SuggestType(ctx context.Context, doc TypeDocument) (TypeSuggestion, error)
}

type TypeSuggestion struct {
	Status      decisions.Status `json:"status"`
	Reason      string           `json:"reason,omitempty"`
	Type        string           `json:"type,omitempty"`
	Probability float64          `json:"probability"`
	Top         []TypeScore      `json:"top,omitempty"`
	ReceiptKey  string           `json:"receipt,omitempty"`
}