learning

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package learning defines host-driven completed-trajectory observation, evidence-backed reflection, and evaluated agent-owned skill lifecycle values. It owns policy and bounded contracts only; persistence, scheduling, model transport, and runtime catalog activation remain host concerns.

Index

Constants

View Source 
const (
	MaxProposalsPerPartition = 4096
	MaxProposalDecisions     = 16
	MaxProposalReasonBytes   = 1024
	MaxProposalActorBytes    = 256
	DefaultProposalPageSize  = 50
	MaxProposalPageSize      = 200
)
View Source 
const (
	// MaxInputMessages bounds one reflection input's transcript.
	MaxInputMessages = 256
	// MaxInputEvents bounds one reflection input's optional event projection.
	MaxInputEvents = 512
	// MaxInputSignals bounds caller-supplied and structurally detected signals.
	MaxInputSignals = 64
	// MaxExistingFacts bounds comparison-only existing memory.
	MaxExistingFacts = 256
	// MaxCandidates bounds one reflection outcome.
	MaxCandidates = 16
	// MaxCandidateEvidence bounds the evidence handles attached to one candidate.
	MaxCandidateEvidence = 16
	// MaxCandidateKeyBytes bounds a fact's stable key.
	MaxCandidateKeyBytes = 256
	// MaxCandidateValueBytes bounds a fact's value.
	MaxCandidateValueBytes = 8 << 10
	// MaxCandidateDescriptionBytes bounds optional explanatory fact text.
	MaxCandidateDescriptionBytes = 2 << 10
	// MaxCandidateTitleBytes bounds a procedure title.
	MaxCandidateTitleBytes = 256
	// MaxCandidateBodyBytes bounds procedure content.
	MaxCandidateBodyBytes = 8 << 10
)
View Source 
const (
	MaxSkillsPerPartition       = 1024
	MaxSkillVersionsPerSkill    = 32
	MaxSkillReceipts            = 32
	MaxSkillReceiptHistory      = 32768
	MaxSkillEvaluations         = 16
	MaxSkillProposals           = 16
	MaxSkillEvidence            = 32
	MaxSkillSignals             = 16
	MaxSkillFixtures            = 32
	MaxSkillDescriptionBytes    = 1024
	MaxSkillBodyBytes           = 32 << 10
	MaxSkillEvaluationTextBytes = 4096
	MaxSkillOwnerBytes          = 256
	DefaultSkillPageSize        = 50
	MaxSkillPageSize            = 200
)

Variables

View Source 
var (
	ErrInvalidProposal         = errors.New("learning: invalid proposal")
	ErrProposalNotFound        = errors.New("learning: proposal not found")
	ErrProposalVersionConflict = errors.New("learning: proposal version conflict")
	ErrProposalTransition      = errors.New("learning: invalid proposal transition")
	ErrProposalLimit           = errors.New("learning: proposal limit exceeded")
)
View Source 
var (
	// ErrInvalidInput reports an invalid or unbounded reflection input.
	ErrInvalidInput = errors.New("learning: invalid reflection input")
	// ErrInvalidOutcome reports a malformed reflection outcome.
	ErrInvalidOutcome = errors.New("learning: invalid reflection outcome")
	// ErrInvalidCandidate reports a candidate that is unsafe, unbounded, or unsupported.
	ErrInvalidCandidate = errors.New("learning: invalid candidate")
	// ErrInvalidEvidence reports an evidence handle not resolvable against the exact input.
	ErrInvalidEvidence = errors.New("learning: invalid evidence reference")
)
View Source 
var (
	ErrInvalidSkill       = errors.New("learning: invalid skill")
	ErrSkillNotFound      = errors.New("learning: skill not found")
	ErrSkillConflict      = errors.New("learning: skill revision conflict")
	ErrSkillTransition    = errors.New("learning: invalid skill transition")
	ErrSkillLimit         = errors.New("learning: skill limit exceeded")
	ErrSkillOwnerMismatch = errors.New("learning: skill owner mismatch")
	ErrSkillNameCollision = errors.New("learning: skill name collision")
	ErrSkillCursor        = errors.New("learning: invalid or stale skill cursor")
)

Functions

func EvidenceHandle 

func EvidenceHandle(ref EvidenceRef) string

EvidenceHandle returns the compact model-facing handle for a reference.

func EvidencePreview 

func EvidencePreview(in Input, ref EvidenceRef) (string, error)

EvidencePreview returns the bounded canonical projection of one digest-verified evidence item. It excludes reasoning, raw tool/permission arguments, and binary bytes and applies the same secret/control repair used for reflector input.

func ResolveEvidence 

func ResolveEvidence(in Input, ref EvidenceRef) error

ResolveEvidence validates a content-addressed handle against the exact Input.

func ValidLearnedSkillName 

func ValidLearnedSkillName(name string) bool

func ValidateCandidate 

func ValidateCandidate(in Input, candidate Candidate) error

ValidateCandidate rejects unsupported, transient, unsafe, duplicate, or unevidenced durable proposals.

func ValidateDecision 

func ValidateDecision(d Decision) error

func ValidateInput 

func ValidateInput(in Input) error

ValidateInput enforces domain bounds and validates caller-supplied signals.

func ValidateOutcome 

func ValidateOutcome(in Input, out Outcome) error

ValidateOutcome enforces abstention/proposal structure and duplicate keys.

func ValidateProposalMaterial 

func ValidateProposalMaterial(p ProposalPartition, input string, c Candidate, signals []Signal) error

ValidateProposalMaterial validates the bounded persistence shape without requiring transcript data.

func ValidateSkillBundle 

func ValidateSkillBundle(bundle SkillBundle) error

func ValidateSkillCandidate 

func ValidateSkillCandidate(in Input, candidate Candidate) error

ValidateSkillCandidate requires the named procedure shape used for skill materialization.

func ValidateSkillEvaluation 

func ValidateSkillEvaluation(e SkillEvaluation) error

func ValidateSkillPartition 

func ValidateSkillPartition(partition SkillPartition, ownerAgent string) error

func ValidateSkillProvenance 

func ValidateSkillProvenance(p SkillProvenance) error

ValidateSkillProvenance validates bounded proposal, evidence, and signal linkage.

Types

type Activity 

type Activity struct {
	Kind        ActivityKind
	Reason      AdmissionReason
	Sensitivity Sensitivity
	Count       int64
}

Activity carries only closed labels and a count. It deliberately has no identity, path, digest, project, principal, session, or model-authored text.

type ActivityKind 

type ActivityKind string

ActivityKind is the closed, content-free learning telemetry vocabulary. 

const (
	ActivityAdmitted                ActivityKind = "admitted"
	ActivitySkipped                 ActivityKind = "skipped"
	ActivityRateLimited             ActivityKind = "rate_limited"
	ActivityDuplicate               ActivityKind = "duplicate"
	ActivityQueueFull               ActivityKind = "queue_full"
	ActivityClosed                  ActivityKind = "closed"
	ActivityAbstained               ActivityKind = "abstained"
	ActivityStaged                  ActivityKind = "staged"
	ActivityPromoted                ActivityKind = "promoted"
	ActivityConflicted              ActivityKind = "conflicted"
	ActivityFailed                  ActivityKind = "failed"
	ActivityTimedOut                ActivityKind = "timed_out"
	ActivityReservedTokens          ActivityKind = "reserved_tokens"
	ActivitySkillActivatedValidated ActivityKind = "skill_activated_validated"
	ActivitySkillActivatedEvaluated ActivityKind = "skill_activated_evaluated"
	ActivitySkillStaged             ActivityKind = "skill_staged"
	ActivitySkillRejected           ActivityKind = "skill_rejected"
)

Activity kinds cover admission, reflection outcomes, transitions, and reservation counts.

func (ActivityKind) Valid 

func (k ActivityKind) Valid() bool

Valid reports whether k belongs to the closed activity vocabulary.

type AdmissionClass 

type AdmissionClass string

AdmissionClass is the closed kind of an admission decision. 

const (
	AdmissionSkipped       AdmissionClass = "skipped"
	AdmissionWeighted      AdmissionClass = "weighted"
	AdmissionHard          AdmissionClass = "hard"
	AdmissionHostRequested AdmissionClass = "host_requested"
)

Admission class values distinguish skip, weighted, hard, and host-requested work.

func (AdmissionClass) Valid 

func (c AdmissionClass) Valid() bool

Valid reports whether c belongs to the closed admission-class vocabulary.

type AdmissionDecision 

type AdmissionDecision struct {
	Admitted  bool
	Class     AdmissionClass
	Score     int
	Threshold int
	Reasons   []AdmissionReason
	Signals   []Signal
}

AdmissionDecision is deterministic and content-free apart from its validated signals.

type AdmissionPolicy 

type AdmissionPolicy interface {
	Decide(AdmissionRequest) AdmissionDecision
}

AdmissionPolicy decides whether an automatic completed trajectory warrants reflection.

type AdmissionReason 

type AdmissionReason string

AdmissionReason is a closed, content-free explanation suitable for metrics. 

const (
	ReasonBelowThreshold           AdmissionReason = "below_threshold"
	ReasonInvalidCurrentSpan       AdmissionReason = "invalid_current_span"
	ReasonNonMainSession           AdmissionReason = "non_main_session"
	ReasonIneligibleStop           AdmissionReason = "ineligible_stop"
	ReasonTrivialRun               AdmissionReason = "trivial_run"
	ReasonExplicitRemember         AdmissionReason = "explicit_remember"
	ReasonExplicitLearnProcedure   AdmissionReason = "explicit_learn_procedure"
	ReasonRepeatedCorrection       AdmissionReason = "repeated_correction"
	ReasonTrustedHostContradiction AdmissionReason = "trusted_host_contradiction"
	ReasonFailureRecovery          AdmissionReason = "failure_recovery"
	ReasonRepeatedToolSequence     AdmissionReason = "repeated_tool_sequence"
	ReasonSubstantialSuccess       AdmissionReason = "substantial_success"
	ReasonModelTurnsModifier       AdmissionReason = "model_turns_modifier"
	ReasonSuccessfulToolsModifier  AdmissionReason = "successful_tools_modifier"
	ReasonRunTokensModifier        AdmissionReason = "run_tokens_modifier" //nolint:gosec // closed token-count label, not a credential
	ReasonPolicyAlways             AdmissionReason = "policy_always"
	ReasonPolicyNever              AdmissionReason = "policy_never"
	ReasonHostRequested            AdmissionReason = "host_requested"
	ReasonHardTrigger              AdmissionReason = "hard"
	ReasonWeightedThreshold        AdmissionReason = "weighted"
	ReasonDuplicate                AdmissionReason = "duplicate"
	ReasonRateLimit                AdmissionReason = "rate_limit"
	ReasonQueueFull                AdmissionReason = "queue_full"
	ReasonCoordinatorClosed        AdmissionReason = "closed"
	ReasonTimeout                  AdmissionReason = "timeout"
	ReasonReflectionFailed         AdmissionReason = "reflection_failed"
	ReasonAbstained                AdmissionReason = "abstained"
	ReasonStaged                   AdmissionReason = "staged"
	ReasonPromoted                 AdmissionReason = "promoted"
	ReasonConflicted               AdmissionReason = "conflicted"
)

Admission reasons are closed, content-free policy and modifier labels.

func (AdmissionReason) Valid 

func (r AdmissionReason) Valid() bool

Valid reports whether r belongs to the closed admission-reason vocabulary.

type AdmissionRequest 

type AdmissionRequest struct {
	Input Input
}

AdmissionRequest contains the bounded reflection input to classify.

type AlwaysPolicy 

type AlwaysPolicy struct{}

AlwaysPolicy admits valid main/current trajectories, primarily for hosts and tests.

func (AlwaysPolicy) Decide 

func (AlwaysPolicy) Decide(req AdmissionRequest) AdmissionDecision

Decide admits any valid main/current trajectory.

type Candidate 

type Candidate struct {
	Kind        CandidateKind `json:"kind"`
	Key         string        `json:"key,omitempty"`
	Value       string        `json:"value,omitempty"`
	Description string        `json:"description,omitempty"`
	Name        string        `json:"name,omitempty"`
	Title       string        `json:"title,omitempty"`
	Body        string        `json:"body,omitempty"`
	Evidence    []EvidenceRef `json:"evidence"`
}

Candidate is a bounded durable-learning proposal. Facts use Key, Value, and optional Description. Procedures use Title and Body; new skill-materializable procedures also carry Name. Name remains optional here so historical title/body procedure proposals remain readable.

func NewCandidate 

func NewCandidate(in Input, candidate Candidate) (Candidate, error)

NewCandidate validates and constructs a candidate against the exact input.

type CandidateKind 

type CandidateKind string

CandidateKind is the closed durable-learning vocabulary. The zero value is invalid. 

const (
	// CandidateOperatorFact is a durable operator-wide fact.
	CandidateOperatorFact CandidateKind = "operator_fact"
	// CandidateProjectFact is a durable project-scoped fact.
	CandidateProjectFact CandidateKind = "project_fact"
	// CandidateProcedure is a bounded title/body procedure proposal.
	CandidateProcedure CandidateKind = "procedure"
)

func (CandidateKind) Valid 

func (k CandidateKind) Valid() bool

Valid reports whether k belongs to the closed candidate vocabulary.

type Decision 

type Decision struct {
	Kind   DecisionKind `json:"kind"`
	Actor  string       `json:"actor,omitempty"`
	Reason string       `json:"reason,omitempty"`
	At     time.Time    `json:"at"`
}

type DecisionKind 

type DecisionKind string
const (
	DecisionApprove DecisionKind = "approve"
	DecisionReject  DecisionKind = "reject"
	DecisionDefer   DecisionKind = "defer"
)

type DetectionScope 

type DetectionScope struct {
	Current MessageSpan
}

DetectionScope limits signal evidence to the genuine current run.

type EvaluationVerdict 

type EvaluationVerdict string
const (
	EvaluationPass    EvaluationVerdict = "pass"
	EvaluationFail    EvaluationVerdict = "fail"
	EvaluationAbstain EvaluationVerdict = "abstain"
	// EvaluationError is the durable, non-activatable marker for an evaluator
	// infrastructure failure. It carries no provider error detail.
	EvaluationError EvaluationVerdict = "error"
)

func (EvaluationVerdict) Valid 

func (v EvaluationVerdict) Valid() bool

type EventProjection 

type EventProjection struct {
	Evidence   *EvidenceProjection `json:"evidence,omitempty"`
	Type       session.EventType   `json:"type"`
	Seq        int64               `json:"seq"`
	Turn       int                 `json:"turn"`
	Text       string              `json:"text,omitempty"`
	ToolCall   *ToolProjection     `json:"tool_call,omitempty"`
	ToolResult *ResultProjection   `json:"tool_result,omitempty"`
	Stop       session.StopReason  `json:"stop,omitempty"`
}

EventProjection is the canonical bounded evidence view of one supplied event.

type EvidenceEventData 

type EvidenceEventData struct {
	Type       session.EventType
	Seq        int64
	Turn       int
	Text       string
	ToolCall   *ToolProjection
	ToolResult *ResultProjection
	Stop       session.StopReason
}

EvidenceEventData is the owned, bounded subset of a session event that can become reflection evidence. It has no actor, permission arguments, or delegation payload.

type EvidenceLocator 

type EvidenceLocator string

EvidenceLocator identifies which bounded projection an EvidenceRef addresses. 

const (
	// EvidenceMessage identifies a trajectory message ordinal.
	EvidenceMessage EvidenceLocator = "message"
	// EvidenceEvent identifies a supplied event ordinal.
	EvidenceEvent EvidenceLocator = "event"
)

type EvidenceProjection 

type EvidenceProjection struct {
	Handle     string             `json:"handle"`
	Digest     string             `json:"digest"`
	EventSeq   *int64             `json:"event_seq,omitempty"`
	ToolCallID session.ToolCallID `json:"tool_call_id,omitempty"`
}

EvidenceProjection is model-facing content-addressed evidence metadata.

type EvidenceRef 

type EvidenceRef struct {
	SessionID  session.SessionID  `json:"session_id"`
	Locator    EvidenceLocator    `json:"locator"`
	Ordinal    int                `json:"ordinal"`
	EventSeq   *int64             `json:"event_seq,omitempty"`
	ToolCallID session.ToolCallID `json:"tool_call_id,omitempty"`
	Digest     string             `json:"digest"`
}

EvidenceRef is a content-addressed handle into the exact Input supplied to a reflector. Ordinal is zero-based in Trajectory.Messages or Input.Events.

func EventEvidenceRef 

func EventEvidenceRef(in Input, ordinal int, callID session.ToolCallID) (EvidenceRef, error)

EventEvidenceRef returns the canonical handle for an event ordinal.

func MessageEvidenceRef 

func MessageEvidenceRef(in Input, ordinal int, callID session.ToolCallID) (EvidenceRef, error)

MessageEvidenceRef returns the canonical handle for a message ordinal.

func ResolveEvidenceHandle 

func ResolveEvidenceHandle(in Input, handle string) (EvidenceRef, error)

ResolveEvidenceHandle resolves only a supplied m:<ordinal> or e:<ordinal> handle and returns its canonical digest-bound reference.

type ExistingFact 

type ExistingFact struct {
	Kind        CandidateKind `json:"kind"`
	Key         string        `json:"key"`
	Value       string        `json:"value"`
	Description string        `json:"description,omitempty"`
}

ExistingFact is bounded comparison data. It is never evidence and cannot carry procedure or promotion metadata.

type Input 

type Input struct {
	Trajectory Trajectory          `json:"trajectory"`
	Events     []EvidenceEventData `json:"events,omitempty"`
	Signals    []Signal            `json:"signals,omitempty"`
	Existing   []ExistingFact      `json:"existing,omitempty"`
}

Input is the bounded, owned material available to one reflection. Construct it with NewInput so transcript, event, signal, and existing-fact storage does not alias caller-owned values.

func NewInput 

func NewInput(trajectory Trajectory, events []session.Event, signals []Signal, existing []ExistingFact) Input

NewInput constructs an owned reflection input from existing session data.

type MessageProjection 

type MessageProjection struct {
	Evidence   *EvidenceProjection `json:"evidence,omitempty"`
	Role       session.Role        `json:"role"`
	Text       string              `json:"text,omitempty"`
	ToolCalls  []ToolProjection    `json:"tool_calls,omitempty"`
	ToolResult *ResultProjection   `json:"tool_result,omitempty"`
	Parts      []PartProjection    `json:"parts,omitempty"`
}

MessageProjection is the canonical, bounded, provider-neutral evidence view of a message.

type MessageSpan 

type MessageSpan struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

MessageSpan is a half-open range in Trajectory.Messages. A zero span is invalid.

func (MessageSpan) Contains 

func (s MessageSpan) Contains(ordinal int) bool

Contains reports whether ordinal belongs to the half-open span.

func (MessageSpan) Valid 

func (s MessageSpan) Valid(messageCount int) bool

Valid reports whether the span is non-empty and within messageCount.

type Mode 

type Mode uint8

Mode controls automatic completed-trajectory observation. The zero value is Off. 

const (
	// Off disables automatic completed-trajectory observation and is the zero value.
	Off Mode = iota
	// Review permits signal-gated reflection and durable proposal staging without memory writes.
	Review
	// Auto stages proposals and permits conservative eligible-fact promotion.
	Auto
)

func ParseMode 

func ParseMode(s string) (Mode, error)

ParseMode parses the closed settings vocabulary strictly.

func (Mode) Next 

func (m Mode) Next() Mode

Next returns the next mode in the operator-selection cycle Off → Review → Auto → Off.

func (Mode) String 

func (m Mode) String() string

type NeverPolicy 

type NeverPolicy struct{}

NeverPolicy disables automatic admission.

func (NeverPolicy) Decide 

func (NeverPolicy) Decide(AdmissionRequest) AdmissionDecision

Decide always returns the closed policy-never skip.

type Observer 

type Observer interface {
	Observe(context.Context, Trajectory) error
}

Observer synchronously observes an eligible completed trajectory. Implementations own any model calls or durable effects and should honor ctx.

type Outcome 

type Outcome struct {
	Kind       OutcomeKind `json:"kind"`
	Candidates []Candidate `json:"candidates,omitempty"`
}

Outcome is either explicit abstention with no candidates or a non-empty set of proposals.

type OutcomeKind 

type OutcomeKind string

OutcomeKind is the closed reflector result vocabulary. The zero value is invalid. 

const (
	// OutcomeAbstained means reflection intentionally produced no candidates.
	OutcomeAbstained OutcomeKind = "abstained"
	// OutcomeProposed means reflection produced one or more candidates.
	OutcomeProposed OutcomeKind = "proposed"
)

func (OutcomeKind) Valid 

func (k OutcomeKind) Valid() bool

Valid reports whether k belongs to the closed outcome vocabulary.

type PartProjection 

type PartProjection struct {
	Kind        string `json:"kind,omitempty"`
	MIMEType    string `json:"mime_type,omitempty"`
	Text        string `json:"text,omitempty"`
	Name        string `json:"name,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Binary      bool   `json:"binary,omitempty"`
}

PartProjection contains only bounded textual material and public media metadata.

type Projection 

type Projection struct {
	SessionID session.SessionID   `json:"session_id"`
	Stop      session.StopReason  `json:"stop,omitempty"`
	Messages  []MessageProjection `json:"messages"`
	Events    []EventProjection   `json:"events,omitempty"`
	Signals   []SignalProjection  `json:"signals,omitempty"`
	Existing  []ExistingFact      `json:"existing,omitempty"`
}

Projection is the canonical model-facing representation of Input. Existing facts are comparison-only and intentionally carry no evidence handles.

func ProjectInput 

func ProjectInput(in Input) (Projection, error)

ProjectInput builds the canonical bounded projection used both for evidence digests and for the model request.

type PromotionReceipt 

type PromotionReceipt struct {
	MemoryKey       string `json:"memory_key"`
	PreviousExists  bool   `json:"previous_exists"`
	PreviousVersion string `json:"previous_version,omitempty"`
	ResultVersion   string `json:"result_version"`
}

type ProposalID 

type ProposalID string

func DeterministicProposalID 

func DeterministicProposalID(p ProposalPartition, input string, c Candidate) (ProposalID, error)

DeterministicProposalID hashes identity, scope, input, candidate, and evidence digests; it never includes transcript text.

type ProposalList 

type ProposalList struct {
	After  ProposalID
	Limit  int
	Status ProposalStatus
}

type ProposalPage 

type ProposalPage struct {
	Records []ProposalRecord
	Next    ProposalID
}

type ProposalPartition 

type ProposalPartition struct {
	Principal string `json:"principal"`
	Project   string `json:"project,omitempty"`
}

type ProposalRecord 

type ProposalRecord struct {
	ID          ProposalID        `json:"id"`
	Version     ProposalVersion   `json:"version"`
	Status      ProposalStatus    `json:"status"`
	Partition   ProposalPartition `json:"partition"`
	InputDigest string            `json:"input_digest"`
	Candidate   Candidate         `json:"candidate"`
	Signals     []Signal          `json:"signals,omitempty"`
	Decisions   []Decision        `json:"decisions,omitempty"`
	Receipt     *PromotionReceipt `json:"receipt,omitempty"`
	SkillID     SkillID           `json:"skill_id,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
}

type ProposalRepository 

type ProposalRepository interface {
	StageBatch(context.Context, ProposalPartition, string, []Candidate, []Signal) ([]ProposalRecord, error)
	List(context.Context, ProposalPartition, ProposalList) (ProposalPage, error)
	Get(context.Context, ProposalPartition, ProposalID) (ProposalRecord, bool, error)
	ClaimDecision(context.Context, ProposalPartition, ProposalID, ProposalVersion, Decision) (ProposalRecord, error)
	ClaimPromotion(context.Context, ProposalPartition, ProposalID, ProposalVersion) (ProposalRecord, error)
	Finalize(context.Context, ProposalPartition, ProposalID, ProposalVersion, ProposalStatus, *PromotionReceipt, Decision) (ProposalRecord, error)
	LinkSkillDraft(context.Context, ProposalPartition, ProposalID, ProposalVersion, SkillID, Decision) (ProposalRecord, error)
}

type ProposalStatus 

type ProposalStatus string
const (
	ProposalStaged              ProposalStatus = "staged"
	ProposalPromoting           ProposalStatus = "promoting"
	ProposalPromoted            ProposalStatus = "promoted"
	ProposalRejected            ProposalStatus = "rejected"
	ProposalDeferredUnsupported ProposalStatus = "deferred_unsupported"
	ProposalConflicted          ProposalStatus = "conflicted"
	ProposalUndone              ProposalStatus = "undone"
	ProposalSkillMaterialized   ProposalStatus = "skill_materialized"
)

func (ProposalStatus) Valid 

func (s ProposalStatus) Valid() bool

type ProposalVersion 

type ProposalVersion string

type Reflector 

type Reflector interface {
	Reflect(context.Context, Input) (Outcome, error)
}

Reflector conservatively proposes durable learning from bounded evidence.

type ResultProjection 

type ResultProjection struct {
	CallID  session.ToolCallID `json:"call_id"`
	Content string             `json:"content,omitempty"`
	IsError bool               `json:"is_error,omitempty"`
	Parts   []PartProjection   `json:"parts,omitempty"`
}

ResultProjection excludes binary content and bounds all model/tool-authored text.

type Revision 

type Revision string

type Sensitivity 

type Sensitivity uint8

Sensitivity controls the score required for automatic weighted admission. Its order is tighten-only: Conservative < Balanced < Eager. 

const (
	SensitivityUnset Sensitivity = iota
	Conservative
	Balanced
	Eager
)

Sensitivity values are ordered from unset through increasingly eager policy.

func ParseSensitivity 

func ParseSensitivity(value string) (Sensitivity, error)

ParseSensitivity parses the strict lower-case settings vocabulary.

func (Sensitivity) Next 

func (s Sensitivity) Next() Sensitivity

Next returns the operator-selection cycle Conservative → Balanced → Eager → Conservative.

func (Sensitivity) String 

func (s Sensitivity) String() string

func (Sensitivity) Threshold 

func (s Sensitivity) Threshold() int

Threshold returns the standard weighted-admission threshold.

type Signal 

type Signal struct {
	Kind     SignalKind    `json:"kind"`
	Evidence []EvidenceRef `json:"evidence,omitempty"`
}

Signal is a host-supplied or structurally detected reflection admission hint. Evidence may be empty for a caller-supplied cross-session signal.

func DetectSignals 

func DetectSignals(in Input) []Signal

DetectSignals returns only signals structurally defensible within this input. It never invents cross-session repetition or contradiction; hosts supply those explicitly through Input.Signals.

func DetectSignalsScoped 

func DetectSignalsScoped(in Input, scope DetectionScope) []Signal

DetectSignalsScoped returns deterministic standard signals whose complete pattern evidence belongs to the genuine current run. Trusted host signals are deliberately limited to contradiction and host-requested provenance; callers cannot forge built-in evidence classes.

type SignalKind 

type SignalKind string

SignalKind is a closed reason to admit conservative reflection. A signal never proves that a durable candidate should be produced. 

const (
	// SignalSubstantialSuccess marks a substantial clean successful workflow.
	SignalSubstantialSuccess SignalKind = "substantial_success"
	// SignalRepeatedCorrection marks multiple correction turns in one input.
	SignalRepeatedCorrection SignalKind = "repeated_correction"
	// SignalFailureRecovery marks a same-tool failure followed by success.
	SignalFailureRecovery SignalKind = "failure_recovery"
	// SignalRepeatedToolSequence marks a stable repeated multi-tool sequence.
	SignalRepeatedToolSequence SignalKind = "repeated_tool_sequence"
	// SignalExplicitRemember marks a narrow explicit fact remember/learn request.
	SignalExplicitRemember SignalKind = "explicit_remember"
	// SignalExplicitLearnProcedure marks an explicit request to retain a reusable procedure.
	SignalExplicitLearnProcedure SignalKind = "explicit_learn_procedure"
	// SignalContradiction is supplied by a trusted host with cross-session knowledge.
	SignalContradiction SignalKind = "contradiction"
	// SignalHostRequested marks an authenticated explicit reflection request. It is
	// host provenance, not evidence that automatic learning should run.
	SignalHostRequested SignalKind = "host_requested"
)

func (SignalKind) Valid 

func (k SignalKind) Valid() bool

Valid reports whether k belongs to the closed signal vocabulary.

type SignalProjection 

type SignalProjection struct {
	Kind     SignalKind `json:"kind"`
	Evidence []string   `json:"evidence,omitempty"`
}

SignalProjection is a model-facing admission hint whose evidence uses only supplied compact handles.

type SkillActivationPolicy 

type SkillActivationPolicy string

SkillActivationPolicy controls the assurance required for automatic learned-skill activation. 

const (
	// SkillActivationEvaluated requires a trusted evaluator PASS. It is the zero
	// value to preserve the historical engine/embedder policy.
	SkillActivationEvaluated SkillActivationPolicy = "evaluated"
	// SkillActivationValidated permits structurally validated, evidence-backed
	// ABSTAIN candidates to activate without granting any additional capability.
	SkillActivationValidated SkillActivationPolicy = "validated"
)

func ParseSkillActivationPolicy 

func ParseSkillActivationPolicy(value string) (SkillActivationPolicy, error)

ParseSkillActivationPolicy parses the closed activation-policy vocabulary.

func (SkillActivationPolicy) Effective 

func (p SkillActivationPolicy) Effective() SkillActivationPolicy

Effective returns evaluated for the zero value.

func (SkillActivationPolicy) String 

func (p SkillActivationPolicy) String() string

String returns the configuration token, treating zero as evaluated.

func (SkillActivationPolicy) Valid 

func (p SkillActivationPolicy) Valid() bool

Valid reports whether policy belongs to the closed vocabulary.

type SkillBundle 

type SkillBundle struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Body        string `json:"body"`
}

type SkillDraftInput 

type SkillDraftInput struct {
	Partition  SkillPartition
	OwnerAgent string
	Bundle     SkillBundle
	Provenance SkillProvenance
}

SkillDraftInput is a validated body-only draft ready for repository creation.

type SkillEvaluation 

type SkillEvaluation struct {
	Verdict    EvaluationVerdict `json:"verdict"`
	FixtureIDs []string          `json:"fixture_ids,omitempty"`
	Baseline   string            `json:"baseline,omitempty"`
	Treatment  string            `json:"treatment,omitempty"`
	Reason     string            `json:"reason,omitempty"`
	At         time.Time         `json:"at"`
}

type SkillEvaluationRequest 

type SkillEvaluationRequest struct {
	Partition  SkillPartition
	OwnerAgent string
	Version    SkillVersion
}

type SkillEvaluator 

type SkillEvaluator interface {
	Evaluate(context.Context, SkillEvaluationRequest) (SkillEvaluation, error)
}

SkillEvaluator is trusted host admission control. ABSTAIN is a deliberate, validated-eligible decision; infrastructure failures must return an error and are persisted by the lifecycle as the distinct, non-activatable ERROR verdict.

type SkillID 

type SkillID string

type SkillInventoryItem 

type SkillInventoryItem struct {
	Name       string
	OwnerAgent string
	AgentOwned bool
	Bundle     SkillBundle
	SkillID    SkillID
	Version    VersionID
}

type SkillList 

type SkillList struct {
	After      SkillID
	Limit      int
	Name       string
	State      SkillState
	OwnerAgent string
}

type SkillPage 

type SkillPage struct {
	Versions []SkillVersion
	Next     SkillID
}

type SkillPartition 

type SkillPartition struct {
	Principal string `json:"principal"`
	Project   string `json:"project,omitempty"`
}

type SkillProvenance 

type SkillProvenance struct {
	Origin                SkillProvenanceOrigin `json:"origin,omitempty"`
	ValidationDisposition ValidationDisposition `json:"validation_disposition,omitempty"`
	ProposalIDs           []ProposalID          `json:"proposal_ids,omitempty"`
	EvidenceRefs          []EvidenceRef         `json:"evidence_refs,omitempty"`
	Signals               []Signal              `json:"signals,omitempty"`
}

type SkillProvenanceOrigin 

type SkillProvenanceOrigin string
const (
	// SkillProvenanceLegacyModel marks an explicitly imported origin:model quarantine draft.
	// It is the sole provenance allowed without proposal, evidence, or signal linkage.
	SkillProvenanceLegacyModel SkillProvenanceOrigin = "legacy_model"
)

type SkillReceipt 

type SkillReceipt struct {
	Operation string     `json:"operation"`
	From      SkillState `json:"from"`
	To        SkillState `json:"to"`
	Version   VersionID  `json:"version"`
	At        time.Time  `json:"at"`
}

type SkillReceiptList 

type SkillReceiptList struct {
	After string
	Limit int
}

type SkillReceiptPage 

type SkillReceiptPage struct {
	Records []SkillReceiptRecord
	Next    string
}

type SkillReceiptRecord 

type SkillReceiptRecord struct {
	ID         string
	SkillID    SkillID
	Name       string
	OwnerAgent string
	Version    VersionID
	Receipt    SkillReceipt
}

type SkillReceiptRepository 

type SkillReceiptRepository interface {
	ListSkillReceipts(context.Context, SkillPartition, SkillReceiptList) (SkillReceiptPage, error)
}

SkillReceiptRepository is the optional bounded durable lifecycle-history seam. Cursors are opaque and stale/invalid cursors fail with ErrSkillCursor.

type SkillRepository 

type SkillRepository interface {
	CreateDraft(context.Context, SkillPartition, string, SkillBundle, SkillProvenance) (SkillVersion, error)
	Get(context.Context, SkillPartition, string, SkillID, VersionID) (SkillVersion, bool, error)
	List(context.Context, SkillPartition, SkillList) (SkillPage, error)
	RecordEvaluation(context.Context, SkillPartition, string, SkillID, VersionID, Revision, SkillEvaluation) (SkillVersion, error)
	Stage(context.Context, SkillPartition, string, SkillID, VersionID, Revision) (SkillVersion, error)
	Activate(context.Context, SkillPartition, string, SkillID, VersionID, Revision) (SkillVersion, error)
	Reject(context.Context, SkillPartition, string, SkillID, VersionID, Revision) (SkillVersion, error)
	Archive(context.Context, SkillPartition, string, SkillID, VersionID, Revision) (SkillVersion, error)
	Rollback(context.Context, SkillPartition, string, SkillID, Revision, VersionID) (SkillVersion, error)
}

type SkillState 

type SkillState string
const (
	SkillDraft     SkillState = "draft"
	SkillEvaluated SkillState = "evaluated"
	SkillStaged    SkillState = "staged"
	SkillActive    SkillState = "active"
	SkillArchived  SkillState = "archived"
	SkillRejected  SkillState = "rejected"
)

func (SkillState) Valid 

func (s SkillState) Valid() bool

type SkillValidation 

type SkillValidation struct {
	Disposition ValidationDisposition
	Duplicate   *SkillInventoryItem
	Similar     []SkillInventoryItem
}

type SkillValidationRequest 

type SkillValidationRequest struct {
	Partition  SkillPartition
	OwnerAgent string
	Bundle     SkillBundle
	Provenance SkillProvenance
	Assets     []string
	Inventory  []SkillInventoryItem
}

type SkillValidator 

type SkillValidator interface {
	Validate(context.Context, SkillValidationRequest) (SkillValidation, error)
}

type SkillVersion 

type SkillVersion struct {
	ID          SkillID               `json:"id"`
	Version     VersionID             `json:"version"`
	Revision    Revision              `json:"revision"`
	State       SkillState            `json:"state"`
	OwnerAgent  string                `json:"owner_agent"`
	Partition   SkillPartition        `json:"partition"`
	Bundle      SkillBundle           `json:"bundle"`
	Provenance  SkillProvenance       `json:"provenance"`
	Disposition ValidationDisposition `json:"validation_disposition,omitempty"`
	Evaluations []SkillEvaluation     `json:"evaluations,omitempty"`
	Receipts    []SkillReceipt        `json:"receipts,omitempty"`
	Supersedes  VersionID             `json:"supersedes,omitempty"`
	CreatedAt   time.Time             `json:"created_at"`
	UpdatedAt   time.Time             `json:"updated_at"`
}

SkillVersion is an immutable body revision plus CAS-controlled lifecycle metadata. Bundle, Version, Supersedes, OwnerAgent, Partition, and CreatedAt never change.

type ThresholdPolicy 

type ThresholdPolicy struct{ Sensitivity Sensitivity }

ThresholdPolicy implements the standard weighted and hard-trigger policy.

func (ThresholdPolicy) Decide 

func (p ThresholdPolicy) Decide(req AdmissionRequest) AdmissionDecision

Decide applies hard provenance, stop/kind exclusions, standard weights, and modifiers.

type ToolProjection 

type ToolProjection struct {
	ID   session.ToolCallID `json:"id"`
	Name string             `json:"name"`
}

ToolProjection excludes raw arguments and provider item identifiers.

type Trajectory 

type Trajectory struct {
	SessionID session.SessionID
	Workspace string
	Stop      session.StopReason
	Usage     session.Usage
	Messages  []session.Message
	// Kind identifies the trusted producer. Automatic admission accepts main only.
	Kind session.SessionKind
	// Counters are the completed current run's model/tool counters.
	Counters session.Counters
	// Current is the verified half-open message span for the current run.
	Current MessageSpan
	// Principal is a copied completed-session owner for host partitioning.
	Principal *session.Principal
}

Trajectory is an owned snapshot of one newly completed run. Messages has a fresh backing slice and never aliases a live session aggregate.

func NewTrajectory 

func NewTrajectory(id session.SessionID, workspace string, stop session.StopReason, usage session.Usage, messages []session.Message) Trajectory

NewTrajectory constructs an owned completed-run snapshot. Every mutable nested value is copied so an Observer cannot mutate the live or persisted Session history.

type ValidatedSkillActivator 

type ValidatedSkillActivator interface {
	ActivateValidated(context.Context, SkillPartition, string, SkillID, VersionID, Revision) (SkillVersion, error)
}

ValidatedSkillActivator is an optional repository capability for the lower- assurance automatic path. Implementations must atomically enforce evidence, exact/accepted validation, ABSTAIN, staged state, ownership, partition, and CAS.

type ValidationDisposition 

type ValidationDisposition string

ValidationDisposition describes logical admission without mutating a repository. 

const (
	ValidationAccept           ValidationDisposition = "accept"
	ValidationExactDuplicate   ValidationDisposition = "exact_duplicate"
	ValidationSimilarStageHint ValidationDisposition = "similar_stage_hint"
)

func (ValidationDisposition) Valid 

func (d ValidationDisposition) Valid() bool

type VersionID 

type VersionID string

func SkillVersionID 

func SkillVersionID(bundle SkillBundle) (VersionID, error)

SkillVersionID content-addresses a body-only bundle. Provenance and lifecycle do not affect it.

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.