obscorpus

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 8 Imported by: 0

Documentation

Overview

Package obscorpus is the experimental OCA-V0 contract (docs/specs/observation-corpus-authority-v0.md): bounded harness observations and a sealed owner-labelled corpus replay. It is pure: it opens no file, network connection, or process, and no ranking, learning, evidence, or authority path imports it.

Index

Constants

View Source 
const (
	VerdictPass        = "PASS"
	VerdictFail        = "FAIL"
	VerdictNotRun      = "NOT_RUN"
	VerdictNotObserved = "NOT_OBSERVED"
)

Corpus verdicts (OCA-V0-005).

View Source 
const (
	ReasonResultMissing   = "result-missing"
	ReasonLabelMissing    = "label-missing"
	ReasonVerifierMissing = "verifier-result-missing"
	ReasonTelemetryAbsent = "telemetry-not-observed"
)

Closed verdict reasons.

View Source 
const (
	EvidenceOwnerLabelled = "owner-labelled"
	AuthorityNone         = "none"
	ScoringExactLabel     = "exact-label-match"
	MaxSubjects           = 1024
)

Non-authority markers every replay report carries (OCA-V0-004).

View Source 
const (
	StatusObserved    = "OBSERVED"
	StatusNotObserved = "NOT_OBSERVED"
)

Field and verdict states.

View Source 
const (
	ReasonNotReported      = "not-reported"
	ReasonCaptureFailed    = "capture-failed"
	ReasonOutOfBounds      = "out-of-bounds"
	ReasonNotImmutable     = "revision-not-immutable"
	ReasonUnboundedText    = "unbounded-text"
	ReasonSecretScreened   = "secret-screened"
	ReasonIdentityNotBound = "identity-not-observed"
	ReasonCountBound       = "count-bound"
)

Closed NOT_OBSERVED reasons for captured fields (OCA-V0-001..002).

View Source 
const (
	MaxIdentityBytes = 128
	MaxTokens        = 10_000_000
	MaxLatencyMillis = 3_600_000
	MaxObservations  = 256
)

Capture bounds.

Variables

View Source 
var (
	ErrInvalidCorpus  = errors.New("invalid corpus")
	ErrChangedCorpus  = errors.New("changed corpus inputs are a new corpus")
	ErrSealMismatch   = errors.New("result is not bound to this sealed corpus")
	ErrInvalidResults = errors.New("invalid replay results")
)

Refusals.

Functions

This section is empty.

Types

type Batch 

type Batch struct {
	Observations  []Observation `json:"observations"`
	Dropped       int           `json:"dropped"`
	DroppedReason string        `json:"droppedReason,omitempty"`
}

Batch is a count-bounded capture; observations past MaxObservations are dropped and counted.

func CaptureAll 

func CaptureAll(raws []RawTelemetry) Batch

CaptureAll captures at most MaxObservations reports in input order.

type Corpus 

type Corpus struct {
	Subjects          []Subject         `json:"subjects"`
	Labels            map[string]string `json:"labels"`
	EvaluatorRevision string            `json:"evaluatorRevision"`
	ScoringRule       string            `json:"scoringRule"`
}

Corpus is the owner's unsealed input. A subject without a label is allowed and can never score PASS.

type Count 

type Count struct {
	Status string `json:"status"`
	Value  *int64 `json:"value,omitempty"`
	Reason string `json:"reason,omitempty"`
}

Count is a bounded integer field. Value is nil unless directly observed, so a missing count can never read as zero.

type Observation 

type Observation struct {
	Status        string `json:"status"`
	Reason        string `json:"reason,omitempty"`
	Identity      Text   `json:"identity"`
	Revision      Text   `json:"revision"`
	InputTokens   Count  `json:"inputTokens"`
	OutputTokens  Count  `json:"outputTokens"`
	LatencyMillis Count  `json:"latencyMillis"`
}

Observation binds one event/turn identity to its revision, tokens, and latency.

func Capture 

func Capture(raw RawTelemetry) Observation

Capture bounds one raw report. It never fails: an unbound identity makes the whole observation NOT_OBSERVED so no measure is recorded unbound.

func CaptureFrom 

func CaptureFrom(source func() (RawTelemetry, error)) (observation Observation)

CaptureFrom is fail-open: a telemetry source that errors or panics yields a NOT_OBSERVED capture-failed observation and never blocks the harness event.

func (Observation) Complete 

func (o Observation) Complete() bool

Complete reports whether every field was directly observed.

type RawTelemetry 

type RawTelemetry struct {
	Identity      string `json:"identity"`
	Revision      string `json:"revision"`
	InputTokens   *int64 `json:"inputTokens"`
	OutputTokens  *int64 `json:"outputTokens"`
	LatencyMillis *int64 `json:"latencyMillis"`
}

RawTelemetry is what a harness reports. It has no field for prompts, source bodies, commands, or command output, so none can be captured (OCA-V0-006).

type Report 

type Report struct {
	Schema                string    `json:"schema"`
	SealID                string    `json:"sealId"`
	Evidence              string    `json:"evidence"`
	Authority             string    `json:"authority"`
	IndependentValidation bool      `json:"independentValidation"`
	Overall               string    `json:"overall"`
	Pass                  int       `json:"pass"`
	Fail                  int       `json:"fail"`
	NotRun                int       `json:"notRun"`
	NotObserved           int       `json:"notObserved"`
	Denominator           int       `json:"denominator"`
	Verdicts              []Verdict `json:"verdicts"`
}

Report is owner-labelled evidence, never authority. Denominator is every sealed subject and only PASS counts as success.

type Result 

type Result struct {
	SealID    string      `json:"sealId"`
	SubjectID string      `json:"subjectId"`
	Outcome   string      `json:"outcome"`
	Telemetry Observation `json:"telemetry"`
}

Result is one revealed verifier outcome for a sealed subject.

type Sealed 

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

Sealed is an immutable corpus identity; only Seal constructs one, so results can be scored only after the inputs are sealed.

func Seal 

func Seal(corpus Corpus) (Sealed, error)

Seal validates and seals a corpus independently of subject and label order.

func (Sealed) ID 

func (s Sealed) ID() string

ID is the SHA-256 of the canonical sealed subject/label/evaluator/scoring form.

func (Sealed) Replay 

func (s Sealed) Replay(results []Result) (Report, error)

Replay scores revealed results against the sealed corpus deterministically.

func (Sealed) Reuse 

func (s Sealed) Reuse(corpus Corpus) error

Reuse admits a corpus only when its sealed identity is identical.

type Subject 

type Subject struct {
	ID       string `json:"id"`
	Revision string `json:"revision"`
}

Subject is one corpus subject pinned to an immutable source revision.

type Text 

type Text struct {
	Status string `json:"status"`
	Value  string `json:"value,omitempty"`
	Reason string `json:"reason,omitempty"`
}

Text is a bounded string field; Value is set only when Status is OBSERVED.

type Verdict 

type Verdict struct {
	SubjectID string `json:"subjectId"`
	Verdict   string `json:"verdict"`
	Reason    string `json:"reason,omitempty"`
}

Verdict carries no outcome or label text, only the closed status and reason.

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.