gate

package
v0.3.0-beta.3 Latest Latest
Warning

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

Go to latest
Published: Aug 1, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package gate evaluates loop verification gates.

Index

Constants

View Source
const (
	// JudgeMalformedOutputIssueID is the canonical blocker for responsive invalid judge JSON.
	JudgeMalformedOutputIssueID = "judge_output_malformed"
	// JudgeEvidenceRequiredIssueID is the ADR-018 blocker for empty approved evidence.
	JudgeEvidenceRequiredIssueID = "judge_evidence_required"
	// JudgeTransportFailureIssueID is the canonical blocker for broken judge transport.
	JudgeTransportFailureIssueID = "judge_transport_failure"
	// JudgeRubricInvalidIssueID is the canonical blocker for template/render failures.
	JudgeRubricInvalidIssueID = "judge_rubric_invalid"
)
View Source
const (
	// DefaultBrokenJudgeStreakLimit is the ADR-012 fail-open guard.
	DefaultBrokenJudgeStreakLimit = 3
)

Variables

View Source
var (
	// ErrInvalidGate reports an authored gate that cannot be evaluated.
	ErrInvalidGate = errors.New("loop gate: invalid gate")
	// ErrMaxRevisionsCeiling reports a gate above the hard revision ceiling.
	ErrMaxRevisionsCeiling = errors.New("loop gate: max_revisions exceeds ceiling")
	// ErrVerdictPolicyRequiresJudge reports a revise policy without a verdict source.
	ErrVerdictPolicyRequiresJudge = errors.New("loop gate: verdict_policy revise_until_clean requires judge or human")
)

Functions

func RenderAgentJudgeRubric

func RenderAgentJudgeRubric(
	criterion dsl.GateCriterion,
	contract dsl.Contract,
	templateData map[string]any,
	evidence JudgeEvidence,
) (string, error)

RenderAgentJudgeRubric renders a contract-aware, evidence-required judge prompt.

Types

type BlockingIssue

type BlockingIssue struct {
	ID   string `json:"id"`
	Note string `json:"note"`
}

BlockingIssue is the structured blocker ID shape from ADR-022.

type CommandRequest

type CommandRequest struct {
	GateID      string
	CriterionID string
	Command     string
	Expect      string
	Contains    string
}

CommandRequest is one command criterion invocation.

type CommandResult

type CommandResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

CommandResult captures the deterministic command result.

type CommandRunner

type CommandRunner interface {
	RunCommand(ctx context.Context, req CommandRequest) (CommandResult, error)
}

CommandRunner executes command criteria.

type CriterionResult

type CriterionResult struct {
	ID             string              `json:"id"`
	Type           dsl.CriterionType   `json:"type"`
	Outcome        VerdictOutcome      `json:"outcome"`
	Passed         bool                `json:"passed"`
	Broken         bool                `json:"broken,omitempty"`
	ExitCode       *int                `json:"exit_code,omitempty"`
	Stdout         string              `json:"stdout,omitempty"`
	Stderr         string              `json:"stderr,omitempty"`
	Confidence     *float64            `json:"confidence,omitempty"`
	Evidence       json.RawMessage     `json:"evidence,omitempty"`
	BlockingIssues []BlockingIssue     `json:"blocking_issues,omitempty"`
	Warnings       []DiagnosticWarning `json:"warnings,omitempty"`
	Payload        json.RawMessage     `json:"payload,omitempty"`
	// contains filtered or unexported fields
}

CriterionResult is the observable per-criterion outcome for SSE/UI consumers.

func ParseJudgeVerdict

func ParseJudgeVerdict(criterionID string, criterionType dsl.CriterionType, raw string) CriterionResult

ParseJudgeVerdict maps raw judge output into the ADR-022 criterion result.

type DiagnosticWarning

type DiagnosticWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

DiagnosticWarning is a non-terminal evaluator diagnostic.

type Evaluator

type Evaluator struct {
	// contains filtered or unexported fields
}

Evaluator evaluates gate criteria using injected runtime boundaries.

func NewEvaluator

func NewEvaluator(opts ...Option) *Evaluator

NewEvaluator creates an evaluator with deterministic defaults.

func (*Evaluator) Evaluate

func (e *Evaluator) Evaluate(ctx context.Context, gate Gate, in GateInput) (Verdict, error)

Evaluate runs every criterion in one gate bundle and returns one aggregate verdict.

type Gate

type Gate struct {
	ID            string
	Criteria      []dsl.GateCriterion
	VerdictPolicy dsl.VerdictPolicy
	// OnResult maps verdict result keys to route overrides. Recognized keys are
	// pass, approval, fail, blocked, error, timeout, and invalid_output.
	OnResult     map[string]any
	MaxRevisions int
}

Gate is the runtime shape of a control gate or definition-of-done gate.

func GateFromContract

func GateFromContract(id string, contract dsl.Contract, maxRevisions int) Gate

GateFromContract adapts contract verification criteria into a DoD gate.

func GateFromNode

func GateFromNode(node dsl.Node) Gate

GateFromNode adapts a DSL gate node into the evaluator input.

type GateEvaluator

type GateEvaluator interface {
	Evaluate(ctx context.Context, gate Gate, in GateInput) (Verdict, error)
}

GateEvaluator evaluates one gate criteria bundle and returns its verdict and route.

type GateInput

type GateInput struct {
	LoopRunID                string
	Placement                Placement
	Contract                 *dsl.Contract
	TemplateData             map[string]any
	Revision                 int
	BrokenJudgeStreak        int
	BrokenJudgeStreakLimit   int
	HumanDecisions           map[string]HumanDecision
	ToolScope                tools.Scope
	ToolCallCorrelationID    string
	ToolSensitiveInputFields []string
	JudgeRuntime             dsl.RuntimeSpec
	JudgeUsageReporter       JudgeUsageReporter
	JudgeEvidence            JudgeEvidence
	NetworkParticipation     *participation.Spec
}

GateInput carries runtime state required to evaluate and route a gate.

type HumanDecision

type HumanDecision struct {
	Decision HumanDecisionKind
	Actor    task.ActorContext
	Note     string
}

HumanDecision captures one human gate decision made through a trusted actor context.

type HumanDecisionKind

type HumanDecisionKind string

HumanDecisionKind is the closed approval vocabulary for human criteria.

const (
	// HumanDecisionApprove resumes the passing path.
	HumanDecisionApprove HumanDecisionKind = "approve"
	// HumanDecisionRequestChanges routes to revise or next generation.
	HumanDecisionRequestChanges HumanDecisionKind = "request_changes"
	// HumanDecisionReject routes to terminal halt.
	HumanDecisionReject HumanDecisionKind = "reject"
)

type JudgeEvidence

type JudgeEvidence struct {
	Text       string
	Structured json.RawMessage
}

JudgeEvidence is the authoritative completed candidate supplied to an agent judge.

type JudgeRequest

type JudgeRequest struct {
	LoopRunID            string
	GateID               string
	CriterionID          string
	Attempt              int
	CorrelationID        string
	WorkspaceID          string
	Agent                string
	Runtime              dsl.RuntimeSpec
	Rubric               string
	Contract             dsl.Contract
	NetworkParticipation *participation.Spec
}

JudgeRequest is the rendered agent-judge invocation.

type JudgeResponse

type JudgeResponse struct {
	Raw            string
	TokensUsed     int64
	TokensReported bool
}

JudgeResponse is the raw judge response payload.

type JudgeRunner

type JudgeRunner interface {
	Judge(ctx context.Context, req JudgeRequest) (JudgeResponse, error)
}

JudgeRunner executes agent-judge criteria.

type JudgeUsageReporter

type JudgeUsageReporter interface {
	ReportJudgeTokensUsed(int64)
}

JudgeUsageReporter receives one aggregate cumulative token total for a gate evaluation.

type JudgeUsageReporterFunc

type JudgeUsageReporterFunc func(int64)

JudgeUsageReporterFunc adapts a function to JudgeUsageReporter.

func (JudgeUsageReporterFunc) ReportJudgeTokensUsed

func (f JudgeUsageReporterFunc) ReportJudgeTokensUsed(tokens int64)

ReportJudgeTokensUsed implements JudgeUsageReporter.

type Option

type Option func(*Evaluator)

Option configures an Evaluator.

func WithBrokenJudgeStreakLimit

func WithBrokenJudgeStreakLimit(limit int) Option

WithBrokenJudgeStreakLimit overrides the ADR-012 broken judge streak limit.

func WithCommandRunner

func WithCommandRunner(runner CommandRunner) Option

WithCommandRunner injects command criterion execution.

func WithJudgeRunner

func WithJudgeRunner(runner JudgeRunner) Option

WithJudgeRunner injects agent-judge criterion execution.

func WithMaxRevisionsCeiling

func WithMaxRevisionsCeiling(ceiling int) Option

WithMaxRevisionsCeiling overrides the structural max_revisions ceiling.

func WithToolCaller

func WithToolCaller(caller ToolCaller) Option

WithToolCaller injects tools/call dispatch for extension criteria.

type Placement

type Placement string

Placement identifies where a gate verdict is consumed.

const (
	// PlacementInBody is a gate control node inside the graph body.
	PlacementInBody Placement = "in_body"
	// PlacementDefinitionOfDone is the loop contract gate between generations.
	PlacementDefinitionOfDone Placement = "definition_of_done"
)

type RouteAction

type RouteAction string

RouteAction is the closed routing vocabulary produced by the evaluator.

const (
	// RouteContinue advances past an in-body gate.
	RouteContinue RouteAction = "continue"
	// RouteRevise re-enters the body revision path.
	RouteRevise RouteAction = "revise"
	// RouteBranch selects a named branch.
	RouteBranch RouteAction = "branch"
	// RouteHalt stops the loop.
	RouteHalt RouteAction = "halt"
	// RouteEscalate parks for human approval.
	RouteEscalate RouteAction = "escalate"
	// RouteDone marks a definition-of-done gate complete.
	RouteDone RouteAction = "done"
	// RouteNextGeneration schedules the next generation.
	RouteNextGeneration RouteAction = "next_generation"
)

type RouteDecision

type RouteDecision struct {
	Placement      Placement   `json:"placement"`
	Action         RouteAction `json:"action"`
	Branch         string      `json:"branch,omitempty"`
	TerminalStatus string      `json:"terminal_status,omitempty"`
	ReasonCode     string      `json:"reason_code,omitempty"`
}

RouteDecision is the routing result for the gate placement.

type ToolCaller

type ToolCaller interface {
	Call(ctx context.Context, scope tools.Scope, req tools.CallRequest) (tools.ToolResult, error)
}

ToolCaller is the tools/call subset used by extension gate checks.

type Verdict

type Verdict struct {
	Outcome        VerdictOutcome    `json:"outcome"`
	Criteria       []CriterionResult `json:"criteria"`
	BlockingIssues []BlockingIssue   `json:"blocking_issues,omitempty"`
	// Payload carries the first aggregate verdict-source evidence or payload.
	Payload json.RawMessage `json:"payload,omitempty"`
	// Broken marks fail-open transport failure; consumers must use Route for control flow.
	Broken                 bool                `json:"broken,omitempty"`
	Warnings               []DiagnosticWarning `json:"warnings,omitempty"`
	Route                  RouteDecision       `json:"route"`
	NextBrokenJudgeStreak  int                 `json:"next_broken_judge_streak,omitempty"`
	BlockingIssueSignature []string            `json:"blocking_issue_signature,omitempty"`
}

Verdict is the aggregate gate verdict.

type VerdictOutcome

type VerdictOutcome string

VerdictOutcome is the canonical criterion and aggregate verdict taxonomy.

const (
	// VerdictOutcomeApproved accepts the gate.
	VerdictOutcomeApproved VerdictOutcome = "approved"
	// VerdictOutcomeRejected rejects the gate and requests revision.
	VerdictOutcomeRejected VerdictOutcome = "rejected"
	// VerdictOutcomeAwaitingApproval parks the gate until a human decision arrives.
	VerdictOutcomeAwaitingApproval VerdictOutcome = "awaiting_approval"
	// VerdictOutcomeBlocked reports an explicit external blocker.
	VerdictOutcomeBlocked VerdictOutcome = "blocked"
	// VerdictOutcomeError reports a checker execution error.
	VerdictOutcomeError VerdictOutcome = "error"
	// VerdictOutcomeTimeout reports a checker timeout.
	VerdictOutcomeTimeout VerdictOutcome = "timeout"
	// VerdictOutcomeInvalidOutput reports a responsive checker with unusable output.
	VerdictOutcomeInvalidOutput VerdictOutcome = "invalid_output"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL