verify

Documentation

Overview

Package verify re-confirms what a concept points outward at, and records the result as §5.3's machine-confirmed tier. It answers one question per concept: does everything this document derives from still resolve, unchanged?

Index

• Constants
• Variables
• func CommitExists(repo, sha string) bool
• func FetchURL(client *http.Client, rawURL string) (string, error)
• func Main(args []string, w io.Writer, set okf.Rules) int
• func PathExists(repo, bundle, rel string) bool
• func SetSourceDigest(path, resource, digest string) (bool, error)
• func Shas(resource string) []string
• func Stamp(path, actor string, at time.Time) (changed bool, err error)
• type Kind
  • func Classify(resource string) Kind
• type Options
• type Verdict
  • func Verify(root string, opts Options) ([]Verdict, error)
  • func (v Verdict) Passed() bool

Constants

const DefaultActor = "process:okf-verify"

Variables

var ErrHandStamp = fmt.Errorf("unsupported verified: shape, stamp by hand")

ErrHandStamp reports a `verified:` shape the line writer will not touch. The fleet writes the flow mapping and the flow list; a block mapping is legal YAML that re-serializing would silently reformat, so it is refused instead.

Functions

func CommitExists

func CommitExists(repo, sha string) bool

CommitExists asks the repo, not the network. This is why most of the fleet verifies offline: a sha names an object that either is in this history or is not, and it can never change afterwards.

func FetchURL

func FetchURL(client *http.Client, rawURL string) (string, error)

FetchURL returns the sha256 of a source's stable text form. A docs site that answers a bare path with a JS shell rewrites that HTML on every deploy, so digesting it reports drift forever; the `.md` sibling both Claude docs hosts serve is the byte-stable thing to hash.

func Main

func Main(args []string, w io.Writer, set okf.Rules) int

Main runs `okf verify`. Without -stamp it writes nothing, so the report and the run that acts on it are the same code path. Exit 1 means a stampable concept is blocked — drift, a dead path, a failing verifier.

func PathExists

func PathExists(repo, bundle, rel string) bool

PathExists resolves a §6.2 path-valued source against the repo root and the bundle root, because the fleet writes both.

func SetSourceDigest

func SetSourceDigest(path, resource, digest string) (bool, error)

SetSourceDigest records what a URL source hashed to, on the entry naming it. §4.1 lets a producer add keys and forbids a consumer rejecting them, so the digest lives with the other credibility signals rather than in a sidecar that would split provenance from the concept.

func Shas

func Shas(resource string) []string

Shas pulls the revisions out of a `commit`/`commits` descriptor. A token that is not a hex sha is dropped rather than failed: the prose half of "commits a, b (the rename)" is not a claim about a revision.

func Stamp

func Stamp(path, actor string, at time.Time) (changed bool, err error)

Stamp appends a verification event to path, or moves the `at` of the event already naming actor. It edits the frontmatter lines and leaves every other byte alone: a full YAML round-trip would reflow the two flow-map spellings and the tag lists the fleet has in it.

Types

type Kind

type Kind int

Kind is what a §5.1 `resource` turns out to be. The spec allows a population or scope descriptor a consumer cannot follow, so classifying comes first: demanding reachability of everything would fail concepts that are correct.

const (
	Descriptor Kind = iota // "all queries in project X" — unverifiable by design
	Commit                 // "commit 30102961" — immutable, checkable offline
	URL                    // an absolute URL — fetched and digested
	Path                   // a repo- or bundle-relative file
)

func Classify

func Classify(resource string) Kind

type Options

type Options struct {
	Rules        okf.Rules
	Actor        string
	Now          time.Time
	Offline      bool
	RunVerifiers bool
	Client       *http.Client
}

type Verdict

type Verdict struct {
	Rel       string
	Stampable bool
	Proven    []string
	Blocked   []string
	Warn      []string
	Digests   map[string]string
}

Verdict is one concept's outcome. Stampable is the load-bearing field: a concept with nothing outward to check is not evidence of anything, so it is left unverified rather than stamped on the strength of the rules alone.

func Verify

func Verify(root string, opts Options) ([]Verdict, error)

Verify walks a bundle and judges every concept. It writes nothing; Stamp and SetSourceDigest are the caller's to run, which is what keeps --dry-run honest.

func (Verdict) Passed

func (v Verdict) Passed() bool