goalflow

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package goalflow binds the neutral Goal policy to bounded Coding evidence. It owns neither a work driver nor a scheduler; Runtime supplies both admission and explicit notification delivery.

Index

Constants

View Source
const (
	MaxRecords       = 32
	MaxResultBytes   = 4096
	MaxEvidenceBytes = 192 << 10
	MaxGaps          = 16
)

Evidence payload bounds are independent of provider context limits.

View Source
const MaxSkepticSessionBytes = 128

MaxSkepticSessionBytes bounds the resumed child session id the panel stores.

Variables

This section is empty.

Functions

func Bound

func Bound(text string, maximum int) string

Bound caps UTF-8 text without cutting a code point.

func CanonicalArguments

func CanonicalArguments(data ai.JSON) ai.JSON

CanonicalArguments normalizes object ordering for evidence identity.

func DecodeStrict

func DecodeStrict(data ai.JSON, value any) error

DecodeStrict rejects unknown fields, trailing values and oversized payloads.

func Digest

func Digest(text string) string

Digest identifies the complete observed result, before truncation.

func Encode

func Encode(value any) (ai.JSON, error)

Encode enforces the persisted policy payload bound.

func PartsText

func PartsText(parts []ai.Part) string

PartsText extracts the textual channel from an actual tool result.

func SkepticTransportFailure added in v0.1.9

func SkepticTransportFailure(cause error) error

SkepticTransportFailure wraps a transport-level failure, which Verify turns into the panel's infrastructure pause instead of a skeptic's synthetic refute.

func ValidUsage

func ValidUsage(usage ai.Usage) bool

ValidUsage rejects impossible observed token counters.

Types

type ChangeSource added in v0.1.9

type ChangeSource func(context.Context) Changes

ChangeSource captures the per-verification change evidence. It runs once per verification and never fails a Decision: a missing repository, a Git failure or a timeout renders the reference's own sentinels.

type Changes added in v0.1.9

type Changes struct {
	Diff          string
	DiffTruncated bool
	ChangedFiles  []string
}

Changes is the reference's per-verification change evidence.

type Controller

type Controller struct {
	Evaluator goal.Evaluator
	Verifier  *Verifier
	// FailedUsage journals observed usage of a failed Decision separately. The
	// generic runtime intentionally commits usage only on successful Decisions.
	FailedUsage func(ai.Usage) error
	KnownFailed func() ai.Usage
	Invalidated func() bool
	Phase       func(string) error
	// Declared reports and consumes the model's completion declaration for the
	// running Goal. It is consulted once at a decision point: when it reports true
	// the verifier audits the recorded evidence in place of the ordinary condition
	// assessment, and a later decision point never sees the same declaration. The
	// declaration is never evidence — the verifier still reads the workspace and
	// the recorded tool results.
	Declared func() bool
	// Transcript supplies the assessment's session-derived input: the bounded
	// rendering of the conversation and the Goal's plan. It is consulted inside
	// the evaluator wrapper below rather than carried on the durable request,
	// because a decision retried after an interruption rebuilds that request from
	// durable state and would carry an empty or stale transcript.
	Transcript func() (transcript, plan string)
	// ResetVerification reports and consumes an explicit user resume, so the
	// per-goal verification run count and the gap-stall state start again. Like
	// the declaration it is process-local state of the run that produced it, and
	// the reference's own resume resets the same counters.
	ResetVerification func() bool
}

Controller decorates the SDK Goal policy with Coding's gates, independent evidence audit, and substantive progress classification.

func (*Controller) Decide

Decide preserves Coding gates around the neutral SDK Goal policy.

type Evidence

type Evidence struct {
	InteractionID string   `json:"interaction_id"`
	AttemptID     string   `json:"attempt_id"`
	Records       []Record `json:"records"`
	Claim         string   `json:"claim,omitempty"`
	Gate          string   `json:"gate,omitempty"`
	Background    bool     `json:"background,omitempty"`
	Stopped       bool     `json:"stopped,omitempty"`
	Truncated     bool     `json:"truncated,omitempty"`
}

Evidence is persisted at the Work/Decision boundary. Claims cannot substitute for Records. Gate and Background defer assessment without invoking a model.

func Merge

func Merge(previous, next Evidence) Evidence

Merge retains a bounded latest-result ledger. Evicted essential evidence cannot authorize completion: truncation is sticky until explicit invalidation.

func (Evidence) Fingerprint

func (e Evidence) Fingerprint() string

Fingerprint deliberately excludes conversation text, identity, and repeated identical calls. Only substantive tool evidence advances this marker.

type Finding added in v0.1.9

type Finding struct {
	Kind     string `json:"kind"`
	Location string `json:"location"`
	Detail   string `json:"detail"`
}

Finding is one concise skeptic finding: the implementer-facing gap list. Kind is the prompt's bug|gap|todo, rendered as given after trim.

type Packet added in v0.1.9

type Packet struct {
	Objective     string
	Diff          string
	DiffTruncated bool
	ChangedFiles  []string
	PlanFile      string
	PlanChanges   string
	FinalResponse string
	PriorGaps     []string
	// PriorSkeptic0 names the first skeptic's completed child session from the
	// previous verification, so a panel larger than one resumes it instead of
	// judging cold. It is empty on the first verification, for a one-skeptic
	// panel, and for an in-process panel.
	PriorSkeptic0 string
}

Packet is the reference's verification evidence packet: everything one verification hands the panel beyond pips' recorded tool-result ledger. Objective, FinalResponse, PriorGaps and PriorSkeptic0 come from the controller; the change evidence comes from the verifier's change source.

type PanelReportSink added in v0.1.9

type PanelReportSink func(context.Context, []SkepticReport)

PanelReportSink receives one spawned panel's diagnostic record. It is consulted after the panel ran and never gates a decision.

type Record

type Record struct {
	ID        string  `json:"id"`
	RunID     string  `json:"run_id,omitempty"`
	CallID    string  `json:"call_id"`
	EntryID   string  `json:"entry_id"`
	Tool      string  `json:"tool"`
	Arguments ai.JSON `json:"arguments"`
	Body      string  `json:"body"`
	Digest    string  `json:"digest"`
	Substance string  `json:"substance,omitempty"`
	OK        bool    `json:"ok"`
	Truncated bool    `json:"truncated"`
}

Record is an actual committed tool result, not an assistant claim. Digest covers the complete result even when the bounded body is truncated.

type SkepticBlocking added in v0.1.9

type SkepticBlocking string

SkepticBlocking classifies a refute. BlockingNone is the ordinary model-fixable gap and the default for a missing or unrecognised value; the other two cannot progress by iterating.

const (
	BlockingNone          SkepticBlocking = "none"
	BlockingContradiction SkepticBlocking = "contradiction"
	BlockingUnverifiable  SkepticBlocking = "unverifiable"
)

SkepticBlocking values. BlockingNone is the default for a missing or unrecognised wire value and is the ordinary model-fixable gap.

type SkepticConfidence added in v0.1.9

type SkepticConfidence string

SkepticConfidence is a skeptic's own confidence in its verdict. A missing or unrecognised wire value becomes ConfidenceUnknown, so a fallback can never be decisive.

const (
	ConfidenceHigh    SkepticConfidence = "high"
	ConfidenceMedium  SkepticConfidence = "medium"
	ConfidenceLow     SkepticConfidence = "low"
	ConfidenceUnknown SkepticConfidence = "unknown"
)

SkepticConfidence values. ConfidenceUnknown is the default for a missing or unrecognised wire value, so a fallback can never be decisive.

type SkepticReport added in v0.1.9

type SkepticReport struct {
	Index          int
	Resumed        bool
	ChildSessionID string
	Refuted        bool
	Confidence     SkepticConfidence
	Blocking       SkepticBlocking
	Evidence       string
	DetailsMD      string
	// Failure names why this skeptic produced a synthetic refute instead of a
	// verdict document.
	Failure string
}

SkepticReport is one skeptic's diagnostic record in the panel report. It is additive: the per-skeptic detail stays the child's own durable transcript.

type SkepticRequest added in v0.1.9

type SkepticRequest struct {
	Index      int
	Total      int
	Prompt     string
	ResumeFrom string
	// ColdPrompt is the same skeptic's prompt with no prior session. A spawner
	// that cannot start the resume uses it, so a cold judge is never told it has
	// a transcript it does not have. It is empty for a request that never
	// resumes.
	ColdPrompt string
}

SkepticRequest is one skeptic's spawn request: its panel position, the task that carries the contract and the packet, and the completed child session a resumed skeptic continues.

type SkepticResult added in v0.1.9

type SkepticResult struct {
	Terminal       string
	ChildSessionID string
	Usage          ai.Usage
}

SkepticResult is one spawned skeptic's terminal answer.

type SkepticSpawner added in v0.1.9

type SkepticSpawner interface {
	Spawn(context.Context, SkepticRequest) (SkepticResult, error)
}

SkepticSpawner runs one skeptic as a real foreground child agent with the general-purpose tool inventory. A spawn or child failure is that skeptic's own failure; a failure of the transport itself is a panel-level failure and should be reported with SkepticTransportFailure.

type SkepticTransportError added in v0.1.9

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

SkepticTransportError marks a failure of the child transport itself, before any skeptic ran: the panel cannot spawn at all, so it is a panel-level failure rather than one skeptic's own.

func (*SkepticTransportError) Error added in v0.1.9

func (failure *SkepticTransportError) Error() string

func (*SkepticTransportError) Unwrap added in v0.1.9

func (failure *SkepticTransportError) Unwrap() error

type SkepticVerdict added in v0.1.9

type SkepticVerdict struct {
	Refuted    bool              `json:"refuted"`
	Evidence   string            `json:"evidence"`
	Confidence SkepticConfidence `json:"confidence"`
	Blocking   SkepticBlocking   `json:"blocking"`
	DetailsMD  string            `json:"details_md"`
	Findings   []Finding         `json:"findings"`
}

SkepticVerdict is the per-skeptic wire document: the reference's {refuted, evidence, confidence, blocking, findings, details_md}. The JSON tags are the wire names, so a test can marshal a scripted verdict.

type State

type State struct {
	Version     int      `json:"version"`
	Goal        ai.JSON  `json:"goal"`
	Evidence    Evidence `json:"evidence"`
	Digest      string   `json:"digest,omitempty"`
	EmptyRounds int      `json:"empty_rounds"`
	Gaps        []string `json:"gaps,omitempty"`
	References  []string `json:"references,omitempty"`
	// VerifyRuns counts the Goal's verification runs, capped by
	// goalVerifierMaxRuns and reset by an explicit resume.
	VerifyRuns int `json:"verify_runs,omitempty"`
	// GapStalls counts consecutive not-achieved verifications whose aggregate gap
	// digest was unchanged; GapDigest is that digest.
	GapStalls int    `json:"gap_stalls,omitempty"`
	GapDigest string `json:"gap_digest,omitempty"`
	// VerifyGaps is the last verification's aggregate gaps, rendered into the next
	// panel's PRIOR_GAPS block. It is additive, so an older state decodes.
	VerifyGaps []string `json:"verify_gaps,omitempty"`
	// Skeptic0Session is the first skeptic's child session id after a spawned
	// panel larger than one ran, so the next verification resumes it instead of
	// judging cold. It is additive, so an older state decodes.
	Skeptic0Session string `json:"skeptic0_session,omitempty"`
}

State is the Coding wrapper around the unchanged SDK Goal State V1. Digest and EmptyRounds are retained only so a state written before Phase AD still decodes: the three-unchanged-evidence guard they fed is gone, and no decision reads either of them. The verification fields are additive.

func Decode

func Decode(data ai.JSON) (State, error)

Decode validates persisted Coding Goal wrapper state.

func Prepare

func Prepare(condition string) (State, ai.JSON, error)

Prepare wraps the unchanged SDK Goal State V1.

type Verdict

type Verdict struct {
	Verified   bool
	Blocked    bool
	Reason     string
	Gaps       []string
	References []string
	// Skeptic0Session is the first skeptic's child session after a spawned
	// panel larger than one ran, so the next verification can resume it. It is
	// empty for an in-process panel and for a one-skeptic panel.
	Skeptic0Session string
}

Verdict is the internal aggregate the controller acts on. It is no longer the model-facing document — that is SkepticVerdict — so it carries no JSON tags. Blocked reports a panel whose every refuter is a non-model-fixable blocker.

type Verifier

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

Verifier audits captured evidence with a panel of independent skeptics. A spawned panel runs each skeptic as a foreground general-purpose child with the full tool inventory; the fallback runs each in-process over its own read-only workspace catalog.

func NewVerifier

func NewVerifier(
	ctx context.Context, model ai.LanguageModel, tree *workspace.Tree, options ...VerifierOption,
) (*Verifier, error)

NewVerifier constructs an isolated verifier without shell, MCP or delegation. It validates the read-only catalog once; each skeptic builds its own catalog at audit time, so no tool instance is shared between concurrent audits.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, packet Packet, evidence Evidence) (Verdict, ai.Usage, error)

Verify runs the panel: one independent audit per skeptic, in parallel, over the same immutable packet and the same prior gaps. With a spawner configured each skeptic is a real foreground general-purpose child; without one each is an in-process read-only audit over the recorded ledger. The verdicts are aggregated with the reference's cold majority, its decisive gatekeeper veto and its blocking route. A panel-level transport failure returns its error, which the Controller turns into a fail-closed pause; one skeptic's own spawn or child failure is that skeptic's synthetic refute. The Goal's budget is the driver's boundary check, so the panel carries no per-call token pre-check.

type VerifierOption added in v0.1.9

type VerifierOption func(*verifierConfig) error

VerifierOption configures the verifier's panel.

func WithChanges added in v0.1.9

func WithChanges(source ChangeSource) VerifierOption

WithChanges supplies the reference's per-verification change evidence. It is consulted once per verification; without one the packet renders the reference's own sentinels.

func WithPanelReport added in v0.1.9

func WithPanelReport(sink PanelReportSink) VerifierOption

WithPanelReport supplies the diagnostic sink the spawned panel's record is written to. It never gates a decision.

func WithSkeptics added in v0.1.9

func WithSkeptics(skeptics int) VerifierOption

WithSkeptics sets the number of independent skeptics. The count is clamped to the reference's one-through-five range, and the default is the reference's three.

func WithSpawner added in v0.1.9

func WithSpawner(spawner SkepticSpawner) VerifierOption

WithSpawner runs each skeptic as a real foreground child agent through the spawner. Without one the verifier keeps the in-process read-only auditor, so a unit test or an embedder that cannot serve a child keeps working.

Jump to

Keyboard shortcuts

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