evidence

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SchemaVersion = 1
	ClassTestRun  = "test-run"
)
View Source 
const (
	ClassBuild  = "build"
	ClassLint   = "lint"
	ClassReview = "review"
)

Stage 8 adds three proof classes beside the stage-5 test-run class. Every class stays distinct: no record of one class can satisfy a requirement for another, and review never executes anything.

Variables

This section is empty.

Functions

func Append 

func Append(path, actor string, value TestRun) (record.Record, error)

func AppendProduction 

func AppendProduction(path, actor string, value Production) (record.Record, error)

AppendProduction persists one production observation. A review record whose reviewer is the recording actor is refused: an agent cannot review itself.

func ClassOf 

func ClassOf(raw []byte) (string, error)

ClassOf reads the declared class of any evidence payload without decoding class-specific fields, so one class never has to parse another's record.

func EvidenceSetHash 

func EvidenceSetHash(items []record.Record, change string) (string, error)

EvidenceSetHash identifies the exact runnable evidence a reviewer read for one change. Review records are excluded on purpose: a verdict would otherwise change the set it binds and stale itself the moment it was written. Unknown or malformed records fail closed rather than silently shrinking the set.

func Project 

func Project(path string, subject Subject) ([]TestRun, *TestRun, error)

Project returns all observations and the sole latest applicable pass. Malformed, unknown, future, duplicate, or ambiguous ledgers fail closed.

func Runnable 

func Runnable(class string) bool

Runnable reports whether a class is proven by executing a command through the stage-5 runner. Review is authored by a reviewer and is never runnable.

Types

type Production 

type Production struct {
	SchemaVersion int    `json:"schema_version"`
	Class         string `json:"class"`
	CheckID       string `json:"check"`
	PolicyDigest  string `json:"policy_digest"`
	Change        string `json:"change"`
	TaskID        string `json:"task"`
	AttemptID     string `json:"attempt"`
	HEAD          string `json:"head"`
	TaskHash      string `json:"task_hash"`
	CommandHash   string `json:"command_hash"`
	Reviewer      string `json:"reviewer"`
	// Findings, EvidenceSet, and PacketHash belong to the review class alone.
	// They are the reviewer's actionable findings and the two bindings a
	// runnable observation has no use for: the evidence set the reviewer read
	// and the bounded packet they read it in. A runnable record never carries
	// them, and an absent field is never treated as a match.
	Findings      string `json:"findings,omitempty"`
	EvidenceSet   string `json:"evidence_set,omitempty"`
	PacketHash    string `json:"packet_hash,omitempty"`
	ApprovalHash  string `json:"approval_hash"`
	StateRevision uint64 `json:"state_revision"`
	StartedAt     string `json:"started_at"`
	EndedAt       string `json:"ended_at"`
	ExitCode      int    `json:"exit_code"`
	Passed        bool   `json:"passed"`
	TimedOut      bool   `json:"timed_out"`
	Interrupted   bool   `json:"interrupted"`
	StdoutDigest  string `json:"stdout_digest"`
	StderrDigest  string `json:"stderr_digest"`
	StdoutCut     bool   `json:"stdout_truncated"`
	StderrCut     bool   `json:"stderr_truncated"`
}

Production is the stage-8 evidence payload for the build, lint, and review classes. The test-run class keeps the unchanged stage-5 TestRun payload, so a default-profile ledger is byte-identical to what stage 5 wrote.

func DecodeProduction 

func DecodeProduction(raw []byte) (Production, error)

func NewProduction 

func NewProduction(subject ProductionSubject, result verifyexec.Result) (Production, error)

NewProduction records one runnable production observation using the sole stage-5 runner result. It never invents a pass: timeout and interruption stay recorded as bounded failures.

func NewReview 

func NewReview(subject ProductionSubject, reviewer string, passed bool, observed time.Time) (Production, error)

NewReview records one review verdict. Review carries a reviewer identity instead of a command and can never satisfy a runnable class.

func RecordReview 

func RecordReview(path, actor string, binding ReviewBinding, reviewer, findings string, approved bool, observed time.Time) (Production, record.Record, error)

RecordReview appends one reviewer verdict. It is the only review writer: it reuses the single review payload and appender, checks identity separation before anything is persisted, requires the full binding, and refuses a reject that names no finding. Findings are redacted and sampled by the caller's bounded-output owner; the record keeps that bounded text durably.

func (Production) Applicable 

func (value Production) Applicable(subject ProductionSubject) bool

func (Production) Matches 

func (value Production) Matches(subject ProductionSubject) bool

Matches is exact identity: class, check id, subject, current HEAD, and policy digest. The executed command is recorded but never widens applicability. A review record additionally binds the evidence set and packet it was taken against, so evidence drift invalidates it exactly like code or policy drift.

func (Production) Validate 

func (value Production) Validate() error

type ProductionSubject 

type ProductionSubject struct {
	Subject
	Check        RequiredCheck
	PolicyDigest string
	// EvidenceSet and PacketHash are the review-class bindings. They are empty
	// for every runnable class, which never reads them.
	EvidenceSet string
	PacketHash  string
}

ProductionSubject is the exact identity a production record must match: stage-5 subject facts plus class, check id, and policy digest.

type RequiredCheck 

type RequiredCheck struct {
	Class   string `json:"class"`
	CheckID string `json:"check"`
}

RequiredCheck is one exact proof declaration. It is the single check identity shared by policy, production gates, verification, and completion.

func MissingProduction 

func MissingProduction(items []record.Record, required []RequiredCheck, subject Subject, policyDigest string) (missing []RequiredCheck, priorDigest string, err error)

MissingProduction returns the required checks with no current applicable passing record, in declaration order. priorDigest names the policy digest of a record that matched everything except the current policy, which is policy drift rather than missing proof. Malformed or unknown records fail closed.

func (RequiredCheck) String 

func (check RequiredCheck) String() string

func (RequiredCheck) Valid 

func (check RequiredCheck) Valid() bool

type ReviewBinding 

type ReviewBinding struct {
	ProductionSubject
	Approver    string
	Implementer string
}

ReviewBinding is the exact identity one verdict is bound to: the production subject that already owns change, task, attempt, current HEAD, artifact hashes, state revision, check, and policy digest, plus the two actors a reviewer may never be. Separateness is data, not prose, so a shared or unknown identity fails closed instead of counting as review.

type ReviewState 

type ReviewState string

ReviewState is the deterministic status of the review class for one binding. It stays separate from human approval and from runnable proof: an approved review authorizes nothing on its own and satisfies no other class. 

const (
	ReviewApproved ReviewState = "approved"
	ReviewRejected ReviewState = "rejected"
	ReviewStale    ReviewState = "stale"
	ReviewMissing  ReviewState = "missing"
)

type ReviewVerdict 

type ReviewVerdict struct {
	State       ReviewState `json:"state"`
	Reviewer    string      `json:"reviewer,omitempty"`
	Findings    string      `json:"findings,omitempty"`
	RecordID    string      `json:"record,omitempty"`
	ObservedAt  string      `json:"observed_at,omitempty"`
	PriorDigest string      `json:"prior_policy_digest,omitempty"`
	Reason      string      `json:"reason,omitempty"`
}

ReviewVerdict is the projected review outcome for one binding. It carries facts only; the recovery action belongs to the caller that refuses.

func CurrentReview 

func CurrentReview(items []record.Record, binding ReviewBinding) (ReviewVerdict, error)

CurrentReview projects the review state of one binding from the evidence ledger. A verdict is current only when every stored binding still matches: code, artifact, evidence-set, and policy drift each break it on their own. Malformed, future, cross-class, and unknown-actor records fail closed and never count as review.

type Subject 

type Subject struct {
	Change, TaskID, AttemptID, HEAD string
	TaskHash, CommandHash           string
	ApprovalHash                    string
	StateRevision                   uint64
}

type TestRun 

type TestRun struct {
	SchemaVersion int    `json:"schema_version"`
	Class         string `json:"class"`
	Change        string `json:"change"`
	TaskID        string `json:"task"`
	AttemptID     string `json:"attempt"`
	HEAD          string `json:"head"`
	TaskHash      string `json:"task_hash"`
	CommandHash   string `json:"command_hash"`
	ApprovalHash  string `json:"approval_hash"`
	StateRevision uint64 `json:"state_revision"`
	StartedAt     string `json:"started_at"`
	EndedAt       string `json:"ended_at"`
	ExitCode      int    `json:"exit_code"`
	Passed        bool   `json:"passed"`
	TimedOut      bool   `json:"timed_out"`
	Interrupted   bool   `json:"interrupted"`
	NonVacuous    bool   `json:"non_vacuous"`
	ZeroMatch     bool   `json:"zero_match"`
	StdoutDigest  string `json:"stdout_digest"`
	StderrDigest  string `json:"stderr_digest"`
	StdoutCut     bool   `json:"stdout_truncated"`
	StderrCut     bool   `json:"stderr_truncated"`
}

TestRun is the sole stage-5 evidence payload. Output text is deliberately absent: only bounded execution facts and full-stream digests are durable.

func Decode 

func Decode(raw []byte) (TestRun, error)

func NewTestRun 

func NewTestRun(subject Subject, result verifyexec.Result) (TestRun, error)

func (TestRun) Applicable 

func (value TestRun) Applicable(subject Subject) bool

func (TestRun) Matches 

func (value TestRun) Matches(subject Subject) bool

func (TestRun) Validate 

func (value TestRun) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.