receipt

Documentation

Overview

Package receipt projects privacy-safe, portable observations from Yield's authoritative append-only run journal.

Index

• Constants
• func CanonicalBytes(value any) ([]byte, error)
• func Seal(receipt *RunReceipt) error
• func VerifyCanonical(receipt *RunReceipt, raw []byte) error
• type DivergenceOutcome
• type ExperimentContext
  • func DecodeExperiment(raw []byte) (*ExperimentContext, error)
  • func (context ExperimentContext) Validate() error
• type JournalBinding
• type LocalReport
  • func BuildReport(receipts []*RunReceipt, options ReportOptions) (LocalReport, error)
• type NamedCount
• type OperationObservation
• type OperationSummary
• type OutcomeSummary
• type ProfileDigest
• type ReportOperationSummary
• type ReportOptions
• type RequirementOutcome
• type ResponseRejectionSummary
• type RunIdentity
• type RunReceipt
  • func Project(snapshot Snapshot) (*RunReceipt, error)
  • func (receipt *RunReceipt) Validate() error
• type RuntimeIdentity
• type SkillIdentity
• type Snapshot
• type Store
  • func NewStore(yieldDir string) *Store
  • func StoreForRunsDir(runsDir string) *Store
  • func (s *Store) ListRuns() ([]string, error)
  • func (s *Store) LoadDigest(receiptDigest string) (*RunReceipt, []byte, error)
  • func (s *Store) LoadRun(runID string) (*RunReceipt, []byte, error)
  • func (s *Store) Materialize(snapshot Snapshot) (*RunReceipt, []byte, error)
  • func (s *Store) Put(r *RunReceipt, raw []byte) error
• type TimingSummary

Constants

const (
	Schema = "yield.observation.v1"
	Kind   = "run_receipt"
)

Functions

func CanonicalBytes

func CanonicalBytes(value any) ([]byte, error)

CanonicalBytes returns RFC 8785-compatible JSON for the receipt's closed, integer-only data model.

func Seal

func Seal(receipt *RunReceipt) error

Seal sets the deterministic receipt digest.

func VerifyCanonical

func VerifyCanonical(receipt *RunReceipt, raw []byte) error

VerifyCanonical proves that bytes are the canonical encoding named by the receipt digest.

Types

type DivergenceOutcome

type DivergenceOutcome struct {
	Sequence int    `json:"sequence"`
	Expected string `json:"expected_digest"`
	Got      string `json:"got_digest"`
}

type ExperimentContext

type ExperimentContext struct {
	ExperimentID       string `json:"experiment_id"`
	CohortID           string `json:"cohort_id,omitempty"`
	VariantID          string `json:"variant_id"`
	Role               string `json:"role"`
	BaselineVariantID  string `json:"baseline_variant_id,omitempty"`
	ParentSkillVersion string `json:"parent_skill_version,omitempty"`
}

func DecodeExperiment

func DecodeExperiment(raw []byte) (*ExperimentContext, error)

DecodeExperiment admits a closed, non-personal experiment context.

func (ExperimentContext) Validate

func (context ExperimentContext) Validate() error

type JournalBinding

type JournalBinding struct {
	RunID        string `json:"run_id"`
	HeadSequence int    `json:"head_sequence"`
	HeadDigest   string `json:"head_digest"`
}

type LocalReport

type LocalReport struct {
	ReceiptCount           int                      `json:"receipt_count"`
	Lifecycle              []NamedCount             `json:"lifecycle"`
	Terminal               []NamedCount             `json:"terminal"`
	Operations             []ReportOperationSummary `json:"operations"`
	ResponseRejections     []NamedCount             `json:"response_rejections"`
	Requirements           []NamedCount             `json:"requirements"`
	DivergenceCount        int                      `json:"divergence_count"`
	RuntimeGroups          []NamedCount             `json:"runtime_groups"`
	SourceGroups           []NamedCount             `json:"source_groups"`
	ExperimentGroups       []NamedCount             `json:"experiment_groups"`
	OpenOlderThanThreshold int                      `json:"open_older_than_threshold,omitempty"`
}

func BuildReport

func BuildReport(receipts []*RunReceipt, options ReportOptions) (LocalReport, error)

type NamedCount

type NamedCount struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

type OperationObservation

type OperationObservation struct {
	Sequence           int             `json:"sequence"`
	Kind               protocol.OpKind `json:"kind"`
	OperationKeyDigest string          `json:"operation_key_digest"`
	RequestedAt        string          `json:"requested_at"`
	CompletedAt        string          `json:"completed_at,omitempty"`
	ElapsedMS          *int64          `json:"elapsed_ms,omitempty"`
	ResultDigest       string          `json:"result_digest,omitempty"`
	ClockAnomaly       bool            `json:"clock_anomaly,omitempty"`
}

type OperationSummary

type OperationSummary struct {
	Kind           protocol.OpKind `json:"kind"`
	Requested      int             `json:"requested"`
	Completed      int             `json:"completed"`
	TotalElapsedMS int64           `json:"total_elapsed_ms"`
}

type OutcomeSummary

type OutcomeSummary struct {
	Phase               string `json:"phase"`
	TerminalDisposition string `json:"terminal_disposition,omitempty"`
	TerminalCause       string `json:"terminal_cause,omitempty"`
	ResultDigest        string `json:"result_digest,omitempty"`
	FailureCode         string `json:"failure_code,omitempty"`
}

type ProfileDigest

type ProfileDigest struct {
	Profile string `json:"profile"`
	Value   string `json:"value"`
}

type ReportOperationSummary

type ReportOperationSummary struct {
	Kind           protocol.OpKind `json:"kind"`
	Requested      int             `json:"requested"`
	Completed      int             `json:"completed"`
	TotalElapsedMS int64           `json:"total_elapsed_ms"`
}

type ReportOptions

type ReportOptions struct {
	From             time.Time
	To               time.Time
	OpenAgeThreshold time.Duration
	ReferenceTime    time.Time
	ExperimentID     string
}

type RequirementOutcome

type RequirementOutcome struct {
	Outcome        string `json:"outcome"`
	ClaimDigest    string `json:"claim_digest"`
	EvidenceDigest string `json:"evidence_digest,omitempty"`
}

type ResponseRejectionSummary

type ResponseRejectionSummary struct {
	Reason string `json:"reason"`
	Count  int    `json:"count"`
}

type RunIdentity

type RunIdentity struct {
	ID          string `json:"id"`
	InputDigest string `json:"input_digest,omitempty"`
}

type RunReceipt

type RunReceipt struct {
	Schema             string                     `json:"schema"`
	Kind               string                     `json:"kind"`
	ReceiptDigest      string                     `json:"receipt_digest,omitempty"`
	Journal            JournalBinding             `json:"journal"`
	Run                RunIdentity                `json:"run"`
	Skill              SkillIdentity              `json:"skill"`
	Runtime            *RuntimeIdentity           `json:"runtime,omitempty"`
	Timing             TimingSummary              `json:"timing"`
	Operations         []OperationObservation     `json:"operations"`
	OperationSummaries []OperationSummary         `json:"operation_summaries"`
	Outcome            OutcomeSummary             `json:"outcome"`
	Requirements       []RequirementOutcome       `json:"requirements"`
	ResponseRejections []ResponseRejectionSummary `json:"response_rejections"`
	Divergences        []DivergenceOutcome        `json:"divergences"`
	Experiment         *ExperimentContext         `json:"experiment,omitempty"`
}

func Project

func Project(snapshot Snapshot) (*RunReceipt, error)

Project deterministically derives one receipt from one exact journal prefix.

func (*RunReceipt) Validate

func (receipt *RunReceipt) Validate() error

Validate checks the closed Go representation against the public contract.

type RuntimeIdentity

type RuntimeIdentity struct {
	SupervisorVersion string `json:"supervisor_version,omitempty"`
	RequiredVersion   string `json:"required_version,omitempty"`
	Compatible        *bool  `json:"compatible,omitempty"`
}

type SkillIdentity

type SkillIdentity struct {
	Name          string         `json:"name"`
	Version       string         `json:"version,omitempty"`
	BindingDigest string         `json:"binding_digest,omitempty"`
	SourceDigest  *ProfileDigest `json:"source_digest,omitempty"`
}

type Snapshot

type Snapshot struct {
	Bytes  []byte
	Events []runlog.Event
}

Snapshot is the complete, immutable input to one projection.

type Store

type Store struct {
	Root string
}

Store materializes immutable receipt objects and mutable per-run references.

func NewStore

func NewStore(yieldDir string) *Store

func StoreForRunsDir

func StoreForRunsDir(runsDir string) *Store

func (*Store) ListRuns

func (s *Store) ListRuns() ([]string, error)

ListRuns returns run IDs with materialized latest-receipt references.

func (*Store) LoadDigest

func (s *Store) LoadDigest(receiptDigest string) (*RunReceipt, []byte, error)

LoadDigest reads and verifies an immutable receipt object.

func (*Store) LoadRun

func (s *Store) LoadRun(runID string) (*RunReceipt, []byte, error)

LoadRun reads the latest materialized receipt for a run.

func (*Store) Materialize

func (s *Store) Materialize(snapshot Snapshot) (*RunReceipt, []byte, error)

Materialize projects and durably stores the receipt for one exact prefix.

func (*Store) Put

func (s *Store) Put(r *RunReceipt, raw []byte) error

Put durably stores an already-sealed receipt.

type TimingSummary

type TimingSummary struct {
	StartedAt      string `json:"started_at"`
	LastObservedAt string `json:"last_observed_at"`
	EndedAt        string `json:"ended_at,omitempty"`
	ElapsedMS      *int64 `json:"elapsed_ms,omitempty"`
	ClockAnomaly   bool   `json:"clock_anomaly,omitempty"`
}