learning

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"
)

func (k ActivityKind) Valid() bool

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"
)

func (c AdmissionClass) Valid() bool

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 AdmissionProvenance ¶ added in v0.14.0

type AdmissionProvenance struct {
	Class         AdmissionClass       `json:"class"`
	Source        AttemptSource        `json:"source"`
	CurrentPrompt CurrentPromptBinding `json:"current_prompt"`
	Binding       ProvenanceBinding    `json:"binding"`
}

AdmissionProvenance is immutable after creation. Validate must be called at every persistence or worker boundary; Binding detects field substitution.

func NewAdmissionProvenance(class AdmissionClass, source AttemptSource, prompt CurrentPromptBinding) (AdmissionProvenance, error)

func (p AdmissionProvenance) Validate(expected AttemptSource, expectedPrompt CurrentPromptBinding) error

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"
)

func (r AdmissionReason) Valid() bool

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(req AdmissionRequest) AdmissionDecision

type AttemptCheckpoint ¶ added in v0.14.0

type AttemptCheckpoint struct {
	Stage      AttemptCheckpointStage
	ProposalID ProposalID
	SkillID    SkillID
}

func (c AttemptCheckpoint) Validate() error

type AttemptCheckpointStage ¶ added in v0.14.0

type AttemptCheckpointStage string

const (
	AttemptCheckpointNone               AttemptCheckpointStage = ""
	AttemptCheckpointEvidenceVerified   AttemptCheckpointStage = "evidence_verified"
	AttemptCheckpointReflectionComplete AttemptCheckpointStage = "reflection_complete"
	AttemptCheckpointProposalLinked     AttemptCheckpointStage = "proposal_linked"
	AttemptCheckpointSkillLinked        AttemptCheckpointStage = "skill_linked"
)

func (s AttemptCheckpointStage) CanAdvanceTo(next AttemptCheckpointStage) bool

func (s AttemptCheckpointStage) Valid() bool

type AttemptClaim ¶ added in v0.14.0

type AttemptClaim struct {
	Generation ClaimGeneration `json:"generation"`
	ExpiresAt  time.Time       `json:"expires_at"`
}

func (c AttemptClaim) Valid() bool

func (c AttemptClaim) ValidAt(now time.Time) bool

type AttemptCreate ¶ added in v0.14.0

type AttemptCreate struct {
	ID         AttemptID
	Provenance AdmissionProvenance
}

func (c AttemptCreate) Validate() error

type AttemptFailureCode ¶ added in v0.14.0

type AttemptFailureCode string

const (
	FailureNone                AttemptFailureCode = ""
	FailureEvidenceUnavailable AttemptFailureCode = "evidence_unavailable"
	FailureEvaluationRejected  AttemptFailureCode = "evaluation_rejected"
	FailurePublicationFailed   AttemptFailureCode = "publication_failed"
	FailureClaimExpired        AttemptFailureCode = "claim_expired"
	FailureRetryExhausted      AttemptFailureCode = "retry_exhausted"
	FailureUnavailable         AttemptFailureCode = "unavailable"
	FailureInternal            AttemptFailureCode = "internal"
)

func (c AttemptFailureCode) Valid() bool

type AttemptFinalization ¶ added in v0.14.0

type AttemptFinalization struct {
	State       AttemptState
	Outcome     AttemptOutcome
	FailureCode AttemptFailureCode
}

func (f AttemptFinalization) Validate() error

type AttemptGeneration ¶ added in v0.14.0

type AttemptGeneration uint64

type AttemptID ¶ added in v0.14.0

type AttemptID string

func DeterministicAttemptID(caller string, source AttemptSource) (AttemptID, error)

type AttemptList ¶ added in v0.14.0

type AttemptList struct {
	After AttemptID
	Limit int
	State AttemptState
}

func (q AttemptList) Validate() error

type AttemptOutcome ¶ added in v0.14.0

type AttemptOutcome string

const (
	AttemptOutcomeNone      AttemptOutcome = ""
	AttemptOutcomeSucceeded AttemptOutcome = "succeeded"
	AttemptOutcomeAbstained AttemptOutcome = "abstained"
	AttemptOutcomeFailed    AttemptOutcome = "failed"
	AttemptOutcomeAbandoned AttemptOutcome = "abandoned"
)

func (o AttemptOutcome) Valid() bool

type AttemptPage ¶ added in v0.14.0

type AttemptPage struct {
	Records []AttemptRecord
	Next    AttemptID
}

type AttemptPartition ¶ added in v0.14.0

type AttemptPartition string

AttemptPartition is an opaque, one-way owner partition. Repositories must not persist or return the identity material from which it was derived.

func DeriveAttemptPartition(identity string) (AttemptPartition, error)

type AttemptProjection ¶ added in v0.14.0

type AttemptProjection struct {
	ID                AttemptID              `json:"id"`
	Version           AttemptVersion         `json:"version"`
	State             AttemptState           `json:"state"`
	Outcome           AttemptOutcome         `json:"outcome,omitempty"`
	FailureCode       AttemptFailureCode     `json:"failure_code,omitempty"`
	Source            AttemptSource          `json:"source"`
	AttemptGeneration AttemptGeneration      `json:"attempt_generation"`
	ClaimGeneration   ClaimGeneration        `json:"claim_generation,omitempty"`
	ClaimExpiresAt    time.Time              `json:"claim_expires_at,omitempty"`
	CheckpointStage   AttemptCheckpointStage `json:"checkpoint_stage,omitempty"`
	ProposalID        ProposalID             `json:"proposal_id,omitempty"`
	SkillID           SkillID                `json:"skill_id,omitempty"`
	CreatedAt         time.Time              `json:"created_at"`
	UpdatedAt         time.Time              `json:"updated_at"`
}

func ProjectAttempt(record AttemptRecord) (AttemptProjection, error)

type AttemptRecord ¶ added in v0.14.0

type AttemptRecord struct {
	ID                AttemptID              `json:"id"`
	Version           AttemptVersion         `json:"version"`
	State             AttemptState           `json:"state"`
	Outcome           AttemptOutcome         `json:"outcome,omitempty"`
	FailureCode       AttemptFailureCode     `json:"failure_code,omitempty"`
	Provenance        AdmissionProvenance    `json:"provenance"`
	AttemptGeneration AttemptGeneration      `json:"attempt_generation"`
	ClaimGeneration   ClaimGeneration        `json:"claim_generation,omitempty"`
	ClaimExpiresAt    time.Time              `json:"claim_expires_at,omitempty"`
	CheckpointStage   AttemptCheckpointStage `json:"checkpoint_stage,omitempty"`
	ProposalID        ProposalID             `json:"proposal_id,omitempty"`
	SkillID           SkillID                `json:"skill_id,omitempty"`
	CreatedAt         time.Time              `json:"created_at"`
	UpdatedAt         time.Time              `json:"updated_at"`
}

type AttemptRepository ¶ added in v0.14.0

type AttemptRepository interface {
	Create(context.Context, AttemptPartition, AttemptCreate) (AttemptRecord, error)
	Get(context.Context, AttemptPartition, AttemptID) (AttemptRecord, bool, error)
	List(context.Context, AttemptPartition, AttemptList) (AttemptPage, error)
	DiscoverWork(context.Context, AttemptWorkList) (AttemptWorkPage, error)
	AcquireClaim(context.Context, AttemptPartition, AttemptID, AttemptVersion, time.Duration) (AttemptRecord, AttemptClaim, error)
	RenewClaim(context.Context, AttemptPartition, AttemptID, AttemptVersion, AttemptClaim, time.Duration) (AttemptRecord, AttemptClaim, error)
	Checkpoint(context.Context, AttemptPartition, AttemptID, AttemptVersion, AttemptClaim, AttemptCheckpoint) (AttemptRecord, error)
	ReleaseClaim(context.Context, AttemptPartition, AttemptID, AttemptVersion, AttemptClaim) (AttemptRecord, error)
	Finalize(context.Context, AttemptPartition, AttemptID, AttemptVersion, AttemptClaim, AttemptFinalization) (AttemptRecord, error)
	Retry(context.Context, AttemptPartition, AttemptID, AttemptVersion) (AttemptRecord, error)
	Abandon(context.Context, AttemptPartition, AttemptID, AttemptVersion) (AttemptRecord, error)
	Delete(context.Context, AttemptPartition, AttemptID, AttemptVersion) error
	DeleteTerminalOlderThan(context.Context, AttemptPartition, time.Duration, int) (int, error)
}

AttemptRepository is the authoritative storage-neutral attempt lifecycle.

Every mutation is atomic. expected is an opaque CAS version from the latest returned record; stale values return ErrAttemptVersionConflict without a write. Create is idempotent for the same partition, ID, and immutable provenance and returns the existing record; an identity collision with different immutable material returns ErrAttemptCreateConflict. Each partition retains at most MaxAttemptsPerPartition records. Create at that boundary evicts only the oldest terminal record (UpdatedAt, then ID); if none exists it returns ErrAttemptQuotaExceeded without changing queued or running work. The limit and cleanup are partition-local, so saturation cannot block a peer.

AcquireClaim accepts queued attempts or running attempts whose claim is expired according to the repository backend's authoritative clock. Clients request a bounded duration; they never supply authority time or an absolute expiry. It allocates a strictly newer ClaimGeneration and returns the exact claim required by RenewClaim, Checkpoint, ReleaseClaim, and Finalize. Those operations atomically match expected and claim generation and require an expiry strictly after the backend's current time; otherwise they return ErrAttemptClaimLost without a write. AcquireClaim on a live claim returns ErrAttemptClaimConflict. ReleaseClaim returns running work to queued and clears the lease. Retry is failed-to-queued only, increments AttemptGeneration, and clears the claim. Abandon follows ValidAttemptTransition and must reject a live claim.

Checkpoint is monotonic by AttemptCheckpointStage. Replaying the same stage and links is permitted with the current version; rollback or changing links at a committed stage returns ErrAttemptTransition. Finalize accepts only AttemptFinalization.Validate terminal shapes and clears the claim.

Delete requires a terminal attempt or an unclaimed queued attempt. It must reject every claimed nonterminal attempt, including an expired claim, until a successor acquisition/release/abandon transition resolves it. DeleteTerminalOlderThan removes at most limit terminal records whose age, measured by the repository backend's authoritative clock, exceeds olderThan. The duration must be in (0, MaxAttemptRetentionAge]. DiscoverWork returns one bounded page of queued attempts and running attempts whose claim has expired according to that same clock, ordered by opaque partition then ID. Its cursor is an exclusive, disposable scan position; it grants no authority. This is the infrastructure worker's durable discovery seam, not a caller list or watch API.

type AttemptSource ¶ added in v0.14.0

type AttemptSource struct {
	SessionID       session.SessionID `json:"session_id"`
	RunID           DurableRunID      `json:"run_id"`
	CanonicalDigest CanonicalDigest   `json:"canonical_digest"`
}

func (s AttemptSource) Valid() bool

type AttemptState ¶ added in v0.14.0

type AttemptState string

const (
	AttemptQueued    AttemptState = "queued"
	AttemptRunning   AttemptState = "running"
	AttemptCompleted AttemptState = "completed"
	AttemptFailed    AttemptState = "failed"
	AttemptAbandoned AttemptState = "abandoned"
)

func (s AttemptState) Terminal() bool

func (s AttemptState) Valid() bool

type AttemptVersion ¶ added in v0.14.0

type AttemptVersion string

type AttemptWork ¶ added in v0.14.0

type AttemptWork struct {
	Partition AttemptPartition
	Record    AttemptRecord
}

AttemptWork identifies one repository-authoritative queued attempt or running attempt whose claim has expired. Partition is opaque infrastructure routing metadata and must never be projected to callers.

type AttemptWorkCursor ¶ added in v0.14.0

type AttemptWorkCursor struct {
	Partition AttemptPartition
	ID        AttemptID
}

type AttemptWorkList ¶ added in v0.14.0

type AttemptWorkList struct {
	After AttemptWorkCursor
	Limit int
}

func (q AttemptWorkList) Validate() error

type AttemptWorkPage ¶ added in v0.14.0

type AttemptWorkPage struct {
	Work []AttemptWork
	Next AttemptWorkCursor
}

type AutomaticAdmissionLedger ¶ added in v0.14.0

type AutomaticAdmissionLedger interface {
	Reserve(context.Context, AutomaticReservationRequest) (AutomaticReservation, error)
	Get(context.Context, AutomaticReservationID) (AutomaticReservation, bool, error)
	DiscoverExpired(context.Context, uint32) ([]AutomaticReservation, error)
	Reassign(context.Context, AutomaticReservationID, AutomaticReservationVersion) (AutomaticReservation, error)
	Retain(context.Context, AutomaticReservationID, AutomaticReservationVersion, AutomaticReservationFence) (AutomaticReservation, error)
	Reclaim(context.Context, AutomaticReservationID, AutomaticReservationVersion, AutomaticReservationFence) (AutomaticReservation, error)
}

AutomaticAdmissionLedger is the authoritative storage-neutral accounting seam for automatic learning admission. It is accounting and deduplication, not a work queue; admitted work enters AttemptRepository's existing queue.

Reserve atomically applies one global and one Principal-scoped sliding count and token window, global Digest deduplication, and Principal cooldown. A hard request bypasses cooldown only; it remains subject to dedupe and every budget. Same-ID retries with identical immutable material are idempotent. Changed immutable material returns ErrAutomaticReservationConflict. A different ID with a live dedupe digest returns ErrAutomaticAdmissionDuplicate. Limit and cooldown refusals return ErrAutomaticAdmissionLimit and ErrAutomaticAdmissionCooldown without creating a record.

Every mutation atomically matches expected and the current fence. Stale CAS returns ErrAutomaticReservationVersion; expired or superseded ownership returns ErrAutomaticReservationFence, both without a write. Reassign accepts only a held reservation at or after backend-clock fence expiry, mints its new expiry from the original ClaimDuration, advances generation, and never adds a second count/token charge. DiscoverExpired is the backend-authoritative recovery claim: it atomically selects at most limit held reservations whose fences have expired according to backend time, reassigns each under a fresh fence, and returns only those successfully claimed by this caller. A zero or over-maximum limit is invalid. The returned order is stable but carries no durable cursor; newly live fences naturally exclude claimed records until they expire again. A reconciler checks AttemptRepository and then retains or reclaims under that fresh fence.

Retain consumes the current fence as durable authority for the linked attempt-create boundary and makes its charge non-reclaimable. The caller must retain before AttemptRepository.Create; if create fails or its response is lost, the conservative charge remains and only a same-identity retry may finish creation. Later attempt failure, timeout, or abandonment does not refund it. Reclaim is valid only before create authority is consumed and releases effects atomically. Thus a successor first reassigns an expired uncertain reservation, checks AttemptRepository, then retains or reclaims exactly once. Natural charge, dedupe, and ownership expiry are evaluated against the backend-owned clock; callers cannot accelerate any transition with skew. Implementations retain at most MaxAutomaticReservationRecords globally and MaxAutomaticReservationRecordsPerPrincipal in one opaque principal partition. Resolved records may be removed only after dedupe expiry; unresolved saturation fails closed with ErrAutomaticAdmissionLimit rather than evicting held work.

type AutomaticAdmissionPolicy ¶ added in v0.14.0

type AutomaticAdmissionPolicy struct {
	Window                   time.Duration
	Cooldown                 time.Duration
	DedupeWindow             time.Duration
	MaxCount                 uint64
	MaxTokens                uint64
	MaxCountPerPrincipal     uint64
	MaxTokensPerPrincipal    uint64
	ReservationClaimDuration time.Duration
}

AutomaticAdmissionPolicy is immutable backend-owned admission policy. Zero limits are closed, not unlimited. Clients carry only its derived revision.

func (p AutomaticAdmissionPolicy) Validate() error

type AutomaticAdmissionPolicyRevision ¶ added in v0.14.0

type AutomaticAdmissionPolicyRevision string

func AutomaticAdmissionPolicyRevisionFor(p AutomaticAdmissionPolicy) (AutomaticAdmissionPolicyRevision, error)

type AutomaticChargeDisposition ¶ added in v0.14.0

type AutomaticChargeDisposition string

const (
	AutomaticChargeHeld      AutomaticChargeDisposition = "held"
	AutomaticChargeRetained  AutomaticChargeDisposition = "retained"
	AutomaticChargeReclaimed AutomaticChargeDisposition = "reclaimed"
)

func (d AutomaticChargeDisposition) Valid() bool

type AutomaticReservation ¶ added in v0.14.0

type AutomaticReservation struct {
	ID              AutomaticReservationID
	AttemptID       AttemptID
	Version         AutomaticReservationVersion
	Principal       AttemptPartition
	Digest          CanonicalDigest
	Class           AdmissionClass
	PolicyRevision  AutomaticAdmissionPolicyRevision
	Tokens          uint64
	Charge          AutomaticChargeDisposition
	AttemptCreated  bool
	ReservedAt      time.Time
	ChargeExpiresAt time.Time
	DedupeExpiresAt time.Time
	ClaimDuration   time.Duration
	Fence           AutomaticReservationFence
}

AutomaticReservation records one count charge and Tokens token charges. ChargeExpiresAt bounds budget accounting; DedupeExpiresAt may outlive it. AttemptCreated is monotonic and records that the current reservation fence was durably consumed to authorize the linked attempt-create boundary. Because the attempt repository is independent, it may be true while create's outcome is uncertain; that conservative charge cannot be reclaimed.

func (r AutomaticReservation) Validate() error

type AutomaticReservationFence ¶ added in v0.14.0

type AutomaticReservationFence struct {
	Generation AutomaticReservationGeneration
	ExpiresAt  time.Time
}

AutomaticReservationFence is the opaque ownership token for resolving a reservation. Expiry is exclusive; reassignment mints a newer generation.

func (f AutomaticReservationFence) Valid() bool

func (f AutomaticReservationFence) ValidAt(now time.Time) bool

type AutomaticReservationGeneration ¶ added in v0.14.0

type AutomaticReservationGeneration uint64

type AutomaticReservationID ¶ added in v0.14.0

type AutomaticReservationID string

func AutomaticReservationIDForAttempt(attemptID AttemptID) (AutomaticReservationID, error)

type AutomaticReservationRequest ¶ added in v0.14.0

type AutomaticReservationRequest struct {
	ID                     AutomaticReservationID
	AttemptID              AttemptID
	Principal              AttemptPartition
	Digest                 CanonicalDigest
	Class                  AdmissionClass
	Tokens                 uint64
	ExpectedPolicyRevision AutomaticAdmissionPolicyRevision
}

AutomaticReservationRequest is bounded, content-free admission material. Principal is an opaque one-way partition and Digest is the canonical input digest. Only weighted and genuine-current-user hard decisions are automatic; host-requested reflection remains an explicit path outside this ledger.

func (r AutomaticReservationRequest) Validate() error

type AutomaticReservationVersion ¶ added in v0.14.0

type AutomaticReservationVersion string

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(in Input, candidate Candidate) (Candidate, error)

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 (k CandidateKind) Valid() bool

type CanonicalDigest ¶ added in v0.14.0

type CanonicalDigest string

type ClaimGeneration ¶ added in v0.14.0

type ClaimGeneration uint64

type CurrentPromptBinding ¶ added in v0.14.0

type CurrentPromptBinding struct {
	Ordinal int             `json:"ordinal"`
	Digest  CanonicalDigest `json:"digest"`
	Origin  PromptOrigin    `json:"origin"`
}

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 DurableRunID ¶ added in v0.14.0

type DurableRunID string

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 (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(in Input, ordinal int, callID session.ToolCallID) (EvidenceRef, error)

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

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

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(trajectory Trajectory, events []session.Event, signals []Signal, existing []ExistingFact) Input

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 (s MessageSpan) Contains(ordinal int) bool

func (s MessageSpan) Valid(messageCount int) bool

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(s string) (Mode, error)

func (m Mode) Next() Mode

func (m Mode) String() string

type NeverPolicy ¶

type NeverPolicy struct{}

NeverPolicy disables automatic admission.

func (NeverPolicy) Decide(AdmissionRequest) AdmissionDecision

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 (k OutcomeKind) Valid() bool

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(in Input) (Projection, error)

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 PromptOrigin ¶ added in v0.14.0

type PromptOrigin string

const (
	PromptOriginCurrentPrincipal PromptOrigin = "current_principal"
	// PromptOriginSynthetic is an explicit invalid sentinel used by admission boundaries.
	PromptOriginSynthetic PromptOrigin = "synthetic"
)

func (o PromptOrigin) Valid() bool

type ProposalID ¶

type ProposalID string

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

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 (s ProposalStatus) Valid() bool

type ProposalVersion ¶

type ProposalVersion string

type ProvenanceBinding ¶ added in v0.14.0

type ProvenanceBinding 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
)

func ParseSensitivity(value string) (Sensitivity, error)

func (s Sensitivity) Next() Sensitivity

func (s Sensitivity) String() string

func (s Sensitivity) Threshold() int

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(in Input) []Signal

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

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 (k SignalKind) Valid() bool

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(value string) (SkillActivationPolicy, error)

func (p SkillActivationPolicy) Effective() SkillActivationPolicy

func (p SkillActivationPolicy) String() string

func (p SkillActivationPolicy) Valid() bool

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 SkillGeneration ¶ added in v0.14.0

type SkillGeneration uint64

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
	Generation SkillGeneration
}

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 {
	// Generation returns the durable monotonic generation for one caller/project
	// partition. Successful mutations advance only that partition.
	Generation(context.Context, SkillPartition) (SkillGeneration, error)
	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 (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 (p ThresholdPolicy) Decide(req AdmissionRequest) AdmissionDecision

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 {
	// RunID binds this completion to the durable host-minted run that produced it.
	// Empty or non-durable identities cannot authorize durable learning admission.
	RunID     string
	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(id session.SessionID, workspace string, stop session.StopReason, usage session.Usage, messages []session.Message) Trajectory

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 (d ValidationDisposition) Valid() bool

type VersionID ¶

type VersionID string

func SkillVersionID(bundle SkillBundle) (VersionID, error)