guard

Documentation

Overview

Package guard owns every refusal in the protocol. Each rejection reason corresponds to a supervisory obligation from the Locus derivation (docs/locus): the controllability theorem rests on these events being genuinely refusable, so each has a named check and a refusing test.

Index

• func CheckCompletion(s *RunState, reqs []protocol.Requirement) error
• func CheckDigest(s *RunState, currentDigest string, migrate bool) error
• func CheckResponse(s *RunState, resp protocol.ResponseEnvelope) error
• type RejectReason
• type Rejection
  • func (r *Rejection) Error() string
• type RunState
  • func Reconstruct(l *runlog.Log) (*RunState, error)

Functions

func CheckCompletion

func CheckCompletion(s *RunState, reqs []protocol.Requirement) error

CheckCompletion refuses run.completed when any requirement has failed: evidence-bound completion is a supervisory invariant, not advice.

func CheckDigest

func CheckDigest(s *RunState, currentDigest string, migrate bool) error

CheckDigest refuses to act on a run whose skill source changed since the run was bound, unless the caller explicitly migrates. This is the migrate_digest mechanism from the lifecycle model — without it, a diverged-source run would block.

func CheckResponse

func CheckResponse(s *RunState, resp protocol.ResponseEnvelope) error

CheckResponse decides whether a response envelope may be accepted for the run's pending operation. Refusals: wrong run, stale, duplicate, wrong request id, schema-invalid result.

Types

type RejectReason

type RejectReason string

const (
	RejectWrongRun       RejectReason = "wrong-run"
	RejectStale          RejectReason = "stale-response"
	RejectDuplicate      RejectReason = "duplicate-response"
	RejectWrongRequest   RejectReason = "wrong-request"
	RejectSchemaInvalid  RejectReason = "schema-invalid"
	RejectDigestMismatch RejectReason = "digest-mismatch"
	RejectUnproven       RejectReason = "completion-unproven"
	RejectRunClosed      RejectReason = "run-closed"
	RejectNoPendingOp    RejectReason = "no-pending-operation"
)

type Rejection

type Rejection struct {
	Reason RejectReason
	Detail string
}

Rejection is a typed refusal; it renders calmly and names its reason.

func (*Rejection) Error

func (r *Rejection) Error() string

type RunState

type RunState struct {
	RunID       string
	BoundDigest string
	Skill       protocol.SkillRef
	Pending     *protocol.RequestEnvelope // unanswered operation, if any
	Completed   map[int]string            // sequence -> result digest
	Closed      bool                      // a terminal run.* event exists
	ReqFailed   bool                      // a requirement.failed event exists
	Diverged    bool
}

RunState is the guard-relevant projection of a run log.

func Reconstruct

func Reconstruct(l *runlog.Log) (*RunState, error)

Reconstruct folds a run log into its guard state. The log is the only source of truth; nothing else is consulted.