capsule

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package capsule contains the provider-neutral, bounded continuity capsule.

The package deliberately has no runtime, provider, or wire-protocol dependencies. It is the semantic value object used by the feature's adapters and workers.

Index

Constants

View Source 
const (
	SchemaVersion uint8 = 1

	SourceStructured     Source = "structured"
	SourceUserExplicit   Source = "user_explicit"
	SourceUserAcceptance Source = "user_acceptance"
	SourceSemantic       Source = "semantic"

	PlanDraft     PlanStatus = "draft"
	PlanAccepted  PlanStatus = "accepted"
	PlanCompleted PlanStatus = "completed"

	StepPending    StepStatus = "pending"
	StepInProgress StepStatus = "in_progress"
	StepCompleted  StepStatus = "completed"
	StepCancelled  StepStatus = "cancelled"

	FactActive     FactStatus = "active"
	FactSuperseded FactStatus = "superseded"
	FactRejected   FactStatus = "rejected"

	DecisionActive     DecisionStatus = "active"
	DecisionSuperseded DecisionStatus = "superseded"
	DecisionRejected   DecisionStatus = "rejected"

	AuthorityUserExplicit   Authority = "user_explicit"
	AuthorityUserAcceptance Authority = "user_acceptance"
	AuthorityStructured     Authority = "structured"
	AuthoritySemantic       Authority = "semantic"
)

Variables

View Source 
var (
	ErrInvalidCapsule            = errors.New("capsule: invalid capsule")
	ErrInvalidBranch             = errors.New("capsule: invalid branch binding")
	ErrDigestMismatch            = errors.New("capsule: content digest mismatch")
	ErrBranchMismatch            = errors.New("capsule: branch binding mismatch")
	ErrStaleRevision             = errors.New("capsule: stale revision")
	ErrUnknownSupersede          = errors.New("capsule: unknown supersedes reference")
	ErrFactConflict              = errors.New("capsule: conflicting duplicate fact")
	ErrCapsuleTooLarge           = errors.New("capsule: cannot fit capsule budget")
	ErrInvalidDecisionTransition = errors.New("capsule: invalid decision transition")
)

Functions

func BranchBinding 

func BranchBinding(key BranchKey) (string, error)

BranchBinding returns the content-free binding for an authoritative parent branch. At least one authoritative identity must be present.

func CanonicalBytes 

func CanonicalBytes(e Envelope) ([]byte, error)

func Encode 

func Encode(e Envelope) ([]byte, error)

Encode emits the canonical sealed envelope bytes and never emits an unsealed transport envelope by accident.

func NewBranchBinding 

func NewBranchBinding(sessionID, aLegID, principalPartition string) (string, error)

NewBranchBinding is a convenience for the usual parent identity fields.

func StableFactID 

func StableFactID(kind, statement, sourceRef string) string

func StableID 

func StableID(kind string, parts ...string) string

func StableStepID 

func StableStepID(text string) string

func TokenEquivalent 

func TokenEquivalent(data []byte) int

TokenEquivalent returns the deterministic provider-neutral token estimate used for capsule bounds. Counting UTF-8 bytes one-for-one is intentionally conservative and avoids depending on a provider tokenizer.

Types

type Authority 

type Authority string

type BranchKey 

type BranchKey struct {
	AuthoritativeSessionID string `json:"authoritative_session_id"`
	ALegID                 string `json:"a_leg_id"`
	PrincipalPartition     string `json:"principal_partition"`
}

BranchKey is the authoritative parent identity used to bind capsule state. The auxiliary child A-leg must never be substituted for ALegID.

type Decision 

type Decision struct {
	ID              string         `json:"id"`
	ConflictKey     string         `json:"conflict_key"`
	Supersedes      []string       `json:"supersedes"`
	Statement       string         `json:"statement"`
	Status          DecisionStatus `json:"status"`
	Authority       Authority      `json:"authority"`
	Rationale       string         `json:"rationale"`
	SourceRef       string         `json:"source_ref"`
	StatusSourceRef string         `json:"status_source_ref,omitempty"`
}

type DecisionStatus 

type DecisionStatus string

type DecisionTransition 

type DecisionTransition struct {
	ID        string         `json:"id"`
	Status    DecisionStatus `json:"status"`
	Authority Authority      `json:"authority"`
	SourceRef string         `json:"source_ref"`
}

DecisionTransition changes only the terminal status of an existing active semantic decision. It is intentionally narrower than Decision so semantic extraction cannot rewrite or remove user/structured authority.

type Delta 

type Delta struct {
	SchemaVersion        uint8
	BaseRevision         uint64
	BranchBinding        string
	SourceHighWatermark  string
	Plan                 *Plan
	Decisions            []Decision
	DecisionTransitions  []DecisionTransition
	Constraints          []Fact
	RejectedAlternatives []Fact
	OpenQuestions        []Fact
}

Delta is the validated input to a compare-and-merge operation. A zero SchemaVersion is accepted as a convenience for local callers and normalized to v1; non-zero unknown versions are rejected.

type Envelope 

type Envelope struct {
	SchemaVersion        uint8      `json:"schema_version"`
	Revision             uint64     `json:"revision"`
	SourceHighWatermark  string     `json:"source_high_watermark"`
	BranchBinding        string     `json:"branch_binding"`
	ContentDigest        string     `json:"content_digest,omitempty"`
	Plan                 Plan       `json:"plan"`
	Decisions            []Decision `json:"decisions"`
	Constraints          []Fact     `json:"constraints"`
	RejectedAlternatives []Fact     `json:"rejected_alternatives"`
	OpenQuestions        []Fact     `json:"open_questions"`
}

func Decode 

func Decode(data []byte) (Envelope, error)

Decode parses, validates, and verifies one complete envelope.

func Merge 

func Merge(previous Envelope, delta Delta) (Envelope, error)

Merge applies a validated deterministic/semantic delta using compare-and- merge semantics. The previous envelope is never modified.

func New 

func New(branchBinding string) (Envelope, error)

New returns a sealed v1 capsule at revision one for branchBinding.

func Parse 

func Parse(data []byte) (Envelope, error)

func Prune 

func Prune(input Envelope, maxBytes int) (Envelope, error)

Prune preserves the original byte-only API. New callers that have both configured dimensions should use PruneWithLimits.

func PruneWithLimits 

func PruneWithLimits(input Envelope, limits Limits) (Envelope, error)

PruneWithLimits removes complete facts, then historical facts, as whole values until the sealed canonical envelope satisfies every configured dimension. Active decisions, constraints, and pending/in-progress plan steps are retained whenever possible.

func Verify 

func Verify(data []byte, expectedBranch string) (Envelope, error)

Verify parses and verifies a serialized capsule against an optional parent binding. An empty expectedBranch only checks the self-digest.

func (Envelope) Clone 

func (e Envelope) Clone() Envelope

func (Envelope) ComputeDigest 

func (e Envelope) ComputeDigest() (string, error)

func (*Envelope) Seal 

func (e *Envelope) Seal() error

Seal normalizes collection fields, validates semantic values, and computes the canonical content digest. Only the digest field is excluded from the digest input.

func (Envelope) Validate 

func (e Envelope) Validate() error

Validate checks semantic and envelope invariants without requiring a caller-supplied branch. Verify additionally checks the self-digest.

func (Envelope) Verify 

func (e Envelope) Verify() error

func (Envelope) VerifyBranch 

func (e Envelope) VerifyBranch(expectedBranch string) error

type Fact 

type Fact struct {
	ID        string     `json:"id"`
	Statement string     `json:"statement"`
	Status    FactStatus `json:"status"`
	Authority Authority  `json:"authority"`
	Rationale string     `json:"rationale"`
	SourceRef string     `json:"source_ref"`
}

type FactStatus 

type FactStatus string

type Limits 

type Limits struct {
	MaxBytes  int
	MaxTokens int
}

Limits bounds the serialized capsule. MaxBytes and MaxTokens are independent dimensions; a zero value leaves that dimension unbounded. MaxTokens uses the conservative provider-neutral convention of one token-equivalent per UTF-8 byte in the canonical JSON.

type Plan 

type Plan struct {
	Status PlanStatus `json:"status"`
	Source Source     `json:"source"`
	Steps  []PlanStep `json:"steps"`
}

type PlanStatus 

type PlanStatus string

type PlanStep 

type PlanStep struct {
	ID        string     `json:"id"`
	Text      string     `json:"text"`
	Status    StepStatus `json:"status"`
	SourceRef string     `json:"source_ref"`
}

type Source 

type Source string

type StepStatus 

type StepStatus string

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.