kbvalidate

Documentation

Overview

Package kbvalidate provides deterministic structural validation of OKF knowledge-base entries (the merge gate) and an LLM-assisted semantic advisory. The structural checks mirror what curator.draftKBEntry emits and what catalog.parseEntry consumes, so a RunLore-authored entry that passes meetsBar also passes ValidateStructural by construction.

Index

• func HasErrors(issues []Issue) bool
• func WarnInvalid(entries []catalog.Entry, onInvalid func(path string, errs []Issue)) int
• type Advisory
  • func ReviewSemantic(ctx context.Context, e catalog.Entry, m providers.ModelProvider) (Advisory, error)
• type Issue
  • func ValidateStructural(e catalog.Entry) []Issue
• type Severity
  • func (s Severity) String() string
• type Verdict

Functions

func HasErrors

func HasErrors(issues []Issue) bool

HasErrors reports whether any issue is Severity=Error — the gate signal.

func WarnInvalid

func WarnInvalid(entries []catalog.Entry, onInvalid func(path string, errs []Issue)) int

WarnInvalid is the load-time strict-warn hook: it calls onInvalid(path, errs) for each invalid entry; the caller logs + increments a metric, but the entry is still served (one bad entry never empties the catalog). Returns the count of invalid entries. Warnings are not reported here.

It is deliberately looser than the merge gate: OKF conformance (§9) requires consumers to tolerate unknown types gracefully, so an entry outside the RunLore vocabulary (a foreign bundle's "Metric", "API Endpoint", …) is checked only for OKF conformance — a non-empty `type`. Entries claiming a RunLore type are held to the full ValidateStructural shape, since those are the ones the merge gate promised were well-formed.

Types

type Advisory

type Advisory struct {
	CauseExplainsSymptom Verdict
	Durable              Verdict
	Skipped              bool
}

Advisory is the LLM-assisted semantic review of an entry. It is ADVISORY only — never a merge gate. Skipped is true when no model is configured or the review could not be obtained (the structural gate still applies).

func ReviewSemantic

func ReviewSemantic(ctx context.Context, e catalog.Entry, m providers.ModelProvider) (Advisory, error)

ReviewSemantic asks the model to judge cause-explains-symptom and durability. It NEVER gates: a nil model, a model error, or a missing tool-call all return an Advisory with Skipped=true. The returned error is for logging only.

type Issue

type Issue struct {
	Severity Severity
	Field    string
	Message  string
}

Issue is one validation finding against a frontmatter field or body section.

func ValidateStructural

func ValidateStructural(e catalog.Entry) []Issue

ValidateStructural runs deterministic structural checks on a parsed catalog entry. Errors fail the merge gate; warnings are advisory.

type Severity

type Severity int

Severity classifies an Issue. Only SeverityError fails the merge gate.

const (
	SeverityError Severity = iota
	SeverityWarning
)

Issue severities. Only SeverityError fails the merge gate; SeverityWarning is advisory.

func (Severity) String

func (s Severity) String() string

String renders the severity for human/CI output.

type Verdict

type Verdict struct {
	OK        bool
	Rationale string
}

Verdict is one advisory judgement: whether the property holds, with a reason.