ledger

type ActorKind ¶

type ActorKind string

ActorKind is trusted provenance supplied after transport authentication.

const (
	ActorKindAgent    ActorKind = "agent"
	ActorKindUser     ActorKind = "user"
	ActorKindSystem   ActorKind = "system"
	ActorKindTool     ActorKind = "tool"
	ActorKindExternal ActorKind = "external"
)

type Constitution ¶

type Constitution struct {
	MemoryRef string
	Text      string
}

Constitution is an immutable external normative snapshot, never writable Memory. The zero value represents an unknown baseline.

type Episode ¶

type Episode struct {
	Ref            string
	Scope          Scope
	RunRef         string
	SourceGroupRef string
	Links          []SourceLink
}

Episode is the deterministic envelope for one stable run/source group. Links are returned in role then source-ref order.

type EpisodeBinding ¶

type EpisodeBinding struct {
	RunRef         string
	SourceGroupRef string
	Role           SourceRole
}

EpisodeBinding requests one typed provenance link in a stable run/source group. An incomplete binding admits the SourceEvent without guessing a boundary and can be retried later with all fields present.

type Ledger ¶

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

Ledger runs after transport request-idempotency. It admits immutable SourceEvents and materializes Episodes once distinct sources provide a situation and an actual agent act. It deliberately contains no semantic or time-based boundary inference.

func New() *Ledger

func (l *Ledger) Observe(event SourceEvent, binding EpisodeBinding) (Episode, bool, error)

type MemoryDelivery ¶

type MemoryDelivery struct {
	IdempotencyKey      string
	Scope               Scope
	RunRef              string
	MemoryContextRef    string
	DeliveredMemoryRefs []string
}

MemoryDelivery states only which stable memories a Harness can prove were exposed. It does not claim that the model used them.

type MemoryDeliveryReceipt ¶

type MemoryDeliveryReceipt struct {
	Ref string
}

type ObserveReceipt ¶

type ObserveReceipt struct {
	SourceEventRef string
	EpisodeRef     string
}

ObserveReceipt is the immutable result frozen by one transport idempotency key. EpisodeRef is empty until that request materializes or appends to an already materialized Episode.

type OutcomeReceipt ¶

type OutcomeReceipt struct {
	OutcomeEventRef string
	EpisodeRef      string
}

type OutcomeReport ¶

type OutcomeReport struct {
	IdempotencyKey         string
	Event                  SourceEvent
	RunRef                 string
	SourceGroupRef         string
	DeliveryReceiptRefs    []string
	RelatedSourceEventRefs []string
}

OutcomeReport is an observed source-bound result, never a reinforcement instruction. Delivery attribution remains optional.

type Scope ¶

type Scope struct {
	Kind            ScopeKind
	TenantRef       string
	AgentRef        string
	RelationshipRef string
	SessionRef      string
}

type ScopeKind ¶

type ScopeKind string

Scope is the exact authorization boundary shared by an Episode and all of its SourceEvents. SessionRef may be empty, but when present is part of the exact boundary and Episode identity.

const (
	ScopeKindAgent        ScopeKind = "agent"
	ScopeKindRelationship ScopeKind = "relationship"
)

type SourceEvent ¶

type SourceEvent struct {
	Ref          string
	Scope        Scope
	ActorKind    ActorKind
	ActorRef     string
	Text         string
	Constitution Constitution
}

SourceEvent is an immutable input value within its exact Scope. Episode membership and role are separate relations, not properties of the source.

type SourceLink ¶

type SourceLink struct {
	SourceEventRef string
	Role           SourceRole
}

SourceLink is a typed provenance edge from an Episode to a SourceEvent.

type SourceRole ¶

type SourceRole string

SourceRole states how a SourceEvent is linked to an Episode.

const (
	RoleSituation SourceRole = "situation"
	RoleAgentAct  SourceRole = "agent_act"
	RoleOutcome   SourceRole = "outcome"
)