learning

package
v1.10.4 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package learning defines lessons accepted from governed evidence.

Index

Constants

View Source 
const PrefixLesson id.Prefix = "lesson"

PrefixLesson identifies lessons accepted from ordinary verified runs.

Variables

View Source 
var (
	ErrInvalid     = errors.New("cortex: learning: invalid lesson")
	ErrDenied      = errors.New("cortex: learning: access denied")
	ErrConflict    = errors.New("cortex: learning: conflicting lesson revision")
	ErrUnavailable = errors.New("cortex: learning: capability unavailable")
	ErrNotFound    = errors.New("cortex: learning: lesson not found")
	ErrIneligible  = errors.New("cortex: learning: evidence is not eligible")
)

Stable errors distinguish unavailable authority, stale evidence and conflicts.

Functions

func Digest 

func Digest(lesson Lesson) (string, error)

Digest preserves the complete lesson's deterministic JSON representation.

func ValidateContent 

func ValidateContent(domain, statement string, applicability, contraindications []string) error

ValidateContent bounds lesson text without asserting that its claim is true.

func ValidateProvenance 

func ValidateProvenance(provenance run.ExecutionProvenance) error

ValidateProvenance rejects recalled lessons as independent evidence, including legacy source markers. Callers must supply the authoritative saved run.

func ValidatePurpose 

func ValidatePurpose(purpose run.ExecutionPurpose, state run.State, status verification.Status) error

ValidatePurpose permits only completed, passed ordinary runs as lesson sources.

func ValidateSnapshot 

func ValidateSnapshot(lesson Lesson, snapshot verification.ResultSnapshot, at time.Time) error

ValidateSnapshot reuses committed-result and report freshness validation. Ordinary lessons preserve the exact verified output; a derived claim needs its own verification. Source lessons cannot attest themselves through recall.

Types

type AcceptRequest 

type AcceptRequest struct {
	ID                id.ID                          `json:"id"`
	Domain            string                         `json:"domain"`
	Applicability     []string                       `json:"applicability"`
	Contraindications []string                       `json:"contraindications"`
	Result            verification.ResultReadRequest `json:"result"`
	ExpiresAt         time.Time                      `json:"expires_at"`
	Actor             string                         `json:"actor"`
	Corrects          *Ref                           `json:"corrects,omitempty"`
}

AcceptRequest proposes applicability for one current verified output. The repository supplies the statement and report digests from the saved result.

type Action 

type Action string

Action names the host grant needed for a lesson operation. 

const (
	ActionRead    Action = "read"
	ActionPublish Action = "publish"
	ActionRevoke  Action = "revoke"
	ActionRetry   Action = "retry"
)
const ActionDelete Action = "delete"

ActionDelete requires a host grant separate from ordinary publication ownership.

type Authorizer 

type Authorizer interface {
	AuthorizeLesson(context.Context, Action, Resource) error
}

Authorizer resolves the caller's current lesson grants. It supplies no default.

type DeletionRequest 

type DeletionRequest struct {
	ID               id.ID
	ExpectedRevision int64
	Actor            string
	Reason           string
}

DeletionRequest removes local lesson payloads, including historical outboxes. Reason is a bounded policy code, never deleted source content.

type EvidenceClass 

type EvidenceClass string

EvidenceClass separates observations from claims supported by verification. 

const (
	EvidenceValidated      EvidenceClass = "validated"
	EvidenceContrastive    EvidenceClass = "contrastive"
	EvidenceExploratory    EvidenceClass = "exploratory"
	EvidenceObservation    EvidenceClass = "observation"
	EvidenceFailedApproach EvidenceClass = "failed_approach"
)

func ClassifyActivity 

func ClassifyActivity(state run.State) EvidenceClass

ClassifyActivity labels an ordinary lifecycle observation. Completion alone never establishes a validated result, even if a caller mentions verification.

type Guard 

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

Guard rechecks local eligibility and source authority around each operation.

func NewGuard 

func NewGuard(config GuardConfig) (*Guard, error)

NewGuard requires explicit host authority and a synchronous revision fence.

func (*Guard) Accept 

func (g *Guard) Accept(ctx context.Context, request AcceptRequest) (Publication, error)

Accept commits lesson eligibility and its outbox while source grants are held.

func (*Guard) AcceptResult 

func (g *Guard) AcceptResult(ctx context.Context, request AcceptRequest, source verification.ResultContentRequest) (PublicationSummary, error)

AcceptResult derives the private receipt reference from current storage. You supply applicability and a stable lesson ID, never replacement answer text. Leave request.Result empty; source selects the governed result to accept.

func (*Guard) Authorize 

func (g *Guard) Authorize(ctx context.Context, action Action, identifier id.ID, domain string) error

Authorize checks exact caller scope before any model-visible lesson lookup.

func (*Guard) Delete 

func (g *Guard) Delete(ctx context.Context, request DeletionRequest) (Tombstone, error)

Delete authorizes retention workers independently of the lesson's old owner.

func (*Guard) Publications 

func (g *Guard) Publications(ctx context.Context, after string, limit int) (PublicationReviewPage, error)

Publications returns delivery metadata under current lesson grants. Source content is available only through Resolve and its result-evidence fence.

func (*Guard) Resolve 

func (g *Guard) Resolve(ctx context.Context, ref Ref) (Lesson, error)

Resolve returns a currently eligible lesson after source and grant checks.

func (*Guard) Retry 

func (g *Guard) Retry(ctx context.Context, identifier id.ID, revision, generation int64) error

Retry requests one new delivery cycle at the exact retained generation. It does not restore eligibility, extend retention or bypass delivery-time grants.

func (*Guard) Review 

func (g *Guard) Review(ctx context.Context, identifier id.ID) (LessonSummary, error)

Review returns metadata even after withdrawal, without restoring eligibility.

func (*Guard) Revoke 

func (g *Guard) Revoke(ctx context.Context, request RevokeRequest) (Publication, error)

Revoke withdraws local eligibility even when source evidence has expired.

func (*Guard) WithLesson 

func (g *Guard) WithLesson(ctx context.Context, ref Ref, action Action, operation func(context.Context, Lesson) error) (Lesson, error)

WithLesson holds current source authority around external delivery or hydration. It rechecks local withdrawal after the callback before returning any content.

type GuardConfig 

type GuardConfig struct {
	Repository       Repository
	Results          verification.ResultContentStore
	ContentAuthority verification.ResultContentAuthorizer
	Authority        Authorizer
	Fence            verification.CommitFence
	Clock            verification.Clock
}

GuardConfig supplies existing result provenance and current host fences.

type Lesson 

type Lesson struct {
	ID                id.ID                           `json:"id"`
	Scope             cortex.Scope                    `json:"scope"`
	Domain            string                          `json:"domain"`
	HarnessSchema     int                             `json:"harness_schema"`
	Statement         string                          `json:"statement"`
	Applicability     []string                        `json:"applicability"`
	Contraindications []string                        `json:"contraindications"`
	DecisionIDs       []id.ID                         `json:"decision_ids"`
	TrialIDs          []id.ID                         `json:"trial_ids"`
	EvidenceClass     EvidenceClass                   `json:"evidence_class"`
	Revision          int64                           `json:"revision"`
	CreatedAt         time.Time                       `json:"created_at"`
	ExpiresAt         time.Time                       `json:"expires_at"`
	RevokedAt         time.Time                       `json:"revoked_at"`
	RevocationReason  string                          `json:"revocation_reason,omitempty"`
	Result            *verification.ResultReadRequest `json:"result,omitempty"`
	SourceReports     []ReportRef                     `json:"source_reports,omitempty"`
	Corrects          *Ref                            `json:"corrects,omitempty"`
	SupersededBy      *Ref                            `json:"superseded_by,omitempty"`
}

Lesson retains local eligibility even if remote publication or revocation fails.

func (Lesson) Validate 

func (lesson Lesson) Validate(at time.Time) error

Validate checks stored ordinary lesson shape and expiry. It cannot authorize content or prove that the reports are still available; Resolve must do both.

type LessonSummary 

type LessonSummary struct {
	Ref            Ref           `json:"ref"`
	Domain         string        `json:"domain"`
	EvidenceClass  EvidenceClass `json:"evidence_class"`
	CreatedAt      time.Time     `json:"created_at"`
	ExpiresAt      time.Time     `json:"expires_at"`
	RevokedAt      time.Time     `json:"revoked_at"`
	SourceRunID    id.AgentRunID `json:"source_run_id"`
	SourceResultID id.ID         `json:"source_result_id"`
	Corrects       *Ref          `json:"corrects,omitempty"`
	SupersededBy   *Ref          `json:"superseded_by,omitempty"`
}

LessonSummary exposes identity and lifecycle without disclosing retained text. Read the source result through its current authorized publication path.

type Page 

type Page struct {
	Items []Lesson `json:"items"`
	Next  string   `json:"next,omitempty"`
}

Page returns individual lessons with their original applicability and evidence.

type Publication 

type Publication struct {
	LessonID         id.ID     `json:"lesson_id"`
	Revision         int64     `json:"revision"`
	SourceID         id.ID     `json:"source_id"`
	Operation        string    `json:"operation"`
	Payload          Lesson    `json:"payload"`
	PayloadDigest    string    `json:"payload_digest"`
	AggregateID      string    `json:"aggregate_id"`
	AcceptanceDigest string    `json:"acceptance_digest"`
	Actor            string    `json:"actor"`
	Generation       int64     `json:"generation"`
	Attempts         int       `json:"attempts"`
	Owner            string    `json:"owner"`
	LeaseUntil       time.Time `json:"lease_until"`
	NextAttempt      time.Time `json:"next_attempt"`
	ErrorCode        string    `json:"error_code"`
	Receipt          *Receipt  `json:"receipt,omitempty"`
}

Publication keeps one accepted payload and visible durable delivery progress.

type PublicationPage 

type PublicationPage struct {
	Items []Publication
	After string
}

PublicationPage is a bounded exact-scope scan of durable publication work.

type PublicationReviewPage 

type PublicationReviewPage struct {
	Items []PublicationSummary `json:"items"`
	After string               `json:"after,omitempty"`
}

PublicationReviewPage preserves the store's bounded exact-scope cursor.

type PublicationSummary 

type PublicationSummary struct {
	LessonID      id.ID     `json:"lesson_id"`
	Revision      int64     `json:"revision"`
	Domain        string    `json:"domain"`
	Operation     string    `json:"operation"`
	PayloadDigest string    `json:"payload_digest"`
	Generation    int64     `json:"generation"`
	Attempts      int       `json:"attempts"`
	LeaseUntil    time.Time `json:"lease_until"`
	NextAttempt   time.Time `json:"next_attempt"`
	ErrorCode     string    `json:"error_code,omitempty"`
	Acknowledged  bool      `json:"acknowledged"`
}

PublicationSummary excludes lesson text, actor input and retained result bytes. Acknowledged describes destination delivery, not current recall eligibility.

type Publisher 

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

Publisher drains one bounded page of exact-scope durable publication work. A host schedules repeated calls and supplies the worker's current authority.

func NewPublisher 

func NewPublisher(repository Repository, sink Sink, guard *Guard, owner string) (*Publisher, error)

NewPublisher requires durable storage and a guarded destination adapter.

func (*Publisher) Retry 

func (p *Publisher) Retry(ctx context.Context, publication Publication) error

Retry authorizes an operator-requested retry at an exact delivery generation.

func (*Publisher) WorkPage 

func (p *Publisher) WorkPage(ctx context.Context, after string) (string, error)

WorkPage resumes from the supplied durable scan cursor. Delivery leases and acknowledgments survive worker replacement; a lost reply keeps its aggregate ID.

type Query 

type Query struct {
	Scope         cortex.Scope `json:"scope"`
	Domain        string       `json:"domain"`
	HarnessSchema int          `json:"harness_schema"`
	Query         string       `json:"query"`
	Cutoff        time.Time    `json:"cutoff"`
	Limit         int          `json:"limit"`
	Cursor        string       `json:"cursor,omitempty"`
}

Query fixes exact scope, domain, schema and cutoff before semantic recall.

type Receipt 

type Receipt struct {
	LessonID       id.ID     `json:"lesson_id"`
	PayloadDigest  string    `json:"payload_digest"`
	AggregateID    string    `json:"aggregate_id"`
	Version        int64     `json:"version"`
	AcknowledgedAt time.Time `json:"acknowledged_at"`
}

Receipt binds one destination aggregate revision to the exact lesson payload.

type Ref 

type Ref struct {
	ID       id.ID  `json:"id"`
	Revision int64  `json:"revision"`
	Digest   string `json:"digest"`
}

Ref freezes local eligibility and content at experiment creation.

type ReportRef 

type ReportRef struct {
	ID     id.ID  `json:"id"`
	Digest string `json:"digest"`
}

ReportRef binds a source report to its exact immutable digest.

type Repository 

type Repository interface {
	AcceptLesson(context.Context, AcceptRequest) (Publication, error)
	GetLesson(context.Context, id.ID) (Lesson, error)
	ResolveLesson(context.Context, Ref) (Lesson, error)
	RevokeLesson(context.Context, RevokeRequest) (Publication, error)
	GetLessonPublication(context.Context, id.ID, int64) (Publication, error)
	ListLessonPublications(context.Context, string, int) (PublicationPage, error)
	ClaimLessonPublication(context.Context, id.ID, int64, string) (Publication, error)
	CompleteLessonPublication(context.Context, Publication, *Receipt, string) error
	RetryLessonPublication(context.Context, id.ID, int64, int64) error
}

Repository is an optional persistence capability shared by all root backends. Acceptance and its outbox commit together under the source run's transaction.

type Resource 

type Resource struct {
	Scope  cortex.Scope
	ID     id.ID
	Domain string
}

Resource binds host authorization to exact scope and optional lesson/domain.

type RetentionStore 

type RetentionStore interface {
	DeleteLesson(context.Context, DeletionRequest) (Tombstone, error)
	GetLessonTombstone(context.Context, id.ID) (Tombstone, error)
	ListLessonTombstones(context.Context, string, int) (TombstonePage, error)
}

RetentionStore erases local payloads and retains minimal exact-scope audit data. Remote event history has its own destination retention policy.

type RevokeRequest 

type RevokeRequest struct {
	ID               id.ID  `json:"id"`
	ExpectedRevision int64  `json:"expected_revision"`
	Actor            string `json:"actor"`
	Reason           string `json:"reason"`
}

RevokeRequest withdraws local eligibility at one expected revision.

type Sink 

type Sink interface {
	Deliver(context.Context, Publication) (Receipt, error)
}

Sink reconciles an accepted publication against authoritative remote state.

type Store 

type Store interface {
	Publish(context.Context, Lesson) (Receipt, error)
	Recall(context.Context, Query) (Page, error)
	Revoke(context.Context, RevokeRequest) error
}

Store is a governed destination. Publish requires an accepted durable outbox.

type Tombstone 

type Tombstone struct {
	ID          id.ID        `json:"id"`
	Scope       cortex.Scope `json:"scope"`
	Revision    int64        `json:"revision"`
	Digest      string       `json:"digest"`
	AggregateID string       `json:"aggregate_id"`
	Actor       string       `json:"actor"`
	Reason      string       `json:"reason"`
	DeletedAt   time.Time    `json:"deleted_at"`
}

Tombstone reserves an erased lesson identity without retaining its content.

type TombstonePage 

type TombstonePage struct {
	Items []Tombstone
	After string
}

TombstonePage is a bounded scan for restartable destination cleanup.

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.