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
- func Bound(text string, maximum int) string
- func CanonicalArguments(data ai.JSON) ai.JSON
- func DecodeStrict(data ai.JSON, value any) error
- func Digest(text string) string
- func Encode(value any) (ai.JSON, error)
- func PartsText(parts []ai.Part) string
- func SkepticTransportFailure(cause error) error
- func ValidUsage(usage ai.Usage) bool
- type ChangeSource
- type Changes
- type Controller
- type Evidence
- type Finding
- type Packet
- type PanelReportSink
- type Record
- type SkepticBlocking
- type SkepticConfidence
- type SkepticReport
- type SkepticRequest
- type SkepticResult
- type SkepticSpawner
- type SkepticTransportError
- type SkepticVerdict
- type State
- type Verdict
- type Verifier
- type VerifierOption
Constants ¶
const ( MaxRecords = 32 MaxResultBytes = 4096 MaxEvidenceBytes = 192 << 10 MaxGaps = 16 )
Evidence payload bounds are independent of provider context limits.
const MaxSkepticSessionBytes = 128
MaxSkepticSessionBytes bounds the resumed child session id the panel stores.
Variables ¶
This section is empty.
Functions ¶
func CanonicalArguments ¶
CanonicalArguments normalizes object ordering for evidence identity.
func DecodeStrict ¶
DecodeStrict rejects unknown fields, trailing values and oversized payloads.
func SkepticTransportFailure ¶ added in v0.1.9
SkepticTransportFailure wraps a transport-level failure, which Verify turns into the panel's infrastructure pause instead of a skeptic's synthetic refute.
func ValidUsage ¶
ValidUsage rejects impossible observed token counters.
Types ¶
type ChangeSource ¶ added in v0.1.9
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 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 ¶
func (c *Controller) Decide(ctx context.Context, request continuation.DecisionRequest) (continuation.Decision, error)
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 ¶
Merge retains a bounded latest-result ledger. Evicted essential evidence cannot authorize completion: truncation is sticky until explicit invalidation.
func (Evidence) Fingerprint ¶
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
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.
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.